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