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     wxRichTextRange AddParagraph(const wxString& text);
 183
 184     /**
 185         Returns @true if the buffer is currently collapsing commands into a single
 186         notional command.
 187     */
 188     virtual bool BatchingUndo() const;
 189
 190     /**
 191         Begins using alignment.
 192     */
 193     bool BeginAlignment(wxTextAttrAlignment alignment);
 194
 195     /**
 196         Begins collapsing undo/redo commands. Note that this may not work properly
 197         if combining commands that delete or insert content, changing ranges for
 198         subsequent actions.
 199
 200         @a cmdName should be the name of the combined command that will appear
 201         next to Undo and Redo in the edit menu.
 202     */
 203     virtual bool BeginBatchUndo(const wxString& cmdName);
 204
 205     /**
 206         Begin applying bold.
 207     */
 208     bool BeginBold();
 209
 210     /**
 211         Begins applying the named character style.
 212     */
 213     bool BeginCharacterStyle(const wxString& characterStyle);
 214
 215     /**
 216         Begins using this font.
 217     */
 218     bool BeginFont(const wxFont& font);
 219
 220     /**
 221         Begins using the given point size.
 222     */
 223     bool BeginFontSize(int pointSize);
 224
 225     /**
 226         Begins using italic.
 227     */
 228     bool BeginItalic();
 229
 230     /**
 231         Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent for
 232         the sub-indent. Both are expressed in tenths of a millimetre.
 233
 234         The sub-indent is an offset from the left of the paragraph, and is used for all
 235         but the first line in a paragraph. A positive value will cause the first line to appear
 236         to the left of the subsequent lines, and a negative value will cause the first line to be
 237         indented relative to the subsequent lines.
 238     */
 239     bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0);
 240
 241     /**
 242         Begins line spacing using the specified value. @e spacing is a multiple, where
 243         10 means single-spacing, 15 means 1.5 spacing, and 20 means double spacing.
 244
 245         The ::wxTextAttrLineSpacing enumeration values are defined for convenience.
 246     */
 247     bool BeginLineSpacing(int lineSpacing);
 248
 249     /**
 250         Begins using a specified list style.
 251         Optionally, you can also pass a level and a number.
 252     */
 253     bool BeginListStyle(const wxString& listStyle, int level = 1,
 254                         int number = 1);
 255
 256     /**
 257         Begins a numbered bullet.
 258
 259         This call will be needed for each item in the list, and the
 260         application should take care of incrementing the numbering.
 261
 262         @a bulletNumber is a number, usually starting with 1.
 263         @a leftIndent and @a leftSubIndent are values in tenths of a millimetre.
 264         @a bulletStyle is a bitlist of the following values:
 265
 266         wxRichTextBuffer uses indentation to render a bulleted item.
 267         The left indent is the distance between the margin and the bullet.
 268         The content of the paragraph, including the first line, starts
 269         at leftMargin + leftSubIndent.
 270         So the distance between the left edge of the bullet and the
 271         left of the actual paragraph is leftSubIndent.
 272     */
 273     bool BeginNumberedBullet(int bulletNumber, int leftIndent,
 274                              int leftSubIndent,
 275                              int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD);
 276
 277     /**
 278         Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing
 279         in tenths of a millimetre.
 280     */
 281     bool BeginParagraphSpacing(int before, int after);
 282
 283     /**
 284         Begins applying the named paragraph style.
 285     */
 286     bool BeginParagraphStyle(const wxString& paragraphStyle);
 287
 288     /**
 289         Begins a right indent, specified in tenths of a millimetre.
 290     */
 291     bool BeginRightIndent(int rightIndent);
 292
 293     /**
 294         Begins applying a standard bullet, using one of the standard bullet names
 295         (currently @c standard/circle or @c standard/square.
 296
 297         See BeginNumberedBullet() for an explanation of how indentation is used to
 298         render the bulleted paragraph.
 299     */
 300     bool BeginStandardBullet(const wxString& bulletName,
 301                              int leftIndent,
 302                              int leftSubIndent,
 303                              int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_STANDARD);
 304
 305     /**
 306         Begins using a specified style.
 307     */
 308     virtual bool BeginStyle(const wxTextAttr& style);
 309
 310     /**
 311         Begins suppressing undo/redo commands. The way undo is suppressed may be
 312         implemented differently by each command.
 313         If not dealt with by a command implementation, then it will be implemented
 314         automatically by not storing the command in the undo history when the
 315         action is submitted to the command processor.
 316     */
 317     virtual bool BeginSuppressUndo();
 318
 319     /**
 320         Begins applying a symbol bullet, using a character from the current font.
 321
 322         See BeginNumberedBullet() for an explanation of how indentation is used
 323         to render the bulleted paragraph.
 324     */
 325     bool BeginSymbolBullet(wxChar symbol, int leftIndent,
 326                            int leftSubIndent,
 327                            int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL);
 328
 329     /**
 330         Begins using the specified text foreground colour.
 331     */
 332     bool BeginTextColour(const wxColour& colour);
 333
 334     /**
 335         Begins applying wxTEXT_ATTR_URL to the content.
 336
 337         Pass a URL and optionally, a character style to apply, since it is common
 338         to mark a URL with a familiar style such as blue text with underlining.
 339     */
 340     bool BeginURL(const wxString& url,
 341                   const wxString& characterStyle = wxEmptyString);
 342
 343     /**
 344         Begins using underline.
 345     */
 346     bool BeginUnderline();
 347
 348     /**
 349         Returns @true if content can be pasted from the clipboard.
 350     */
 351     virtual bool CanPasteFromClipboard() const;
 352
 353     /**
 354         Cleans up the file handlers.
 355     */
 356     static void CleanUpHandlers();
 357
 358     /**
 359         Clears the buffer.
 360     */
 361     virtual void Clear();
 362
 363     //@{
 364     /**
 365         Clears the list style from the given range, clearing list-related attributes
 366         and applying any named paragraph style associated with each paragraph.
 367
 368         @a flags is a bit list of the following:
 369         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 370
 371         @see SetListStyle(), PromoteList(), NumberList()
 372     */
 373     bool ClearListStyle(const wxRichTextRange& range,
 374                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 375     bool ClearListStyle(const wxRichTextRange& range,
 376                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 377     //@}
 378
 379     /**
 380         Clears the style stack.
 381     */
 382     virtual void ClearStyleStack();
 383
 384     /**
 385         Clones the object.
 386     */
 387     virtual wxRichTextObject* Clone() const;
 388
 389     /**
 390         Copies the given buffer.
 391     */
 392     void Copy(const wxRichTextBuffer& obj);
 393
 394     /**
 395         Copy the given range to the clipboard.
 396     */
 397     virtual bool CopyToClipboard(const wxRichTextRange& range);
 398
 399     /**
 400         Submits a command to delete the given range.
 401     */
 402     bool DeleteRangeWithUndo(const wxRichTextRange& range,
 403                              wxRichTextCtrl* ctrl);
 404
 405     //@{
 406     /**
 407         Dumps the contents of the buffer for debugging purposes.
 408     */
 409     void Dump();
 410     void Dump(wxTextOutputStream& stream);
 411     //@}
 412
 413     /**
 414         Ends alignment.
 415     */
 416     bool EndAlignment();
 417
 418     /**
 419         Ends all styles that have been started with a Begin... command.
 420     */
 421     virtual bool EndAllStyles();
 422
 423     /**
 424         Ends collapsing undo/redo commands, and submits the combined command.
 425     */
 426     virtual bool EndBatchUndo();
 427
 428     /**
 429         Ends using bold.
 430     */
 431     bool EndBold();
 432
 433     /**
 434         Ends using the named character style.
 435     */
 436     bool EndCharacterStyle();
 437
 438     /**
 439         Ends using a font.
 440     */
 441     bool EndFont();
 442
 443     /**
 444         Ends using a point size.
 445     */
 446     bool EndFontSize();
 447
 448     /**
 449         Ends using italic.
 450     */
 451     bool EndItalic();
 452
 453     /**
 454         Ends using a left indent.
 455     */
 456     bool EndLeftIndent();
 457
 458     /**
 459         Ends using a line spacing.
 460     */
 461     bool EndLineSpacing();
 462
 463     /**
 464         Ends using a specified list style.
 465     */
 466     bool EndListStyle();
 467
 468     /**
 469         Ends a numbered bullet.
 470     */
 471     bool EndNumberedBullet();
 472
 473     /**
 474         Ends paragraph spacing.
 475     */
 476     bool EndParagraphSpacing();
 477
 478     /**
 479         Ends applying a named character style.
 480     */
 481     bool EndParagraphStyle();
 482
 483     /**
 484         Ends using a right indent.
 485     */
 486     bool EndRightIndent();
 487
 488     /**
 489         Ends using a standard bullet.
 490     */
 491     bool EndStandardBullet();
 492
 493     /**
 494         Ends the current style.
 495     */
 496     virtual bool EndStyle();
 497
 498     /**
 499         Ends suppressing undo/redo commands.
 500     */
 501     virtual bool EndSuppressUndo();
 502
 503     /**
 504         Ends using a symbol bullet.
 505     */
 506     bool EndSymbolBullet();
 507
 508     /**
 509         Ends using a text foreground colour.
 510     */
 511     bool EndTextColour();
 512
 513     /**
 514         Ends applying a URL.
 515     */
 516     bool EndURL();
 517
 518     /**
 519         Ends using underline.
 520     */
 521     bool EndUnderline();
 522
 523     /**
 524         Finds a handler by type.
 525     */
 526     wxRichTextFileHandler* FindHandler(int imageType);
 527
 528     /**
 529         Finds a handler by extension and type.
 530     */
 531     wxRichTextFileHandler* FindHandler(const wxString& extension,
 532                                        int 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     wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename,
 543                                                      int imageType);
 544
 545     /**
 546         Gets the basic (overall) style.
 547
 548         This is the style of the whole buffer before further styles are applied,
 549         unlike the default style, which only affects the style currently being
 550         applied (for example, setting the default style to bold will cause
 551         subsequently inserted text to be bold).
 552     */
 553     const wxTextAttr GetBasicStyle() const;
 554
 555     /**
 556         Gets the collapsed command.
 557     */
 558     virtual wxRichTextCommand* GetBatchedCommand() const;
 559
 560     /**
 561         Gets the command processor.
 562         A text buffer always creates its own command processor when it is initialized.
 563     */
 564     wxCommandProcessor* GetCommandProcessor() const;
 565
 566     /**
 567         Returns the current default style, affecting the style currently being applied
 568         (for example, setting the default style to bold will cause subsequently
 569         inserted text to be bold).
 570     */
 571     const wxTextAttr GetDefaultStyle() const;
 572
 573     /**
 574         Gets a wildcard incorporating all visible handlers.
 575         If @a types is present, it will be filled with the file type corresponding
 576         to each filter. This can be used to determine the type to pass to LoadFile()
 577         given a selected filter.
 578     */
 579     wxString GetExtWildcard(bool combine = false, bool save = false,
 580                             wxArrayInt* types = NULL);
 581
 582     /**
 583         Returns the list of file handlers.
 584     */
 585     wxList GetHandlers();
 586
 587     /**
 588         Returns the object to be used to render certain aspects of the content, such as
 589         bullets.
 590     */
 591     static wxRichTextRenderer* GetRenderer();
 592
 593     /**
 594         Gets the attributes at the given position.
 595
 596         This function gets the combined style - that is, the style you see on the
 597         screen as a result of combining base style, paragraph style and character
 598         style attributes. To get the character or paragraph style alone,
 599         use GetUncombinedStyle().
 600     */
 601     virtual bool GetStyle(long position, wxTextAttr& style);
 602
 603     /**
 604         This function gets a style representing the common, combined attributes in the
 605         given range.
 606         Attributes which have different values within the specified range will not be
 607         included the style flags.
 608
 609         The function is used to get the attributes to display in the formatting dialog:
 610         the user can edit the attributes common to the selection, and optionally specify the
 611         values of further attributes to be applied uniformly.
 612
 613         To apply the edited attributes, you can use SetStyle() specifying
 614         the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that
 615         are different from the @e combined attributes within the range.
 616         So, the user edits the effective, displayed attributes for the range,
 617         but his choice won't be applied unnecessarily to content. As an example,
 618         say the style for a paragraph specifies bold, but the paragraph text doesn't
 619         specify a weight.
 620         The combined style is bold, and this is what the user will see on-screen and
 621         in the formatting dialog. The user now specifies red text, in addition to bold.
 622         When applying with SetStyle(), the content font weight attributes won't be
 623         changed to bold because this is already specified by the paragraph.
 624         However the text colour attributes @e will be changed to show red.
 625     */
 626     bool GetStyleForRange(const wxRichTextRange& range,
 627                           wxTextAttr& style);
 628
 629     /**
 630         Returns the current style sheet associated with the buffer, if any.
 631     */
 632     virtual wxRichTextStyleSheet* GetStyleSheet() const;
 633
 634     /**
 635         Get the size of the style stack, for example to check correct nesting.
 636     */
 637     virtual size_t GetStyleStackSize() const;
 638
 639     /**
 640         Gets the attributes at the given position.
 641
 642         This function gets the @e uncombined style - that is, the attributes associated
 643         with the paragraph or character content, and not necessarily the combined
 644         attributes you see on the screen. To get the combined attributes, use GetStyle().
 645         If you specify (any) paragraph attribute in @e style's flags, this function
 646         will fetch the paragraph attributes.
 647         Otherwise, it will return the character attributes.
 648     */
 649     virtual bool GetUncombinedStyle(long position, wxTextAttr& style);
 650
 651     /**
 652         Finds the text position for the given position, putting the position in
 653         @a textPosition if one is found.
 654         @a pt is in logical units (a zero y position is at the beginning of the buffer).
 655
 656         @return One of the ::wxRichTextHitTestFlags values.
 657     */
 658     virtual int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition);
 659
 660     /**
 661         Initialisation.
 662     */
 663     void Init();
 664
 665     /**
 666         Initialises the standard handlers.
 667         Currently, only the plain text loading/saving handler is initialised by default.
 668     */
 669     static void InitStandardHandlers();
 670
 671     /**
 672         Inserts a handler at the front of the list.
 673     */
 674     static void InsertHandler(wxRichTextFileHandler* handler);
 675
 676     /**
 677         Submits a command to insert the given image.
 678     */
 679     bool InsertImageWithUndo(long pos,
 680                              const wxRichTextImageBlock& imageBlock,
 681                              wxRichTextCtrl* ctrl);
 682
 683     /**
 684         Submits a command to insert a newline.
 685     */
 686     bool InsertNewlineWithUndo(long pos, wxRichTextCtrl* ctrl);
 687
 688     /**
 689         Submits a command to insert the given text.
 690     */
 691     bool InsertTextWithUndo(long pos, const wxString& text,
 692                             wxRichTextCtrl* ctrl);
 693
 694     /**
 695         Returns @true if the buffer has been modified.
 696     */
 697     bool IsModified() const;
 698
 699     /**
 700         Loads content from a stream.
 701     */
 702     bool LoadFile(wxInputStream& stream,
 703                   int type = wxRICHTEXT_TYPE_ANY);
 704
 705     /**
 706         Loads content from a file.
 707     */
 708     bool LoadFile(const wxString& filename,
 709                   int type = wxRICHTEXT_TYPE_ANY);
 710
 711     /**
 712         Marks the buffer as modified or unmodified.
 713     */
 714     void Modify(bool modify = true);
 715
 716     //@{
 717     /**
 718         Numbers the paragraphs in the given range.
 719
 720         Pass flags to determine how the attributes are set.
 721         Either the style definition or the name of the style definition (in the current
 722         sheet) can be passed.
 723
 724         @a flags is a bit list of the following:
 725         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 726         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 727           @a startFrom, otherwise existing attributes are used.
 728         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 729           as the level for all paragraphs, otherwise the current indentation will be used.
 730
 731         @see SetListStyle(), PromoteList(), ClearListStyle()
 732     */
 733     bool NumberList(const wxRichTextRange& range,
 734                     const wxRichTextListStyleDefinition* style,
 735                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 736                     int startFrom = -1,
 737                     int listLevel = -1);
 738     bool Number(const wxRichTextRange& range,
 739                 const wxString& styleName,
 740                 int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 741                 int startFrom = -1,
 742                 int listLevel = -1);
 743     //@}
 744
 745     /**
 746         Pastes the clipboard content to the buffer at the given position.
 747     */
 748     virtual bool PasteFromClipboard(long position);
 749
 750     //@{
 751     /**
 752         Promotes or demotes the paragraphs in the given range.
 753
 754         A positive @a promoteBy produces a smaller indent, and a negative number
 755         produces a larger indent. Pass flags to determine how the attributes are set.
 756         Either the style definition or the name of the style definition (in the current
 757         sheet) can be passed.
 758
 759         @a flags is a bit list of the following:
 760         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 761         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 762           @a startFrom, otherwise existing attributes are used.
 763         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 764           as the level for all paragraphs, otherwise the current indentation will be used.
 765
 766         @see SetListStyle(), SetListStyle(), ClearListStyle()
 767     */
 768     bool PromoteList(int promoteBy, const wxRichTextRange& range,
 769                      const wxRichTextListStyleDefinition* style,
 770                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 771                      int listLevel = -1);
 772     bool PromoteList(int promoteBy, const wxRichTextRange& range,
 773                      const wxString& styleName,
 774                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 775                      int listLevel = -1);
 776     //@}
 777
 778     /**
 779         Removes an event handler from the buffer's list of handlers, deleting the
 780         object if @a deleteHandler is @true.
 781     */
 782     bool RemoveEventHandler(wxEvtHandler* handler,
 783                             bool deleteHandler = false);
 784
 785     /**
 786         Removes a handler.
 787     */
 788     static bool RemoveHandler(const wxString& name);
 789
 790     /**
 791         Clears the buffer, adds a new blank paragraph, and clears the command history.
 792     */
 793     virtual void ResetAndClearCommands();
 794
 795     /**
 796         Saves content to a stream.
 797     */
 798     bool SaveFile(wxOutputStream& stream,
 799                   int type = wxRICHTEXT_TYPE_ANY);
 800
 801     /**
 802         Saves content to a file.
 803     */
 804     bool SaveFile(const wxString& filename,
 805                   int type = wxRICHTEXT_TYPE_ANY);
 806
 807     /**
 808         Sets the basic (overall) style. This is the style of the whole
 809         buffer before further styles are applied, unlike the default style, which
 810         only affects the style currently being applied (for example, setting the default
 811         style to bold will cause subsequently inserted text to be bold).
 812     */
 813     virtual void SetBasicStyle(const wxTextAttr& style);
 814
 815     /**
 816         Sets the default style, affecting the style currently being applied
 817         (for example, setting the default style to bold will cause subsequently
 818         inserted text to be bold).
 819
 820         This is not cumulative - setting the default style will replace the previous
 821         default style.
 822     */
 823     void SetDefaultStyle(const wxTextAttr& style);
 824
 825     //@{
 826     /**
 827         Sets the list attributes for the given range, passing flags to determine how
 828         the attributes are set.
 829         Either the style definition or the name of the style definition (in the current
 830         sheet) can be passed.
 831
 832         @a flags is a bit list of the following:
 833         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 834         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 835           @a startFrom, otherwise existing attributes are used.
 836         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 837           as the level for all paragraphs, otherwise the current indentation will be used.
 838
 839         @see NumberList(), PromoteList(), ClearListStyle().
 840     */
 841     bool SetListStyle(const wxRichTextRange& range,
 842                       const wxRichTextListStyleDefinition* style,
 843                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 844                       int startFrom = -1,
 845                       int listLevel = -1);
 846     bool SetListStyle(const wxRichTextRange& range,
 847                       const wxString& styleName,
 848                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 849                       int startFrom = -1,
 850                       int listLevel = -1);
 851     //@}
 852
 853     /**
 854         Sets @a renderer as the object to be used to render certain aspects of the
 855         content, such as bullets.
 856
 857         You can override default rendering by deriving a new class from
 858         wxRichTextRenderer or wxRichTextStdRenderer, overriding one or more
 859         virtual functions, and setting an instance of the class using this function.
 860     */
 861     static void SetRenderer(wxRichTextRenderer* renderer);
 862
 863     /**
 864         Sets the attributes for the given range. Pass flags to determine how the
 865         attributes are set.
 866
 867         The end point of range is specified as the last character position of the span
 868         of text. So, for example, to set the style for a character at position 5,
 869         use the range (5,5).
 870         This differs from the wxRichTextCtrl API, where you would specify (5,6).
 871
 872         @a flags may contain a bit list of the following values:
 873         - wxRICHTEXT_SETSTYLE_NONE: no style flag.
 874         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
 875           undoable.
 876         - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
 877           if the combined style at this point is already the style in question.
 878         - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
 879           applied to paragraphs, and not the content.
 880           This allows content styling to be preserved independently from that
 881           of e.g. a named paragraph style.
 882         - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
 883           applied to characters, and not the paragraph.
 884           This allows content styling to be preserved independently from that
 885           of e.g. a named paragraph style.
 886         - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
 887           the new style.
 888         - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style.
 889           Only the style flags are used in this operation.
 890     */
 891     virtual bool SetStyle(const wxRichTextRange& range, const wxTextAttr& style,
 892                           int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 893
 894     /**
 895         Sets the current style sheet, if any.
 896
 897         This will allow the application to use named character and paragraph
 898         styles found in the style sheet.
 899     */
 900     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 901
 902     /**
 903         Submit an action immediately, or delay it according to whether collapsing is on.
 904     */
 905     virtual bool SubmitAction(wxRichTextAction* action);
 906
 907     /**
 908         Returns @true if undo suppression is currently on.
 909     */
 910     virtual bool SuppressingUndo() const;
 911 };
 912
 913
 914
 915 /**
 916     @class wxRichTextFileHandler
 917
 918     This is the base class for file handlers, for loading and/or saving content
 919     associated with a wxRichTextBuffer.
 920
 921     @library{wxrichtext}
 922     @category{richtext}
 923 */
 924 class wxRichTextFileHandler : public wxObject
 925 {
 926 public:
 927     /**
 928         Constructor.
 929     */
 930     wxRichTextFileHandler(const wxString& name = wxEmptyString,
 931                           const wxString& ext = wxEmptyString,
 932                           int type = 0);
 933
 934     /**
 935         Override this function and return @true if this handler can we handle
 936         @a filename.
 937
 938         By default, this function checks the extension.
 939     */
 940     virtual bool CanHandle(const wxString& filename) const;
 941
 942     /**
 943         Override and return @true if this handler can load content.
 944     */
 945     virtual bool CanLoad() const;
 946
 947     /**
 948         Override and return @true if this handler can save content.
 949     */
 950     virtual bool CanSave() const;
 951
 952     /**
 953         Returns the encoding associated with the handler (if any).
 954     */
 955     const wxString GetEncoding() const;
 956
 957     /**
 958         Returns the extension associated with the handler.
 959     */
 960     wxString GetExtension() const;
 961
 962     /**
 963         Returns flags that change the behaviour of loading or saving.
 964
 965         See the documentation for each handler class to see what flags are
 966         relevant for each handler.
 967     */
 968     int GetFlags() const;
 969
 970     /**
 971         Returns the name of the handler.
 972     */
 973     wxString GetName() const;
 974
 975     /**
 976         Returns the type of the handler.
 977     */
 978     int GetType() const;
 979
 980     /**
 981         Returns @true if this handler should be visible to the user.
 982     */
 983     virtual bool IsVisible() const;
 984
 985     //@{
 986     /**
 987         Loads content from a stream or file.
 988         Not all handlers will implement file loading.
 989     */
 990     bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream);
 991     bool LoadFile(wxRichTextBuffer* buffer, const wxString& filename);
 992     //@}
 993
 994     //@{
 995     /**
 996         Saves content to a stream or file.
 997         Not all handlers will implement file saving.
 998     */
 999     bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream);
1000     bool SaveFile(wxRichTextBuffer* buffer, const wxString& filename);
1001     //@}
1002
1003     /**
1004         Sets the encoding to use when saving a file.
1005         If empty, a suitable encoding is chosen.
1006     */
1007     void SetEncoding(const wxString& encoding);
1008
1009     /**
1010         Sets the default extension to recognise.
1011     */
1012     void SetExtension(const wxString& ext);
1013
1014     /**
1015         Sets flags that change the behaviour of loading or saving.
1016         See the documentation for each handler class to see what flags are relevant
1017         for each handler.
1018
1019         You call this function directly if you are using a file handler explicitly
1020         (without going through the text control or buffer LoadFile/SaveFile API).
1021         Or, you can call the control or buffer's SetHandlerFlags function to set
1022         the flags that will be used for subsequent load and save operations.
1023     */
1024     void SetFlags(int flags);
1025
1026     /**
1027         Sets the name of the handler.
1028     */
1029     void SetName(const wxString& name);
1030
1031     /**
1032         Sets the handler type.
1033     */
1034     void SetType(int type);
1035
1036     /**
1037         Sets whether the handler should be visible to the user (via the application's
1038         load and save dialogs).
1039     */
1040     virtual void SetVisible(bool visible);
1041
1042 protected:
1043     /**
1044         Override to load content from @a stream into @a buffer.
1045     */
1046     bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream);
1047
1048     /**
1049         Override to save content to @a stream from @a buffer.
1050     */
1051     bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream);
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