interface/wx/richtext/richtextbuffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextbuffer.h
   3 // Purpose:     interface of wxRichTextBuffer
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10
  11 /*!
  12  * File types in wxRichText context.
  13  */
  14 enum wxRichTextFileType
  15 {
  16     wxRICHTEXT_TYPE_ANY = 0,
  17     wxRICHTEXT_TYPE_TEXT,
  18     wxRICHTEXT_TYPE_XML,
  19     wxRICHTEXT_TYPE_HTML,
  20     wxRICHTEXT_TYPE_RTF,
  21     wxRICHTEXT_TYPE_PDF
  22 };
  23
  24 /*!
  25  * Flags determining the available space, passed to Layout
  26  */
  27
  28 #define wxRICHTEXT_FIXED_WIDTH      0x01
  29 #define wxRICHTEXT_FIXED_HEIGHT     0x02
  30 #define wxRICHTEXT_VARIABLE_WIDTH   0x04
  31 #define wxRICHTEXT_VARIABLE_HEIGHT  0x08
  32
  33 // Only lay out the part of the buffer that lies within
  34 // the rect passed to Layout.
  35 #define wxRICHTEXT_LAYOUT_SPECIFIED_RECT 0x10
  36
  37 /*!
  38  * Flags to pass to Draw
  39  */
  40
  41 // Ignore paragraph cache optimization, e.g. for printing purposes
  42 // where one line may be drawn higher (on the next page) compared
  43 // with the previous line
  44 #define wxRICHTEXT_DRAW_IGNORE_CACHE    0x01
  45
  46 /*!
  47  * Flags returned from hit-testing
  48  */
  49 enum wxRichTextHitTestFlags
  50 {
  51     /// The point was not on this object
  52     wxRICHTEXT_HITTEST_NONE =    0x01,
  53
  54     /// The point was before the position returned from HitTest
  55     wxRICHTEXT_HITTEST_BEFORE =  0x02,
  56
  57     /// The point was after the position returned from HitTest
  58     wxRICHTEXT_HITTEST_AFTER =   0x04,
  59
  60     /// The point was on the position returned from HitTest
  61     wxRICHTEXT_HITTEST_ON =      0x08,
  62
  63     /// The point was on space outside content
  64     wxRICHTEXT_HITTEST_OUTSIDE = 0x10
  65 };
  66
  67 /*!
  68  * Flags for GetRangeSize
  69  */
  70
  71 #define wxRICHTEXT_FORMATTED        0x01
  72 #define wxRICHTEXT_UNFORMATTED      0x02
  73 #define wxRICHTEXT_CACHE_SIZE       0x04
  74 #define wxRICHTEXT_HEIGHT_ONLY      0x08
  75
  76 /*!
  77  * Flags for SetStyle/SetListStyle
  78  */
  79
  80 #define wxRICHTEXT_SETSTYLE_NONE            0x00
  81
  82 // Specifies that this operation should be undoable
  83 #define wxRICHTEXT_SETSTYLE_WITH_UNDO       0x01
  84
  85 // Specifies that the style should not be applied if the
  86 // combined style at this point is already the style in question.
  87 #define wxRICHTEXT_SETSTYLE_OPTIMIZE        0x02
  88
  89 // Specifies that the style should only be applied to paragraphs,
  90 // and not the content. This allows content styling to be
  91 // preserved independently from that of e.g. a named paragraph style.
  92 #define wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY 0x04
  93
  94 // Specifies that the style should only be applied to characters,
  95 // and not the paragraph. This allows content styling to be
  96 // preserved independently from that of e.g. a named paragraph style.
  97 #define wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY 0x08
  98
  99 // For SetListStyle only: specifies starting from the given number, otherwise
 100 // deduces number from existing attributes
 101 #define wxRICHTEXT_SETSTYLE_RENUMBER        0x10
 102
 103 // For SetListStyle only: specifies the list level for all paragraphs, otherwise
 104 // the current indentation will be used
 105 #define wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL   0x20
 106
 107 // Resets the existing style before applying the new style
 108 #define wxRICHTEXT_SETSTYLE_RESET           0x40
 109
 110 // Removes the given style instead of applying it
 111 #define wxRICHTEXT_SETSTYLE_REMOVE          0x80
 112
 113 /*!
 114  * Flags for text insertion
 115  */
 116
 117 #define wxRICHTEXT_INSERT_NONE                              0x00
 118 #define wxRICHTEXT_INSERT_WITH_PREVIOUS_PARAGRAPH_STYLE     0x01
 119 #define wxRICHTEXT_INSERT_INTERACTIVE                       0x02
 120
 121 // A special flag telling the buffer to keep the first paragraph style
 122 // as-is, when deleting a paragraph marker. In future we might pass a
 123 // flag to InsertFragment and DeleteRange to indicate the appropriate mode.
 124 #define wxTEXT_ATTR_KEEP_FIRST_PARA_STYLE   0x10000000
 125
 126 /*!
 127  * Default superscript/subscript font multiplication factor
 128  */
 129
 130 #define wxSCRIPT_MUL_FACTOR             1.5
 131
 132
 133 /**
 134     @class wxRichTextBuffer
 135
 136     This class represents the whole buffer associated with a wxRichTextCtrl.
 137
 138     @library{wxrichtext}
 139     @category{richtext}
 140
 141     @see wxTextAttr, wxRichTextCtrl
 142 */
 143 class wxRichTextBuffer : public wxRichTextParagraphLayoutBox
 144 {
 145 public:
 146     /**
 147         Default constructor.
 148     */
 149     wxRichTextBuffer();
 150
 151     /**
 152         Copy ctor.
 153     */
 154     wxRichTextBuffer(const wxRichTextBuffer& obj);
 155
 156     /**
 157         Destructor.
 158     */
 159     virtual ~wxRichTextBuffer();
 160
 161     /**
 162         Adds an event handler to the buffer's list of handlers.
 163
 164         A buffer associated with a control has the control as the only event handler,
 165         but the application is free to add more if further notification is required.
 166         All handlers are notified of an event originating from the buffer, such as
 167         the replacement of a style sheet during loading.
 168
 169         The buffer never deletes any of the event handlers, unless RemoveEventHandler()
 170         is called with @true as the second argument.
 171     */
 172     bool AddEventHandler(wxEvtHandler* handler);
 173
 174     /**
 175         Adds a file handler.
 176     */
 177     static void AddHandler(wxRichTextFileHandler* handler);
 178
 179     /**
 180         Adds a paragraph of text.
 181     */
 182     virtual wxRichTextRange AddParagraph(const wxString& text,
 183                                          wxTextAttr* paraStyle = 0);
 184
 185     /**
 186         Returns @true if the buffer is currently collapsing commands into a single
 187         notional command.
 188     */
 189     virtual bool BatchingUndo() const;
 190
 191     /**
 192         Begins using alignment.
 193     */
 194     bool BeginAlignment(wxTextAttrAlignment alignment);
 195
 196     /**
 197         Begins collapsing undo/redo commands. Note that this may not work properly
 198         if combining commands that delete or insert content, changing ranges for
 199         subsequent actions.
 200
 201         @a cmdName should be the name of the combined command that will appear
 202         next to Undo and Redo in the edit menu.
 203     */
 204     virtual bool BeginBatchUndo(const wxString& cmdName);
 205
 206     /**
 207         Begin applying bold.
 208     */
 209     bool BeginBold();
 210
 211     /**
 212         Begins applying the named character style.
 213     */
 214     bool BeginCharacterStyle(const wxString& characterStyle);
 215
 216     /**
 217         Begins using this font.
 218     */
 219     bool BeginFont(const wxFont& font);
 220
 221     /**
 222         Begins using the given point size.
 223     */
 224     bool BeginFontSize(int pointSize);
 225
 226     /**
 227         Begins using italic.
 228     */
 229     bool BeginItalic();
 230
 231     /**
 232         Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent for
 233         the sub-indent. Both are expressed in tenths of a millimetre.
 234
 235         The sub-indent is an offset from the left of the paragraph, and is used for all
 236         but the first line in a paragraph. A positive value will cause the first line to appear
 237         to the left of the subsequent lines, and a negative value will cause the first line to be
 238         indented relative to the subsequent lines.
 239     */
 240     bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0);
 241
 242     /**
 243         Begins line spacing using the specified value. @e spacing is a multiple, where
 244         10 means single-spacing, 15 means 1.5 spacing, and 20 means double spacing.
 245
 246         The ::wxTextAttrLineSpacing enumeration values are defined for convenience.
 247     */
 248     bool BeginLineSpacing(int lineSpacing);
 249
 250     /**
 251         Begins using a specified list style.
 252         Optionally, you can also pass a level and a number.
 253     */
 254     bool BeginListStyle(const wxString& listStyle, int level = 1,
 255                         int number = 1);
 256
 257     /**
 258         Begins a numbered bullet.
 259
 260         This call will be needed for each item in the list, and the
 261         application should take care of incrementing the numbering.
 262
 263         @a bulletNumber is a number, usually starting with 1.
 264         @a leftIndent and @a leftSubIndent are values in tenths of a millimetre.
 265         @a bulletStyle is a bitlist of the following values:
 266
 267         wxRichTextBuffer uses indentation to render a bulleted item.
 268         The left indent is the distance between the margin and the bullet.
 269         The content of the paragraph, including the first line, starts
 270         at leftMargin + leftSubIndent.
 271         So the distance between the left edge of the bullet and the
 272         left of the actual paragraph is leftSubIndent.
 273     */
 274     bool BeginNumberedBullet(int bulletNumber, int leftIndent,
 275                              int leftSubIndent,
 276                              int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD);
 277
 278     /**
 279         Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing
 280         in tenths of a millimetre.
 281     */
 282     bool BeginParagraphSpacing(int before, int after);
 283
 284     /**
 285         Begins applying the named paragraph style.
 286     */
 287     bool BeginParagraphStyle(const wxString& paragraphStyle);
 288
 289     /**
 290         Begins a right indent, specified in tenths of a millimetre.
 291     */
 292     bool BeginRightIndent(int rightIndent);
 293
 294     /**
 295         Begins applying a standard bullet, using one of the standard bullet names
 296         (currently @c standard/circle or @c standard/square.
 297
 298         See BeginNumberedBullet() for an explanation of how indentation is used to
 299         render the bulleted paragraph.
 300     */
 301     bool BeginStandardBullet(const wxString& bulletName,
 302                              int leftIndent,
 303                              int leftSubIndent,
 304                              int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_STANDARD);
 305
 306     /**
 307         Begins using a specified style.
 308     */
 309     virtual bool BeginStyle(const wxTextAttr& style);
 310
 311     /**
 312         Begins suppressing undo/redo commands. The way undo is suppressed may be
 313         implemented differently by each command.
 314         If not dealt with by a command implementation, then it will be implemented
 315         automatically by not storing the command in the undo history when the
 316         action is submitted to the command processor.
 317     */
 318     virtual bool BeginSuppressUndo();
 319
 320     /**
 321         Begins applying a symbol bullet, using a character from the current font.
 322
 323         See BeginNumberedBullet() for an explanation of how indentation is used
 324         to render the bulleted paragraph.
 325     */
 326     bool BeginSymbolBullet(const wxString& symbol, int leftIndent,
 327                            int leftSubIndent,
 328                            int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL);
 329
 330     /**
 331         Begins using the specified text foreground colour.
 332     */
 333     bool BeginTextColour(const wxColour& colour);
 334
 335     /**
 336         Begins applying wxTEXT_ATTR_URL to the content.
 337
 338         Pass a URL and optionally, a character style to apply, since it is common
 339         to mark a URL with a familiar style such as blue text with underlining.
 340     */
 341     bool BeginURL(const wxString& url,
 342                   const wxString& characterStyle = wxEmptyString);
 343
 344     /**
 345         Begins using underline.
 346     */
 347     bool BeginUnderline();
 348
 349     /**
 350         Returns @true if content can be pasted from the clipboard.
 351     */
 352     virtual bool CanPasteFromClipboard() const;
 353
 354     /**
 355         Cleans up the file handlers.
 356     */
 357     static void CleanUpHandlers();
 358
 359     /**
 360         Clears the buffer.
 361     */
 362     virtual void Clear();
 363
 364     //@{
 365     /**
 366         Clears the list style from the given range, clearing list-related attributes
 367         and applying any named paragraph style associated with each paragraph.
 368
 369         @a flags is a bit list of the following:
 370         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 371
 372         @see SetListStyle(), PromoteList(), NumberList()
 373     */
 374     bool ClearListStyle(const wxRichTextRange& range,
 375                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 376     bool ClearListStyle(const wxRichTextRange& range,
 377                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 378     //@}
 379
 380     /**
 381         Clears the style stack.
 382     */
 383     virtual void ClearStyleStack();
 384
 385     /**
 386         Clones the object.
 387     */
 388     virtual wxRichTextObject* Clone() const;
 389
 390     /**
 391         Copies the given buffer.
 392     */
 393     void Copy(const wxRichTextBuffer& obj);
 394
 395     /**
 396         Copy the given range to the clipboard.
 397     */
 398     virtual bool CopyToClipboard(const wxRichTextRange& range);
 399
 400     /**
 401         Submits a command to delete the given range.
 402     */
 403     bool DeleteRangeWithUndo(const wxRichTextRange& range,
 404                              wxRichTextCtrl* ctrl);
 405
 406     //@{
 407     /**
 408         Dumps the contents of the buffer for debugging purposes.
 409     */
 410     void Dump();
 411     void Dump(wxTextOutputStream& stream);
 412     //@}
 413
 414     /**
 415         Ends alignment.
 416     */
 417     bool EndAlignment();
 418
 419     /**
 420         Ends all styles that have been started with a Begin... command.
 421     */
 422     virtual bool EndAllStyles();
 423
 424     /**
 425         Ends collapsing undo/redo commands, and submits the combined command.
 426     */
 427     virtual bool EndBatchUndo();
 428
 429     /**
 430         Ends using bold.
 431     */
 432     bool EndBold();
 433
 434     /**
 435         Ends using the named character style.
 436     */
 437     bool EndCharacterStyle();
 438
 439     /**
 440         Ends using a font.
 441     */
 442     bool EndFont();
 443
 444     /**
 445         Ends using a point size.
 446     */
 447     bool EndFontSize();
 448
 449     /**
 450         Ends using italic.
 451     */
 452     bool EndItalic();
 453
 454     /**
 455         Ends using a left indent.
 456     */
 457     bool EndLeftIndent();
 458
 459     /**
 460         Ends using a line spacing.
 461     */
 462     bool EndLineSpacing();
 463
 464     /**
 465         Ends using a specified list style.
 466     */
 467     bool EndListStyle();
 468
 469     /**
 470         Ends a numbered bullet.
 471     */
 472     bool EndNumberedBullet();
 473
 474     /**
 475         Ends paragraph spacing.
 476     */
 477     bool EndParagraphSpacing();
 478
 479     /**
 480         Ends applying a named character style.
 481     */
 482     bool EndParagraphStyle();
 483
 484     /**
 485         Ends using a right indent.
 486     */
 487     bool EndRightIndent();
 488
 489     /**
 490         Ends using a standard bullet.
 491     */
 492     bool EndStandardBullet();
 493
 494     /**
 495         Ends the current style.
 496     */
 497     virtual bool EndStyle();
 498
 499     /**
 500         Ends suppressing undo/redo commands.
 501     */
 502     virtual bool EndSuppressUndo();
 503
 504     /**
 505         Ends using a symbol bullet.
 506     */
 507     bool EndSymbolBullet();
 508
 509     /**
 510         Ends using a text foreground colour.
 511     */
 512     bool EndTextColour();
 513
 514     /**
 515         Ends applying a URL.
 516     */
 517     bool EndURL();
 518
 519     /**
 520         Ends using underline.
 521     */
 522     bool EndUnderline();
 523
 524     /**
 525         Finds a handler by type.
 526     */
 527     static wxRichTextFileHandler* FindHandler(wxRichTextFileType imageType);
 528
 529     /**
 530         Finds a handler by extension and type.
 531     */
 532     static wxRichTextFileHandler* FindHandler(const wxString& extension, wxRichTextFileType imageType);
 533
 534     /**
 535         Finds a handler by name.
 536     */
 537     static wxRichTextFileHandler* FindHandler(const wxString& name);
 538
 539     /**
 540         Finds a handler by filename or, if supplied, type.
 541     */
 542     static wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename, wxRichTextFileType imageType);
 543
 544     /**
 545         Gets the basic (overall) style.
 546
 547         This is the style of the whole buffer before further styles are applied,
 548         unlike the default style, which only affects the style currently being
 549         applied (for example, setting the default style to bold will cause
 550         subsequently inserted text to be bold).
 551     */
 552     virtual const wxTextAttr& GetBasicStyle() const;
 553
 554     /**
 555         Gets the collapsed command.
 556     */
 557     virtual wxRichTextCommand* GetBatchedCommand() const;
 558
 559     /**
 560         Gets the command processor.
 561         A text buffer always creates its own command processor when it is initialized.
 562     */
 563     wxCommandProcessor* GetCommandProcessor() const;
 564
 565     /**
 566         Returns the current default style, affecting the style currently being applied
 567         (for example, setting the default style to bold will cause subsequently
 568         inserted text to be bold).
 569     */
 570     virtual const wxTextAttr& GetDefaultStyle() const;
 571
 572     /**
 573         Gets a wildcard incorporating all visible handlers.
 574         If @a types is present, it will be filled with the file type corresponding
 575         to each filter. This can be used to determine the type to pass to LoadFile()
 576         given a selected filter.
 577     */
 578     static wxString GetExtWildcard(bool combine = false, bool save = false,
 579                                    wxArrayInt* types = NULL);
 580
 581     /**
 582         Returns the list of file handlers.
 583     */
 584     static wxList& GetHandlers();
 585
 586     /**
 587         Returns the object to be used to render certain aspects of the content, such as
 588         bullets.
 589     */
 590     static wxRichTextRenderer* GetRenderer();
 591
 592     /**
 593         Gets the attributes at the given position.
 594
 595         This function gets the combined style - that is, the style you see on the
 596         screen as a result of combining base style, paragraph style and character
 597         style attributes. To get the character or paragraph style alone,
 598         use GetUncombinedStyle().
 599     */
 600     virtual bool GetStyle(long position, wxTextAttr& style);
 601
 602     /**
 603         This function gets a style representing the common, combined attributes in the
 604         given range.
 605         Attributes which have different values within the specified range will not be
 606         included the style flags.
 607
 608         The function is used to get the attributes to display in the formatting dialog:
 609         the user can edit the attributes common to the selection, and optionally specify the
 610         values of further attributes to be applied uniformly.
 611
 612         To apply the edited attributes, you can use SetStyle() specifying
 613         the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that
 614         are different from the @e combined attributes within the range.
 615         So, the user edits the effective, displayed attributes for the range,
 616         but his choice won't be applied unnecessarily to content. As an example,
 617         say the style for a paragraph specifies bold, but the paragraph text doesn't
 618         specify a weight.
 619         The combined style is bold, and this is what the user will see on-screen and
 620         in the formatting dialog. The user now specifies red text, in addition to bold.
 621         When applying with SetStyle(), the content font weight attributes won't be
 622         changed to bold because this is already specified by the paragraph.
 623         However the text colour attributes @e will be changed to show red.
 624     */
 625     virtual bool GetStyleForRange(const wxRichTextRange& range,
 626                                   wxTextAttr& style);
 627
 628     /**
 629         Returns the current style sheet associated with the buffer, if any.
 630     */
 631     virtual wxRichTextStyleSheet* GetStyleSheet() const;
 632
 633     /**
 634         Get the size of the style stack, for example to check correct nesting.
 635     */
 636     virtual size_t GetStyleStackSize() const;
 637
 638     /**
 639         Gets the attributes at the given position.
 640
 641         This function gets the @e uncombined style - that is, the attributes associated
 642         with the paragraph or character content, and not necessarily the combined
 643         attributes you see on the screen. To get the combined attributes, use GetStyle().
 644         If you specify (any) paragraph attribute in @e style's flags, this function
 645         will fetch the paragraph attributes.
 646         Otherwise, it will return the character attributes.
 647     */
 648     virtual bool GetUncombinedStyle(long position, wxTextAttr& style);
 649
 650     /**
 651         Finds the text position for the given position, putting the position in
 652         @a textPosition if one is found.
 653         @a pt is in logical units (a zero y position is at the beginning of the buffer).
 654
 655         @return One of the ::wxRichTextHitTestFlags values.
 656     */
 657     virtual int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition);
 658
 659     /**
 660         Initialisation.
 661     */
 662     void Init();
 663
 664     /**
 665         Initialises the standard handlers.
 666         Currently, only the plain text loading/saving handler is initialised by default.
 667     */
 668     static void InitStandardHandlers();
 669
 670     /**
 671         Inserts a handler at the front of the list.
 672     */
 673     static void InsertHandler(wxRichTextFileHandler* handler);
 674
 675     /**
 676         Submits a command to insert the given image.
 677     */
 678     bool InsertImageWithUndo(long pos, const wxRichTextImageBlock& imageBlock,
 679                              wxRichTextCtrl* ctrl, int flags = 0);
 680
 681     /**
 682         Submits a command to insert a newline.
 683     */
 684     bool InsertNewlineWithUndo(long pos, wxRichTextCtrl* ctrl, int flags = 0);
 685
 686     /**
 687         Submits a command to insert the given text.
 688     */
 689     bool InsertTextWithUndo(long pos, const wxString& text,
 690                             wxRichTextCtrl* ctrl, int flags = 0);
 691
 692     /**
 693         Returns @true if the buffer has been modified.
 694     */
 695     bool IsModified() const;
 696
 697     /**
 698         Loads content from a stream.
 699     */
 700     virtual bool LoadFile(wxInputStream& stream,
 701                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 702
 703     /**
 704         Loads content from a file.
 705     */
 706     virtual bool LoadFile(const wxString& filename,
 707                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 708
 709     /**
 710         Marks the buffer as modified or unmodified.
 711     */
 712     void Modify(bool modify = true);
 713
 714     //@{
 715     /**
 716         Numbers the paragraphs in the given range.
 717
 718         Pass flags to determine how the attributes are set.
 719         Either the style definition or the name of the style definition (in the current
 720         sheet) can be passed.
 721
 722         @a flags is a bit list of the following:
 723         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 724         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 725           @a startFrom, otherwise existing attributes are used.
 726         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 727           as the level for all paragraphs, otherwise the current indentation will be used.
 728
 729         @see SetListStyle(), PromoteList(), ClearListStyle()
 730     */
 731     bool NumberList(const wxRichTextRange& range,
 732                     const wxRichTextListStyleDefinition* style,
 733                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 734                     int startFrom = -1,
 735                     int listLevel = -1);
 736     bool Number(const wxRichTextRange& range,
 737                 const wxString& styleName,
 738                 int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 739                 int startFrom = -1,
 740                 int listLevel = -1);
 741     //@}
 742
 743     /**
 744         Pastes the clipboard content to the buffer at the given position.
 745     */
 746     virtual bool PasteFromClipboard(long position);
 747
 748     //@{
 749     /**
 750         Promotes or demotes the paragraphs in the given range.
 751
 752         A positive @a promoteBy produces a smaller indent, and a negative number
 753         produces a larger indent. Pass flags to determine how the attributes are set.
 754         Either the style definition or the name of the style definition (in the current
 755         sheet) can be passed.
 756
 757         @a flags is a bit list of the following:
 758         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 759         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 760           @a startFrom, otherwise existing attributes are used.
 761         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 762           as the level for all paragraphs, otherwise the current indentation will be used.
 763
 764         @see SetListStyle(), SetListStyle(), ClearListStyle()
 765     */
 766     bool PromoteList(int promoteBy, const wxRichTextRange& range,
 767                      const wxRichTextListStyleDefinition* style,
 768                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 769                      int listLevel = -1);
 770     bool PromoteList(int promoteBy, const wxRichTextRange& range,
 771                      const wxString& styleName,
 772                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 773                      int listLevel = -1);
 774     //@}
 775
 776     /**
 777         Removes an event handler from the buffer's list of handlers, deleting the
 778         object if @a deleteHandler is @true.
 779     */
 780     bool RemoveEventHandler(wxEvtHandler* handler,
 781                             bool deleteHandler = false);
 782
 783     /**
 784         Removes a handler.
 785     */
 786     static bool RemoveHandler(const wxString& name);
 787
 788     /**
 789         Clears the buffer, adds a new blank paragraph, and clears the command history.
 790     */
 791     virtual void ResetAndClearCommands();
 792
 793     /**
 794         Saves content to a stream.
 795     */
 796     virtual bool SaveFile(wxOutputStream& stream,
 797                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 798
 799     /**
 800         Saves content to a file.
 801     */
 802     virtual bool SaveFile(const wxString& filename,
 803                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 804
 805     /**
 806         Sets the basic (overall) style. This is the style of the whole
 807         buffer before further styles are applied, unlike the default style, which
 808         only affects the style currently being applied (for example, setting the default
 809         style to bold will cause subsequently inserted text to be bold).
 810     */
 811     virtual void SetBasicStyle(const wxTextAttr& style);
 812
 813     /**
 814         Sets the default style, affecting the style currently being applied
 815         (for example, setting the default style to bold will cause subsequently
 816         inserted text to be bold).
 817
 818         This is not cumulative - setting the default style will replace the previous
 819         default style.
 820     */
 821     virtual bool SetDefaultStyle(const wxTextAttr& style);
 822
 823     //@{
 824     /**
 825         Sets the list attributes for the given range, passing flags to determine how
 826         the attributes are set.
 827         Either the style definition or the name of the style definition (in the current
 828         sheet) can be passed.
 829
 830         @a flags is a bit list of the following:
 831         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 832         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 833           @a startFrom, otherwise existing attributes are used.
 834         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 835           as the level for all paragraphs, otherwise the current indentation will be used.
 836
 837         @see NumberList(), PromoteList(), ClearListStyle().
 838     */
 839     bool SetListStyle(const wxRichTextRange& range,
 840                       const wxRichTextListStyleDefinition* style,
 841                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 842                       int startFrom = -1,
 843                       int listLevel = -1);
 844     bool SetListStyle(const wxRichTextRange& range,
 845                       const wxString& styleName,
 846                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 847                       int startFrom = -1,
 848                       int listLevel = -1);
 849     //@}
 850
 851     /**
 852         Sets @a renderer as the object to be used to render certain aspects of the
 853         content, such as bullets.
 854
 855         You can override default rendering by deriving a new class from
 856         wxRichTextRenderer or wxRichTextStdRenderer, overriding one or more
 857         virtual functions, and setting an instance of the class using this function.
 858     */
 859     static void SetRenderer(wxRichTextRenderer* renderer);
 860
 861     /**
 862         Sets the attributes for the given range. Pass flags to determine how the
 863         attributes are set.
 864
 865         The end point of range is specified as the last character position of the span
 866         of text. So, for example, to set the style for a character at position 5,
 867         use the range (5,5).
 868         This differs from the wxRichTextCtrl API, where you would specify (5,6).
 869
 870         @a flags may contain a bit list of the following values:
 871         - wxRICHTEXT_SETSTYLE_NONE: no style flag.
 872         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
 873           undoable.
 874         - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
 875           if the combined style at this point is already the style in question.
 876         - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
 877           applied to paragraphs, and not the content.
 878           This allows content styling to be preserved independently from that
 879           of e.g. a named paragraph style.
 880         - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
 881           applied to characters, and not the paragraph.
 882           This allows content styling to be preserved independently from that
 883           of e.g. a named paragraph style.
 884         - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
 885           the new style.
 886         - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style.
 887           Only the style flags are used in this operation.
 888     */
 889     virtual bool SetStyle(const wxRichTextRange& range, const wxTextAttr& style,
 890                           int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 891
 892     /**
 893         Sets the current style sheet, if any.
 894
 895         This will allow the application to use named character and paragraph
 896         styles found in the style sheet.
 897     */
 898     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 899
 900     /**
 901         Submit an action immediately, or delay it according to whether collapsing is on.
 902     */
 903     virtual bool SubmitAction(wxRichTextAction* action);
 904
 905     /**
 906         Returns @true if undo suppression is currently on.
 907     */
 908     virtual bool SuppressingUndo() const;
 909 };
 910
 911
 912
 913 /**
 914     @class wxRichTextFileHandler
 915
 916     This is the base class for file handlers, for loading and/or saving content
 917     associated with a wxRichTextBuffer.
 918
 919     @library{wxrichtext}
 920     @category{richtext}
 921 */
 922 class wxRichTextFileHandler : public wxObject
 923 {
 924 public:
 925     /**
 926         Constructor.
 927     */
 928     wxRichTextFileHandler(const wxString& name = wxEmptyString,
 929                           const wxString& ext = wxEmptyString,
 930                           int type = 0);
 931
 932     /**
 933         Override this function and return @true if this handler can we handle
 934         @a filename.
 935
 936         By default, this function checks the extension.
 937     */
 938     virtual bool CanHandle(const wxString& filename) const;
 939
 940     /**
 941         Override and return @true if this handler can load content.
 942     */
 943     virtual bool CanLoad() const;
 944
 945     /**
 946         Override and return @true if this handler can save content.
 947     */
 948     virtual bool CanSave() const;
 949
 950     /**
 951         Returns the encoding associated with the handler (if any).
 952     */
 953     const wxString& GetEncoding() const;
 954
 955     /**
 956         Returns the extension associated with the handler.
 957     */
 958     wxString GetExtension() const;
 959
 960     /**
 961         Returns flags that change the behaviour of loading or saving.
 962
 963         See the documentation for each handler class to see what flags are
 964         relevant for each handler.
 965     */
 966     int GetFlags() const;
 967
 968     /**
 969         Returns the name of the handler.
 970     */
 971     wxString GetName() const;
 972
 973     /**
 974         Returns the type of the handler.
 975     */
 976     int GetType() const;
 977
 978     /**
 979         Returns @true if this handler should be visible to the user.
 980     */
 981     virtual bool IsVisible() const;
 982
 983     //@{
 984     /**
 985         Loads content from a stream or file.
 986         Not all handlers will implement file loading.
 987     */
 988     bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream);
 989     bool LoadFile(wxRichTextBuffer* buffer, const wxString& filename);
 990     //@}
 991
 992     //@{
 993     /**
 994         Saves content to a stream or file.
 995         Not all handlers will implement file saving.
 996     */
 997     bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream);
 998     bool SaveFile(wxRichTextBuffer* buffer, const wxString& filename);
 999     //@}
1000
1001     /**
1002         Sets the encoding to use when saving a file.
1003         If empty, a suitable encoding is chosen.
1004     */
1005     void SetEncoding(const wxString& encoding);
1006
1007     /**
1008         Sets the default extension to recognise.
1009     */
1010     void SetExtension(const wxString& ext);
1011
1012     /**
1013         Sets flags that change the behaviour of loading or saving.
1014         See the documentation for each handler class to see what flags are relevant
1015         for each handler.
1016
1017         You call this function directly if you are using a file handler explicitly
1018         (without going through the text control or buffer LoadFile/SaveFile API).
1019         Or, you can call the control or buffer's SetHandlerFlags function to set
1020         the flags that will be used for subsequent load and save operations.
1021     */
1022     void SetFlags(int flags);
1023
1024     /**
1025         Sets the name of the handler.
1026     */
1027     void SetName(const wxString& name);
1028
1029     /**
1030         Sets the handler type.
1031     */
1032     void SetType(int type);
1033
1034     /**
1035         Sets whether the handler should be visible to the user (via the application's
1036         load and save dialogs).
1037     */
1038     virtual void SetVisible(bool visible);
1039
1040 protected:
1041     /**
1042         Override to load content from @a stream into @a buffer.
1043     */
1044     virtual bool DoLoadFile(wxRichTextBuffer* buffer,
1045                             wxInputStream& stream) = 0;
1046
1047     /**
1048         Override to save content to @a stream from @a buffer.
1049     */
1050     virtual bool DoSaveFile(wxRichTextBuffer* buffer,
1051                             wxOutputStream& stream) = 0;
1052 };
1053
1054
1055
1056 /**
1057     @class wxRichTextRange
1058
1059     This class stores beginning and end positions for a range of data.
1060
1061     @library{wxrichtext}
1062     @category{richtext}
1063 */
1064 class wxRichTextRange
1065 {
1066 public:
1067     //@{
1068     /**
1069         Constructors.
1070     */
1071     wxRichTextRange(long start, long end);
1072     wxRichTextRange(const wxRichTextRange& range);
1073     wxRichTextRange();
1074     //@}
1075
1076     /**
1077         Destructor.
1078     */
1079     ~wxRichTextRange();
1080
1081     /**
1082         Returns @true if the given position is within this range.
1083         Does not match if the range is empty.
1084     */
1085     bool Contains(long pos) const;
1086
1087     /**
1088         Converts the internal range, which uses the first and last character positions
1089         of the range, to the API-standard range, whose end is one past the last
1090         character in the range.
1091         In other words, one is added to the end position.
1092     */
1093     wxRichTextRange FromInternal() const;
1094
1095     /**
1096         Returns the end position.
1097     */
1098     long GetEnd() const;
1099
1100     /**
1101         Returns the length of the range.
1102     */
1103     long GetLength() const;
1104
1105     /**
1106         Returns the start of the range.
1107     */
1108     long GetStart() const;
1109
1110     /**
1111         Returns @true if this range is completely outside @e range.
1112     */
1113     bool IsOutside(const wxRichTextRange& range) const;
1114
1115     /**
1116         Returns @true if this range is completely within @e range.
1117     */
1118     bool IsWithin(const wxRichTextRange& range) const;
1119
1120     /**
1121         Limits this range to be within @e range.
1122     */
1123     bool LimitTo(const wxRichTextRange& range);
1124
1125     /**
1126         Sets the end of the range.
1127     */
1128     void SetEnd(long end);
1129
1130     /**
1131         Sets the range.
1132     */
1133     void SetRange(long start, long end);
1134
1135     /**
1136         Sets the start of the range.
1137     */
1138     void SetStart(long start);
1139
1140     /**
1141         Swaps the start and end.
1142     */
1143     void Swap();
1144
1145     /**
1146         Converts the API-standard range, whose end is one past the last character in
1147         the range, to the internal form, which uses the first and last character
1148         positions of the range.
1149         In other words, one is subtracted from the end position.
1150     */
1151     wxRichTextRange ToInternal() const;
1152
1153     /**
1154         Adds @a range to this range.
1155     */
1156     wxRichTextRange operator+(const wxRichTextRange& range) const;
1157
1158     /**
1159         Subtracts @a range from this range.
1160     */
1161     wxRichTextRange operator-(const wxRichTextRange& range) const;
1162
1163     /**
1164         Assigns @a range to this range.
1165     */
1166     void operator=(const wxRichTextRange& range);
1167
1168     /**
1169         Returns @true if @a range is the same as this range.
1170     */
1171     bool operator==(const wxRichTextRange& range) const;
1172 };
1173