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