interface/richtext/richtextctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextctrl.h
   3 // Purpose:     interface of wxRichTextEvent
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRichTextEvent
  11     @headerfile richtextctrl.h wx/richtext/richtextctrl.h
  12
  13     This is the event class for wxRichTextCtrl notifications.
  14
  15     @library{wxrichtext}
  16     @category{richtext}
  17 */
  18 class wxRichTextEvent : public wxNotifyEvent
  19 {
  20 public:
  21     //@{
  22     /**
  23         Constructors.
  24     */
  25     wxRichTextEvent(const wxRichTextEvent& event);
  26     wxRichTextEvent(wxEventType commandType = wxEVT_NULL,
  27                     int winid = 0);
  28     //@}
  29
  30     /**
  31         Clones the event.
  32     */
  33     wxEvent* Clone() const;
  34
  35     /**
  36         Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event.
  37     */
  38     wxChar GetCharacter() const;
  39
  40     /**
  41         Returns flags indicating modifier keys pressed. Possible values are
  42         wxRICHTEXT_CTRL_DOWN,
  43         wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN.
  44     */
  45     int GetFlags() const;
  46
  47     /**
  48         Returns the new style sheet. Can be used in a
  49         wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or
  50         wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler.
  51     */
  52     wxRichTextStyleSheet* GetNewStyleSheet() const;
  53
  54     /**
  55         Returns the old style sheet. Can be used in a
  56         wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or
  57         wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler.
  58     */
  59     wxRichTextStyleSheet* GetOldStyleSheet() const;
  60
  61     /**
  62         Returns the buffer position at which the event occured.
  63     */
  64     long GetPosition() const;
  65
  66     /**
  67         Gets the range for the current operation.
  68     */
  69     wxRichTextRange GetRange() const;
  70
  71     /**
  72         Sets the character variable.
  73     */
  74     void SetCharacter(wxChar ch);
  75
  76     /**
  77         Sets flags indicating modifier keys pressed. Possible values are
  78         wxRICHTEXT_CTRL_DOWN,
  79         wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN.
  80     */
  81     void SetFlags(int flags);
  82
  83     /**
  84         Sets the new style sheet variable.
  85     */
  86     void SetNewStyleSheet(wxRichTextStyleSheet* sheet);
  87
  88     /**
  89         Sets the old style sheet variable.
  90     */
  91     void SetOldStyleSheet(wxRichTextStyleSheet* sheet);
  92
  93     /**
  94         Sets the buffer position variable.
  95     */
  96     void SetPosition(long pos);
  97
  98     /**
  99         Sets the range variable.
 100     */
 101     void SetRange(const wxRichTextRange& range);
 102 };
 103
 104
 105
 106 /**
 107     @class wxRichTextCtrl
 108     @headerfile richtextctrl.h wx/richtext/richtextctrl.h
 109
 110     wxRichTextCtrl provides a generic, ground-up implementation of a text control
 111     capable of showing multiple styles and images.
 112
 113     wxRichTextCtrl sends notification events: see wxRichTextEvent.
 114     It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and
 115     wxEVT_COMMAND_TEXT_UPDATED,
 116     and wxTextUrlEvent when URL content is clicked.
 117
 118     For more information, see the @ref overview_wxrichtextctrloverview
 119     "wxRichTextCtrl overview".
 120
 121     @library{wxrichtext}
 122     @category{richtext}
 123 */
 124 class wxRichTextCtrl
 125 {
 126 public:
 127     //@{
 128     /**
 129         Constructors.
 130     */
 131     wxRichTextCtrl();
 132     wxRichTextCtrl(wxWindow* parent, wxWindowID id = wxID_ANY,
 133                    const wxString& value = wxEmptyString,
 134                    const wxPoint& pos = wxDefaultPosition,
 135                    const wxSize& size = wxDefaultSize,
 136                    long style = wxRE_MULTILINE,
 137                    const wxValidator& validator = wxDefaultValidator,
 138                    const wxString& name = wxTextCtrlNameStr);
 139     //@}
 140
 141     /**
 142         Destructor.
 143     */
 144     ~wxRichTextCtrl();
 145
 146     /**
 147         Adds an image to the control's buffer.
 148     */
 149     wxRichTextRange AddImage(const wxImage& image);
 150
 151     /**
 152         Adds a new paragraph of text to the end of the buffer.
 153     */
 154     wxRichTextRange AddParagraph(const wxString& text);
 155
 156     /**
 157         Sets the insertion point to the end of the buffer and writes the text.
 158     */
 159     void AppendText(const wxString& text);
 160
 161     /**
 162         Applies the given alignment to the selection (undoable).
 163         For alignment values, see wxTextAttr.
 164     */
 165     bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment);
 166
 167     /**
 168         Apples bold to the selection (undoable).
 169     */
 170     bool ApplyBoldToSelection();
 171
 172     /**
 173         Applies italic to the selection (undoable).
 174     */
 175     bool ApplyItalicToSelection();
 176
 177     /**
 178         Applies the given style to the selection.
 179     */
 180     bool ApplyStyle(wxRichTextStyleDefinition* def);
 181
 182     /**
 183         Applies the style sheet to the buffer, matching paragraph styles in the sheet
 184         against named styles
 185         in the buffer. This might be useful if the styles have changed. If @a sheet is
 186         @NULL, the
 187         sheet set with SetStyleSheet is used.
 188         Currently this applies paragraph styles only.
 189     */
 190     bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL);
 191
 192     /**
 193         Applies underline to the selection (undoable).
 194     */
 195     bool ApplyUnderlineToSelection();
 196
 197     /**
 198         Returns @true if undo commands are being batched.
 199     */
 200     bool BatchingUndo() const;
 201
 202     /**
 203         Begins using alignment
 204         For alignment values, see wxTextAttr.
 205     */
 206     bool BeginAlignment(wxTextAttrAlignment alignment);
 207
 208     /**
 209         Starts batching undo history for commands.
 210     */
 211     bool BeginBatchUndo(const wxString& cmdName);
 212
 213     /**
 214         Begins using bold.
 215     */
 216     bool BeginBold();
 217
 218     /**
 219         Begins using the named character style.
 220     */
 221     bool BeginCharacterStyle(const wxString& characterStyle);
 222
 223     /**
 224         Begins using this font.
 225     */
 226     bool BeginFont(const wxFont& font);
 227
 228     /**
 229         Begins using the given point size.
 230     */
 231     bool BeginFontSize(int pointSize);
 232
 233     /**
 234         Begins using italic.
 235     */
 236     bool BeginItalic();
 237
 238     /**
 239         Begins applying a left indent and subindent in tenths of a millimetre.
 240         The sub-indent is an offset from the left of the paragraph, and is used for all
 241         but the
 242         first line in a paragraph. A positive value will cause the first line to appear
 243         to the left
 244         of the subsequent lines, and a negative value will cause the first line to be
 245         indented
 246         relative to the subsequent lines.
 247         wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
 248         the distance between
 249         the margin and the bullet. The content of the paragraph, including the first
 250         line, starts
 251         at leftMargin + leftSubIndent. So the distance between the left edge of the
 252         bullet and the
 253         left of the actual paragraph is leftSubIndent.
 254     */
 255     bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0);
 256
 257     /**
 258         Begins appling line spacing. @e spacing is a multiple, where 10 means
 259         single-spacing,
 260         15 means 1.5 spacing, and 20 means double spacing. The following constants are
 261         defined for convenience:
 262     */
 263     bool BeginLineSpacing(int lineSpacing);
 264
 265     /**
 266         Begins using a specified list style. Optionally, you can also pass a level and
 267         a number.
 268     */
 269     bool BeginListStyle(const wxString& listStyle, int level = 1,
 270                         int number = 1);
 271
 272     /**
 273         Begins a numbered bullet. This call will be needed for each item in the list,
 274         and the
 275         application should take care of incrementing the numbering.
 276         @a bulletNumber is a number, usually starting with 1.
 277         @a leftIndent and @a leftSubIndent are values in tenths of a millimetre.
 278         @a bulletStyle is a bitlist of the following values:
 279
 280         wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
 281         the distance between
 282         the margin and the bullet. The content of the paragraph, including the first
 283         line, starts
 284         at leftMargin + leftSubIndent. So the distance between the left edge of the
 285         bullet and the
 286         left of the actual paragraph is leftSubIndent.
 287     */
 288     bool BeginNumberedBullet(int bulletNumber, int leftIndent,
 289                              int leftSubIndent,
 290                              int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD);
 291
 292     /**
 293         Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing
 294         in tenths of
 295         a millimetre.
 296     */
 297     bool BeginParagraphSpacing(int before, int after);
 298
 299     /**
 300         Begins applying the named paragraph style.
 301     */
 302     bool BeginParagraphStyle(const wxString& paragraphStyle);
 303
 304     /**
 305         Begins a right indent, specified in tenths of a millimetre.
 306     */
 307     bool BeginRightIndent(int rightIndent);
 308
 309     /**
 310         Begins applying a style.
 311     */
 312     bool BeginStyle(const wxTextAttr& style);
 313
 314     /**
 315         Starts suppressing undo history for commands.
 316     */
 317     bool BeginSuppressUndo();
 318
 319     /**
 320         Begins applying a symbol bullet, using a character from the current font. See
 321         BeginNumberedBullet() for
 322         an explanation of how indentation is used to render the bulleted paragraph.
 323     */
 324     bool BeginSymbolBullet(wxChar symbol, int leftIndent,
 325                            int leftSubIndent,
 326                            int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL);
 327
 328     /**
 329         Begins using this colour.
 330     */
 331     bool BeginTextColour(const wxColour& colour);
 332
 333     /**
 334         Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a
 335         character style to apply,
 336         since it is common to mark a URL with a familiar style such as blue text with
 337         underlining.
 338     */
 339     bool BeginURL(const wxString& url,
 340                   const wxString& characterStyle = wxEmptyString);
 341
 342     /**
 343         Begins using underlining.
 344     */
 345     bool BeginUnderline();
 346
 347     /**
 348         Returns @true if selected content can be copied to the clipboard.
 349     */
 350     bool CanCopy() const;
 351
 352     /**
 353         Returns @true if selected content can be copied to the clipboard and deleted.
 354     */
 355     bool CanCut() const;
 356
 357     /**
 358         Returns @true if selected content can be deleted.
 359     */
 360     bool CanDeleteSelection() const;
 361
 362     /**
 363         Returns @true if the clipboard content can be pasted to the buffer.
 364     */
 365     bool CanPaste() const;
 366
 367     /**
 368         Returns @true if there is a command in the command history that can be redone.
 369     */
 370     bool CanRedo() const;
 371
 372     /**
 373         Returns @true if there is a command in the command history that can be undone.
 374     */
 375     bool CanUndo() const;
 376
 377     /**
 378         Clears the buffer content, leaving a single empty paragraph. Cannot be undone.
 379     */
 380     void Clear();
 381
 382     //@{
 383     /**
 384         Clears the list style from the given range, clearing list-related attributes
 385         and applying any named paragraph style associated with each paragraph.
 386         @a flags is a bit list of the following:
 387          wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 388         See also SetListStyle(), PromoteList(), NumberList().
 389     */
 390     bool ClearListStyle(const wxRichTextRange& range,
 391                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 392     bool ClearListStyle(const wxRichTextRange& range,
 393                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 394     //@}
 395
 396     /**
 397         Sends the event to the control.
 398     */
 399     void Command(wxCommandEvent& event);
 400
 401     /**
 402         Copies the selected content (if any) to the clipboard.
 403     */
 404     void Copy();
 405
 406     /**
 407         Creates the underlying window.
 408     */
 409     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 410                 const wxString& value = wxEmptyString,
 411                 const wxPoint& pos = wxDefaultPosition,
 412                 const wxSize& size = wxDefaultSize,
 413                 long style = wxRE_MULTILINE,
 414                 const wxValidator& validator = wxDefaultValidator,
 415                 const wxString& name = wxTextCtrlNameStr);
 416
 417     /**
 418         Copies the selected content (if any) to the clipboard and deletes the selection.
 419         This is undoable.
 420     */
 421     void Cut();
 422
 423     /**
 424         Deletes the content within the given range.
 425     */
 426     bool Delete(const wxRichTextRange& range);
 427
 428     /**
 429         Deletes content if there is a selection, e.g. when pressing a key.
 430         Returns the new caret position in @e newPos, or leaves it if there
 431         was no action. This is undoable.
 432     */
 433     bool DeleteSelectedContent(long* newPos = NULL);
 434
 435     /**
 436         Deletes the content in the selection, if any. This is undoable.
 437     */
 438     void DeleteSelection();
 439
 440     /**
 441         Sets the buffer's modified status to @false, and clears the buffer's command
 442         history.
 443     */
 444     void DiscardEdits();
 445
 446     /**
 447         Currently this simply returns @c wxSize(10, 10).
 448     */
 449     wxSize DoGetBestSize() const;
 450
 451     /**
 452         Ends alignment.
 453     */
 454     bool EndAlignment();
 455
 456     /**
 457         Ends application of all styles in the current style stack.
 458     */
 459     bool EndAllStyles();
 460
 461     /**
 462         Ends batching undo command history.
 463     */
 464     bool EndBatchUndo();
 465
 466     /**
 467         Ends using bold.
 468     */
 469     bool EndBold();
 470
 471     /**
 472         Ends application of a named character style.
 473     */
 474     bool EndCharacterStyle();
 475
 476     /**
 477         Ends using a font.
 478     */
 479     bool EndFont();
 480
 481     /**
 482         Ends using a point size.
 483     */
 484     bool EndFontSize();
 485
 486     /**
 487         Ends using italic.
 488     */
 489     bool EndItalic();
 490
 491     /**
 492         Ends left indent.
 493     */
 494     bool EndLeftIndent();
 495
 496     /**
 497         Ends line spacing.
 498     */
 499     bool EndLineSpacing();
 500
 501     /**
 502         Ends using a specified list style.
 503     */
 504     bool EndListStyle();
 505
 506     /**
 507         Ends application of a numbered bullet.
 508     */
 509     bool EndNumberedBullet();
 510
 511     /**
 512         Ends paragraph spacing.
 513     */
 514     bool EndParagraphSpacing();
 515
 516     /**
 517         Ends application of a named character style.
 518     */
 519     bool EndParagraphStyle();
 520
 521     /**
 522         Ends right indent.
 523     */
 524     bool EndRightIndent();
 525
 526     /**
 527         Ends the current style.
 528     */
 529     bool EndStyle();
 530
 531     /**
 532         Ends suppressing undo command history.
 533     */
 534     bool EndSuppressUndo();
 535
 536     /**
 537         Ends applying a symbol bullet.
 538     */
 539     bool EndSymbolBullet();
 540
 541     /**
 542         Ends applying a text colour.
 543     */
 544     bool EndTextColour();
 545
 546     /**
 547         Ends applying a URL.
 548     */
 549     bool EndURL();
 550
 551     /**
 552         End applying underlining.
 553     */
 554     bool EndUnderline();
 555
 556     /**
 557         Helper function for extending the selection, returning @true if the selection
 558         was
 559         changed. Selections are in caret positions.
 560     */
 561     bool ExtendSelection(long oldPosition, long newPosition,
 562                          int flags);
 563
 564     /**
 565         Helper function for finding the caret position for the next word. Direction
 566         is 1 (forward) or -1 (backwards).
 567     */
 568     long FindNextWordPosition(int direction = 1) const;
 569
 570     /**
 571         Call this function to prevent refresh and allow fast updates, and then Thaw() to
 572         refresh the control.
 573     */
 574     void Freeze();
 575
 576     /**
 577         Gets the basic (overall) style. This is the style of the whole
 578         buffer before further styles are applied, unlike the default style, which
 579         only affects the style currently being applied (for example, setting the default
 580         style to bold will cause subsequently inserted text to be bold).
 581     */
 582     const wxTextAttr GetBasicStyle() const;
 583
 584     //@{
 585     /**
 586         Returns the buffer associated with the control.
 587     */
 588     const wxRichTextBuffer GetBuffer();
 589     const wxRichTextBuffer&  GetBuffer();
 590     //@}
 591
 592     /**
 593         Returns the current caret position.
 594     */
 595     long GetCaretPosition() const;
 596
 597     /**
 598         Returns the caret height and position for the given character position
 599     */
 600     bool GetCaretPositionForIndex(long position, wxRect& rect);
 601
 602     /**
 603         Gets the command processor associated with the control's buffer.
 604     */
 605     wxCommandProcessor* GetCommandProcessor() const;
 606
 607     /**
 608         Returns the current default style, which can be used to change how subsequently
 609         inserted
 610         text is displayed.
 611     */
 612     const wxTextAttr GetDefaultStyle() const;
 613
 614     /**
 615         Gets the size of the buffer beyond which layout is delayed during resizing.
 616         This optimizes sizing for large buffers. The default is 20000.
 617     */
 618     long GetDelayedLayoutThreshold() const;
 619
 620     /**
 621         Gets the current filename associated with the control.
 622     */
 623     wxString GetFilename() const;
 624
 625     /**
 626         Returns the first visible position in the current view.
 627     */
 628     long GetFirstVisiblePosition() const;
 629
 630     /**
 631         Returns flags that change the behaviour of loading or saving. See the
 632         documentation for each
 633         handler class to see what flags are relevant for each handler.
 634     */
 635     int GetHandlerFlags() const;
 636
 637     /**
 638         Returns the current insertion point.
 639     */
 640     long GetInsertionPoint() const;
 641
 642     /**
 643         Returns the last position in the buffer.
 644     */
 645     wxTextPos GetLastPosition() const;
 646
 647     /**
 648         Returns the length of the specified line in characters.
 649     */
 650     int GetLineLength(long lineNo) const;
 651
 652     /**
 653         Returns the text for the given line.
 654     */
 655     wxString GetLineText(long lineNo) const;
 656
 657     /**
 658         Transforms physical window position to logical (unscrolled) position.
 659     */
 660     wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const;
 661
 662     /**
 663         Returns the number of lines in the buffer.
 664     */
 665     int GetNumberOfLines() const;
 666
 667     /**
 668         Transforms logical (unscrolled) position to physical window position.
 669     */
 670     wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const;
 671
 672     /**
 673         Gets the text for the given range.
 674         The end point of range is specified as the last character position of the span
 675         of text, plus one.
 676     */
 677     wxString GetRange(long from, long to) const;
 678
 679     /**
 680         Returns the range of the current selection.
 681         The end point of range is specified as the last character position of the span
 682         of text, plus one.
 683         If the return values @a from and @a to are the same, there is no selection.
 684     */
 685     void GetSelection(long* from, long* to) const;
 686
 687     /**
 688         Returns the selection range in character positions. -1, -1 means no selection.
 689     */
 690     const wxRichTextRange GetSelectionRange() const;
 691
 692     /**
 693         Returns the text within the current selection range, if any.
 694     */
 695     wxString GetStringSelection() const;
 696
 697     /**
 698         Gets the attributes at the given position.
 699         This function gets the combined style - that is, the style you see on the
 700         screen as a result
 701         of combining base style, paragraph style and character style attributes. To get
 702         the character
 703         or paragraph style alone, use GetUncombinedStyle().
 704     */
 705     bool GetStyle(long position, wxTextAttr& style);
 706
 707     /**
 708         Gets the attributes common to the specified range. Attributes that differ in
 709         value within the range will
 710         not be included in @e style's flags.
 711     */
 712     bool GetStyleForRange(const wxRichTextRange& range,
 713                           wxTextAttr& style);
 714
 715     /**
 716         Returns the style sheet associated with the control, if any. A style sheet
 717         allows named
 718         character and paragraph styles to be applied.
 719     */
 720     wxRichTextStyleSheet* GetStyleSheet() const;
 721
 722     /**
 723         Gets the attributes at the given position.
 724         This function gets the @e uncombined style - that is, the attributes associated
 725         with the
 726         paragraph or character content, and not necessarily the combined attributes you
 727         see on the
 728         screen. To get the combined attributes, use GetStyle().
 729         If you specify (any) paragraph attribute in @e style's flags, this function
 730         will fetch
 731         the paragraph attributes. Otherwise, it will return the character attributes.
 732     */
 733     bool GetUncombinedStyle(long position, wxTextAttr& style);
 734
 735     /**
 736         Returns the content of the entire control as a string.
 737     */
 738     wxString GetValue() const;
 739
 740     /**
 741         Internal helper function returning the line for the visible caret position. If
 742         the caret is
 743         shown at the very end of the line, it means the next character is actually
 744         on the following line. So this function gets the line we're expecting to find
 745         if this is the case.
 746     */
 747     wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const;
 748
 749     /**
 750         Test if this whole range has character attributes of the specified kind. If any
 751         of the attributes are different within the range, the test fails. You
 752         can use this to implement, for example, bold button updating. @a style must have
 753         flags indicating which attributes are of interest.
 754     */
 755     bool HasCharacterAttributes(const wxRichTextRange& range,
 756                                 const wxTextAttr& style) const;
 757
 758     /**
 759         Test if this whole range has paragraph attributes of the specified kind. If any
 760         of the attributes are different within the range, the test fails. You
 761         can use this to implement, for example, centering button updating. @a style
 762         must have
 763         flags indicating which attributes are of interest.
 764     */
 765     bool HasParagraphAttributes(const wxRichTextRange& range,
 766                                 const wxTextAttr& style) const;
 767
 768     /**
 769         Returns @true if there is a selection.
 770     */
 771     bool HasSelection() const;
 772
 773     //@{
 774     /**
 775         Finds the character at the given position in pixels.
 776         @a pt is in device coords (not adjusted for the client area origin nor for
 777         scrolling).
 778     */
 779     wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos) const;
 780     const wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
 781                                           wxTextCoord* col,
 782                                           wxTextCoord* row) const;
 783     //@}
 784
 785     /**
 786         Initialises the members of the control.
 787     */
 788     void Init();
 789
 790     /**
 791         Initialises the command event.
 792     */
 793     void InitCommandEvent(wxCommandEvent& event) const;
 794
 795     /**
 796         Returns @true if the user has recently set the default style without moving
 797         the caret,
 798         and therefore the UI needs to reflect the default style and not the style at
 799         the caret.
 800         Below is an example of code that uses this function to determine whether the UI
 801         should show that the current style is bold.
 802
 803         See also SetAndShowDefaultStyle().
 804     */
 805     bool IsDefaultStyleShowing() const;
 806
 807     /**
 808         Returns @true if the control is editable.
 809     */
 810     bool IsEditable() const;
 811
 812     /**
 813         Returns @true if Freeze has been called without a Thaw.
 814     */
 815     bool IsFrozen() const;
 816
 817     /**
 818         Returns @true if the buffer has been modified.
 819     */
 820     bool IsModified() const;
 821
 822     /**
 823         Returns @true if the control is multiline.
 824     */
 825     bool IsMultiLine() const;
 826
 827     /**
 828         Returns @true if the given position is visible on the screen.
 829     */
 830     bool IsPositionVisible(long pos) const;
 831
 832     /**
 833         Returns @true if all of the selection is aligned according to the specified
 834         flag.
 835     */
 836     bool IsSelectionAligned(wxTextAttrAlignment alignment) const;
 837
 838     /**
 839         Returns @true if all of the selection is bold.
 840     */
 841     bool IsSelectionBold() const;
 842
 843     /**
 844         Returns @true if all of the selection is italic.
 845     */
 846     bool IsSelectionItalics() const;
 847
 848     /**
 849         Returns @true if all of the selection is underlined.
 850     */
 851     bool IsSelectionUnderlined() const;
 852
 853     /**
 854         Returns @true if the control is single-line. Currently wxRichTextCtrl does not
 855         support single-line editing.
 856     */
 857     bool IsSingleLine() const;
 858
 859     /**
 860         Helper function implementing keyboard navigation.
 861     */
 862     bool KeyboardNavigate(int keyCode, int flags);
 863
 864     /**
 865         Lays out the buffer, which must be done before certain operations, such as
 866         setting the caret position. This function should not normally be required by the
 867         application.
 868     */
 869     bool LayoutContent(bool onlyVisibleRect = false);
 870
 871     /**
 872         Inserts a line break at the current insertion point. A line break forces
 873         wrapping within a paragraph, and
 874         can be introduced by using this function, by appending the wxChar value @b
 875         wxRichTextLineBreakChar to text content,
 876         or by typing Shift-Return.
 877     */
 878     bool LineBreak();
 879
 880     /**
 881         Loads content into the control's buffer using the given type. If the specified
 882         type
 883         is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension.
 884         This function looks for a suitable wxRichTextFileHandler object.
 885     */
 886     bool LoadFile(const wxString& file,
 887                   int type = wxRICHTEXT_TYPE_ANY);
 888
 889     /**
 890         Marks the buffer as modified.
 891     */
 892     void MarkDirty();
 893
 894     /**
 895         Move the caret to the given character position.
 896     */
 897     bool MoveCaret(long pos, bool showAtLineStart = false);
 898
 899     /**
 900         Move the caret one visual step forward: this may mean setting a flag
 901         and keeping the same position if we're going from the end of one line
 902         to the start of the next, which may be the exact same caret position.
 903     */
 904     void MoveCaretBack(long oldPosition);
 905
 906     /**
 907         Move the caret one visual step forward: this may mean setting a flag
 908         and keeping the same position if we're going from the end of one line
 909         to the start of the next, which may be the exact same caret position.
 910     */
 911     void MoveCaretForward(long oldPosition);
 912
 913     /**
 914         Moves the caret down.
 915     */
 916     bool MoveDown(int noLines = 1, int flags = 0);
 917
 918     /**
 919         Moves to the end of the buffer.
 920     */
 921     bool MoveEnd(int flags = 0);
 922
 923     /**
 924         Moves to the start of the buffer.
 925     */
 926     bool MoveHome(int flags = 0);
 927
 928     /**
 929         Moves left.
 930     */
 931     bool MoveLeft(int noPositions = 1, int flags = 0);
 932
 933     /**
 934         Moves right.
 935     */
 936     bool MoveRight(int noPositions = 1, int flags = 0);
 937
 938     /**
 939         Moves to the end of the line.
 940     */
 941     bool MoveToLineEnd(int flags = 0);
 942
 943     /**
 944         Moves to the start of the line.
 945     */
 946     bool MoveToLineStart(int flags = 0);
 947
 948     /**
 949         Moves to the end of the paragraph.
 950     */
 951     bool MoveToParagraphEnd(int flags = 0);
 952
 953     /**
 954         Moves to the start of the paragraph.
 955     */
 956     bool MoveToParagraphStart(int flags = 0);
 957
 958     /**
 959         Moves up.
 960     */
 961     bool MoveUp(int noLines = 1, int flags = 0);
 962
 963     /**
 964         Inserts a new paragraph at the current insertion point. See also LineBreak().
 965     */
 966     bool Newline();
 967
 968     //@{
 969     /**
 970         Numbers the paragraphs in the given range. Pass flags to determine how the
 971         attributes are set.
 972         Either the style definition or the name of the style definition (in the current
 973         sheet) can be passed.
 974         @a flags is a bit list of the following:
 975          wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 976          wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
 977         startFrom, otherwise existing attributes are used.
 978          wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
 979         as the level for all paragraphs, otherwise the current indentation will be used.
 980         See also SetListStyle(), PromoteList(), ClearListStyle().
 981     */
 982     bool NumberList(const wxRichTextRange& range,
 983                     const wxRichTextListStyleDefinition* style,
 984                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 985                     int startFrom = -1,
 986                     int listLevel = -1);
 987     bool Number(const wxRichTextRange& range,
 988                 const wxString& styleName,
 989                 int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
 990                 int startFrom = -1,
 991                 int listLevel = -1);
 992     //@}
 993
 994     /**
 995         Standard handler for the wxID_CLEAR command.
 996     */
 997     void OnClear(wxCommandEvent& event);
 998
 999     /**
1000         Shows a standard context menu with undo, redo, cut, copy, paste, clear, and
1001         select all commands.
1002     */
1003     void OnContextMenu(wxContextMenuEvent& event);
1004
1005     /**
1006         Standard handler for the wxID_COPY command.
1007     */
1008     void OnCopy(wxCommandEvent& event);
1009
1010     /**
1011         Standard handler for the wxID_CUT command.
1012     */
1013     void OnCut(wxCommandEvent& event);
1014
1015     /**
1016         Loads the first dropped file.
1017     */
1018     void OnDropFiles(wxDropFilesEvent& event);
1019
1020     /**
1021         Standard handler for the wxID_PASTE command.
1022     */
1023     void OnPaste(wxCommandEvent& event);
1024
1025     /**
1026         Standard handler for the wxID_REDO command.
1027     */
1028     void OnRedo(wxCommandEvent& event);
1029
1030     /**
1031         Standard handler for the wxID_SELECTALL command.
1032     */
1033     void OnSelectAll(wxCommandEvent& event);
1034
1035     /**
1036         Standard handler for the wxID_PASTE command.
1037     */
1038     void OnUndo(wxCommandEvent& event);
1039
1040     /**
1041         Standard update handler for the wxID_CLEAR command.
1042     */
1043     void OnUpdateClear(wxUpdateUIEvent& event);
1044
1045     /**
1046         Standard update handler for the wxID_COPY command.
1047     */
1048     void OnUpdateCopy(wxUpdateUIEvent& event);
1049
1050     /**
1051         Standard update handler for the wxID_CUT command.
1052     */
1053     void OnUpdateCut(wxUpdateUIEvent& event);
1054
1055     /**
1056         Standard update handler for the wxID_PASTE command.
1057     */
1058     void OnUpdatePaste(wxUpdateUIEvent& event);
1059
1060     /**
1061         Standard update handler for the wxID_REDO command.
1062     */
1063     void OnUpdateRedo(wxUpdateUIEvent& event);
1064
1065     /**
1066         Standard update handler for the wxID_SELECTALL command.
1067     */
1068     void OnUpdateSelectAll(wxUpdateUIEvent& event);
1069
1070     /**
1071         Standard update handler for the wxID_UNDO command.
1072     */
1073     void OnUpdateUndo(wxUpdateUIEvent& event);
1074
1075     /**
1076         Moves one or more pages down.
1077     */
1078     bool PageDown(int noPages = 1, int flags = 0);
1079
1080     /**
1081         Moves one or more pages up.
1082     */
1083     bool PageUp(int noPages = 1, int flags = 0);
1084
1085     /**
1086         Paints the background.
1087     */
1088     void PaintBackground(wxDC& dc);
1089
1090     /**
1091         Pastes content from the clipboard to the buffer.
1092     */
1093     void Paste();
1094
1095     /**
1096         Internal function to position the visible caret according to the current caret
1097         position.
1098     */
1099     void PositionCaret();
1100
1101     /**
1102         Converts a text position to zero-based column and line numbers.
1103     */
1104     bool PositionToXY(long pos, long* x, long* y) const;
1105
1106     //@{
1107     /**
1108         Promotes or demotes the paragraphs in the given range. A positive @a promoteBy
1109         produces a smaller indent, and a negative number
1110         produces a larger indent. Pass flags to determine how the attributes are set.
1111         Either the style definition or the name of the style definition (in the current
1112         sheet) can be passed.
1113         @a flags is a bit list of the following:
1114          wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1115          wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
1116         startFrom, otherwise existing attributes are used.
1117          wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1118         as the level for all paragraphs, otherwise the current indentation will be used.
1119         See also SetListStyle(), See also SetListStyle(), ClearListStyle().
1120     */
1121     bool PromoteList(int promoteBy, const wxRichTextRange& range,
1122                      const wxRichTextListStyleDefinition* style,
1123                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1124                      int listLevel = -1);
1125     bool PromoteList(int promoteBy, const wxRichTextRange& range,
1126                      const wxString& styleName,
1127                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1128                      int listLevel = -1);
1129     //@}
1130
1131     /**
1132         Redoes the current command.
1133     */
1134     void Redo();
1135
1136     /**
1137         Removes the content in the specified range.
1138     */
1139     void Remove(long from, long to);
1140
1141     /**
1142         Replaces the content in the specified range with the string specified by @e
1143         value.
1144     */
1145     void Replace(long from, long to, const wxString& value);
1146
1147     /**
1148         Saves the buffer content using the given type. If the specified type
1149         is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension.
1150         This function looks for a suitable wxRichTextFileHandler object.
1151     */
1152     bool SaveFile(const wxString& file = wxEmptyString,
1153                   int type = wxRICHTEXT_TYPE_ANY);
1154
1155     /**
1156         Scrolls @a position into view. This function takes a caret position.
1157     */
1158     bool ScrollIntoView(long position, int keyCode);
1159
1160     /**
1161         Selects all the text in the buffer.
1162     */
1163     void SelectAll();
1164
1165     /**
1166         Cancels any selection.
1167     */
1168     void SelectNone();
1169
1170     /**
1171         Sets @a attr as the default style and tells the control that the UI should
1172         reflect
1173         this attribute until the user moves the caret.
1174         See also IsDefaultStyleShowing().
1175     */
1176     void SetAndShowDefaultStyle(const wxTextAttr& attr);
1177
1178     /**
1179         Sets the basic (overall) style. This is the style of the whole
1180         buffer before further styles are applied, unlike the default style, which
1181         only affects the style currently being applied (for example, setting the default
1182         style to bold will cause subsequently inserted text to be bold).
1183     */
1184     void SetBasicStyle(const wxTextAttr& style);
1185
1186     /**
1187         The caret position is the character position just before the caret.
1188         A value of -1 means the caret is at the start of the buffer.
1189     */
1190     void SetCaretPosition(long position,
1191                           bool showAtLineStart = false);
1192
1193     /**
1194         Sets the current default style, which can be used to change how subsequently
1195         inserted
1196         text is displayed.
1197     */
1198     bool SetDefaultStyle(const wxTextAttr& style);
1199
1200     /**
1201         Sets the default style to the style under the cursor.
1202     */
1203     bool SetDefaultStyleToCursorStyle();
1204
1205     /**
1206         Sets the size of the buffer beyond which layout is delayed during resizing.
1207         This optimizes sizing for large buffers. The default is 20000.
1208     */
1209     void SetDelayedLayoutThreshold(long threshold);
1210
1211     /**
1212         Makes the control editable, or not.
1213     */
1214     void SetEditable(bool editable);
1215
1216     /**
1217         Sets the current filename.
1218     */
1219     void SetFilename(const wxString& filename);
1220
1221     /**
1222         Sets the font, and also the basic and default attributes (see
1223         wxRichTextCtrl::SetDefaultStyle).
1224     */
1225     bool SetFont(const wxFont& font);
1226
1227     /**
1228         Sets flags that change the behaviour of loading or saving. See the
1229         documentation for each
1230         handler class to see what flags are relevant for each handler.
1231     */
1232     void SetHandlerFlags(int flags);
1233
1234     /**
1235         Sets the insertion point.
1236     */
1237     void SetInsertionPoint(long pos);
1238
1239     /**
1240         Sets the insertion point to the end of the text control.
1241     */
1242     void SetInsertionPointEnd();
1243
1244     //@{
1245     /**
1246         Sets the list attributes for the given range, passing flags to determine how
1247         the attributes are set.
1248         Either the style definition or the name of the style definition (in the current
1249         sheet) can be passed.
1250         @a flags is a bit list of the following:
1251          wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1252          wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
1253         startFrom, otherwise existing attributes are used.
1254          wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1255         as the level for all paragraphs, otherwise the current indentation will be used.
1256         See also NumberList(), PromoteList(), ClearListStyle().
1257     */
1258     bool SetListStyle(const wxRichTextRange& range,
1259                       const wxRichTextListStyleDefinition* style,
1260                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1261                       int startFrom = -1,
1262                       int listLevel = -1);
1263     bool SetListStyle(const wxRichTextRange& range,
1264                       const wxString& styleName,
1265                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1266                       int startFrom = -1,
1267                       int listLevel = -1);
1268     //@}
1269
1270     /**
1271         Sets the selection to the given range.
1272         The end point of range is specified as the last character position of the span
1273         of text, plus one.
1274         So, for example, to set the selection for a character at position 5, use the
1275         range (5,6).
1276     */
1277     void SetSelection(long from, long to);
1278
1279     /**
1280         Sets the selection to the given range.
1281         The end point of range is specified as the last character position of the span
1282         of text, plus one.
1283         So, for example, to set the selection for a character at position 5, use the
1284         range (5,6).
1285     */
1286     void SetSelectionRange(const wxRichTextRange& range);
1287
1288     //@{
1289     /**
1290         Sets the attributes for the given range.
1291         The end point of range is specified as the last character position of the span
1292         of text, plus one.
1293         So, for example, to set the style for a character at position 5, use the range
1294         (5,6).
1295     */
1296     bool SetStyle(const wxRichTextRange& range,
1297                   const wxTextAttr& style);
1298     bool SetStyle(long start, long end, const wxTextAttr& style);
1299     //@}
1300
1301     //@{
1302     /**
1303         Sets the attributes for the given range, passing flags to determine how the
1304         attributes are set.
1305         The end point of range is specified as the last character position of the span
1306         of text, plus one.
1307         So, for example, to set the style for a character at position 5, use the range
1308         (5,6).
1309         @a flags may contain a bit list of the following values:
1310          wxRICHTEXT_SETSTYLE_NONE: no style flag.
1311          wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
1312         undoable.
1313          wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
1314         if the
1315         combined style at this point is already the style in question.
1316          wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
1317         applied to paragraphs,
1318         and not the content. This allows content styling to be preserved independently
1319         from that of e.g. a named paragraph style.
1320          wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
1321         applied to characters,
1322         and not the paragraph. This allows content styling to be preserved
1323         independently from that of e.g. a named paragraph style.
1324          wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
1325         the new style.
1326          wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags
1327         are used in this operation.
1328     */
1329     bool SetStyleEx(const wxRichTextRange& range,
1330                     const wxTextAttr& style,
1331                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
1332     bool SetStyleEx(long start, long end,
1333                     const wxTextAttr& style,
1334                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
1335     //@}
1336
1337     /**
1338         Sets the style sheet associated with the control. A style sheet allows named
1339         character and paragraph styles to be applied.
1340     */
1341     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
1342
1343     /**
1344         Replaces existing content with the given text.
1345     */
1346     void SetValue(const wxString& value);
1347
1348     /**
1349         A helper function setting up scrollbars, for example after a resize.
1350     */
1351     void SetupScrollbars(bool atTop = false);
1352
1353     /**
1354         Scrolls the buffer so that the given position is in view.
1355     */
1356     void ShowPosition(long pos);
1357
1358     /**
1359         Returns @true if undo history suppression is on.
1360     */
1361     bool SuppressingUndo() const;
1362
1363     /**
1364         Call this function to end a Freeze and refresh the display.
1365     */
1366     void Thaw();
1367
1368     /**
1369         Undoes the command at the top of the command history, if there is one.
1370     */
1371     void Undo();
1372
1373     /**
1374         Moves a number of words to the left.
1375     */
1376     bool WordLeft(int noWords = 1, int flags = 0);
1377
1378     /**
1379         Move a nuber of words to the right.
1380     */
1381     bool WordRight(int noWords = 1, int flags = 0);
1382
1383     //@{
1384     /**
1385         Write a bitmap or image at the current insertion point. Supply an optional type
1386         to use
1387         for internal and file storage of the raw data.
1388     */
1389     bool WriteImage(const wxString& filename, int bitmapType);
1390     bool WriteImage(const wxRichTextImageBlock& imageBlock);
1391     bool WriteImage(const wxBitmap& bitmap,
1392                     int bitmapType = wxBITMAP_TYPE_PNG);
1393     bool WriteImage(const wxImage& image,
1394                     int bitmapType = wxBITMAP_TYPE_PNG);
1395     //@}
1396
1397     /**
1398         Writes text at the current position.
1399     */
1400     void WriteText(const wxString& text);
1401
1402     /**
1403         Translates from column and line number to position.
1404     */
1405     long XYToPosition(long x, long y) const;
1406 };
1407