// Purpose: interface of wxRichTextCtrl and wxRichTextEvent
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@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
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;
/**
Gets the range for the current operation.
*/
- wxRichTextRange GetRange() const;
+ const wxRichTextRange& GetRange() const;
/**
Sets the character variable.
/**
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);
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
{
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);
*/
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.
@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.
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);
*/
virtual void DiscardEdits();
- /**
- Currently this simply returns @c wxSize(10, 10).
- */
- virtual wxSize DoGetBestSize() const;
-
/**
Ends alignment.
*/
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;
//@{
/**
/**
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);
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.
/**
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.
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);
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
*/
virtual bool GetStyleForRange(const wxRichTextRange& range,
wxTextAttr& style);
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);
*/
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
/**
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);
void OnSelectAll(wxCommandEvent& event);
/**
- Standard handler for the wxID_PASTE command.
+ Standard handler for the wxID_UNDO command.
*/
void OnUndo(wxCommandEvent& event);
*/
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.
*/
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);
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);
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.
- 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.
/**
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.
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;
};
projects / wxWidgets.git / blobdiff