interface/wx/richtext/richtextbuffer.h

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