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