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