interface/wx/richtext/richtextbuffer.h

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