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