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