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     /**
 448         Clears the list style from the given range, clearing list-related attributes
 449         and applying any named paragraph style associated with each paragraph.
 450
 451         @a flags is a bit list of the following:
 452         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
 453
 454         @see SetListStyle(), PromoteList(), NumberList().
 455     */
 456     bool ClearListStyle(const wxRichTextRange& range,
 457                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 458     bool ClearListStyle(const wxRichTextRange& range,
 459                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 460     //@}
 461
 462     /**
 463         Sends the event to the control.
 464     */
 465     virtual void Command(wxCommandEvent& event);
 466
 467     /**
 468         Copies the selected content (if any) to the clipboard.
 469     */
 470     virtual void Copy();
 471
 472     /**
 473         Creates the underlying window.
 474     */
 475     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 476                 const wxString& value = wxEmptyString,
 477                 const wxPoint& pos = wxDefaultPosition,
 478                 const wxSize& size = wxDefaultSize,
 479                 long style = wxRE_MULTILINE,
 480                 const wxValidator& validator = wxDefaultValidator,
 481                 const wxString& name = wxTextCtrlNameStr);
 482
 483     /**
 484         Copies the selected content (if any) to the clipboard and deletes the selection.
 485         This is undoable.
 486     */
 487     virtual void Cut();
 488
 489     /**
 490         Deletes the content within the given range.
 491     */
 492     virtual bool Delete(const wxRichTextRange& range);
 493
 494     /**
 495         Deletes content if there is a selection, e.g. when pressing a key.
 496         Returns the new caret position in @e newPos, or leaves it if there
 497         was no action. This is undoable.
 498     */
 499     bool DeleteSelectedContent(long* newPos = NULL);
 500
 501     /**
 502         Deletes the content in the selection, if any. This is undoable.
 503     */
 504     virtual void DeleteSelection();
 505
 506     /**
 507         Sets the buffer's modified status to @false, and clears the buffer's command
 508         history.
 509     */
 510     virtual void DiscardEdits();
 511
 512     /**
 513         Ends alignment.
 514     */
 515     bool EndAlignment();
 516
 517     /**
 518         Ends application of all styles in the current style stack.
 519     */
 520     virtual bool EndAllStyles();
 521
 522     /**
 523         Ends batching undo command history.
 524     */
 525     virtual bool EndBatchUndo();
 526
 527     /**
 528         Ends using bold.
 529     */
 530     bool EndBold();
 531
 532     /**
 533         Ends application of a named character style.
 534     */
 535     bool EndCharacterStyle();
 536
 537     /**
 538         Ends using a font.
 539     */
 540     bool EndFont();
 541
 542     /**
 543         Ends using a point size.
 544     */
 545     bool EndFontSize();
 546
 547     /**
 548         Ends using italic.
 549     */
 550     bool EndItalic();
 551
 552     /**
 553         Ends left indent.
 554     */
 555     bool EndLeftIndent();
 556
 557     /**
 558         Ends line spacing.
 559     */
 560     bool EndLineSpacing();
 561
 562     /**
 563         Ends using a specified list style.
 564     */
 565     bool EndListStyle();
 566
 567     /**
 568         Ends application of a numbered bullet.
 569     */
 570     bool EndNumberedBullet();
 571
 572     /**
 573         Ends paragraph spacing.
 574     */
 575     bool EndParagraphSpacing();
 576
 577     /**
 578         Ends application of a named character style.
 579     */
 580     bool EndParagraphStyle();
 581
 582     /**
 583         Ends right indent.
 584     */
 585     bool EndRightIndent();
 586
 587     /**
 588         Ends the current style.
 589     */
 590     virtual bool EndStyle();
 591
 592     /**
 593         Ends suppressing undo command history.
 594     */
 595     virtual bool EndSuppressUndo();
 596
 597     /**
 598         Ends applying a symbol bullet.
 599     */
 600     bool EndSymbolBullet();
 601
 602     /**
 603         Ends applying a text colour.
 604     */
 605     bool EndTextColour();
 606
 607     /**
 608         Ends applying a URL.
 609     */
 610     bool EndURL();
 611
 612     /**
 613         End applying underlining.
 614     */
 615     bool EndUnderline();
 616
 617     /**
 618         Helper function for extending the selection, returning @true if the selection
 619         was changed. Selections are in caret positions.
 620     */
 621     virtual bool ExtendSelection(long oldPosition, long newPosition, int flags);
 622
 623     /**
 624         Helper function for finding the caret position for the next word.
 625         Direction is 1 (forward) or -1 (backwards).
 626     */
 627     virtual long FindNextWordPosition(int direction = 1) const;
 628
 629     /**
 630         Call this function to prevent refresh and allow fast updates, and then Thaw() to
 631         refresh the control.
 632     */
 633     void Freeze();
 634
 635     /**
 636         Gets the basic (overall) style.
 637
 638         This is the style of the whole buffer before further styles are applied,
 639         unlike the default style, which only affects the style currently being
 640         applied (for example, setting the default style to bold will cause
 641         subsequently inserted text to be bold).
 642     */
 643     virtual const wxTextAttr& GetBasicStyle() const;
 644
 645     //@{
 646     /**
 647         Returns the buffer associated with the control.
 648     */
 649     const wxRichTextBuffer GetBuffer();
 650     const wxRichTextBuffer&  GetBuffer();
 651     //@}
 652
 653     /**
 654         Returns the current caret position.
 655     */
 656     long GetCaretPosition() const;
 657
 658     /**
 659         Returns the caret height and position for the given character position.
 660     */
 661     bool GetCaretPositionForIndex(long position, wxRect& rect);
 662
 663     /**
 664         Gets the command processor associated with the control's buffer.
 665     */
 666     wxCommandProcessor* GetCommandProcessor() const;
 667
 668     /**
 669         Returns the current default style, which can be used to change how subsequently
 670         inserted text is displayed.
 671     */
 672     virtual const wxTextAttr& GetDefaultStyle() const;
 673
 674     /**
 675         Gets the size of the buffer beyond which layout is delayed during resizing.
 676         This optimizes sizing for large buffers. The default is 20000.
 677     */
 678     long GetDelayedLayoutThreshold() const;
 679
 680     /**
 681         Gets the current filename associated with the control.
 682     */
 683     wxString GetFilename() const;
 684
 685     /**
 686         Returns the first visible position in the current view.
 687     */
 688     long GetFirstVisiblePosition() const;
 689
 690     /**
 691         Returns flags that change the behaviour of loading or saving.
 692         See the documentation for each handler class to see what flags are
 693         relevant for each handler.
 694     */
 695     int GetHandlerFlags() const;
 696
 697     /**
 698         Returns the current insertion point.
 699     */
 700     virtual long GetInsertionPoint() const;
 701
 702     /**
 703         Returns the last position in the buffer.
 704     */
 705     virtual wxTextPos GetLastPosition() const;
 706
 707     /**
 708         Returns the length of the specified line in characters.
 709     */
 710     virtual int GetLineLength(long lineNo) const;
 711
 712     /**
 713         Returns the text for the given line.
 714     */
 715     virtual wxString GetLineText(long lineNo) const;
 716
 717     /**
 718         Transforms physical window position to logical (unscrolled) position.
 719     */
 720     wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const;
 721
 722     /**
 723         Returns the number of lines in the buffer.
 724     */
 725     virtual int GetNumberOfLines() const;
 726
 727     /**
 728         Transforms logical (unscrolled) position to physical window position.
 729     */
 730     wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const;
 731
 732     /**
 733         Gets the text for the given range.
 734         The end point of range is specified as the last character position of
 735         the span of text, plus one.
 736     */
 737     virtual wxString GetRange(long from, long to) const;
 738
 739     /**
 740         Returns the range of the current selection.
 741         The end point of range is specified as the last character position of the span
 742         of text, plus one.
 743         If the return values @a from and @a to are the same, there is no selection.
 744     */
 745     virtual void GetSelection(long* from, long* to) const;
 746
 747     /**
 748         Returns the selection range in character positions. -1, -1 means no selection.
 749     */
 750     wxRichTextRange GetSelectionRange() const;
 751
 752     /**
 753         Returns the text within the current selection range, if any.
 754     */
 755     virtual wxString GetStringSelection() const;
 756
 757     /**
 758         Gets the attributes at the given position.
 759         This function gets the combined style - that is, the style you see on the
 760         screen as a result of combining base style, paragraph style and character
 761         style attributes.
 762
 763         To get the character or paragraph style alone, use GetUncombinedStyle().
 764     */
 765     virtual bool GetStyle(long position, wxTextAttr& style);
 766
 767     /**
 768         Gets the attributes common to the specified range.
 769         Attributes that differ in value within the range will not be included
 770         in @a style flags.
 771     */
 772     virtual bool GetStyleForRange(const wxRichTextRange& range,
 773                                   wxTextAttr& style);
 774
 775     /**
 776         Returns the style sheet associated with the control, if any.
 777         A style sheet allows named character and paragraph styles to be applied.
 778     */
 779     wxRichTextStyleSheet* GetStyleSheet() const;
 780
 781     /**
 782         Gets the attributes at the given position.
 783         This function gets the @e uncombined style - that is, the attributes associated
 784         with the paragraph or character content, and not necessarily the combined
 785         attributes you see on the screen.
 786         To get the combined attributes, use GetStyle().
 787
 788         If you specify (any) paragraph attribute in @e style's flags, this function
 789         will fetch the paragraph attributes.
 790         Otherwise, it will return the character attributes.
 791     */
 792     virtual bool GetUncombinedStyle(long position, wxTextAttr& style);
 793
 794     /**
 795         Returns the content of the entire control as a string.
 796     */
 797     virtual wxString GetValue() const;
 798
 799     /**
 800         Internal helper function returning the line for the visible caret position.
 801         If the caret is shown at the very end of the line, it means the next character
 802         is actually on the following line.
 803         So this function gets the line we're expecting to find if this is the case.
 804     */
 805     wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const;
 806
 807     /**
 808         Test if this whole range has character attributes of the specified kind.
 809         If any of the attributes are different within the range, the test fails.
 810
 811         You can use this to implement, for example, bold button updating.
 812         @a style must have flags indicating which attributes are of interest.
 813     */
 814     virtual bool HasCharacterAttributes(const wxRichTextRange& range,
 815                                         const wxTextAttr& style) const;
 816
 817     /**
 818         Test if this whole range has paragraph attributes of the specified kind.
 819         If any of the attributes are different within the range, the test fails.
 820         You can use this to implement, for example, centering button updating.
 821         @a style must have flags indicating which attributes are of interest.
 822     */
 823     virtual bool HasParagraphAttributes(const wxRichTextRange& range,
 824                                         const wxTextAttr& style) const;
 825
 826     /**
 827         Returns @true if there is a selection.
 828     */
 829     virtual bool HasSelection() const;
 830
 831     //@{
 832     /**
 833         Finds the character at the given position in pixels.
 834         @a pt is in device coords (not adjusted for the client area origin nor for
 835         scrolling).
 836     */
 837     wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos) const;
 838     const wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
 839                                           wxTextCoord* col,
 840                                           wxTextCoord* row) const;
 841     //@}
 842
 843     /**
 844         Initialises the members of the control.
 845     */
 846     void Init();
 847
 848     /**
 849         Returns @true if the user has recently set the default style without moving
 850         the caret, and therefore the UI needs to reflect the default style and not
 851         the style at the caret.
 852
 853         Below is an example of code that uses this function to determine whether the UI
 854         should show that the current style is bold.
 855
 856         @see SetAndShowDefaultStyle().
 857     */
 858     bool IsDefaultStyleShowing() const;
 859
 860     /**
 861         Returns @true if the control is editable.
 862     */
 863     virtual bool IsEditable() const;
 864
 865     /**
 866         Returns @true if Freeze has been called without a Thaw.
 867     */
 868     bool IsFrozen() const;
 869
 870     /**
 871         Returns @true if the buffer has been modified.
 872     */
 873     virtual bool IsModified() const;
 874
 875     /**
 876         Returns @true if the control is multiline.
 877     */
 878     bool IsMultiLine() const;
 879
 880     /**
 881         Returns @true if the given position is visible on the screen.
 882     */
 883     bool IsPositionVisible(long pos) const;
 884
 885     /**
 886         Returns @true if all of the selection is aligned according to the specified flag.
 887     */
 888     virtual bool IsSelectionAligned(wxTextAttrAlignment alignment);
 889
 890     /**
 891         Returns @true if all of the selection is bold.
 892     */
 893     virtual bool IsSelectionBold();
 894
 895     /**
 896         Returns @true if all of the selection is italic.
 897     */
 898     virtual bool IsSelectionItalics();
 899
 900     /**
 901         Returns @true if all of the selection is underlined.
 902     */
 903     virtual bool IsSelectionUnderlined();
 904
 905     /**
 906         Returns @true if the control is single-line.
 907         Currently wxRichTextCtrl does not support single-line editing.
 908     */
 909     bool IsSingleLine() const;
 910
 911     /**
 912         Helper function implementing keyboard navigation.
 913     */
 914     virtual bool KeyboardNavigate(int keyCode, int flags);
 915
 916     /**
 917         Lays out the buffer, which must be done before certain operations, such as
 918         setting the caret position.
 919         This function should not normally be required by the application.
 920     */
 921     virtual bool LayoutContent(bool onlyVisibleRect = false);
 922
 923     /**
 924         Inserts a line break at the current insertion point.
 925
 926         A line break forces wrapping within a paragraph, and can be introduced by
 927         using this function, by appending the wxChar value @b  wxRichTextLineBreakChar
 928         to text content, or by typing Shift-Return.
 929     */
 930     virtual bool LineBreak();
 931
 932     /**
 933         Loads content into the control's buffer using the given type.
 934
 935         If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from
 936         the filename extension.
 937
 938         This function looks for a suitable wxRichTextFileHandler object.
 939     */
 940     bool LoadFile(const wxString& file,
 941                   int type = wxRICHTEXT_TYPE_ANY);
 942
 943     /**
 944         Marks the buffer as modified.
 945     */
 946     virtual void MarkDirty();
 947
 948     /**
 949         Move the caret to the given character position.
 950     */
 951     virtual bool MoveCaret(long pos, bool showAtLineStart = false);
 952
 953     /**
 954         Move the caret one visual step forward: this may mean setting a flag
 955         and keeping the same position if we're going from the end of one line
 956         to the start of the next, which may be the exact same caret position.
 957     */
 958     void MoveCaretBack(long oldPosition);
 959
 960     /**
 961         Move the caret one visual step forward: this may mean setting a flag
 962         and keeping the same position if we're going from the end of one line
 963         to the start of the next, which may be the exact same caret position.
 964     */
 965     void MoveCaretForward(long oldPosition);
 966
 967     /**
 968         Moves the caret down.
 969     */
 970     virtual bool MoveDown(int noLines = 1, int flags = 0);
 971
 972     /**
 973         Moves to the end of the buffer.
 974     */
 975     virtual bool MoveEnd(int flags = 0);
 976
 977     /**
 978         Moves to the start of the buffer.
 979     */
 980     virtual bool MoveHome(int flags = 0);
 981
 982     /**
 983         Moves left.
 984     */
 985     virtual bool MoveLeft(int noPositions = 1, int flags = 0);
 986
 987     /**
 988         Moves right.
 989     */
 990     virtual bool MoveRight(int noPositions = 1, int flags = 0);
 991
 992     /**
 993         Moves to the end of the line.
 994     */
 995     virtual bool MoveToLineEnd(int flags = 0);
 996
 997     /**
 998         Moves to the start of the line.
 999     */
1000     virtual bool MoveToLineStart(int flags = 0);
1001
1002     /**
1003         Moves to the end of the paragraph.
1004     */
1005     virtual bool MoveToParagraphEnd(int flags = 0);
1006
1007     /**
1008         Moves to the start of the paragraph.
1009     */
1010     virtual bool MoveToParagraphStart(int flags = 0);
1011
1012     /**
1013         Moves up.
1014     */
1015     virtual bool MoveUp(int noLines = 1, int flags = 0);
1016
1017     /**
1018         Inserts a new paragraph at the current insertion point. @see LineBreak().
1019     */
1020     virtual bool Newline();
1021
1022     //@{
1023     /**
1024         Numbers the paragraphs in the given range.
1025         Pass flags to determine how the attributes are set.
1026
1027         Either the style definition or the name of the style definition (in the current
1028         sheet) can be passed.
1029
1030         @a flags is a bit list of the following:
1031         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1032         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
1033           @a startFrom, otherwise existing attributes are used.
1034         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1035           as the level for all paragraphs, otherwise the current indentation will be used.
1036
1037         @see SetListStyle(), PromoteList(), ClearListStyle().
1038     */
1039     bool NumberList(const wxRichTextRange& range,
1040                     const wxRichTextListStyleDefinition* style,
1041                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1042                     int startFrom = -1,
1043                     int listLevel = -1);
1044     bool Number(const wxRichTextRange& range,
1045                 const wxString& styleName,
1046                 int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1047                 int startFrom = -1,
1048                 int listLevel = -1);
1049     //@}
1050
1051     /**
1052         Standard handler for the wxID_CLEAR command.
1053     */
1054     void OnClear(wxCommandEvent& event);
1055
1056     /**
1057         Shows a standard context menu with undo, redo, cut, copy, paste, clear, and
1058         select all commands.
1059     */
1060     void OnContextMenu(wxContextMenuEvent& event);
1061
1062     /**
1063         Standard handler for the wxID_COPY command.
1064     */
1065     void OnCopy(wxCommandEvent& event);
1066
1067     /**
1068         Standard handler for the wxID_CUT command.
1069     */
1070     void OnCut(wxCommandEvent& event);
1071
1072     /**
1073         Loads the first dropped file.
1074     */
1075     void OnDropFiles(wxDropFilesEvent& event);
1076
1077     /**
1078         Standard handler for the wxID_PASTE command.
1079     */
1080     void OnPaste(wxCommandEvent& event);
1081
1082     /**
1083         Standard handler for the wxID_REDO command.
1084     */
1085     void OnRedo(wxCommandEvent& event);
1086
1087     /**
1088         Standard handler for the wxID_SELECTALL command.
1089     */
1090     void OnSelectAll(wxCommandEvent& event);
1091
1092     /**
1093         Standard handler for the wxID_PASTE command.
1094     */
1095     void OnUndo(wxCommandEvent& event);
1096
1097     /**
1098         Standard update handler for the wxID_CLEAR command.
1099     */
1100     void OnUpdateClear(wxUpdateUIEvent& event);
1101
1102     /**
1103         Standard update handler for the wxID_COPY command.
1104     */
1105     void OnUpdateCopy(wxUpdateUIEvent& event);
1106
1107     /**
1108         Standard update handler for the wxID_CUT command.
1109     */
1110     void OnUpdateCut(wxUpdateUIEvent& event);
1111
1112     /**
1113         Standard update handler for the wxID_PASTE command.
1114     */
1115     void OnUpdatePaste(wxUpdateUIEvent& event);
1116
1117     /**
1118         Standard update handler for the wxID_REDO command.
1119     */
1120     void OnUpdateRedo(wxUpdateUIEvent& event);
1121
1122     /**
1123         Standard update handler for the wxID_SELECTALL command.
1124     */
1125     void OnUpdateSelectAll(wxUpdateUIEvent& event);
1126
1127     /**
1128         Standard update handler for the wxID_UNDO command.
1129     */
1130     void OnUpdateUndo(wxUpdateUIEvent& event);
1131
1132     /**
1133         Moves one or more pages down.
1134     */
1135     virtual bool PageDown(int noPages = 1, int flags = 0);
1136
1137     /**
1138         Moves one or more pages up.
1139     */
1140     virtual bool PageUp(int noPages = 1, int flags = 0);
1141
1142     /**
1143         Paints the background.
1144     */
1145     virtual void PaintBackground(wxDC& dc);
1146
1147     /**
1148         Pastes content from the clipboard to the buffer.
1149     */
1150     virtual void Paste();
1151
1152     /**
1153         Internal function to position the visible caret according to the current caret
1154         position.
1155     */
1156     virtual void PositionCaret();
1157
1158     /**
1159         Converts a text position to zero-based column and line numbers.
1160     */
1161     virtual bool PositionToXY(long pos, long* x, long* y) const;
1162
1163     //@{
1164     /**
1165         Promotes or demotes the paragraphs in the given range.
1166         A positive @a promoteBy produces a smaller indent, and a negative number
1167         produces a larger indent. Pass flags to determine how the attributes are set.
1168         Either the style definition or the name of the style definition (in the current
1169         sheet) can be passed.
1170
1171         @a flags is a bit list of the following:
1172         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1173         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
1174           @a startFrom, otherwise existing attributes are used.
1175         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1176         as the level for all paragraphs, otherwise the current indentation will be used.
1177
1178         @see SetListStyle(), @see SetListStyle(), ClearListStyle().
1179     */
1180     bool PromoteList(int promoteBy, const wxRichTextRange& range,
1181                      const wxRichTextListStyleDefinition* style,
1182                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1183                      int listLevel = -1);
1184     bool PromoteList(int promoteBy, const wxRichTextRange& range,
1185                      const wxString& styleName,
1186                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1187                      int listLevel = -1);
1188     //@}
1189
1190     /**
1191         Redoes the current command.
1192     */
1193     virtual void Redo();
1194
1195     /**
1196         Removes the content in the specified range.
1197     */
1198     virtual void Remove(long from, long to);
1199
1200     /**
1201         Replaces the content in the specified range with the string specified by
1202         @a value.
1203     */
1204     virtual void Replace(long from, long to, const wxString& value);
1205
1206     /**
1207         Saves the buffer content using the given type.
1208
1209         If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from
1210         the filename extension.
1211
1212         This function looks for a suitable wxRichTextFileHandler object.
1213     */
1214     bool SaveFile(const wxString& file = wxEmptyString,
1215                   int type = wxRICHTEXT_TYPE_ANY);
1216
1217     /**
1218         Scrolls @a position into view. This function takes a caret position.
1219     */
1220     virtual bool ScrollIntoView(long position, int keyCode);
1221
1222     /**
1223         Selects all the text in the buffer.
1224     */
1225     virtual void SelectAll();
1226
1227     /**
1228         Cancels any selection.
1229     */
1230     virtual void SelectNone();
1231
1232     /**
1233         Sets @a attr as the default style and tells the control that the UI should
1234         reflect this attribute until the user moves the caret.
1235
1236         @see IsDefaultStyleShowing().
1237     */
1238     void SetAndShowDefaultStyle(const wxTextAttr& attr);
1239
1240     /**
1241         Sets the basic (overall) style.
1242
1243         This is the style of the whole buffer before further styles are applied,
1244         unlike the default style, which only affects the style currently being
1245         applied (for example, setting the default style to bold will cause
1246         subsequently inserted text to be bold).
1247     */
1248     virtual void SetBasicStyle(const wxTextAttr& style);
1249
1250     /**
1251         The caret position is the character position just before the caret.
1252         A value of -1 means the caret is at the start of the buffer.
1253     */
1254     void SetCaretPosition(long position,
1255                           bool showAtLineStart = false);
1256
1257     /**
1258         Sets the current default style, which can be used to change how subsequently
1259         inserted text is displayed.
1260     */
1261     virtual bool SetDefaultStyle(const wxTextAttr& style);
1262
1263     /**
1264         Sets the default style to the style under the cursor.
1265     */
1266     bool SetDefaultStyleToCursorStyle();
1267
1268     /**
1269         Sets the size of the buffer beyond which layout is delayed during resizing.
1270         This optimizes sizing for large buffers. The default is 20000.
1271     */
1272     void SetDelayedLayoutThreshold(long threshold);
1273
1274     /**
1275         Makes the control editable, or not.
1276     */
1277     virtual void SetEditable(bool editable);
1278
1279     /**
1280         Sets the current filename.
1281     */
1282     void SetFilename(const wxString& filename);
1283
1284     /**
1285         Sets the font, and also the basic and default attributes
1286         (see wxRichTextCtrl::SetDefaultStyle).
1287     */
1288     virtual bool SetFont(const wxFont& font);
1289
1290     /**
1291         Sets flags that change the behaviour of loading or saving.
1292
1293         See the documentation for each handler class to see what flags are
1294         relevant for each handler.
1295     */
1296     void SetHandlerFlags(int flags);
1297
1298     /**
1299         Sets the insertion point.
1300     */
1301     virtual void SetInsertionPoint(long pos);
1302
1303     /**
1304         Sets the insertion point to the end of the text control.
1305     */
1306     virtual void SetInsertionPointEnd();
1307
1308     //@{
1309     /**
1310         Sets the list attributes for the given range, passing flags to determine how
1311         the attributes are set.
1312
1313         Either the style definition or the name of the style definition (in the current
1314         sheet) can be passed.
1315         @a flags is a bit list of the following:
1316         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1317         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
1318           @a startFrom, otherwise existing attributes are used.
1319         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1320           as the level for all paragraphs, otherwise the current indentation will be used.
1321
1322         @see NumberList(), PromoteList(), ClearListStyle().
1323     */
1324     bool SetListStyle(const wxRichTextRange& range,
1325                       const wxRichTextListStyleDefinition* style,
1326                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1327                       int startFrom = -1,
1328                       int listLevel = -1);
1329     bool SetListStyle(const wxRichTextRange& range,
1330                       const wxString& styleName,
1331                       int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1332                       int startFrom = -1,
1333                       int listLevel = -1);
1334     //@}
1335
1336     /**
1337         Sets the selection to the given range.
1338         The end point of range is specified as the last character position of the span
1339         of text, plus one.
1340
1341         So, for example, to set the selection for a character at position 5, use the
1342         range (5,6).
1343     */
1344     virtual void SetSelection(long from, long to);
1345
1346     /**
1347         Sets the selection to the given range.
1348         The end point of range is specified as the last character position of the span
1349         of text, plus one.
1350
1351         So, for example, to set the selection for a character at position 5, use the
1352         range (5,6).
1353     */
1354     void SetSelectionRange(const wxRichTextRange& range);
1355
1356     //@{
1357     /**
1358         Sets the attributes for the given range.
1359         The end point of range is specified as the last character position of the span
1360         of text, plus one.
1361
1362         So, for example, to set the style for a character at position 5, use the range
1363         (5,6).
1364     */
1365     bool SetStyle(const wxRichTextRange& range,
1366                   const wxTextAttr& style);
1367     bool SetStyle(long start, long end, const wxTextAttr& style);
1368     //@}
1369
1370     //@{
1371     /**
1372         Sets the attributes for the given range, passing flags to determine how the
1373         attributes are set.
1374
1375         The end point of range is specified as the last character position of the span
1376         of text, plus one. So, for example, to set the style for a character at
1377         position 5, use the range (5,6).
1378
1379         @a flags may contain a bit list of the following values:
1380         - wxRICHTEXT_SETSTYLE_NONE: no style flag.
1381         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
1382           undoable.
1383         - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
1384           if the combined style at this point is already the style in question.
1385         - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
1386           applied to paragraphs, and not the content.
1387           This allows content styling to be preserved independently from that
1388           of e.g. a named paragraph style.
1389         - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
1390           applied to characters, and not the paragraph.
1391           This allows content styling to be preserved independently from that
1392           of e.g. a named paragraph style.
1393         - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
1394           the new style.
1395         - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags
1396           are used in this operation.
1397     */
1398     bool SetStyleEx(const wxRichTextRange& range,
1399                     const wxTextAttr& style,
1400                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
1401     bool SetStyleEx(long start, long end,
1402                     const wxTextAttr& style,
1403                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
1404     //@}
1405
1406     /**
1407         Sets the style sheet associated with the control.
1408         A style sheet allows named character and paragraph styles to be applied.
1409     */
1410     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
1411
1412     /**
1413         Replaces existing content with the given text.
1414     */
1415     virtual void SetValue(const wxString& value);
1416
1417     /**
1418         A helper function setting up scrollbars, for example after a resize.
1419     */
1420     virtual void SetupScrollbars(bool atTop = false);
1421
1422     /**
1423         Scrolls the buffer so that the given position is in view.
1424     */
1425     virtual void ShowPosition(long pos);
1426
1427     /**
1428         Returns @true if undo history suppression is on.
1429     */
1430     virtual bool SuppressingUndo() const;
1431
1432     /**
1433         Call this function to end a Freeze and refresh the display.
1434     */
1435     void Thaw();
1436
1437     /**
1438         Undoes the command at the top of the command history, if there is one.
1439     */
1440     virtual void Undo();
1441
1442     /**
1443         Moves a number of words to the left.
1444     */
1445     virtual bool WordLeft(int noWords = 1, int flags = 0);
1446
1447     /**
1448         Move a nuber of words to the right.
1449     */
1450     virtual bool WordRight(int noWords = 1, int flags = 0);
1451
1452     /**
1453         Loads an image from a file and writes it at the current insertion point.
1454     */
1455     virtual bool WriteImage(const wxString& filename, wxBitmapType bitmapType);
1456
1457     /**
1458         Writes an image block at the current insertion point.
1459     */
1460     virtual bool WriteImage(const wxRichTextImageBlock& imageBlock);
1461
1462     //@{
1463     /**
1464         Write a bitmap or image at the current insertion point.
1465         Supply an optional type to use for internal and file storage of the raw data.
1466     */
1467     bool WriteImage(const wxBitmap& bitmap,
1468                     int bitmapType = wxBITMAP_TYPE_PNG);
1469     bool WriteImage(const wxImage& image,
1470                     int bitmapType = wxBITMAP_TYPE_PNG);
1471     //@}
1472
1473     /**
1474         Writes text at the current position.
1475     */
1476     virtual void WriteText(const wxString& text);
1477
1478     /**
1479         Translates from column and line number to position.
1480     */
1481     virtual long XYToPosition(long x, long y) const;
1482
1483 protected:
1484
1485     /**
1486         Currently this simply returns @c wxSize(10, 10).
1487     */
1488     virtual wxSize DoGetBestSize() const;
1489
1490     /**
1491         Initialises the command event.
1492     */
1493     void InitCommandEvent(wxCommandEvent& event) const;
1494 };
1495