interface/wx/richtext/richtextctrl.h

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