interface/richtext/richtextctrl.h

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