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