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         Please note that this does not update the current editing style
 958         from the new position; to do that, call wxRichTextCtrl::SetInsertionPoint instead.
 959     */
 960     virtual bool MoveCaret(long pos, bool showAtLineStart = false);
 961
 962     /**
 963         Move the caret one visual step forward: this may mean setting a flag
 964         and keeping the same position if we're going from the end of one line
 965         to the start of the next, which may be the exact same caret position.
 966     */
 967     void MoveCaretBack(long oldPosition);
 968
 969     /**
 970         Move the caret one visual step forward: this may mean setting a flag
 971         and keeping the same position if we're going from the end of one line
 972         to the start of the next, which may be the exact same caret position.
 973     */
 974     void MoveCaretForward(long oldPosition);
 975
 976     /**
 977         Moves the caret down.
 978     */
 979     virtual bool MoveDown(int noLines = 1, int flags = 0);
 980
 981     /**
 982         Moves to the end of the buffer.
 983     */
 984     virtual bool MoveEnd(int flags = 0);
 985
 986     /**
 987         Moves to the start of the buffer.
 988     */
 989     virtual bool MoveHome(int flags = 0);
 990
 991     /**
 992         Moves left.
 993     */
 994     virtual bool MoveLeft(int noPositions = 1, int flags = 0);
 995
 996     /**
 997         Moves right.
 998     */
 999     virtual bool MoveRight(int noPositions = 1, int flags = 0);
1000
1001     /**
1002         Moves to the end of the line.
1003     */
1004     virtual bool MoveToLineEnd(int flags = 0);
1005
1006     /**
1007         Moves to the start of the line.
1008     */
1009     virtual bool MoveToLineStart(int flags = 0);
1010
1011     /**
1012         Moves to the end of the paragraph.
1013     */
1014     virtual bool MoveToParagraphEnd(int flags = 0);
1015
1016     /**
1017         Moves to the start of the paragraph.
1018     */
1019     virtual bool MoveToParagraphStart(int flags = 0);
1020
1021     /**
1022         Moves up.
1023     */
1024     virtual bool MoveUp(int noLines = 1, int flags = 0);
1025
1026     /**
1027         Inserts a new paragraph at the current insertion point. @see LineBreak().
1028     */
1029     virtual bool Newline();
1030
1031     //@{
1032     /**
1033         Numbers the paragraphs in the given range.
1034         Pass flags to determine how the attributes are set.
1035
1036         Either the style definition or the name of the style definition (in the current
1037         sheet) can be passed.
1038
1039         @a flags is a bit list of the following:
1040         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1041         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
1042           @a startFrom, otherwise existing attributes are used.
1043         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1044           as the level for all paragraphs, otherwise the current indentation will be used.
1045
1046         @see SetListStyle(), PromoteList(), ClearListStyle().
1047     */
1048     bool NumberList(const wxRichTextRange& range,
1049                     const wxRichTextListStyleDefinition* style,
1050                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1051                     int startFrom = -1,
1052                     int listLevel = -1);
1053     bool Number(const wxRichTextRange& range,
1054                 const wxString& styleName,
1055                 int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1056                 int startFrom = -1,
1057                 int listLevel = -1);
1058     //@}
1059
1060     /**
1061         Standard handler for the wxID_CLEAR command.
1062     */
1063     void OnClear(wxCommandEvent& event);
1064
1065     /**
1066         Shows a standard context menu with undo, redo, cut, copy, paste, clear, and
1067         select all commands.
1068     */
1069     void OnContextMenu(wxContextMenuEvent& event);
1070
1071     /**
1072         Standard handler for the wxID_COPY command.
1073     */
1074     void OnCopy(wxCommandEvent& event);
1075
1076     /**
1077         Standard handler for the wxID_CUT command.
1078     */
1079     void OnCut(wxCommandEvent& event);
1080
1081     /**
1082         Loads the first dropped file.
1083     */
1084     void OnDropFiles(wxDropFilesEvent& event);
1085
1086     /**
1087         Standard handler for the wxID_PASTE command.
1088     */
1089     void OnPaste(wxCommandEvent& event);
1090
1091     /**
1092         Standard handler for the wxID_REDO command.
1093     */
1094     void OnRedo(wxCommandEvent& event);
1095
1096     /**
1097         Standard handler for the wxID_SELECTALL command.
1098     */
1099     void OnSelectAll(wxCommandEvent& event);
1100
1101     /**
1102         Standard handler for the wxID_PASTE command.
1103     */
1104     void OnUndo(wxCommandEvent& event);
1105
1106     /**
1107         Standard update handler for the wxID_CLEAR command.
1108     */
1109     void OnUpdateClear(wxUpdateUIEvent& event);
1110
1111     /**
1112         Standard update handler for the wxID_COPY command.
1113     */
1114     void OnUpdateCopy(wxUpdateUIEvent& event);
1115
1116     /**
1117         Standard update handler for the wxID_CUT command.
1118     */
1119     void OnUpdateCut(wxUpdateUIEvent& event);
1120
1121     /**
1122         Standard update handler for the wxID_PASTE command.
1123     */
1124     void OnUpdatePaste(wxUpdateUIEvent& event);
1125
1126     /**
1127         Standard update handler for the wxID_REDO command.
1128     */
1129     void OnUpdateRedo(wxUpdateUIEvent& event);
1130
1131     /**
1132         Standard update handler for the wxID_SELECTALL command.
1133     */
1134     void OnUpdateSelectAll(wxUpdateUIEvent& event);
1135
1136     /**
1137         Standard update handler for the wxID_UNDO command.
1138     */
1139     void OnUpdateUndo(wxUpdateUIEvent& event);
1140
1141     /**
1142         Moves one or more pages down.
1143     */
1144     virtual bool PageDown(int noPages = 1, int flags = 0);
1145
1146     /**
1147         Moves one or more pages up.
1148     */
1149     virtual bool PageUp(int noPages = 1, int flags = 0);
1150
1151     /**
1152         Paints the background.
1153     */
1154     virtual void PaintBackground(wxDC& dc);
1155
1156     /**
1157         Pastes content from the clipboard to the buffer.
1158     */
1159     virtual void Paste();
1160
1161     /**
1162         Internal function to position the visible caret according to the current caret
1163         position.
1164     */
1165     virtual void PositionCaret();
1166
1167     /**
1168         Converts a text position to zero-based column and line numbers.
1169     */
1170     virtual bool PositionToXY(long pos, long* x, long* y) const;
1171
1172     //@{
1173     /**
1174         Promotes or demotes the paragraphs in the given range.
1175         A positive @a promoteBy produces a smaller indent, and a negative number
1176         produces a larger indent. Pass flags to determine how the attributes are set.
1177         Either the style definition or the name of the style definition (in the current
1178         sheet) can be passed.
1179
1180         @a flags is a bit list of the following:
1181         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
1182         - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
1183           @a startFrom, otherwise existing attributes are used.
1184         - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
1185         as the level for all paragraphs, otherwise the current indentation will be used.
1186
1187         @see SetListStyle(), @see SetListStyle(), ClearListStyle().
1188     */
1189     bool PromoteList(int promoteBy, const wxRichTextRange& range,
1190                      const wxRichTextListStyleDefinition* style,
1191                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1192                      int listLevel = -1);
1193     bool PromoteList(int promoteBy, const wxRichTextRange& range,
1194                      const wxString& styleName,
1195                      int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO,
1196                      int listLevel = -1);
1197     //@}
1198
1199     /**
1200         Redoes the current command.
1201     */
1202     virtual void Redo();
1203
1204     /**
1205         Removes the content in the specified range.
1206     */
1207     virtual void Remove(long from, long to);
1208
1209     /**
1210         Replaces the content in the specified range with the string specified by
1211         @a value.
1212     */
1213     virtual void Replace(long from, long to, const wxString& value);
1214
1215     /**
1216         Saves the buffer content using the given type.
1217
1218         If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from
1219         the filename extension.
1220
1221         This function looks for a suitable wxRichTextFileHandler object.
1222     */
1223     bool SaveFile(const wxString& file = wxEmptyString,
1224                   int type = wxRICHTEXT_TYPE_ANY);
1225
1226     /**
1227         Scrolls @a position into view. This function takes a caret position.
1228     */
1229     virtual bool ScrollIntoView(long position, int keyCode);
1230
1231     /**
1232         Selects all the text in the buffer.
1233     */
1234     virtual void SelectAll();
1235
1236     /**
1237         Cancels any selection.
1238     */
1239     virtual void SelectNone();
1240
1241     /**
1242         Sets @a attr as the default style and tells the control that the UI should
1243         reflect this attribute until the user moves the caret.
1244
1245         @see IsDefaultStyleShowing().
1246     */
1247     void SetAndShowDefaultStyle(const wxTextAttr& attr);
1248
1249     /**
1250         Sets the basic (overall) style.
1251
1252         This is the style of the whole buffer before further styles are applied,
1253         unlike the default style, which only affects the style currently being
1254         applied (for example, setting the default style to bold will cause
1255         subsequently inserted text to be bold).
1256     */
1257     virtual void SetBasicStyle(const wxTextAttr& style);
1258
1259     /**
1260         Sets the caret position.
1261
1262         The caret position is the character position just before the caret.
1263         A value of -1 means the caret is at the start of the buffer.
1264         Please note that this does not update the current editing style
1265         from the new position or cause the actual caret to be refreshed; to do that,
1266         call wxRichTextCtrl::SetInsertionPoint instead.
1267     */
1268     void SetCaretPosition(long position,
1269                           bool showAtLineStart = false);
1270
1271     /**
1272         Sets the current default style, which can be used to change how subsequently
1273         inserted text is displayed.
1274     */
1275     virtual bool SetDefaultStyle(const wxTextAttr& style);
1276
1277     /**
1278         Sets the default style to the style under the cursor.
1279     */
1280     bool SetDefaultStyleToCursorStyle();
1281
1282     /**
1283         Sets the size of the buffer beyond which layout is delayed during resizing.
1284         This optimizes sizing for large buffers. The default is 20000.
1285     */
1286     void SetDelayedLayoutThreshold(long threshold);
1287
1288     /**
1289         Makes the control editable, or not.
1290     */
1291     virtual void SetEditable(bool editable);
1292
1293     /**
1294         Sets the current filename.
1295     */
1296     void SetFilename(const wxString& filename);
1297
1298     /**
1299         Sets the font, and also the basic and default attributes
1300         (see wxRichTextCtrl::SetDefaultStyle).
1301     */
1302     virtual bool SetFont(const wxFont& font);
1303
1304     /**
1305         Sets flags that change the behaviour of loading or saving.
1306
1307         See the documentation for each handler class to see what flags are
1308         relevant for each handler.
1309     */
1310     void SetHandlerFlags(int flags);
1311
1312     /**
1313         Sets the insertion point and causes the current editing style to be taken from
1314         the new position (unlike wxRichTextCtrl::SetCaretPosition).
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         Sets the attributes for the given range, passing flags to determine how the
1387         attributes are set.
1388
1389         The end point of range is specified as the last character position of the span
1390         of text, plus one. So, for example, to set the style for a character at
1391         position 5, use the range (5,6).
1392
1393         @a flags may contain a bit list of the following values:
1394         - wxRICHTEXT_SETSTYLE_NONE: no style flag.
1395         - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
1396           undoable.
1397         - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
1398           if the combined style at this point is already the style in question.
1399         - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
1400           applied to paragraphs, and not the content.
1401           This allows content styling to be preserved independently from that
1402           of e.g. a named paragraph style.
1403         - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
1404           applied to characters, and not the paragraph.
1405           This allows content styling to be preserved independently from that
1406           of e.g. a named paragraph style.
1407         - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
1408           the new style.
1409         - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags
1410           are used in this operation.
1411     */
1412     virtual bool SetStyleEx(const wxRichTextRange& range,
1413                     const wxTextAttr& style,
1414                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
1415
1416     /**
1417         Sets the style sheet associated with the control.
1418         A style sheet allows named character and paragraph styles to be applied.
1419     */
1420     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
1421
1422     /**
1423         Replaces existing content with the given text.
1424     */
1425     virtual void SetValue(const wxString& value);
1426
1427     /**
1428         A helper function setting up scrollbars, for example after a resize.
1429     */
1430     virtual void SetupScrollbars(bool atTop = false);
1431
1432     /**
1433         Scrolls the buffer so that the given position is in view.
1434     */
1435     virtual void ShowPosition(long pos);
1436
1437     /**
1438         Returns @true if undo history suppression is on.
1439     */
1440     virtual bool SuppressingUndo() const;
1441
1442     /**
1443         Call this function to end a Freeze and refresh the display.
1444     */
1445     void Thaw();
1446
1447     /**
1448         Undoes the command at the top of the command history, if there is one.
1449     */
1450     virtual void Undo();
1451
1452     /**
1453         Moves a number of words to the left.
1454     */
1455     virtual bool WordLeft(int noWords = 1, int flags = 0);
1456
1457     /**
1458         Move a nuber of words to the right.
1459     */
1460     virtual bool WordRight(int noWords = 1, int flags = 0);
1461
1462     /**
1463         Loads an image from a file and writes it at the current insertion point.
1464     */
1465     virtual bool WriteImage(const wxString& filename, wxBitmapType bitmapType);
1466
1467     /**
1468         Writes an image block at the current insertion point.
1469     */
1470     virtual bool WriteImage(const wxRichTextImageBlock& imageBlock);
1471
1472     //@{
1473     /**
1474         Write a bitmap or image at the current insertion point.
1475         Supply an optional type to use for internal and file storage of the raw data.
1476     */
1477     bool WriteImage(const wxBitmap& bitmap,
1478                     int bitmapType = wxBITMAP_TYPE_PNG);
1479     bool WriteImage(const wxImage& image,
1480                     int bitmapType = wxBITMAP_TYPE_PNG);
1481     //@}
1482
1483     /**
1484         Writes text at the current position.
1485     */
1486     virtual void WriteText(const wxString& text);
1487
1488     /**
1489         Translates from column and line number to position.
1490     */
1491     virtual long XYToPosition(long x, long y) const;
1492
1493 protected:
1494
1495     /**
1496         Currently this simply returns @c wxSize(10, 10).
1497     */
1498     virtual wxSize DoGetBestSize() const;
1499
1500     /**
1501         Initialises the command event.
1502     */
1503     void InitCommandEvent(wxCommandEvent& event) const;
1504 };
1505