X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0004982c831f56c65c390fb617711ff52595c2f3..9df97be2c166a4d2c13e80f6a12411f03c2df023:/interface/wx/richtext/richtextctrl.h?ds=sidebyside diff --git a/interface/wx/richtext/richtextctrl.h b/interface/wx/richtext/richtextctrl.h index a3b6aa953d..d682329896 100644 --- a/interface/wx/richtext/richtextctrl.h +++ b/interface/wx/richtext/richtextctrl.h @@ -3,7 +3,7 @@ // Purpose: interface of wxRichTextCtrl and wxRichTextEvent // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -13,41 +13,41 @@ @beginEventTable{wxRichTextEvent} @event{EVT_RICHTEXT_CHARACTER(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_CHARACTER event, generated when the user + Process a @c wxEVT_COMMAND_RICHTEXT_CHARACTER event, generated when the user presses a character key. Valid event functions: GetFlags, GetPosition, GetCharacter. @event{EVT_RICHTEXT_DELETE(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_DELETE event, generated when the user + Process a @c wxEVT_COMMAND_RICHTEXT_DELETE event, generated when the user presses the backspace or delete key. Valid event functions: GetFlags, GetPosition. @event{EVT_RICHTEXT_RETURN(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_RETURN event, generated when the user + Process a @c wxEVT_COMMAND_RICHTEXT_RETURN event, generated when the user presses the return key. Valid event functions: GetFlags, GetPosition. @event{EVT_RICHTEXT_STYLE_CHANGED(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_STYLE_CHANGED event, generated when + Process a @c wxEVT_COMMAND_RICHTEXT_STYLE_CHANGED event, generated when styling has been applied to the control. Valid event functions: GetPosition, GetRange. @event{EVT_RICHTEXT_STYLESHEET_CHANGED(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING event, generated + Process a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING event, generated when the control's stylesheet has changed, for example the user added, edited or deleted a style. Valid event functions: GetRange, GetPosition. @event{EVT_RICHTEXT_STYLESHEET_REPLACING(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACING event, generated + Process a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACING event, generated when the control's stylesheet is about to be replaced, for example when a file is loaded into the control. Valid event functions: Veto, GetOldStyleSheet, GetNewStyleSheet. @event{EVT_RICHTEXT_STYLESHEET_REPLACED(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACED event, generated + Process a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACED event, generated when the control's stylesheet has been replaced, for example when a file is loaded into the control. Valid event functions: GetOldStyleSheet, GetNewStyleSheet. @event{EVT_RICHTEXT_CONTENT_INSERTED(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_CONTENT_INSERTED event, generated when + Process a @c wxEVT_COMMAND_RICHTEXT_CONTENT_INSERTED event, generated when content has been inserted into the control. Valid event functions: GetPosition, GetRange. @event{EVT_RICHTEXT_CONTENT_DELETED(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_CONTENT_DELETED event, generated when + Process a @c wxEVT_COMMAND_RICHTEXT_CONTENT_DELETED event, generated when content has been deleted from the control. Valid event functions: GetPosition, GetRange. @event{EVT_RICHTEXT_BUFFER_RESET(id, func)} - Process a wxEVT_COMMAND_RICHTEXT_BUFFER_RESET event, generated when the + Process a @c wxEVT_COMMAND_RICHTEXT_BUFFER_RESET event, generated when the buffer has been reset by deleting all content. You can use this to set a default style for the first new paragraph. @endEventTable @@ -74,35 +74,30 @@ public: wxRichTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); /** - Clones the event. - */ - wxEvent* Clone() const; - - /** - Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event. + Returns the character pressed, within a @c wxEVT_COMMAND_RICHTEXT_CHARACTER event. */ wxChar GetCharacter() const; /** Returns flags indicating modifier keys pressed. - Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + Possible values are @c wxRICHTEXT_CTRL_DOWN, @c wxRICHTEXT_SHIFT_DOWN, and @c wxRICHTEXT_ALT_DOWN. */ int GetFlags() const; /** Returns the new style sheet. - Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + Can be used in a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. */ wxRichTextStyleSheet* GetNewStyleSheet() const; /** Returns the old style sheet. - Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + Can be used in a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. */ wxRichTextStyleSheet* GetOldStyleSheet() const; @@ -114,7 +109,7 @@ public: /** Gets the range for the current operation. */ - wxRichTextRange GetRange() const; + const wxRichTextRange& GetRange() const; /** Sets the character variable. @@ -124,7 +119,7 @@ public: /** Sets flags indicating modifier keys pressed. - Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + Possible values are @c wxRICHTEXT_CTRL_DOWN, @c wxRICHTEXT_SHIFT_DOWN, and @c wxRICHTEXT_ALT_DOWN. */ void SetFlags(int flags); @@ -159,13 +154,24 @@ public: wxRichTextCtrl sends notification events: see wxRichTextEvent. - It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and - wxEVT_COMMAND_TEXT_UPDATED, and wxTextUrlEvent when URL content is clicked. + It also sends the standard wxTextCtrl events @c wxEVT_COMMAND_TEXT_ENTER and + @c wxEVT_COMMAND_TEXT_UPDATED, and wxTextUrlEvent when URL content is clicked. For more information, see the @ref overview_richtextctrl. + @beginStyleTable + @style{wxRE_CENTRE_CARET} + The control will try to keep the caret line centred vertically while editing. + wxRE_CENTER_CARET is a synonym for this style. + @style{wxRE_MULTILINE} + The control will be multiline (mandatory). + @style{wxRE_READONLY} + The control will not be editable. + @endStyleTable + @library{wxrichtext} @category{richtext} + @appearance{richtextctrl.png} */ class wxRichTextCtrl { @@ -389,7 +395,7 @@ public: See BeginNumberedBullet() for an explanation of how indentation is used to render the bulleted paragraph. */ - bool BeginSymbolBullet(wxChar symbol, int leftIndent, + bool BeginSymbolBullet(const wxString& symbol, int leftIndent, int leftSubIndent, int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); @@ -447,7 +453,6 @@ public: */ virtual void Clear(); - //@{ /** Clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph. @@ -457,11 +462,8 @@ public: @see SetListStyle(), PromoteList(), NumberList(). */ - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - bool ClearListStyle(const wxRichTextRange& range, + virtual bool ClearListStyle(const wxRichTextRange& range, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - //@} /** Sends the event to the control. @@ -499,6 +501,11 @@ public: Deletes content if there is a selection, e.g. when pressing a key. Returns the new caret position in @e newPos, or leaves it if there was no action. This is undoable. + + @beginWxPerlOnly + In wxPerl this method takes no arguments and returns a 2-element + list (ok, newPos). + @endWxPerlOnly */ bool DeleteSelectedContent(long* newPos = NULL); @@ -513,11 +520,6 @@ public: */ virtual void DiscardEdits(); - /** - Currently this simply returns @c wxSize(10, 10). - */ - virtual wxSize DoGetBestSize() const; - /** Ends alignment. */ @@ -627,8 +629,7 @@ public: Helper function for extending the selection, returning @true if the selection was changed. Selections are in caret positions. */ - bool ExtendSelection(long oldPosition, long newPosition, - int flags); + virtual bool ExtendSelection(long oldPosition, long newPosition, int flags); /** Helper function for finding the caret position for the next word. @@ -650,7 +651,7 @@ public: applied (for example, setting the default style to bold will cause subsequently inserted text to be bold). */ - const wxTextAttr GetBasicStyle() const; + virtual const wxTextAttr& GetBasicStyle() const; //@{ /** @@ -667,6 +668,12 @@ public: /** Returns the caret height and position for the given character position. + + @beginWxPerlOnly + In wxPerl this method is implemented as + GetCaretPositionForIndex(@a position) returning a + 2-element list (ok, rect). + @endWxPerlOnly */ bool GetCaretPositionForIndex(long position, wxRect& rect); @@ -679,7 +686,7 @@ public: Returns the current default style, which can be used to change how subsequently inserted text is displayed. */ - const wxTextAttr GetDefaultStyle() const; + virtual const wxTextAttr& GetDefaultStyle() const; /** Gets the size of the buffer beyond which layout is delayed during resizing. @@ -757,7 +764,7 @@ public: /** Returns the selection range in character positions. -1, -1 means no selection. */ - const wxRichTextRange GetSelectionRange() const; + wxRichTextRange GetSelectionRange() const; /** Returns the text within the current selection range, if any. @@ -771,6 +778,11 @@ public: style attributes. To get the character or paragraph style alone, use GetUncombinedStyle(). + + @beginWxPerlOnly + In wxPerl this method is implemented as GetStyle(@a position) + returning a 2-element list (ok, attr). + @endWxPerlOnly */ virtual bool GetStyle(long position, wxTextAttr& style); @@ -778,9 +790,14 @@ public: Gets the attributes common to the specified range. Attributes that differ in value within the range will not be included in @a style flags. + + @beginWxPerlOnly + In wxPerl this method is implemented as GetStyleForRange(@a position) + returning a 2-element list (ok, attr). + @endWxPerlOnly */ - bool GetStyleForRange(const wxRichTextRange& range, - wxTextAttr& style); + virtual bool GetStyleForRange(const wxRichTextRange& range, + wxTextAttr& style); /** Returns the style sheet associated with the control, if any. @@ -798,6 +815,11 @@ public: If you specify (any) paragraph attribute in @e style's flags, this function will fetch the paragraph attributes. Otherwise, it will return the character attributes. + + @beginWxPerlOnly + In wxPerl this method is implemented as GetUncombinedStyle(@a position) + returning a 2-element list (ok, attr). + @endWxPerlOnly */ virtual bool GetUncombinedStyle(long position, wxTextAttr& style); @@ -821,8 +843,8 @@ public: You can use this to implement, for example, bold button updating. @a style must have flags indicating which attributes are of interest. */ - bool HasCharacterAttributes(const wxRichTextRange& range, - const wxTextAttr& style) const; + virtual bool HasCharacterAttributes(const wxRichTextRange& range, + const wxTextAttr& style) const; /** Test if this whole range has paragraph attributes of the specified kind. @@ -830,8 +852,8 @@ public: You can use this to implement, for example, centering button updating. @a style must have flags indicating which attributes are of interest. */ - bool HasParagraphAttributes(const wxRichTextRange& range, - const wxTextAttr& style) const; + virtual bool HasParagraphAttributes(const wxRichTextRange& range, + const wxTextAttr& style) const; /** Returns @true if there is a selection. @@ -855,11 +877,6 @@ public: */ void Init(); - /** - Initialises the command event. - */ - void InitCommandEvent(wxCommandEvent& event) const; - /** Returns @true if the user has recently set the default style without moving the caret, and therefore the UI needs to reflect the default style and not @@ -962,6 +979,9 @@ public: /** Move the caret to the given character position. + + Please note that this does not update the current editing style + from the new position; to do that, call wxRichTextCtrl::SetInsertionPoint instead. */ virtual bool MoveCaret(long pos, bool showAtLineStart = false); @@ -1105,7 +1125,7 @@ public: void OnSelectAll(wxCommandEvent& event); /** - Standard handler for the wxID_PASTE command. + Standard handler for the wxID_UNDO command. */ void OnUndo(wxCommandEvent& event); @@ -1159,6 +1179,13 @@ public: */ virtual void PaintBackground(wxDC& dc); + /** + Other user defined painting after everything else (i.e. all text) is painted. + + @since 2.9.1 + */ + virtual void PaintAboveContent(wxDC& dc); + /** Pastes content from the clipboard to the buffer. */ @@ -1263,8 +1290,13 @@ public: virtual void SetBasicStyle(const wxTextAttr& style); /** + Sets the caret position. + The caret position is the character position just before the caret. A value of -1 means the caret is at the start of the buffer. + Please note that this does not update the current editing style + from the new position or cause the actual caret to be refreshed; to do that, + call wxRichTextCtrl::SetInsertionPoint instead. */ void SetCaretPosition(long position, bool showAtLineStart = false); @@ -1311,7 +1343,8 @@ public: void SetHandlerFlags(int flags); /** - Sets the insertion point. + Sets the insertion point and causes the current editing style to be taken from + the new position (unlike wxRichTextCtrl::SetCaretPosition). */ virtual void SetInsertionPoint(long pos); @@ -1382,7 +1415,6 @@ public: bool SetStyle(long start, long end, const wxTextAttr& style); //@} - //@{ /** Sets the attributes for the given range, passing flags to determine how the attributes are set. @@ -1410,13 +1442,9 @@ public: - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags are used in this operation. */ - bool SetStyleEx(const wxRichTextRange& range, + virtual bool SetStyleEx(const wxRichTextRange& range, const wxTextAttr& style, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - bool SetStyleEx(long start, long end, - const wxTextAttr& style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - //@} /** Sets the style sheet associated with the control. @@ -1467,7 +1495,7 @@ public: /** Loads an image from a file and writes it at the current insertion point. */ - bool WriteImage(const wxString& filename, int bitmapType); + virtual bool WriteImage(const wxString& filename, wxBitmapType bitmapType); /** Writes an image block at the current insertion point. @@ -1494,5 +1522,17 @@ public: Translates from column and line number to position. */ virtual long XYToPosition(long x, long y) const; + +protected: + + /** + Currently this simply returns @c wxSize(10, 10). + */ + virtual wxSize DoGetBestSize() const; + + /** + Initialises the command event. + */ + void InitCommandEvent(wxCommandEvent& event) const; };