interface/wx/richtext/richtextctrl.h

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