interface/richtext/richtextbuffer.h

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