interface/wx/richtext/richtextctrl.h

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