X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/richtext/richtextctrl.h diff --git a/interface/richtext/richtextctrl.h b/interface/richtext/richtextctrl.h index 0231107f28..c5c7004ec7 100644 --- a/interface/richtext/richtextctrl.h +++ b/interface/richtext/richtextctrl.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: richtext/richtextctrl.h -// Purpose: documentation for wxRichTextEvent class +// Purpose: interface of wxRichTextEvent // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -13,7 +13,7 @@ This is the event class for wxRichTextCtrl notifications. @library{wxrichtext} - @category{events} + @category{richtext} */ class wxRichTextEvent : public wxNotifyEvent { @@ -23,50 +23,50 @@ public: Constructors. */ wxRichTextEvent(const wxRichTextEvent& event); - wxRichTextEvent(wxEventType commandType = wxEVT_@NULL, + wxRichTextEvent(wxEventType commandType = wxEVT_NULL, int winid = 0); //@} /** Clones the event. */ - wxEvent* Clone(); + wxEvent* Clone() const; /** Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event. */ - wxChar GetCharacter(); + wxChar GetCharacter() const; /** Returns flags indicating modifier keys pressed. Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. */ - int GetFlags(); + 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. */ - wxRichTextStyleSheet* GetNewStyleSheet(); + 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. */ - wxRichTextStyleSheet* GetOldStyleSheet(); + wxRichTextStyleSheet* GetOldStyleSheet() const; /** Returns the buffer position at which the event occured. */ - long GetPosition(); + long GetPosition() const; /** Gets the range for the current operation. */ - wxRichTextRange GetRange(); + wxRichTextRange GetRange() const; /** Sets the character variable. @@ -102,6 +102,7 @@ public: }; + /** @class wxRichTextCtrl @headerfile richtextctrl.h wx/richtext/richtextctrl.h @@ -118,8 +119,7 @@ public: "wxRichTextCtrl overview". @library{wxrichtext} - @category{ctrl} - @appearance{richtextctrl.png} + @category{richtext} */ class wxRichTextCtrl { @@ -160,7 +160,6 @@ public: /** Applies the given alignment to the selection (undoable). - For alignment values, see wxTextAttr. */ bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); @@ -183,13 +182,12 @@ public: /** Applies the style sheet to the buffer, matching paragraph styles in the sheet against named styles - in the buffer. This might be useful if the styles have changed. If @e sheet is + in the buffer. This might be useful if the styles have changed. If @a sheet is @NULL, the sheet set with SetStyleSheet is used. - Currently this applies paragraph styles only. */ - bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = @NULL); + bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL); /** Applies underline to the selection (undoable). @@ -199,11 +197,10 @@ public: /** Returns @true if undo commands are being batched. */ - bool BatchingUndo(); + bool BatchingUndo() const; /** Begins using alignment - For alignment values, see wxTextAttr. */ bool BeginAlignment(wxTextAttrAlignment alignment); @@ -240,7 +237,6 @@ public: /** Begins applying a left indent and subindent in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all but the first line in a paragraph. A positive value will cause the first line to appear @@ -248,7 +244,6 @@ public: of the subsequent lines, and a negative value will cause the first line to be indented relative to the subsequent lines. - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between the margin and the bullet. The content of the paragraph, including the first @@ -271,20 +266,16 @@ public: Begins using a specified list style. Optionally, you can also pass a level and a number. */ - bool BeginListStyle(const wxString& listStyle, int level=1, - int number=1); + bool BeginListStyle(const wxString& listStyle, int level = 1, + int number = 1); /** Begins a numbered bullet. This call will be needed for each item in the list, and the application should take care of incrementing the numbering. - - @e bulletNumber is a number, usually starting with 1. - - @e leftIndent and @e leftSubIndent are values in tenths of a millimetre. - - @e bulletStyle is a bitlist of the following values: - + @a bulletNumber is a number, usually starting with 1. + @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. + @a bulletStyle is a bitlist of the following values: wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between @@ -356,32 +347,32 @@ public: /** Returns @true if selected content can be copied to the clipboard. */ - bool CanCopy(); + bool CanCopy() const; /** Returns @true if selected content can be copied to the clipboard and deleted. */ - bool CanCut(); + bool CanCut() const; /** Returns @true if selected content can be deleted. */ - bool CanDeleteSelection(); + bool CanDeleteSelection() const; /** Returns @true if the clipboard content can be pasted to the buffer. */ - bool CanPaste(); + bool CanPaste() const; /** Returns @true if there is a command in the command history that can be redone. */ - bool CanRedo(); + bool CanRedo() const; /** Returns @true if there is a command in the command history that can be undone. */ - bool CanUndo(); + bool CanUndo() const; /** Clears the buffer content, leaving a single empty paragraph. Cannot be undone. @@ -392,11 +383,8 @@ public: /** Clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). */ bool ClearListStyle(const wxRichTextRange& range, @@ -430,7 +418,7 @@ public: Copies the selected content (if any) to the clipboard and deletes the selection. This is undoable. */ -#define void Cut() /* implementation is private */ + void Cut(); /** Deletes the content within the given range. @@ -442,7 +430,7 @@ public: Returns the new caret position in @e newPos, or leaves it if there was no action. This is undoable. */ - bool DeleteSelectedContent(long* newPos = @NULL); + bool DeleteSelectedContent(long* newPos = NULL); /** Deletes the content in the selection, if any. This is undoable. @@ -458,7 +446,7 @@ public: /** Currently this simply returns @c wxSize(10, 10). */ - wxSize DoGetBestSize(); + wxSize DoGetBestSize() const; /** Ends alignment. @@ -558,7 +546,7 @@ public: /** Ends applying a URL. */ -#define bool EndURL() /* implementation is private */ + bool EndURL(); /** End applying underlining. @@ -577,7 +565,7 @@ public: Helper function for finding the caret position for the next word. Direction is 1 (forward) or -1 (backwards). */ - long FindNextWordPosition(int direction = 1); + long FindNextWordPosition(int direction = 1) const; /** Call this function to prevent refresh and allow fast updates, and then Thaw() to @@ -591,20 +579,20 @@ public: only affects the style currently being applied (for example, setting the default style to bold will cause subsequently inserted text to be bold). */ - const wxTextAttr GetBasicStyle(); + const wxTextAttr GetBasicStyle() const; //@{ /** Returns the buffer associated with the control. */ const wxRichTextBuffer GetBuffer(); - wxRichTextBuffer GetBuffer(); + const wxRichTextBuffer& GetBuffer(); //@} /** Returns the current caret position. */ - long GetCaretPosition(); + long GetCaretPosition() const; /** Returns the caret height and position for the given character position @@ -614,104 +602,100 @@ public: /** Gets the command processor associated with the control's buffer. */ - wxCommandProcessor* GetCommandProcessor(); + wxCommandProcessor* GetCommandProcessor() const; /** Returns the current default style, which can be used to change how subsequently inserted text is displayed. */ - const wxTextAttr GetDefaultStyle(); + const wxTextAttr GetDefaultStyle() const; /** Gets the size of the buffer beyond which layout is delayed during resizing. This optimizes sizing for large buffers. The default is 20000. */ - long GetDelayedLayoutThreshold(); + long GetDelayedLayoutThreshold() const; /** Gets the current filename associated with the control. */ - wxString GetFilename(); + wxString GetFilename() const; /** Returns the first visible position in the current view. */ - long GetFirstVisiblePosition(); + long GetFirstVisiblePosition() const; /** Returns flags that change the behaviour of loading or saving. See the documentation for each handler class to see what flags are relevant for each handler. */ - int GetHandlerFlags(); + int GetHandlerFlags() const; /** Returns the current insertion point. */ - long GetInsertionPoint(); + long GetInsertionPoint() const; /** Returns the last position in the buffer. */ - wxTextPos GetLastPosition(); + wxTextPos GetLastPosition() const; /** Returns the length of the specified line in characters. */ - int GetLineLength(long lineNo); + int GetLineLength(long lineNo) const; /** Returns the text for the given line. */ - wxString GetLineText(long lineNo); + wxString GetLineText(long lineNo) const; /** Transforms physical window position to logical (unscrolled) position. */ - wxPoint GetLogicalPoint(const wxPoint& ptPhysical); + wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const; /** Returns the number of lines in the buffer. */ - int GetNumberOfLines(); + int GetNumberOfLines() const; /** Transforms logical (unscrolled) position to physical window position. */ - wxPoint GetPhysicalPoint(const wxPoint& ptLogical); + wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const; /** Gets the text for the given range. - The end point of range is specified as the last character position of the span of text, plus one. */ - wxString GetRange(long from, long to); + wxString GetRange(long from, long to) const; /** Returns the range of the current selection. - The end point of range is specified as the last character position of the span of text, plus one. - - If the return values @e from and @e to are the same, there is no selection. + If the return values @a from and @a to are the same, there is no selection. */ - void GetSelection(long* from, long* to); + void GetSelection(long* from, long* to) const; /** 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. */ - wxString GetStringSelection(); + wxString GetStringSelection() const; /** Gets the attributes at the given position. - This function gets the combined style - that is, the style you see on the screen as a result of combining base style, paragraph style and character style attributes. To get @@ -733,17 +717,15 @@ public: allows named character and paragraph styles to be applied. */ - wxRichTextStyleSheet* GetStyleSheet(); + wxRichTextStyleSheet* GetStyleSheet() const; /** Gets the attributes at the given position. - This function gets the @e uncombined style - that is, the attributes associated with the paragraph or character content, and not necessarily the combined attributes you see on the screen. To get the combined attributes, use GetStyle(). - 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. @@ -753,7 +735,7 @@ public: /** Returns the content of the entire control as a string. */ - wxString GetValue(); + wxString GetValue() const; /** Internal helper function returning the line for the visible caret position. If @@ -762,43 +744,42 @@ public: on the following line. So this function gets the line we're expecting to find if this is the case. */ - wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition); + wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const; /** Test if this whole range has character attributes of the specified kind. If any of the attributes are different within the range, the test fails. You - can use this to implement, for example, bold button updating. @e style must have + 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 wxTextAttr& style) const; /** Test if this whole range has paragraph attributes of the specified kind. If any of the attributes are different within the range, the test fails. You - can use this to implement, for example, centering button updating. @e style + 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 wxTextAttr& style) const; /** Returns @true if there is a selection. */ - bool HasSelection(); + bool HasSelection() const; //@{ /** Finds the character at the given position in pixels. - - @e pt is in device coords (not adjusted for the client area origin nor for + @a pt is in device coords (not adjusted for the client area origin nor for scrolling). */ - wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos); - wxTextCtrlHitTestResult HitTest(const wxPoint& pt, - wxTextCoord* col, - wxTextCoord* row); + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos) const; + const wxTextCtrlHitTestResult HitTest(const wxPoint& pt, + wxTextCoord* col, + wxTextCoord* row) const; //@} /** @@ -809,71 +790,71 @@ public: /** Initialises the command event. */ - void InitCommandEvent(wxCommandEvent& 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 the style at the caret. - Below is an example of code that uses this function to determine whether the UI should show that the current style is bold. + See also SetAndShowDefaultStyle(). */ - bool IsDefaultStyleShowing(); + bool IsDefaultStyleShowing() const; /** Returns @true if the control is editable. */ - bool IsEditable(); + bool IsEditable() const; /** Returns @true if Freeze has been called without a Thaw. */ - bool IsFrozen(); + bool IsFrozen() const; /** Returns @true if the buffer has been modified. */ - bool IsModified(); + bool IsModified() const; /** Returns @true if the control is multiline. */ - bool IsMultiLine(); + bool IsMultiLine() const; /** Returns @true if the given position is visible on the screen. */ - bool IsPositionVisible(long pos); + bool IsPositionVisible(long pos) const; /** Returns @true if all of the selection is aligned according to the specified flag. */ - bool IsSelectionAligned(wxTextAttrAlignment alignment); + bool IsSelectionAligned(wxTextAttrAlignment alignment) const; /** Returns @true if all of the selection is bold. */ - bool IsSelectionBold(); + bool IsSelectionBold() const; /** Returns @true if all of the selection is italic. */ - bool IsSelectionItalics(); + bool IsSelectionItalics() const; /** Returns @true if all of the selection is underlined. */ - bool IsSelectionUnderlined(); + bool IsSelectionUnderlined() const; /** Returns @true if the control is single-line. Currently wxRichTextCtrl does not support single-line editing. */ - bool IsSingleLine(); + bool IsSingleLine() const; /** Helper function implementing keyboard navigation. @@ -885,7 +866,7 @@ public: setting the caret position. This function should not normally be required by the application. */ - bool LayoutContent(bool onlyVisibleRect = @false); + bool LayoutContent(bool onlyVisibleRect = false); /** Inserts a line break at the current insertion point. A line break forces @@ -900,7 +881,6 @@ public: Loads content into the control's buffer using the given type. If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. - This function looks for a suitable wxRichTextFileHandler object. */ bool LoadFile(const wxString& file, @@ -914,7 +894,7 @@ public: /** Move the caret to the given character position. */ - bool MoveCaret(long pos, bool showAtLineStart = @false); + bool MoveCaret(long pos, bool showAtLineStart = false); /** Move the caret one visual step forward: this may mean setting a flag @@ -991,15 +971,12 @@ public: attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). */ bool NumberList(const wxRichTextRange& range, @@ -1124,24 +1101,21 @@ public: /** Converts a text position to zero-based column and line numbers. */ - bool PositionToXY(long pos, long* x, long* y); + bool PositionToXY(long pos, long* x, long* y) const; //@{ /** - Promotes or demotes the paragraphs in the given range. A positive @e promoteBy + Promotes or demotes the paragraphs in the given range. A positive @a promoteBy produces a smaller indent, and a negative number produces a larger indent. Pass flags to determine how the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). */ bool PromoteList(int promoteBy, const wxRichTextRange& range, @@ -1173,14 +1147,13 @@ public: /** Saves the buffer content using the given type. If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. - This function looks for a suitable wxRichTextFileHandler object. */ bool SaveFile(const wxString& file = wxEmptyString, int type = wxRICHTEXT_TYPE_ANY); /** - Scrolls @e position into view. This function takes a caret position. + Scrolls @a position into view. This function takes a caret position. */ bool ScrollIntoView(long position, int keyCode); @@ -1195,10 +1168,9 @@ public: void SelectNone(); /** - Sets @e attr as the default style and tells the control that the UI should + Sets @a attr as the default style and tells the control that the UI should reflect this attribute until the user moves the caret. - See also IsDefaultStyleShowing(). */ void SetAndShowDefaultStyle(const wxTextAttr& attr); @@ -1216,7 +1188,7 @@ public: A value of -1 means the caret is at the start of the buffer. */ void SetCaretPosition(long position, - bool showAtLineStart = @false); + bool showAtLineStart = false); /** Sets the current default style, which can be used to change how subsequently @@ -1275,15 +1247,12 @@ public: the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). */ bool SetListStyle(const wxRichTextRange& range, @@ -1300,7 +1269,6 @@ public: /** Sets the selection to the given range. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the selection for a character at position 5, use the @@ -1310,7 +1278,6 @@ public: /** Sets the selection to the given range. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the selection for a character at position 5, use the @@ -1321,7 +1288,6 @@ public: //@{ /** Sets the attributes for the given range. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the style for a character at position 5, use the range @@ -1336,14 +1302,11 @@ public: /** Sets the attributes for the given range, passing flags to determine how the attributes are set. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the style for a character at position 5, use the range (5,6). - - @e flags may contain a bit list of the following values: - + @a flags may contain a bit list of the following values: wxRICHTEXT_SETSTYLE_NONE: no style flag. wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be undoable. @@ -1385,7 +1348,7 @@ public: /** A helper function setting up scrollbars, for example after a resize. */ - void SetupScrollbars(bool atTop = @false); + void SetupScrollbars(bool atTop = false); /** Scrolls the buffer so that the given position is in view. @@ -1395,7 +1358,7 @@ public: /** Returns @true if undo history suppression is on. */ - bool SuppressingUndo(); + bool SuppressingUndo() const; /** Call this function to end a Freeze and refresh the display. @@ -1439,5 +1402,6 @@ public: /** Translates from column and line number to position. */ - long XYToPosition(long x, long y); + long XYToPosition(long x, long y) const; }; +