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 licence
   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         Clears the list style from the given range, clearing list-related attributes
 366         and applying any named paragraph style associated with each paragraph.
 367
 368         @a flags is a bit list of the following:
 369         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 370
 371         @see SetListStyle(), PromoteList(), NumberList()
 372     */
 373     virtual bool ClearListStyle(const wxRichTextRange& range,
 374                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 375
 376     /**
 377         Clears the style stack.
 378     */
 379     virtual void ClearStyleStack();
 380
 381     /**
 382         Clones the object.
 383     */
 384     virtual wxRichTextObject* Clone() const;
 385
 386     /**
 387         Copies the given buffer.
 388     */
 389     void Copy(const wxRichTextBuffer& obj);
 390
 391     /**
 392         Copy the given range to the clipboard.
 393     */
 394     virtual bool CopyToClipboard(const wxRichTextRange& range);
 395
 396     /**
 397         Submits a command to delete the given range.
 398     */
 399     bool DeleteRangeWithUndo(const wxRichTextRange& range,
 400                              wxRichTextCtrl* ctrl);
 401
 402     //@{
 403     /**
 404         Dumps the contents of the buffer for debugging purposes.
 405     */
 406     void Dump();
 407     void Dump(wxTextOutputStream& stream);
 408     //@}
 409
 410     /**
 411         Ends alignment.
 412     */
 413     bool EndAlignment();
 414
 415     /**
 416         Ends all styles that have been started with a Begin... command.
 417     */
 418     virtual bool EndAllStyles();
 419
 420     /**
 421         Ends collapsing undo/redo commands, and submits the combined command.
 422     */
 423     virtual bool EndBatchUndo();
 424
 425     /**
 426         Ends using bold.
 427     */
 428     bool EndBold();
 429
 430     /**
 431         Ends using the named character style.
 432     */
 433     bool EndCharacterStyle();
 434
 435     /**
 436         Ends using a font.
 437     */
 438     bool EndFont();
 439
 440     /**
 441         Ends using a point size.
 442     */
 443     bool EndFontSize();
 444
 445     /**
 446         Ends using italic.
 447     */
 448     bool EndItalic();
 449
 450     /**
 451         Ends using a left indent.
 452     */
 453     bool EndLeftIndent();
 454
 455     /**
 456         Ends using a line spacing.
 457     */
 458     bool EndLineSpacing();
 459
 460     /**
 461         Ends using a specified list style.
 462     */
 463     bool EndListStyle();
 464
 465     /**
 466         Ends a numbered bullet.
 467     */
 468     bool EndNumberedBullet();
 469
 470     /**
 471         Ends paragraph spacing.
 472     */
 473     bool EndParagraphSpacing();
 474
 475     /**
 476         Ends applying a named character style.
 477     */
 478     bool EndParagraphStyle();
 479
 480     /**
 481         Ends using a right indent.
 482     */
 483     bool EndRightIndent();
 484
 485     /**
 486         Ends using a standard bullet.
 487     */
 488     bool EndStandardBullet();
 489
 490     /**
 491         Ends the current style.
 492     */
 493     virtual bool EndStyle();
 494
 495     /**
 496         Ends suppressing undo/redo commands.
 497     */
 498     virtual bool EndSuppressUndo();
 499
 500     /**
 501         Ends using a symbol bullet.
 502     */
 503     bool EndSymbolBullet();
 504
 505     /**
 506         Ends using a text foreground colour.
 507     */
 508     bool EndTextColour();
 509
 510     /**
 511         Ends applying a URL.
 512     */
 513     bool EndURL();
 514
 515     /**
 516         Ends using underline.
 517     */
 518     bool EndUnderline();
 519
 520     /**
 521         Finds a handler by type.
 522     */
 523     static wxRichTextFileHandler* FindHandler(wxRichTextFileType imageType);
 524
 525     /**
 526         Finds a handler by extension and type.
 527     */
 528     static wxRichTextFileHandler* FindHandler(const wxString& extension, wxRichTextFileType imageType);
 529
 530     /**
 531         Finds a handler by name.
 532     */
 533     static wxRichTextFileHandler* FindHandler(const wxString& name);
 534
 535     /**
 536         Finds a handler by filename or, if supplied, type.
 537     */
 538     static wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename, wxRichTextFileType imageType);
 539
 540     /**
 541         Gets the basic (overall) style.
 542
 543         This is the style of the whole buffer before further styles are applied,
 544         unlike the default style, which only affects the style currently being
 545         applied (for example, setting the default style to bold will cause
 546         subsequently inserted text to be bold).
 547     */
 548     virtual const wxTextAttr& GetBasicStyle() const;
 549
 550     /**
 551         Gets the collapsed command.
 552     */
 553     virtual wxRichTextCommand* GetBatchedCommand() const;
 554
 555     /**
 556         Gets the command processor.
 557         A text buffer always creates its own command processor when it is initialized.
 558     */
 559     wxCommandProcessor* GetCommandProcessor() const;
 560
 561     /**
 562         Returns the current default style, affecting the style currently being applied
 563         (for example, setting the default style to bold will cause subsequently
 564         inserted text to be bold).
 565     */
 566     virtual const wxTextAttr& GetDefaultStyle() const;
 567
 568     /**
 569         Gets a wildcard incorporating all visible handlers.
 570         If @a types is present, it will be filled with the file type corresponding
 571         to each filter. This can be used to determine the type to pass to LoadFile()
 572         given a selected filter.
 573     */
 574     static wxString GetExtWildcard(bool combine = false, bool save = false,
 575                                    wxArrayInt* types = NULL);
 576
 577     /**
 578         Returns the list of file handlers.
 579     */
 580     static wxList& GetHandlers();
 581
 582     /**
 583         Returns the object to be used to render certain aspects of the content, such as
 584         bullets.
 585     */
 586     static wxRichTextRenderer* GetRenderer();
 587
 588     /**
 589         Gets the attributes at the given position.
 590
 591         This function gets the combined style - that is, the style you see on the
 592         screen as a result of combining base style, paragraph style and character
 593         style attributes. To get the character or paragraph style alone,
 594         use GetUncombinedStyle().
 595     */
 596     virtual bool GetStyle(long position, wxTextAttr& style);
 597
 598     /**
 599         This function gets a style representing the common, combined attributes in the
 600         given range.
 601         Attributes which have different values within the specified range will not be
 602         included the style flags.
 603
 604         The function is used to get the attributes to display in the formatting dialog:
 605         the user can edit the attributes common to the selection, and optionally specify the
 606         values of further attributes to be applied uniformly.
 607
 608         To apply the edited attributes, you can use SetStyle() specifying
 609         the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that
 610         are different from the @e combined attributes within the range.
 611         So, the user edits the effective, displayed attributes for the range,
 612         but his choice won't be applied unnecessarily to content. As an example,
 613         say the style for a paragraph specifies bold, but the paragraph text doesn't
 614         specify a weight.
 615         The combined style is bold, and this is what the user will see on-screen and
 616         in the formatting dialog. The user now specifies red text, in addition to bold.
 617         When applying with SetStyle(), the content font weight attributes won't be
 618         changed to bold because this is already specified by the paragraph.
 619         However the text colour attributes @e will be changed to show red.
 620     */
 621     virtual bool GetStyleForRange(const wxRichTextRange& range,
 622                                   wxTextAttr& style);
 623
 624     /**
 625         Returns the current style sheet associated with the buffer, if any.
 626     */
 627     virtual wxRichTextStyleSheet* GetStyleSheet() const;
 628
 629     /**
 630         Get the size of the style stack, for example to check correct nesting.
 631     */
 632     virtual size_t GetStyleStackSize() const;
 633
 634     /**
 635         Gets the attributes at the given position.
 636
 637         This function gets the @e uncombined style - that is, the attributes associated
 638         with the paragraph or character content, and not necessarily the combined
 639         attributes you see on the screen. To get the combined attributes, use GetStyle().
 640         If you specify (any) paragraph attribute in @e style's flags, this function
 641         will fetch the paragraph attributes.
 642         Otherwise, it will return the character attributes.
 643     */
 644     virtual bool GetUncombinedStyle(long position, wxTextAttr& style);
 645
 646     /**
 647         Finds the text position for the given position, putting the position in
 648         @a textPosition if one is found.
 649         @a pt is in logical units (a zero y position is at the beginning of the buffer).
 650
 651         @return One of the ::wxRichTextHitTestFlags values.
 652     */
 653     virtual int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition);
 654
 655     /**
 656         Initialisation.
 657     */
 658     void Init();
 659
 660     /**
 661         Initialises the standard handlers.
 662         Currently, only the plain text loading/saving handler is initialised by default.
 663     */
 664     static void InitStandardHandlers();
 665
 666     /**
 667         Inserts a handler at the front of the list.
 668     */
 669     static void InsertHandler(wxRichTextFileHandler* handler);
 670
 671     /**
 672         Submits a command to insert the given image.
 673     */
 674     bool InsertImageWithUndo(long pos, const wxRichTextImageBlock& imageBlock,
 675                              wxRichTextCtrl* ctrl, int flags = 0);
 676
 677     /**
 678         Submits a command to insert a newline.
 679     */
 680     bool InsertNewlineWithUndo(long pos, wxRichTextCtrl* ctrl, int flags = 0);
 681
 682     /**
 683         Submits a command to insert the given text.
 684     */
 685     bool InsertTextWithUndo(long pos, const wxString& text,
 686                             wxRichTextCtrl* ctrl, int flags = 0);
 687
 688     /**
 689         Returns @true if the buffer has been modified.
 690     */
 691     bool IsModified() const;
 692
 693     /**
 694         Loads content from a stream.
 695     */
 696     virtual bool LoadFile(wxInputStream& stream,
 697                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 698
 699     /**
 700         Loads content from a file.
 701     */
 702     virtual bool LoadFile(const wxString& filename,
 703                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 704
 705     /**
 706         Marks the buffer as modified or unmodified.
 707     */
 708     void Modify(bool modify = true);
 709
 710     //@{
 711     /**
 712         Numbers the paragraphs in the given range.
 713
 714         Pass flags to determine how the attributes are set.
 715         Either the style definition or the name of the style definition (in the current
 716         sheet) can be passed.
 717
 718         @a flags is a bit list of the following:
 719         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 720         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 721           @a startFrom, otherwise existing attributes are used.
 722         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 723           as the level for all paragraphs, otherwise the current indentation will be used.
 724
 725         @see SetListStyle(), PromoteList(), ClearListStyle()
 726     */
 727     bool NumberList(const wxRichTextRange& range,
 728                     const wxRichTextListStyleDefinition* style,
 729                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 730                     int startFrom = -1,
 731                     int listLevel = -1);
 732     bool Number(const wxRichTextRange& range,
 733                 const wxString& styleName,
 734                 int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 735                 int startFrom = -1,
 736                 int listLevel = -1);
 737     //@}
 738
 739     /**
 740         Pastes the clipboard content to the buffer at the given position.
 741     */
 742     virtual bool PasteFromClipboard(long position);
 743
 744     //@{
 745     /**
 746         Promotes or demotes the paragraphs in the given range.
 747
 748         A positive @a promoteBy produces a smaller indent, and a negative number
 749         produces a larger indent. Pass flags to determine how the attributes are set.
 750         Either the style definition or the name of the style definition (in the current
 751         sheet) can be passed.
 752
 753         @a flags is a bit list of the following:
 754         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 755         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 756           @a startFrom, otherwise existing attributes are used.
 757         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 758           as the level for all paragraphs, otherwise the current indentation will be used.
 759
 760         @see SetListStyle(), SetListStyle(), ClearListStyle()
 761     */
 762     bool PromoteList(int promoteBy, const wxRichTextRange& range,
 763                      const wxRichTextListStyleDefinition* style,
 764                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 765                      int listLevel = -1);
 766     bool PromoteList(int promoteBy, const wxRichTextRange& range,
 767                      const wxString& styleName,
 768                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 769                      int listLevel = -1);
 770     //@}
 771
 772     /**
 773         Removes an event handler from the buffer's list of handlers, deleting the
 774         object if @a deleteHandler is @true.
 775     */
 776     bool RemoveEventHandler(wxEvtHandler* handler,
 777                             bool deleteHandler = false);
 778
 779     /**
 780         Removes a handler.
 781     */
 782     static bool RemoveHandler(const wxString& name);
 783
 784     /**
 785         Clears the buffer, adds a new blank paragraph, and clears the command history.
 786     */
 787     virtual void ResetAndClearCommands();
 788
 789     /**
 790         Saves content to a stream.
 791     */
 792     virtual bool SaveFile(wxOutputStream& stream,
 793                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 794
 795     /**
 796         Saves content to a file.
 797     */
 798     virtual bool SaveFile(const wxString& filename,
 799                           wxRichTextFileType type = wxRICHTEXT_TYPE_ANY);
 800
 801     /**
 802         Sets the basic (overall) style. This is the style of the whole
 803         buffer before further styles are applied, unlike the default style, which
 804         only affects the style currently being applied (for example, setting the default
 805         style to bold will cause subsequently inserted text to be bold).
 806     */
 807     virtual void SetBasicStyle(const wxTextAttr& style);
 808
 809     /**
 810         Sets the default style, affecting the style currently being applied
 811         (for example, setting the default style to bold will cause subsequently
 812         inserted text to be bold).
 813
 814         This is not cumulative - setting the default style will replace the previous
 815         default style.
 816     */
 817     virtual bool SetDefaultStyle(const wxTextAttr& style);
 818
 819     //@{
 820     /**
 821         Sets the list attributes for the given range, passing flags to determine how
 822         the attributes are set.
 823         Either the style definition or the name of the style definition (in the current
 824         sheet) can be passed.
 825
 826         @a flags is a bit list of the following:
 827         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 828         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
 829           @a startFrom, otherwise existing attributes are used.
 830         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 831           as the level for all paragraphs, otherwise the current indentation will be used.
 832
 833         @see NumberList(), PromoteList(), ClearListStyle().
 834     */
 835     bool SetListStyle(const wxRichTextRange& range,
 836                       const wxRichTextListStyleDefinition* style,
 837                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 838                       int startFrom = -1,
 839                       int listLevel = -1);
 840     bool SetListStyle(const wxRichTextRange& range,
 841                       const wxString& styleName,
 842                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 843                       int startFrom = -1,
 844                       int listLevel = -1);
 845     //@}
 846
 847     /**
 848         Sets @a renderer as the object to be used to render certain aspects of the
 849         content, such as bullets.
 850
 851         You can override default rendering by deriving a new class from
 852         wxRichTextRenderer or wxRichTextStdRenderer, overriding one or more
 853         virtual functions, and setting an instance of the class using this function.
 854     */
 855     static void SetRenderer(wxRichTextRenderer* renderer);
 856
 857     /**
 858         Sets the attributes for the given range. Pass flags to determine how the
 859         attributes are set.
 860
 861         The end point of range is specified as the last character position of the span
 862         of text. So, for example, to set the style for a character at position 5,
 863         use the range (5,5).
 864         This differs from the wxRichTextCtrl API, where you would specify (5,6).
 865
 866         @a flags may contain a bit list of the following values:
 867         - wxRICHTEXT_SETSTYLE_NONE: no style flag.
 868         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
 869           undoable.
 870         - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
 871           if the combined style at this point is already the style in question.
 872         - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
 873           applied to paragraphs, and not the content.
 874           This allows content styling to be preserved independently from that
 875           of e.g. a named paragraph style.
 876         - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
 877           applied to characters, and not the paragraph.
 878           This allows content styling to be preserved independently from that
 879           of e.g. a named paragraph style.
 880         - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
 881           the new style.
 882         - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style.
 883           Only the style flags are used in this operation.
 884     */
 885     virtual bool SetStyle(const wxRichTextRange& range, const wxTextAttr& style,
 886                           int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 887
 888     /**
 889         Sets the current style sheet, if any.
 890
 891         This will allow the application to use named character and paragraph
 892         styles found in the style sheet.
 893     */
 894     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 895
 896     /**
 897         Submit an action immediately, or delay it according to whether collapsing is on.
 898     */
 899     virtual bool SubmitAction(wxRichTextAction* action);
 900
 901     /**
 902         Returns @true if undo suppression is currently on.
 903     */
 904     virtual bool SuppressingUndo() const;
 905 };
 906
 907
 908
 909 /**
 910     @class wxRichTextFileHandler
 911
 912     This is the base class for file handlers, for loading and/or saving content
 913     associated with a wxRichTextBuffer.
 914
 915     @library{wxrichtext}
 916     @category{richtext}
 917 */
 918 class wxRichTextFileHandler : public wxObject
 919 {
 920 public:
 921     /**
 922         Constructor.
 923     */
 924     wxRichTextFileHandler(const wxString& name = wxEmptyString,
 925                           const wxString& ext = wxEmptyString,
 926                           int type = 0);
 927
 928     /**
 929         Override this function and return @true if this handler can we handle
 930         @a filename.
 931
 932         By default, this function checks the extension.
 933     */
 934     virtual bool CanHandle(const wxString& filename) const;
 935
 936     /**
 937         Override and return @true if this handler can load content.
 938     */
 939     virtual bool CanLoad() const;
 940
 941     /**
 942         Override and return @true if this handler can save content.
 943     */
 944     virtual bool CanSave() const;
 945
 946     /**
 947         Returns the encoding associated with the handler (if any).
 948     */
 949     const wxString& GetEncoding() const;
 950
 951     /**
 952         Returns the extension associated with the handler.
 953     */
 954     wxString GetExtension() const;
 955
 956     /**
 957         Returns flags that change the behaviour of loading or saving.
 958
 959         See the documentation for each handler class to see what flags are
 960         relevant for each handler.
 961     */
 962     int GetFlags() const;
 963
 964     /**
 965         Returns the name of the handler.
 966     */
 967     wxString GetName() const;
 968
 969     /**
 970         Returns the type of the handler.
 971     */
 972     int GetType() const;
 973
 974     /**
 975         Returns @true if this handler should be visible to the user.
 976     */
 977     virtual bool IsVisible() const;
 978
 979     //@{
 980     /**
 981         Loads content from a stream or file.
 982         Not all handlers will implement file loading.
 983     */
 984     bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream);
 985     bool LoadFile(wxRichTextBuffer* buffer, const wxString& filename);
 986     //@}
 987
 988     //@{
 989     /**
 990         Saves content to a stream or file.
 991         Not all handlers will implement file saving.
 992     */
 993     bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream);
 994     bool SaveFile(wxRichTextBuffer* buffer, const wxString& filename);
 995     //@}
 996
 997     /**
 998         Sets the encoding to use when saving a file.
 999         If empty, a suitable encoding is chosen.
1000     */
1001     void SetEncoding(const wxString& encoding);
1002
1003     /**
1004         Sets the default extension to recognise.
1005     */
1006     void SetExtension(const wxString& ext);
1007
1008     /**
1009         Sets flags that change the behaviour of loading or saving.
1010         See the documentation for each handler class to see what flags are relevant
1011         for each handler.
1012
1013         You call this function directly if you are using a file handler explicitly
1014         (without going through the text control or buffer LoadFile/SaveFile API).
1015         Or, you can call the control or buffer's SetHandlerFlags function to set
1016         the flags that will be used for subsequent load and save operations.
1017     */
1018     void SetFlags(int flags);
1019
1020     /**
1021         Sets the name of the handler.
1022     */
1023     void SetName(const wxString& name);
1024
1025     /**
1026         Sets the handler type.
1027     */
1028     void SetType(int type);
1029
1030     /**
1031         Sets whether the handler should be visible to the user (via the application's
1032         load and save dialogs).
1033     */
1034     virtual void SetVisible(bool visible);
1035
1036 protected:
1037     /**
1038         Override to load content from @a stream into @a buffer.
1039     */
1040     virtual bool DoLoadFile(wxRichTextBuffer* buffer,
1041                             wxInputStream& stream) = 0;
1042
1043     /**
1044         Override to save content to @a stream from @a buffer.
1045     */
1046     virtual bool DoSaveFile(wxRichTextBuffer* buffer,
1047                             wxOutputStream& stream) = 0;
1048 };
1049
1050
1051
1052 /**
1053     @class wxRichTextRange
1054
1055     This class stores beginning and end positions for a range of data.
1056
1057     @library{wxrichtext}
1058     @category{richtext}
1059 */
1060 class wxRichTextRange
1061 {
1062 public:
1063     //@{
1064     /**
1065         Constructors.
1066     */
1067     wxRichTextRange(long start, long end);
1068     wxRichTextRange(const wxRichTextRange& range);
1069     wxRichTextRange();
1070     //@}
1071
1072     /**
1073         Destructor.
1074     */
1075     ~wxRichTextRange();
1076
1077     /**
1078         Returns @true if the given position is within this range.
1079         Does not match if the range is empty.
1080     */
1081     bool Contains(long pos) const;
1082
1083     /**
1084         Converts the internal range, which uses the first and last character positions
1085         of the range, to the API-standard range, whose end is one past the last
1086         character in the range.
1087         In other words, one is added to the end position.
1088     */
1089     wxRichTextRange FromInternal() const;
1090
1091     /**
1092         Returns the end position.
1093     */
1094     long GetEnd() const;
1095
1096     /**
1097         Returns the length of the range.
1098     */
1099     long GetLength() const;
1100
1101     /**
1102         Returns the start of the range.
1103     */
1104     long GetStart() const;
1105
1106     /**
1107         Returns @true if this range is completely outside @e range.
1108     */
1109     bool IsOutside(const wxRichTextRange& range) const;
1110
1111     /**
1112         Returns @true if this range is completely within @e range.
1113     */
1114     bool IsWithin(const wxRichTextRange& range) const;
1115
1116     /**
1117         Limits this range to be within @e range.
1118     */
1119     bool LimitTo(const wxRichTextRange& range);
1120
1121     /**
1122         Sets the end of the range.
1123     */
1124     void SetEnd(long end);
1125
1126     /**
1127         Sets the range.
1128     */
1129     void SetRange(long start, long end);
1130
1131     /**
1132         Sets the start of the range.
1133     */
1134     void SetStart(long start);
1135
1136     /**
1137         Swaps the start and end.
1138     */
1139     void Swap();
1140
1141     /**
1142         Converts the API-standard range, whose end is one past the last character in
1143         the range, to the internal form, which uses the first and last character
1144         positions of the range.
1145         In other words, one is subtracted from the end position.
1146     */
1147     wxRichTextRange ToInternal() const;
1148
1149     /**
1150         Adds @a range to this range.
1151     */
1152     wxRichTextRange operator+(const wxRichTextRange& range) const;
1153
1154     /**
1155         Subtracts @a range from this range.
1156     */
1157     wxRichTextRange operator-(const wxRichTextRange& range) const;
1158
1159     /**
1160         Assigns @a range to this range.
1161     */
1162     void operator=(const wxRichTextRange& range);
1163
1164     /**
1165         Returns @true if @a range is the same as this range.
1166     */
1167     bool operator==(const wxRichTextRange& range) const;
1168 };
1169