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