X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0004982c831f56c65c390fb617711ff52595c2f3..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/richtext/richtextctrl.h?ds=sidebyside diff --git a/interface/wx/richtext/richtextctrl.h b/interface/wx/richtext/richtextctrl.h index a3b6aa953d..e0ce27dded 100644 --- a/interface/wx/richtext/richtextctrl.h +++ b/interface/wx/richtext/richtextctrl.h @@ -1,155 +1,163 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextctrl.h -// Purpose: interface of wxRichTextCtrl and wxRichTextEvent -// Author: wxWidgets team +// Name: wx/richtext/richtextctrl.h +// Purpose: A rich edit control +// Author: Julian Smart +// Modified by: +// Created: 2005-09-30 // RCS-ID: $Id$ -// Licence: wxWindows license +// Copyright: (c) Julian Smart +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/* + * Styles and flags + */ + /** - @class wxRichTextEvent + Styles +*/ - This is the event class for wxRichTextCtrl notifications. +#define wxRE_READONLY 0x0010 +#define wxRE_MULTILINE 0x0020 +#define wxRE_CENTRE_CARET 0x8000 +#define wxRE_CENTER_CARET wxRE_CENTRE_CARET - @beginEventTable{wxRichTextEvent} - @event{EVT_RICHTEXT_CHARACTER(id, func)} - Process a 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - buffer has been reset by deleting all content. - You can use this to set a default style for the first new paragraph. - @endEventTable +/** + Flags +*/ - @library{wxrichtext} - @category{events,richtext} +#define wxRICHTEXT_SHIFT_DOWN 0x01 +#define wxRICHTEXT_CTRL_DOWN 0x02 +#define wxRICHTEXT_ALT_DOWN 0x04 + +/** + Extra flags */ -class wxRichTextEvent : public wxNotifyEvent + +// Don't draw guide lines around boxes and tables +#define wxRICHTEXT_EX_NO_GUIDELINES 0x00000100 + + +/* + Defaults +*/ + +#define wxRICHTEXT_DEFAULT_OVERALL_SIZE wxSize(-1, -1) +#define wxRICHTEXT_DEFAULT_IMAGE_SIZE wxSize(80, 80) +#define wxRICHTEXT_DEFAULT_SPACING 3 +#define wxRICHTEXT_DEFAULT_MARGIN 3 +#define wxRICHTEXT_DEFAULT_UNFOCUSSED_BACKGROUND wxColour(175, 175, 175) +#define wxRICHTEXT_DEFAULT_FOCUSSED_BACKGROUND wxColour(140, 140, 140) +#define wxRICHTEXT_DEFAULT_UNSELECTED_BACKGROUND wxSystemSettings::GetColour(wxSYS_COLOUR_3DFACE) +#define wxRICHTEXT_DEFAULT_TYPE_COLOUR wxColour(0, 0, 200) +#define wxRICHTEXT_DEFAULT_FOCUS_RECT_COLOUR wxColour(100, 80, 80) +#define wxRICHTEXT_DEFAULT_CARET_WIDTH 2 +// Minimum buffer size before delayed layout kicks in +#define wxRICHTEXT_DEFAULT_DELAYED_LAYOUT_THRESHOLD 20000 +// Milliseconds before layout occurs after resize +#define wxRICHTEXT_DEFAULT_LAYOUT_INTERVAL 50 + +/* Identifiers + */ +#define wxID_RICHTEXT_PROPERTIES1 (wxID_HIGHEST + 1) +#define wxID_RICHTEXT_PROPERTIES2 (wxID_HIGHEST + 2) +#define wxID_RICHTEXT_PROPERTIES3 (wxID_HIGHEST + 3) + +/* + Normal selection occurs initially and as user drags within one container. + Common ancestor selection occurs when the user starts dragging across containers + that have a common ancestor, for example the cells in a table. + */ + +enum wxRichTextCtrlSelectionState { -public: - /** - Copy constructor. - */ - wxRichTextEvent(const wxRichTextEvent& event); + wxRichTextCtrlSelectionState_Normal, + wxRichTextCtrlSelectionState_CommonAncestor +}; - /** - Constructor. +/** + @class wxRichTextContextMenuPropertiesInfo - @param commandType - The type of the event. - @param id - Window identifier. The value @c wxID_ANY indicates a default value. - */ - wxRichTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); + wxRichTextContextMenuPropertiesInfo keeps track of objects that appear in the context menu, + whose properties are available to be edited. + */ +class WXDLLIMPEXP_RICHTEXT wxRichTextContextMenuPropertiesInfo +{ +public: /** - Clones the event. + Constructor. */ - wxEvent* Clone() const; + wxRichTextContextMenuPropertiesInfo() { Init(); } + +// Operations /** - Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event. + Initialisation. */ - wxChar GetCharacter() const; + void Init() {} /** - Returns flags indicating modifier keys pressed. - - Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + Adds an item. */ - int GetFlags() const; + bool AddItem(const wxString& label, wxRichTextObject* obj); /** - Returns the new style sheet. - - Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + Returns the number of menu items that were added. */ - wxRichTextStyleSheet* GetNewStyleSheet() const; + int AddMenuItems(wxMenu* menu, int startCmd = wxID_RICHTEXT_PROPERTIES1) const; /** - Returns the old style sheet. - - Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + Adds appropriate menu items for the current container and clicked on object + (and container's parent, if appropriate). */ - wxRichTextStyleSheet* GetOldStyleSheet() const; + int AddItems(wxRichTextCtrl* ctrl, wxRichTextObject* container, wxRichTextObject* obj); /** - Returns the buffer position at which the event occured. + Clears the items. */ - long GetPosition() const; + void Clear() { m_objects.Clear(); m_labels.Clear(); } + +// Accessors /** - Gets the range for the current operation. + Returns the nth label. */ - wxRichTextRange GetRange() const; + wxString GetLabel(int n) const { return m_labels[n]; } /** - Sets the character variable. + Returns the nth object. */ - void SetCharacter(wxChar ch); + wxRichTextObject* GetObject(int n) const { return m_objects[n]; } /** - Sets flags indicating modifier keys pressed. - - Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + Returns the array of objects. */ - void SetFlags(int flags); + wxRichTextObjectPtrArray& GetObjects() { return m_objects; } /** - Sets the new style sheet variable. + Returns the array of objects. */ - void SetNewStyleSheet(wxRichTextStyleSheet* sheet); + const wxRichTextObjectPtrArray& GetObjects() const { return m_objects; } /** - Sets the old style sheet variable. + Returns the array of labels. */ - void SetOldStyleSheet(wxRichTextStyleSheet* sheet); + wxArrayString& GetLabels() { return m_labels; } /** - Sets the buffer position variable. + Returns the array of labels. */ - void SetPosition(long pos); + const wxArrayString& GetLabels() const { return m_labels; } /** - Sets the range variable. + Returns the number of items. */ - void SetRange(const wxRichTextRange& range); -}; - + int GetCount() const { return m_objects.GetCount(); } + wxRichTextObjectPtrArray m_objects; + wxArrayString m_labels; +}; /** @class wxRichTextCtrl @@ -159,21 +167,41 @@ 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} -*/ -class wxRichTextCtrl + @appearance{richtextctrl.png} + + */ + +class WXDLLIMPEXP_RICHTEXT wxRichTextCtrl : public wxControl, + public wxTextCtrlIface, + public wxScrollHelper { + DECLARE_CLASS( wxRichTextCtrl ) + DECLARE_EVENT_TABLE() + public: +// Constructors + /** - Default Constructor. + Default constructor. */ - wxRichTextCtrl(); + wxRichTextCtrl( ); /** Constructor, creating and showing a rich text control. @@ -197,622 +225,1274 @@ public: @see Create(), wxValidator */ - wxRichTextCtrl(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxString& value = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxRE_MULTILINE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxTextCtrlNameStr); + wxRichTextCtrl( wxWindow* parent, wxWindowID id = -1, const wxString& value = wxEmptyString, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, + long style = wxRE_MULTILINE, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxTextCtrlNameStr); /** Destructor. */ - virtual ~wxRichTextCtrl(); + virtual ~wxRichTextCtrl( ); + +// Operations /** - Adds an image to the control's buffer. + Creates the underlying window. */ - virtual wxRichTextRange AddImage(const wxImage& image); + bool Create( wxWindow* parent, wxWindowID id = -1, const wxString& value = wxEmptyString, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, + long style = wxRE_MULTILINE, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxTextCtrlNameStr ); /** - Adds a new paragraph of text to the end of the buffer. + Initialises the members of the control. */ - virtual wxRichTextRange AddParagraph(const wxString& text); + void Init(); + +// Accessors /** - Sets the insertion point to the end of the buffer and writes the text. + 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. */ - virtual void AppendText(const wxString& text); + virtual wxString GetRange(long from, long to) const; /** - Applies the given alignment to the selection (undoable). - For alignment values, see wxTextAttr. + Returns the length of the specified line in characters. */ - virtual bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); + virtual int GetLineLength(long lineNo) const ; /** - Apples bold to the selection (undoable). + Returns the text for the given line. */ - virtual bool ApplyBoldToSelection(); + virtual wxString GetLineText(long lineNo) const ; /** - Applies italic to the selection (undoable). + Returns the number of lines in the buffer. */ - virtual bool ApplyItalicToSelection(); + virtual int GetNumberOfLines() const ; /** - Applies the given style to the selection. + Returns @true if the buffer has been modified. */ - virtual bool ApplyStyle(wxRichTextStyleDefinition* def); + virtual bool IsModified() const ; /** - 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 @a sheet is @NULL, the sheet set with SetStyleSheet() is used. - Currently this applies paragraph styles only. + Returns @true if the control is editable. */ - bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL); + virtual bool IsEditable() const ; /** - Applies underline to the selection (undoable). + Returns @true if the control is single-line. + Currently wxRichTextCtrl does not support single-line editing. */ - virtual bool ApplyUnderlineToSelection(); + bool IsSingleLine() const { return !HasFlag(wxRE_MULTILINE); } /** - Returns @true if undo commands are being batched. + Returns @true if the control is multiline. */ - virtual bool BatchingUndo() const; + bool IsMultiLine() const { return !IsSingleLine(); } + //@{ /** - Begins using alignment. - For alignment values, see wxTextAttr. + 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 @a from and @a to are the same, there is no selection. */ - bool BeginAlignment(wxTextAttrAlignment alignment); + virtual void GetSelection(long* from, long* to) const; + const wxRichTextSelection& GetSelection() const { return m_selection; } + wxRichTextSelection& GetSelection() { return m_selection; } + //@} /** - Starts batching undo history for commands. + Returns the text within the current selection range, if any. */ - virtual bool BeginBatchUndo(const wxString& cmdName); + virtual wxString GetStringSelection() const; /** - Begins using bold. + Gets the current filename associated with the control. */ - bool BeginBold(); + wxString GetFilename() const { return m_filename; } /** - Begins using the named character style. + Sets the current filename. */ - bool BeginCharacterStyle(const wxString& characterStyle); + void SetFilename(const wxString& filename) { m_filename = filename; } /** - Begins using this font. + Sets the size of the buffer beyond which layout is delayed during resizing. + This optimizes sizing for large buffers. The default is 20000. */ - bool BeginFont(const wxFont& font); + void SetDelayedLayoutThreshold(long threshold) { m_delayedLayoutThreshold = threshold; } /** - Begins using the given point size. + Gets the size of the buffer beyond which layout is delayed during resizing. + This optimizes sizing for large buffers. The default is 20000. */ - bool BeginFontSize(int pointSize); + long GetDelayedLayoutThreshold() const { return m_delayedLayoutThreshold; } /** - Begins using italic. */ - bool BeginItalic(); + bool GetFullLayoutRequired() const { return m_fullLayoutRequired; } /** - Begins applying a left indent and subindent in tenths of a millimetre. - The subindent is an offset from the left edge 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 to the left of the subsequent lines, and - a negative value will cause the first line to be indented to the right - of the subsequent lines. - - wxRichTextBuffer uses indentation to render a bulleted item. The - content of the paragraph, including the first line, starts at the - @a leftIndent plus the @a leftSubIndent. - - @param leftIndent - The distance between the margin and the bullet. - @param leftSubIndent - The distance between the left edge of the bullet and the left edge - of the actual paragraph. */ - bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); + void SetFullLayoutRequired(bool b) { m_fullLayoutRequired = b; } /** - Begins appling line spacing. @e spacing is a multiple, where 10 means - single-spacing, 15 means 1.5 spacing, and 20 means double spacing. - - The ::wxTextAttrLineSpacing constants are defined for convenience. */ - bool BeginLineSpacing(int lineSpacing); + wxLongLong GetFullLayoutTime() const { return m_fullLayoutTime; } /** - 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); + void SetFullLayoutTime(wxLongLong t) { m_fullLayoutTime = t; } /** - 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. - - @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 ::wxTextAttrBulletStyle values. - - 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 line, starts - at leftMargin + leftSubIndent. - So the distance between the left edge of the bullet and the - left of the actual paragraph is leftSubIndent. */ - bool BeginNumberedBullet(int bulletNumber, int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); + long GetFullLayoutSavedPosition() const { return m_fullLayoutSavedPosition; } /** - Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing - in tenths of a millimetre. */ - bool BeginParagraphSpacing(int before, int after); + void SetFullLayoutSavedPosition(long p) { m_fullLayoutSavedPosition = p; } + // Force any pending layout due to large buffer /** - Begins applying the named paragraph style. */ - bool BeginParagraphStyle(const wxString& paragraphStyle); + void ForceDelayedLayout(); /** - Begins a right indent, specified in tenths of a millimetre. + Sets the text (normal) cursor. */ - bool BeginRightIndent(int rightIndent); + void SetTextCursor(const wxCursor& cursor ) { m_textCursor = cursor; } /** - Begins applying a style. + Returns the text (normal) cursor. */ - virtual bool BeginStyle(const wxTextAttr& style); + wxCursor GetTextCursor() const { return m_textCursor; } /** - Starts suppressing undo history for commands. + Sets the cursor to be used over URLs. */ - virtual bool BeginSuppressUndo(); + void SetURLCursor(const wxCursor& cursor ) { m_urlCursor = cursor; } /** - Begins applying a symbol bullet, using a character from the current font. - See BeginNumberedBullet() for an explanation of how indentation is used - to render the bulleted paragraph. + Returns the cursor to be used over URLs. */ - bool BeginSymbolBullet(wxChar symbol, int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); + wxCursor GetURLCursor() const { return m_urlCursor; } /** - Begins using this colour. + Returns @true if we are showing the caret position at the start of a line + instead of at the end of the previous one. */ - bool BeginTextColour(const wxColour& colour); + bool GetCaretAtLineStart() const { return m_caretAtLineStart; } /** - Begins applying wxTEXT_ATTR_URL to the content. - - Pass a URL and optionally, a character style to apply, since it is common - to mark a URL with a familiar style such as blue text with underlining. + Sets a flag to remember that we are showing the caret position at the start of a line + instead of at the end of the previous one. */ - bool BeginURL(const wxString& url, - const wxString& characterStyle = wxEmptyString); + void SetCaretAtLineStart(bool atStart) { m_caretAtLineStart = atStart; } /** - Begins using underlining. + Returns @true if we are extending a selection. */ - bool BeginUnderline(); + bool GetDragging() const { return m_dragging; } /** - Returns @true if selected content can be copied to the clipboard. + Sets a flag to remember if we are extending a selection. */ - virtual bool CanCopy() const; + void SetDragging(bool dragging) { m_dragging = dragging; } /** - Returns @true if selected content can be copied to the clipboard and deleted. + Are we trying to start Drag'n'Drop? */ - virtual bool CanCut() const; + bool GetPreDrag() const { return m_preDrag; } /** - Returns @true if selected content can be deleted. + Set if we're trying to start Drag'n'Drop */ - virtual bool CanDeleteSelection() const; + void SetPreDrag(bool pd) { m_preDrag = pd; } /** - Returns @true if the clipboard content can be pasted to the buffer. + Get the possible Drag'n'Drop start point */ - virtual bool CanPaste() const; + const wxPoint GetDragStartPoint() const { return m_dragStartPoint; } /** - Returns @true if there is a command in the command history that can be redone. + Set the possible Drag'n'Drop start point */ - virtual bool CanRedo() const; + void SetDragStartPoint(wxPoint sp) { m_dragStartPoint = sp; } /** - Returns @true if there is a command in the command history that can be undone. + Get the possible Drag'n'Drop start time */ - virtual bool CanUndo() const; + const wxDateTime GetDragStartTime() const { return m_dragStartTime; } /** - Clears the buffer content, leaving a single empty paragraph. Cannot be undone. + Set the possible Drag'n'Drop start time */ - virtual void Clear(); + void SetDragStartTime(wxDateTime st) { m_dragStartTime = st; } +#if wxRICHTEXT_BUFFERED_PAINTING //@{ /** - Clears the list style from the given range, clearing list-related attributes - and applying any named paragraph style associated with each paragraph. - - @a flags is a bit list of the following: - - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - - @see SetListStyle(), PromoteList(), NumberList(). + Returns the buffer bitmap if using buffered painting. */ - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + const wxBitmap& GetBufferBitmap() const { return m_bufferBitmap; } + wxBitmap& GetBufferBitmap() { return m_bufferBitmap; } //@} +#endif /** - Sends the event to the control. + Returns the current context menu. */ - virtual void Command(wxCommandEvent& event); + wxMenu* GetContextMenu() const { return m_contextMenu; } /** - Copies the selected content (if any) to the clipboard. + Sets the current context menu. */ - virtual void Copy(); + void SetContextMenu(wxMenu* menu); /** - Creates the underlying window. + Returns an anchor so we know how to extend the selection. + It's a caret position since it's between two characters. */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxString& value = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxRE_MULTILINE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxTextCtrlNameStr); + long GetSelectionAnchor() const { return m_selectionAnchor; } /** - Copies the selected content (if any) to the clipboard and deletes the selection. - This is undoable. + Sets an anchor so we know how to extend the selection. + It's a caret position since it's between two characters. */ - virtual void Cut(); + void SetSelectionAnchor(long anchor) { m_selectionAnchor = anchor; } /** - Deletes the content within the given range. + Returns the anchor object if selecting multiple containers. */ - virtual bool Delete(const wxRichTextRange& range); + wxRichTextObject* GetSelectionAnchorObject() const { return m_selectionAnchorObject; } /** - 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. + Sets the anchor object if selecting multiple containers. */ - bool DeleteSelectedContent(long* newPos = NULL); + void SetSelectionAnchorObject(wxRichTextObject* anchor) { m_selectionAnchorObject = anchor; } + //@{ /** - Deletes the content in the selection, if any. This is undoable. + Returns an object that stores information about context menu property item(s), + in order to communicate between the context menu event handler and the code + that responds to it. The wxRichTextContextMenuPropertiesInfo stores one + item for each object that could respond to a property-editing event. If + objects are nested, several might be editable. */ - virtual void DeleteSelection(); + wxRichTextContextMenuPropertiesInfo& GetContextMenuPropertiesInfo() { return m_contextMenuPropertiesInfo; } + const wxRichTextContextMenuPropertiesInfo& GetContextMenuPropertiesInfo() const { return m_contextMenuPropertiesInfo; } + //@} /** - Sets the buffer's modified status to @false, and clears the buffer's command - history. + Returns the wxRichTextObject object that currently has the editing focus. + If there are no composite objects, this will be the top-level buffer. */ - virtual void DiscardEdits(); + wxRichTextParagraphLayoutBox* GetFocusObject() const { return m_focusObject; } /** - Currently this simply returns @c wxSize(10, 10). + Setter for m_focusObject. */ - virtual wxSize DoGetBestSize() const; + void StoreFocusObject(wxRichTextParagraphLayoutBox* obj); /** - Ends alignment. + Sets the wxRichTextObject object that currently has the editing focus. + @param setCaretPosition + Optionally set the caret position. */ - bool EndAlignment(); + bool SetFocusObject(wxRichTextParagraphLayoutBox* obj, bool setCaretPosition = true); - /** - Ends application of all styles in the current style stack. - */ - virtual bool EndAllStyles(); +// Operations /** - Ends batching undo command history. + Invalidates the whole buffer to trigger painting later. */ - virtual bool EndBatchUndo(); + void Invalidate() { GetBuffer().Invalidate(wxRICHTEXT_ALL); } /** - Ends using bold. + Clears the buffer content, leaving a single empty paragraph. Cannot be undone. */ - bool EndBold(); + virtual void Clear(); /** - Ends application of a named character style. + Replaces the content in the specified range with the string specified by + @a value. */ - bool EndCharacterStyle(); + virtual void Replace(long from, long to, const wxString& value); /** - Ends using a font. + Removes the content in the specified range. */ - bool EndFont(); + virtual void Remove(long from, long to); +#ifdef DOXYGEN /** - Ends using a point size. - */ - bool EndFontSize(); + 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, + int type = wxRICHTEXT_TYPE_ANY); +#endif + + /** + Helper function for LoadFile(). 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. + */ + virtual bool DoLoadFile(const wxString& file, int fileType); + +#ifdef DOXYGEN + /** + 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); +#endif + + /** + Helper function for SaveFile(). 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. + */ + virtual bool DoSaveFile(const wxString& file = wxEmptyString, + int fileType = wxRICHTEXT_TYPE_ANY); + + /** + Sets 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. + */ + void SetHandlerFlags(int flags) { GetBuffer().SetHandlerFlags(flags); } + + /** + 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() const { return GetBuffer().GetHandlerFlags(); } + + /** + Marks the buffer as modified. + */ + virtual void MarkDirty(); + + /** + Sets the buffer's modified status to @false, and clears the buffer's command + history. + */ + virtual void DiscardEdits(); + + /** + Sets the maximum number of characters that may be entered in a single line + text control. For compatibility only; currently does nothing. + */ + virtual void SetMaxLength(unsigned long WXUNUSED(len)) { } + + /** + Writes text at the current position. + */ + virtual void WriteText(const wxString& text); + + /** + Sets the insertion point to the end of the buffer and writes the text. + */ + virtual void AppendText(const wxString& text); + + //@{ + /** + 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 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); + virtual bool GetStyle(long position, wxRichTextAttr& style); + virtual bool GetStyle(long position, wxRichTextAttr& style, wxRichTextParagraphLayoutBox* container); + //@} + + //@{ + /** + 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 + (5,6). + */ + virtual bool SetStyle(long start, long end, const wxTextAttr& style); + virtual bool SetStyle(long start, long end, const wxRichTextAttr& style); + virtual bool SetStyle(const wxRichTextRange& range, const wxTextAttr& style); + virtual bool SetStyle(const wxRichTextRange& range, const wxRichTextAttr& style); + //@} + + /** + Sets the attributes for a single object + */ + virtual void SetStyle(wxRichTextObject *obj, const wxRichTextAttr& textAttr, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + + //@{ + /** + 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); + virtual bool GetStyleForRange(const wxRichTextRange& range, wxRichTextAttr& style); + virtual bool GetStyleForRange(const wxRichTextRange& range, wxRichTextAttr& style, wxRichTextParagraphLayoutBox* container); + //@} + + /** + 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). + + @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. + - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the combined style at this point is already the style in question. + - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, and not the content. + This allows content styling to be preserved independently from that + of e.g. a named paragraph style. + - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, and not the paragraph. + This allows content styling to be preserved independently from that + of e.g. a named paragraph style. + - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags + are used in this operation. + */ + virtual bool SetStyleEx(const wxRichTextRange& range, const wxRichTextAttr& style, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + + //@{ + /** + 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. + + @beginWxPerlOnly + In wxPerl this method is implemented as GetUncombinedStyle(@a position) + returning a 2-element list (ok, attr). + @endWxPerlOnly + */ + virtual bool GetUncombinedStyle(long position, wxRichTextAttr& style); + virtual bool GetUncombinedStyle(long position, wxRichTextAttr& style, wxRichTextParagraphLayoutBox* container); + //@} + + //@{ + /** + Sets the current default style, which can be used to change how subsequently + inserted text is displayed. + */ + virtual bool SetDefaultStyle(const wxTextAttr& style); + virtual bool SetDefaultStyle(const wxRichTextAttr& style); + //@} + + /** + Returns the current default style, which can be used to change how subsequently + inserted text is displayed. + */ + virtual const wxRichTextAttr& GetDefaultStyleEx() const; + + //virtual const wxTextAttr& GetDefaultStyle() const; + + //@{ + /** + Sets the list attributes for the given range, passing 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. + @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 + @a startFrom, otherwise existing attributes are 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 NumberList(), PromoteList(), ClearListStyle(). + */ + virtual bool SetListStyle(const wxRichTextRange& range, wxRichTextListStyleDefinition* def, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, int startFrom = 1, int specifiedLevel = -1); + virtual bool SetListStyle(const wxRichTextRange& range, const wxString& defName, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, int startFrom = 1, int specifiedLevel = -1); + //@} + + /** + Clears the list style from the given range, clearing list-related attributes + and applying any named paragraph style associated with each paragraph. + + @a flags is a bit list of the following: + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + + @see SetListStyle(), PromoteList(), NumberList(). + */ + virtual bool ClearListStyle(const wxRichTextRange& range, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + + //@{ + /** + Numbers the paragraphs in the given range. + 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. + + @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 + @a startFrom, otherwise existing attributes are 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 SetListStyle(), PromoteList(), ClearListStyle(). + */ + virtual bool NumberList(const wxRichTextRange& range, wxRichTextListStyleDefinition* def = NULL, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, int startFrom = 1, int specifiedLevel = -1); + virtual bool NumberList(const wxRichTextRange& range, const wxString& defName, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, int startFrom = 1, int specifiedLevel = -1); + //@} + + //@{ + /** + 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. + + @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 + @a startFrom, otherwise existing attributes are 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 SetListStyle(), @see SetListStyle(), ClearListStyle(). + */ + virtual bool PromoteList(int promoteBy, const wxRichTextRange& range, wxRichTextListStyleDefinition* def = NULL, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, int specifiedLevel = -1); + virtual bool PromoteList(int promoteBy, const wxRichTextRange& range, const wxString& defName, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, int specifiedLevel = -1); + //@} + + /** + Sets the properties for the given range, passing flags to determine how the + attributes are set. You can merge properties or replace them. + + 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 properties for a character at + position 5, use the range (5,6). + + @a flags may contain a bit list of the following values: + - wxRICHTEXT_SETSPROPERTIES_NONE: no flag. + - wxRICHTEXT_SETPROPERTIES_WITH_UNDO: specifies that this operation should be + undoable. + - wxRICHTEXT_SETPROPERTIES_PARAGRAPHS_ONLY: specifies that the properties should only be + applied to paragraphs, and not the content. + - wxRICHTEXT_SETPROPERTIES_CHARACTERS_ONLY: specifies that the properties should only be + applied to characters, and not the paragraph. + - wxRICHTEXT_SETPROPERTIES_RESET: resets (clears) the existing properties before applying + the new properties. + - wxRICHTEXT_SETPROPERTIES_REMOVE: removes the specified properties. + */ + virtual bool SetProperties(const wxRichTextRange& range, const wxRichTextProperties& properties, int flags = wxRICHTEXT_SETPROPERTIES_WITH_UNDO); + + /** + Deletes the content within the given range. + */ + virtual bool Delete(const wxRichTextRange& range); + + /** + Translates from column and line number to position. + */ + virtual long XYToPosition(long x, long y) const; + + /** + Converts a text position to zero-based column and line numbers. + */ + virtual bool PositionToXY(long pos, long *x, long *y) const; + + /** + Scrolls the buffer so that the given position is in view. + */ + virtual void ShowPosition(long pos); + + //@{ + /** + Finds the character at the given position in pixels. + @a pt is in device coords (not adjusted for the client area origin nor for + scrolling). + */ + virtual wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long *pos) const; + virtual wxTextCtrlHitTestResult HitTest(const wxPoint& pt, + wxTextCoord *col, + wxTextCoord *row) const; + + /** + Finds the container at the given point, which is assumed to be in client coordinates. + */ + wxRichTextParagraphLayoutBox* FindContainerAtPoint(const wxPoint pt, long& position, int& hit, wxRichTextObject* hitObj, int flags = 0); + //@} + +// Clipboard operations + + /** + Copies the selected content (if any) to the clipboard. + */ + virtual void Copy(); + + /** + Copies the selected content (if any) to the clipboard and deletes the selection. + This is undoable. + */ + virtual void Cut(); + + /** + Pastes content from the clipboard to the buffer. + */ + virtual void Paste(); + + /** + Deletes the content in the selection, if any. This is undoable. + */ + virtual void DeleteSelection(); + + /** + Returns @true if selected content can be copied to the clipboard. + */ + virtual bool CanCopy() const; + + /** + Returns @true if selected content can be copied to the clipboard and deleted. + */ + virtual bool CanCut() const; + + /** + Returns @true if the clipboard content can be pasted to the buffer. + */ + virtual bool CanPaste() const; + + /** + Returns @true if selected content can be deleted. + */ + virtual bool CanDeleteSelection() const; + + /** + Undoes the command at the top of the command history, if there is one. + */ + virtual void Undo(); + + /** + Redoes the current command. + */ + virtual void Redo(); + + /** + Returns @true if there is a command in the command history that can be undone. + */ + virtual bool CanUndo() const; + + /** + Returns @true if there is a command in the command history that can be redone. + */ + virtual bool CanRedo() const; + + /** + 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); + + /** + Sets the insertion point to the end of the text control. + */ + virtual void SetInsertionPointEnd(); + + /** + Returns the current insertion point. + */ + virtual long GetInsertionPoint() const; + + /** + Returns the last position in the buffer. + */ + virtual wxTextPos GetLastPosition() const; + + //@{ + /** + 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 + range (5,6). + */ + virtual void SetSelection(long from, long to); + void SetSelection(const wxRichTextSelection& sel) { m_selection = sel; } + //@} + + + /** + Selects all the text in the buffer. + */ + virtual void SelectAll(); + + /** + Makes the control editable, or not. + */ + virtual void SetEditable(bool editable); + + /** + Returns @true if there is a selection and the object containing the selection + was the same as the current focus object. + */ + virtual bool HasSelection() const; + + /** + Returns @true if there was a selection, whether or not the current focus object + is the same as the selection's container object. + */ + virtual bool HasUnfocusedSelection() const; + + //@{ + /** + Write a bitmap or image at the current insertion point. + Supply an optional type to use for internal and file storage of the raw data. + */ + virtual bool WriteImage(const wxImage& image, wxBitmapType bitmapType = wxBITMAP_TYPE_PNG, + const wxRichTextAttr& textAttr = wxRichTextAttr()); + + virtual bool WriteImage(const wxBitmap& bitmap, wxBitmapType bitmapType = wxBITMAP_TYPE_PNG, + const wxRichTextAttr& textAttr = wxRichTextAttr()); + //@} + + /** + Loads an image from a file and writes it at the current insertion point. + */ + virtual bool WriteImage(const wxString& filename, wxBitmapType bitmapType, + const wxRichTextAttr& textAttr = wxRichTextAttr()); + + /** + Writes an image block at the current insertion point. + */ + virtual bool WriteImage(const wxRichTextImageBlock& imageBlock, + const wxRichTextAttr& textAttr = wxRichTextAttr()); + + /** + Write a text box at the current insertion point, returning the text box. + You can then call SetFocusObject() to set the focus to the new object. + */ + virtual wxRichTextBox* WriteTextBox(const wxRichTextAttr& textAttr = wxRichTextAttr()); + + /** + Writes a field at the current insertion point. + + @param fieldType + The field type, matching an existing field type definition. + @param properties + Extra data for the field. + @param textAttr + Optional attributes. + + @see wxRichTextField, wxRichTextFieldType, wxRichTextFieldTypeStandard + */ + virtual wxRichTextField* WriteField(const wxString& fieldType, const wxRichTextProperties& properties, + const wxRichTextAttr& textAttr = wxRichTextAttr()); + + /** + Write a table at the current insertion point, returning the table. + You can then call SetFocusObject() to set the focus to the new object. + */ + virtual wxRichTextTable* WriteTable(int rows, int cols, const wxRichTextAttr& tableAttr = wxRichTextAttr(), const wxRichTextAttr& cellAttr = wxRichTextAttr()); + + /** + Inserts a new paragraph at the current insertion point. @see LineBreak(). + */ + virtual bool Newline(); + + /** + Inserts a line break at the current insertion point. + + A line break forces wrapping within a paragraph, and can be introduced by + using this function, by appending the wxChar value @b wxRichTextLineBreakChar + to text content, or by typing Shift-Return. + */ + virtual bool LineBreak(); + + /** + Sets the basic (overall) style. + + This is the style of the whole buffer before further styles are applied, + unlike the default style, which only affects the style currently being + applied (for example, setting the default style to bold will cause + subsequently inserted text to be bold). + */ + virtual void SetBasicStyle(const wxRichTextAttr& style) { GetBuffer().SetBasicStyle(style); } + + /** + Gets the basic (overall) style. + + This is the style of the whole buffer before further styles are applied, + unlike the default style, which only affects the style currently being + applied (for example, setting the default style to bold will cause + subsequently inserted text to be bold). + */ + virtual const wxRichTextAttr& GetBasicStyle() const { return GetBuffer().GetBasicStyle(); } + + /** + Begins applying a style. + */ + virtual bool BeginStyle(const wxRichTextAttr& style) { return GetBuffer().BeginStyle(style); } + + /** + Ends the current style. + */ + virtual bool EndStyle() { return GetBuffer().EndStyle(); } + + /** + Ends application of all styles in the current style stack. + */ + virtual bool EndAllStyles() { return GetBuffer().EndAllStyles(); } + + /** + Begins using bold. + */ + bool BeginBold() { return GetBuffer().BeginBold(); } + + /** + Ends using bold. + */ + bool EndBold() { return GetBuffer().EndBold(); } + + /** + Begins using italic. + */ + bool BeginItalic() { return GetBuffer().BeginItalic(); } + + /** + Ends using italic. + */ + bool EndItalic() { return GetBuffer().EndItalic(); } + + /** + Begins using underlining. + */ + bool BeginUnderline() { return GetBuffer().BeginUnderline(); } + + /** + End applying underlining. + */ + bool EndUnderline() { return GetBuffer().EndUnderline(); } + + /** + Begins using the given point size. + */ + bool BeginFontSize(int pointSize) { return GetBuffer().BeginFontSize(pointSize); } + + /** + Ends using a point size. + */ + bool EndFontSize() { return GetBuffer().EndFontSize(); } + + /** + Begins using this font. + */ + bool BeginFont(const wxFont& font) { return GetBuffer().BeginFont(font); } + + /** + Ends using a font. + */ + bool EndFont() { return GetBuffer().EndFont(); } + + /** + Begins using this colour. + */ + bool BeginTextColour(const wxColour& colour) { return GetBuffer().BeginTextColour(colour); } + + /** + Ends applying a text colour. + */ + bool EndTextColour() { return GetBuffer().EndTextColour(); } + + /** + Begins using alignment. + For alignment values, see wxTextAttr. + */ + bool BeginAlignment(wxTextAttrAlignment alignment) { return GetBuffer().BeginAlignment(alignment); } + + /** + Ends alignment. + */ + bool EndAlignment() { return GetBuffer().EndAlignment(); } + + /** + Begins applying a left indent and subindent in tenths of a millimetre. + The subindent is an offset from the left edge 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 to the left of the subsequent lines, and + a negative value will cause the first line to be indented to the right + of the subsequent lines. + + wxRichTextBuffer uses indentation to render a bulleted item. The + content of the paragraph, including the first line, starts at the + @a leftIndent plus the @a leftSubIndent. + + @param leftIndent + The distance between the margin and the bullet. + @param leftSubIndent + The distance between the left edge of the bullet and the left edge + of the actual paragraph. + */ + bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0) { return GetBuffer().BeginLeftIndent(leftIndent, leftSubIndent); } + + /** + Ends left indent. + */ + bool EndLeftIndent() { return GetBuffer().EndLeftIndent(); } + + /** + Begins a right indent, specified in tenths of a millimetre. + */ + bool BeginRightIndent(int rightIndent) { return GetBuffer().BeginRightIndent(rightIndent); } + + /** + Ends right indent. + */ + bool EndRightIndent() { return GetBuffer().EndRightIndent(); } + + /** + Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing + in tenths of a millimetre. + */ + bool BeginParagraphSpacing(int before, int after) { return GetBuffer().BeginParagraphSpacing(before, after); } + + /** + Ends paragraph spacing. + */ + bool EndParagraphSpacing() { return GetBuffer().EndParagraphSpacing(); } + + /** + Begins appling line spacing. @e spacing is a multiple, where 10 means + single-spacing, 15 means 1.5 spacing, and 20 means double spacing. + + The ::wxTextAttrLineSpacing constants are defined for convenience. + */ + bool BeginLineSpacing(int lineSpacing) { return GetBuffer().BeginLineSpacing(lineSpacing); } + + /** + Ends line spacing. + */ + bool EndLineSpacing() { return GetBuffer().EndLineSpacing(); } /** - Ends using italic. + 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. + + @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 ::wxTextAttrBulletStyle values. + + 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 line, starts + at leftMargin + leftSubIndent. + So the distance between the left edge of the bullet and the + left of the actual paragraph is leftSubIndent. */ - bool EndItalic(); + bool BeginNumberedBullet(int bulletNumber, int leftIndent, int leftSubIndent, int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD) + { return GetBuffer().BeginNumberedBullet(bulletNumber, leftIndent, leftSubIndent, bulletStyle); } /** - Ends left indent. + Ends application of a numbered bullet. */ - bool EndLeftIndent(); + bool EndNumberedBullet() { return GetBuffer().EndNumberedBullet(); } /** - Ends line spacing. + Begins applying a symbol bullet, using a character from the current font. + See BeginNumberedBullet() for an explanation of how indentation is used + to render the bulleted paragraph. */ - bool EndLineSpacing(); + bool BeginSymbolBullet(const wxString& symbol, int leftIndent, int leftSubIndent, int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL) + { return GetBuffer().BeginSymbolBullet(symbol, leftIndent, leftSubIndent, bulletStyle); } /** - Ends using a specified list style. + Ends applying a symbol bullet. */ - bool EndListStyle(); + bool EndSymbolBullet() { return GetBuffer().EndSymbolBullet(); } /** - Ends application of a numbered bullet. + Begins applying a symbol bullet. */ - bool EndNumberedBullet(); + bool BeginStandardBullet(const wxString& bulletName, int leftIndent, int leftSubIndent, int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_STANDARD) + { return GetBuffer().BeginStandardBullet(bulletName, leftIndent, leftSubIndent, bulletStyle); } /** - Ends paragraph spacing. + Begins applying a standard bullet. + */ + bool EndStandardBullet() { return GetBuffer().EndStandardBullet(); } + + /** + Begins using the named character style. */ - bool EndParagraphSpacing(); + bool BeginCharacterStyle(const wxString& characterStyle) { return GetBuffer().BeginCharacterStyle(characterStyle); } /** Ends application of a named character style. */ - bool EndParagraphStyle(); + bool EndCharacterStyle() { return GetBuffer().EndCharacterStyle(); } /** - Ends right indent. + Begins applying the named paragraph style. */ - bool EndRightIndent(); + bool BeginParagraphStyle(const wxString& paragraphStyle) { return GetBuffer().BeginParagraphStyle(paragraphStyle); } /** - Ends the current style. + Ends application of a named paragraph style. */ - virtual bool EndStyle(); + bool EndParagraphStyle() { return GetBuffer().EndParagraphStyle(); } /** - Ends suppressing undo command history. + Begins using a specified list style. + Optionally, you can also pass a level and a number. */ - virtual bool EndSuppressUndo(); + bool BeginListStyle(const wxString& listStyle, int level = 1, int number = 1) { return GetBuffer().BeginListStyle(listStyle, level, number); } /** - Ends applying a symbol bullet. + Ends using a specified list style. */ - bool EndSymbolBullet(); + bool EndListStyle() { return GetBuffer().EndListStyle(); } /** - Ends applying a text colour. + Begins applying wxTEXT_ATTR_URL to the content. + + Pass a URL and optionally, a character style to apply, since it is common + to mark a URL with a familiar style such as blue text with underlining. */ - bool EndTextColour(); + bool BeginURL(const wxString& url, const wxString& characterStyle = wxEmptyString) { return GetBuffer().BeginURL(url, characterStyle); } /** Ends applying a URL. */ - bool EndURL(); + bool EndURL() { return GetBuffer().EndURL(); } /** - End applying underlining. + Sets the default style to the style under the cursor. */ - bool EndUnderline(); + bool SetDefaultStyleToCursorStyle(); /** - Helper function for extending the selection, returning @true if the selection - was changed. Selections are in caret positions. + Cancels any selection. */ - bool ExtendSelection(long oldPosition, long newPosition, - int flags); + virtual void SelectNone(); /** - Helper function for finding the caret position for the next word. - Direction is 1 (forward) or -1 (backwards). + Selects the word at the given character position. */ - virtual long FindNextWordPosition(int direction = 1) const; + virtual bool SelectWord(long position); /** - Call this function to prevent refresh and allow fast updates, and then Thaw() to - refresh the control. + Returns the selection range in character positions. -1, -1 means no selection. + + The range is in API convention, i.e. a single character selection is denoted + by (n, n+1) */ - void Freeze(); + wxRichTextRange GetSelectionRange() const; /** - Gets the basic (overall) style. + 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. - This is the style of the whole buffer before further styles are applied, - unlike the default style, which only affects the style currently being - applied (for example, setting the default style to bold will cause - subsequently inserted text to be bold). + So, for example, to set the selection for a character at position 5, use the + range (5,6). */ - const wxTextAttr GetBasicStyle() const; + void SetSelectionRange(const wxRichTextRange& range); - //@{ /** - Returns the buffer associated with the control. + Returns the selection range in character positions. -2, -2 means no selection + -1, -1 means select everything. + The range is in internal format, i.e. a single character selection is denoted + by (n, n) */ - const wxRichTextBuffer GetBuffer(); - const wxRichTextBuffer& GetBuffer(); - //@} + wxRichTextRange GetInternalSelectionRange() const { return m_selection.GetRange(); } /** - Returns the current caret position. + Sets the selection range in character positions. -2, -2 means no selection + -1, -1 means select everything. + The range is in internal format, i.e. a single character selection is denoted + by (n, n) */ - long GetCaretPosition() const; + void SetInternalSelectionRange(const wxRichTextRange& range) { m_selection.Set(range, GetFocusObject()); } /** - Returns the caret height and position for the given character position. + Adds a new paragraph of text to the end of the buffer. */ - bool GetCaretPositionForIndex(long position, wxRect& rect); + virtual wxRichTextRange AddParagraph(const wxString& text); /** - Gets the command processor associated with the control's buffer. + Adds an image to the control's buffer. */ - wxCommandProcessor* GetCommandProcessor() const; + virtual wxRichTextRange AddImage(const wxImage& image); /** - Returns the current default style, which can be used to change how subsequently - inserted text is displayed. + Lays out the buffer, which must be done before certain operations, such as + setting the caret position. + This function should not normally be required by the application. */ - const wxTextAttr GetDefaultStyle() const; + virtual bool LayoutContent(bool onlyVisibleRect = false); /** - Gets the size of the buffer beyond which layout is delayed during resizing. - This optimizes sizing for large buffers. The default is 20000. + 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. */ - long GetDelayedLayoutThreshold() const; + virtual bool MoveCaret(long pos, bool showAtLineStart = false, wxRichTextParagraphLayoutBox* container = NULL); /** - Gets the current filename associated with the control. + Moves right. */ - wxString GetFilename() const; + virtual bool MoveRight(int noPositions = 1, int flags = 0); /** - Returns the first visible position in the current view. + Moves left. */ - long GetFirstVisiblePosition() const; + virtual bool MoveLeft(int noPositions = 1, int flags = 0); /** - 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. + Moves to the start of the paragraph. */ - int GetHandlerFlags() const; + virtual bool MoveUp(int noLines = 1, int flags = 0); /** - Returns the current insertion point. + Moves the caret down. */ - virtual long GetInsertionPoint() const; + virtual bool MoveDown(int noLines = 1, int flags = 0); /** - Returns the last position in the buffer. + Moves to the end of the line. */ - virtual wxTextPos GetLastPosition() const; + virtual bool MoveToLineEnd(int flags = 0); /** - Returns the length of the specified line in characters. + Moves to the start of the line. */ - virtual int GetLineLength(long lineNo) const; + virtual bool MoveToLineStart(int flags = 0); /** - Returns the text for the given line. + Moves to the end of the paragraph. */ - virtual wxString GetLineText(long lineNo) const; + virtual bool MoveToParagraphEnd(int flags = 0); /** - Transforms physical window position to logical (unscrolled) position. + Moves to the start of the paragraph. */ - wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const; + virtual bool MoveToParagraphStart(int flags = 0); /** - Returns the number of lines in the buffer. + Moves to the start of the buffer. */ - virtual int GetNumberOfLines() const; + virtual bool MoveHome(int flags = 0); /** - Transforms logical (unscrolled) position to physical window position. + Moves to the end of the buffer. */ - wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const; + virtual bool MoveEnd(int flags = 0); /** - 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. + Moves one or more pages up. */ - virtual wxString GetRange(long from, long to) const; + virtual bool PageUp(int noPages = 1, int flags = 0); /** - 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 @a from and @a to are the same, there is no selection. + Moves one or more pages down. */ - virtual void GetSelection(long* from, long* to) const; + virtual bool PageDown(int noPages = 1, int flags = 0); /** - Returns the selection range in character positions. -1, -1 means no selection. + Moves a number of words to the left. */ - const wxRichTextRange GetSelectionRange() const; + virtual bool WordLeft(int noPages = 1, int flags = 0); /** - Returns the text within the current selection range, if any. + Move a nuber of words to the right. */ - virtual wxString GetStringSelection() const; + virtual bool WordRight(int noPages = 1, int flags = 0); + //@{ /** - 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 the character or paragraph style alone, use GetUncombinedStyle(). + Returns the buffer associated with the control. */ - virtual bool GetStyle(long position, wxTextAttr& style); + wxRichTextBuffer& GetBuffer() { return m_buffer; } + const wxRichTextBuffer& GetBuffer() const { return m_buffer; } + //@} /** - Gets the attributes common to the specified range. - Attributes that differ in value within the range will not be included - in @a style flags. + Starts batching undo history for commands. */ - bool GetStyleForRange(const wxRichTextRange& range, - wxTextAttr& style); + virtual bool BeginBatchUndo(const wxString& cmdName) { return m_buffer.BeginBatchUndo(cmdName); } /** - Returns the style sheet associated with the control, if any. - A style sheet allows named character and paragraph styles to be applied. + Ends batching undo command history. */ - wxRichTextStyleSheet* GetStyleSheet() const; + virtual bool EndBatchUndo() { return m_buffer.EndBatchUndo(); } /** - 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(). + Returns @true if undo commands are being batched. + */ + virtual bool BatchingUndo() const { return m_buffer.BatchingUndo(); } - 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. + /** + Starts suppressing undo history for commands. */ - virtual bool GetUncombinedStyle(long position, wxTextAttr& style); + virtual bool BeginSuppressUndo() { return m_buffer.BeginSuppressUndo(); } /** - Returns the content of the entire control as a string. + Ends suppressing undo command history. */ - virtual wxString GetValue() const; + virtual bool EndSuppressUndo() { return m_buffer.EndSuppressUndo(); } /** - Internal helper function returning the line for the visible caret position. - If the caret is shown at the very end of the line, it means the next character - is actually on the following line. - So this function gets the line we're expecting to find if this is the case. + Returns @true if undo history suppression is on. */ - wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const; + virtual bool SuppressingUndo() const { return m_buffer.SuppressingUndo(); } /** Test if this whole range has character attributes of the specified kind. @@ -821,252 +1501,325 @@ 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 wxRichTextAttr& style) const + { + return GetBuffer().HasCharacterAttributes(range.ToInternal(), style); + } + + /** + 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. + @a style must have flags indicating which attributes are of interest. + */ + virtual bool HasParagraphAttributes(const wxRichTextRange& range, const wxRichTextAttr& style) const + { + return GetBuffer().HasParagraphAttributes(range.ToInternal(), style); + } + + /** + Returns @true if all of the selection, or the content at the caret position, is bold. + */ + virtual bool IsSelectionBold(); + + /** + Returns @true if all of the selection, or the content at the caret position, is italic. + */ + virtual bool IsSelectionItalics(); + + /** + Returns @true if all of the selection, or the content at the caret position, is underlined. + */ + virtual bool IsSelectionUnderlined(); + + /** + Returns @true if all of the selection, or the content at the current caret position, has the supplied wxTextAttrEffects flag(s). + */ + virtual bool DoesSelectionHaveTextEffectFlag(int flag); + + /** + Returns @true if all of the selection is aligned according to the specified flag. + */ + virtual bool IsSelectionAligned(wxTextAttrAlignment alignment); + + /** + Apples bold to the selection or the default style (undoable). + */ + virtual bool ApplyBoldToSelection(); + + /** + Applies italic to the selection or the default style (undoable). + */ + virtual bool ApplyItalicToSelection(); + + /** + Applies underline to the selection or the default style (undoable). + */ + virtual bool ApplyUnderlineToSelection(); + + /** + Applies one or more wxTextAttrEffects flags to the selection (undoable). + If there is no selection, it is applied to the default style. + */ + virtual bool ApplyTextEffectToSelection(int flags); + + /** + Applies the given alignment to the selection or the default style (undoable). + For alignment values, see wxTextAttr. + */ + virtual bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); + + /** + 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 @a sheet is @NULL, the sheet set with SetStyleSheet() is used. + Currently this applies paragraph styles only. + */ + virtual bool ApplyStyle(wxRichTextStyleDefinition* def); + + /** + Sets the style sheet associated with the control. + A style sheet allows named character and paragraph styles to be applied. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet) { GetBuffer().SetStyleSheet(styleSheet); } + + /** + Returns the style sheet associated with the control, if any. + A style sheet allows named character and paragraph styles to be applied. + */ + wxRichTextStyleSheet* GetStyleSheet() const { return GetBuffer().GetStyleSheet(); } + + /** + Push the style sheet to top of stack. + */ + bool PushStyleSheet(wxRichTextStyleSheet* styleSheet) { return GetBuffer().PushStyleSheet(styleSheet); } + + /** + Pops the style sheet from top of stack. + */ + wxRichTextStyleSheet* PopStyleSheet() { return GetBuffer().PopStyleSheet(); } /** - 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. - @a style must have flags indicating which attributes are of interest. + Applies the style sheet to the buffer, for example if the styles have changed. */ - bool HasParagraphAttributes(const wxRichTextRange& range, - const wxTextAttr& style) const; + bool ApplyStyleSheet(wxRichTextStyleSheet* styleSheet = NULL); /** - Returns @true if there is a selection. + Shows the given context menu, optionally adding appropriate property-editing commands for the current position in the object hierarchy. */ - virtual bool HasSelection() const; + virtual bool ShowContextMenu(wxMenu* menu, const wxPoint& pt, bool addPropertyCommands); - //@{ /** - Finds the character at the given position in pixels. - @a pt is in device coords (not adjusted for the client area origin nor for - scrolling). + Prepares the context menu, optionally adding appropriate property-editing commands. + Returns the number of property commands added. */ - wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos) const; - const wxTextCtrlHitTestResult HitTest(const wxPoint& pt, - wxTextCoord* col, - wxTextCoord* row) const; - //@} + virtual int PrepareContextMenu(wxMenu* menu, const wxPoint& pt, bool addPropertyCommands); /** - Initialises the members of the control. + Returns @true if we can edit the object's properties via a GUI. */ - void Init(); + virtual bool CanEditProperties(wxRichTextObject* obj) const; /** - Initialises the command event. + Edits the object's properties via a GUI. */ - void InitCommandEvent(wxCommandEvent& event) const; + virtual bool EditProperties(wxRichTextObject* obj, wxWindow* parent); /** - 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. + Gets the object's properties menu label. + */ + virtual wxString GetPropertiesMenuLabel(wxRichTextObject* obj); - Below is an example of code that uses this function to determine whether the UI - should show that the current style is bold. + /** + Prepares the content just before insertion (or after buffer reset). Called by the same function in wxRichTextBuffer. + Currently is only called if undo mode is on. + */ + virtual void PrepareContent(wxRichTextParagraphLayoutBox& WXUNUSED(container)) {} - @see SetAndShowDefaultStyle(). + /** + Can we delete this range? + Sends an event to the control. */ - bool IsDefaultStyleShowing() const; + virtual bool CanDeleteRange(wxRichTextParagraphLayoutBox& container, const wxRichTextRange& range) const; /** - Returns @true if the control is editable. + Can we insert content at this position? + Sends an event to the control. */ - virtual bool IsEditable() const; + virtual bool CanInsertContent(wxRichTextParagraphLayoutBox& container, long pos) const; /** - Returns @true if Freeze has been called without a Thaw. + Enable or disable the vertical scrollbar. */ - bool IsFrozen() const; + virtual void EnableVerticalScrollbar(bool enable); /** - Returns @true if the buffer has been modified. + Returns @true if the vertical scrollbar is enabled. */ - virtual bool IsModified() const; + virtual bool GetVerticalScrollbarEnabled() const; /** - Returns @true if the control is multiline. + Sets the scale factor for displaying fonts, for example for more comfortable + editing. */ - bool IsMultiLine() const; + void SetFontScale(double fontScale, bool refresh = false); /** - Returns @true if the given position is visible on the screen. + Returns the scale factor for displaying fonts, for example for more comfortable + editing. */ - bool IsPositionVisible(long pos) const; + double GetFontScale() const { return GetBuffer().GetFontScale(); } /** - Returns @true if all of the selection is aligned according to the specified flag. + Sets the scale factor for displaying certain dimensions such as indentation and + inter-paragraph spacing. This can be useful when editing in a small control + where you still want legible text, but a minimum of wasted white space. */ - virtual bool IsSelectionAligned(wxTextAttrAlignment alignment); + void SetDimensionScale(double dimScale, bool refresh = false); /** - Returns @true if all of the selection is bold. + Returns the scale factor for displaying certain dimensions such as indentation + and inter-paragraph spacing. */ - virtual bool IsSelectionBold(); + double GetDimensionScale() const { return GetBuffer().GetDimensionScale(); } /** - Returns @true if all of the selection is italic. + Sets an overall scale factor for displaying and editing the content. */ - virtual bool IsSelectionItalics(); + void SetScale(double scale, bool refresh = false); /** - Returns @true if all of the selection is underlined. + Returns an overall scale factor for displaying and editing the content. */ - virtual bool IsSelectionUnderlined(); + double GetScale() const { return m_scale; } /** - Returns @true if the control is single-line. - Currently wxRichTextCtrl does not support single-line editing. + Returns an unscaled point. */ - bool IsSingleLine() const; + wxPoint GetUnscaledPoint(const wxPoint& pt) const; /** - Helper function implementing keyboard navigation. + Returns a scaled point. */ - virtual bool KeyboardNavigate(int keyCode, int flags); + wxPoint GetScaledPoint(const wxPoint& pt) const; /** - Lays out the buffer, which must be done before certain operations, such as - setting the caret position. - This function should not normally be required by the application. + Returns an unscaled size. */ - virtual bool LayoutContent(bool onlyVisibleRect = false); + wxSize GetUnscaledSize(const wxSize& sz) const; /** - Inserts a line break at the current insertion point. + Returns a scaled size. + */ + wxSize GetScaledSize(const wxSize& sz) const; - A line break forces wrapping within a paragraph, and can be introduced by - using this function, by appending the wxChar value @b wxRichTextLineBreakChar - to text content, or by typing Shift-Return. + /** + Returns an unscaled rectangle. */ - virtual bool LineBreak(); + wxRect GetUnscaledRect(const wxRect& rect) const; /** - Loads content into the control's buffer using the given type. + Returns a scaled rectangle. + */ + wxRect GetScaledRect(const wxRect& rect) const; - If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from - the filename extension. +// Command handlers - This function looks for a suitable wxRichTextFileHandler object. + /** + Sends the event to the control. */ - bool LoadFile(const wxString& file, - int type = wxRICHTEXT_TYPE_ANY); + void Command(wxCommandEvent& event); /** - Marks the buffer as modified. + Loads the first dropped file. */ - virtual void MarkDirty(); + void OnDropFiles(wxDropFilesEvent& event); + + void OnCaptureLost(wxMouseCaptureLostEvent& event); + void OnSysColourChanged(wxSysColourChangedEvent& event); /** - Move the caret to the given character position. + Standard handler for the wxID_CUT command. */ - virtual bool MoveCaret(long pos, bool showAtLineStart = false); + void OnCut(wxCommandEvent& event); /** - Move the caret one visual step forward: this may mean setting a flag - and keeping the same position if we're going from the end of one line - to the start of the next, which may be the exact same caret position. + Standard handler for the wxID_COPY command. */ - void MoveCaretBack(long oldPosition); + void OnCopy(wxCommandEvent& event); /** - Move the caret one visual step forward: this may mean setting a flag - and keeping the same position if we're going from the end of one line - to the start of the next, which may be the exact same caret position. + Standard handler for the wxID_PASTE command. */ - void MoveCaretForward(long oldPosition); + void OnPaste(wxCommandEvent& event); /** - Moves the caret down. + Standard handler for the wxID_UNDO command. */ - virtual bool MoveDown(int noLines = 1, int flags = 0); + void OnUndo(wxCommandEvent& event); /** - Moves to the end of the buffer. + Standard handler for the wxID_REDO command. */ - virtual bool MoveEnd(int flags = 0); + void OnRedo(wxCommandEvent& event); /** - Moves to the start of the buffer. + Standard handler for the wxID_SELECTALL command. */ - virtual bool MoveHome(int flags = 0); + void OnSelectAll(wxCommandEvent& event); /** - Moves left. + Standard handler for property commands. */ - virtual bool MoveLeft(int noPositions = 1, int flags = 0); + void OnProperties(wxCommandEvent& event); /** - Moves right. + Standard handler for the wxID_CLEAR command. */ - virtual bool MoveRight(int noPositions = 1, int flags = 0); + void OnClear(wxCommandEvent& event); /** - Moves to the end of the line. + Standard update handler for the wxID_CUT command. */ - virtual bool MoveToLineEnd(int flags = 0); + void OnUpdateCut(wxUpdateUIEvent& event); /** - Moves to the start of the line. + Standard update handler for the wxID_COPY command. */ - virtual bool MoveToLineStart(int flags = 0); + void OnUpdateCopy(wxUpdateUIEvent& event); /** - Moves to the end of the paragraph. + Standard update handler for the wxID_PASTE command. */ - virtual bool MoveToParagraphEnd(int flags = 0); + void OnUpdatePaste(wxUpdateUIEvent& event); /** - Moves to the start of the paragraph. + Standard update handler for the wxID_UNDO command. */ - virtual bool MoveToParagraphStart(int flags = 0); + void OnUpdateUndo(wxUpdateUIEvent& event); /** - Moves up. + Standard update handler for the wxID_REDO command. */ - virtual bool MoveUp(int noLines = 1, int flags = 0); + void OnUpdateRedo(wxUpdateUIEvent& event); /** - Inserts a new paragraph at the current insertion point. @see LineBreak(). + Standard update handler for the wxID_SELECTALL command. */ - virtual bool Newline(); + void OnUpdateSelectAll(wxUpdateUIEvent& event); - //@{ /** - Numbers the paragraphs in the given range. - 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. - - @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 - @a startFrom, otherwise existing attributes are 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 SetListStyle(), PromoteList(), ClearListStyle(). + Standard update handler for property commands. */ - bool NumberList(const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - bool Number(const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - //@} + + void OnUpdateProperties(wxUpdateUIEvent& event); /** - Standard handler for the wxID_CLEAR command. + Standard update handler for the wxID_CLEAR command. */ - void OnClear(wxCommandEvent& event); + void OnUpdateClear(wxUpdateUIEvent& event); /** Shows a standard context menu with undo, redo, cut, copy, paste, clear, and @@ -1074,175 +1827,233 @@ public: */ void OnContextMenu(wxContextMenuEvent& event); - /** - Standard handler for the wxID_COPY command. - */ - void OnCopy(wxCommandEvent& event); +// Event handlers - /** - Standard handler for the wxID_CUT command. - */ - void OnCut(wxCommandEvent& event); + // Painting + void OnPaint(wxPaintEvent& event); + void OnEraseBackground(wxEraseEvent& event); + + // Left-click + void OnLeftClick(wxMouseEvent& event); + + // Left-up + void OnLeftUp(wxMouseEvent& event); + + // Motion + void OnMoveMouse(wxMouseEvent& event); + + // Left-double-click + void OnLeftDClick(wxMouseEvent& event); + + // Middle-click + void OnMiddleClick(wxMouseEvent& event); + + // Right-click + void OnRightClick(wxMouseEvent& event); + + // Key press + void OnChar(wxKeyEvent& event); + + // Sizing + void OnSize(wxSizeEvent& event); + + // Setting/losing focus + void OnSetFocus(wxFocusEvent& event); + void OnKillFocus(wxFocusEvent& event); + + // Idle-time processing + void OnIdle(wxIdleEvent& event); + + // Scrolling + void OnScroll(wxScrollWinEvent& event); /** - Loads the first dropped file. + Sets the font, and also the basic and default attributes + (see wxRichTextCtrl::SetDefaultStyle). */ - void OnDropFiles(wxDropFilesEvent& event); + virtual bool SetFont(const wxFont& font); /** - Standard handler for the wxID_PASTE command. + A helper function setting up scrollbars, for example after a resize. */ - void OnPaste(wxCommandEvent& event); + virtual void SetupScrollbars(bool atTop = false); /** - Standard handler for the wxID_REDO command. + Helper function implementing keyboard navigation. */ - void OnRedo(wxCommandEvent& event); + virtual bool KeyboardNavigate(int keyCode, int flags); /** - Standard handler for the wxID_SELECTALL command. + Paints the background. */ - void OnSelectAll(wxCommandEvent& event); + virtual void PaintBackground(wxDC& dc); /** - Standard handler for the wxID_PASTE command. + Other user defined painting after everything else (i.e. all text) is painted. + + @since 2.9.1 */ - void OnUndo(wxCommandEvent& event); + virtual void PaintAboveContent(wxDC& WXUNUSED(dc)) {} +#if wxRICHTEXT_BUFFERED_PAINTING /** - Standard update handler for the wxID_CLEAR command. + Recreates the buffer bitmap if necessary. */ - void OnUpdateClear(wxUpdateUIEvent& event); + virtual bool RecreateBuffer(const wxSize& size = wxDefaultSize); +#endif + + // Write text + virtual void DoWriteText(const wxString& value, int flags = 0); + + // Should we inherit colours? + virtual bool ShouldInheritColours() const { return false; } /** - Standard update handler for the wxID_COPY command. + Internal function to position the visible caret according to the current caret + position. */ - void OnUpdateCopy(wxUpdateUIEvent& event); + virtual void PositionCaret(wxRichTextParagraphLayoutBox* container = NULL); /** - Standard update handler for the wxID_CUT command. + Helper function for extending the selection, returning @true if the selection + was changed. Selections are in caret positions. */ - void OnUpdateCut(wxUpdateUIEvent& event); + virtual bool ExtendSelection(long oldPosition, long newPosition, int flags); /** - Standard update handler for the wxID_PASTE command. + Scrolls @a position into view. This function takes a caret position. */ - void OnUpdatePaste(wxUpdateUIEvent& event); + virtual bool ScrollIntoView(long position, int keyCode); /** - Standard update handler for the wxID_REDO command. + Refreshes the area affected by a selection change. */ - void OnUpdateRedo(wxUpdateUIEvent& event); + bool RefreshForSelectionChange(const wxRichTextSelection& oldSelection, const wxRichTextSelection& newSelection); /** - Standard update handler for the wxID_SELECTALL command. + 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 OnUpdateSelectAll(wxUpdateUIEvent& event); + void SetCaretPosition(long position, bool showAtLineStart = false) ; /** - Standard update handler for the wxID_UNDO command. + Returns the current caret position. */ - void OnUpdateUndo(wxUpdateUIEvent& event); + long GetCaretPosition() const { return m_caretPosition; } /** - Moves one or more pages down. + The adjusted caret position is the character position adjusted to take + into account whether we're at the start of a paragraph, in which case + style information should be taken from the next position, not current one. */ - virtual bool PageDown(int noPages = 1, int flags = 0); + long GetAdjustedCaretPosition(long caretPos) const; /** - Moves one or more pages up. + Move the caret one visual step forward: this may mean setting a flag + and keeping the same position if we're going from the end of one line + to the start of the next, which may be the exact same caret position. */ - virtual bool PageUp(int noPages = 1, int flags = 0); + void MoveCaretForward(long oldPosition) ; /** - Paints the background. + Move the caret one visual step forward: this may mean setting a flag + and keeping the same position if we're going from the end of one line + to the start of the next, which may be the exact same caret position. */ - virtual void PaintBackground(wxDC& dc); + void MoveCaretBack(long oldPosition) ; /** - Pastes content from the clipboard to the buffer. + Returns the caret height and position for the given character position. + If container is null, the current focus object will be used. + + @beginWxPerlOnly + In wxPerl this method is implemented as + GetCaretPositionForIndex(@a position) returning a + 2-element list (ok, rect). + @endWxPerlOnly */ - virtual void Paste(); + bool GetCaretPositionForIndex(long position, wxRect& rect, wxRichTextParagraphLayoutBox* container = NULL); /** - Internal function to position the visible caret according to the current caret - position. + Internal helper function returning the line for the visible caret position. + If the caret is shown at the very end of the line, it means the next character + is actually on the following line. + So this function gets the line we're expecting to find if this is the case. */ - virtual void PositionCaret(); + wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const; /** - Converts a text position to zero-based column and line numbers. + Gets the command processor associated with the control's buffer. */ - virtual bool PositionToXY(long pos, long* x, long* y) const; + wxCommandProcessor* GetCommandProcessor() const { return GetBuffer().GetCommandProcessor(); } - //@{ /** - 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. + 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. - @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 - @a startFrom, otherwise existing attributes are 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. + @beginWxPerlOnly + In wxPerl this method takes no arguments and returns a 2-element + list (ok, newPos). + @endWxPerlOnly + */ + bool DeleteSelectedContent(long* newPos= NULL); - @see SetListStyle(), @see SetListStyle(), ClearListStyle(). + /** + Transforms logical (unscrolled) position to physical window position. */ - bool PromoteList(int promoteBy, const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int listLevel = -1); - bool PromoteList(int promoteBy, const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int listLevel = -1); - //@} + wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const; /** - Redoes the current command. + Transforms physical window position to logical (unscrolled) position. */ - virtual void Redo(); + wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const; /** - Removes the content in the specified range. + Helper function for finding the caret position for the next word. + Direction is 1 (forward) or -1 (backwards). */ - virtual void Remove(long from, long to); + virtual long FindNextWordPosition(int direction = 1) const; /** - Replaces the content in the specified range with the string specified by - @a value. + Returns @true if the given position is visible on the screen. */ - virtual void Replace(long from, long to, const wxString& value); + bool IsPositionVisible(long pos) const; /** - 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. + Returns the first visible position in the current view. */ - bool SaveFile(const wxString& file = wxEmptyString, - int type = wxRICHTEXT_TYPE_ANY); + long GetFirstVisiblePosition() const; /** - Scrolls @a position into view. This function takes a caret position. + Returns the caret position since the default formatting was changed. As + soon as this position changes, we no longer reflect the default style + in the UI. A value of -2 means that we should only reflect the style of the + content under the caret. */ - virtual bool ScrollIntoView(long position, int keyCode); + long GetCaretPositionForDefaultStyle() const { return m_caretPositionForDefaultStyle; } /** - Selects all the text in the buffer. + Set the caret position for the default style that the user is selecting. */ - virtual void SelectAll(); + void SetCaretPositionForDefaultStyle(long pos) { m_caretPositionForDefaultStyle = pos; } /** - Cancels any selection. + 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 SetAndShowDefaultStyle(). */ - virtual void SelectNone(); + bool IsDefaultStyleShowing() const { return m_caretPositionForDefaultStyle != -2; } /** Sets @a attr as the default style and tells the control that the UI should @@ -1250,249 +2061,383 @@ public: @see IsDefaultStyleShowing(). */ - void SetAndShowDefaultStyle(const wxTextAttr& attr); + void SetAndShowDefaultStyle(const wxRichTextAttr& attr) + { + SetDefaultStyle(attr); + SetCaretPositionForDefaultStyle(GetCaretPosition()); + } /** - Sets the basic (overall) style. - - This is the style of the whole buffer before further styles are applied, - unlike the default style, which only affects the style currently being - applied (for example, setting the default style to bold will cause - subsequently inserted text to be bold). + Returns the first visible point in the window. */ - virtual void SetBasicStyle(const wxTextAttr& style); + wxPoint GetFirstVisiblePoint() const; +#ifdef DOXYGEN /** - 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. + Returns the content of the entire control as a string. */ - void SetCaretPosition(long position, - bool showAtLineStart = false); + virtual wxString GetValue() const; /** - Sets the current default style, which can be used to change how subsequently - inserted text is displayed. + Replaces existing content with the given text. */ - virtual bool SetDefaultStyle(const wxTextAttr& style); + virtual void SetValue(const wxString& value); /** - Sets the default style to the style under the cursor. + Call this function to prevent refresh and allow fast updates, and then Thaw() to + refresh the control. */ - bool SetDefaultStyleToCursorStyle(); + void Freeze(); /** - Sets the size of the buffer beyond which layout is delayed during resizing. - This optimizes sizing for large buffers. The default is 20000. + Call this function to end a Freeze and refresh the display. */ - void SetDelayedLayoutThreshold(long threshold); + void Thaw(); /** - Makes the control editable, or not. + Returns @true if Freeze has been called without a Thaw. */ - virtual void SetEditable(bool editable); + bool IsFrozen() const; + +#endif + +// Implementation /** - Sets the current filename. + Sets up the caret for the given position and container, after a mouse click. */ - void SetFilename(const wxString& filename); + bool SetCaretPositionAfterClick(wxRichTextParagraphLayoutBox* container, long position, int hitTestFlags, bool extendSelection = false); /** - Sets the font, and also the basic and default attributes - (see wxRichTextCtrl::SetDefaultStyle). + Find the caret position for the combination of hit-test flags and character position. + Returns the caret position and also an indication of where to place the caret (caretLineStart) + since this is ambiguous (same position used for end of line and start of next). */ - virtual bool SetFont(const wxFont& font); + long FindCaretPositionForCharacterPosition(long position, int hitTestFlags, wxRichTextParagraphLayoutBox* container, + bool& caretLineStart); /** - Sets 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. + Processes mouse movement in order to change the cursor */ - void SetHandlerFlags(int flags); + virtual bool ProcessMouseMovement(wxRichTextParagraphLayoutBox* container, wxRichTextObject* obj, long position, const wxPoint& pos); /** - Sets the insertion point. + Font names take a long time to retrieve, so cache them (on demand). */ - virtual void SetInsertionPoint(long pos); + static const wxArrayString& GetAvailableFontNames(); /** - Sets the insertion point to the end of the text control. + Clears the cache of available font names. */ - virtual void SetInsertionPointEnd(); + static void ClearAvailableFontNames(); - //@{ - /** - Sets the list attributes for the given range, passing flags to determine how - the attributes are set. + WX_FORWARD_TO_SCROLL_HELPER() - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @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 - @a startFrom, otherwise existing attributes are 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. + // implement wxTextEntry methods + virtual wxString DoGetValue() const; - @see NumberList(), PromoteList(), ClearListStyle(). - */ - bool SetListStyle(const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - bool SetListStyle(const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - //@} +protected: + // implement the wxTextEntry pure virtual method + virtual wxWindow *GetEditableWindow() { return this; } - /** - 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. + // margins functions + virtual bool DoSetMargins(const wxPoint& pt); + virtual wxPoint DoGetMargins() const; - So, for example, to set the selection for a character at position 5, use the - range (5,6). - */ - virtual void SetSelection(long from, long to); + // FIXME: this does not work, it allows this code to compile but will fail + // during run-time +#ifndef __WXUNIVERSAL__ +#ifdef __WXMSW__ + virtual WXHWND GetEditHWND() const { return GetHWND(); } +#endif +#ifdef __WXMOTIF__ + virtual WXWidget GetTextWidget() const { return NULL; } +#endif +#ifdef __WXGTK20__ + virtual GtkEditable *GetEditable() const { return NULL; } + virtual GtkEntry *GetEntry() const { return NULL; } +#endif +#endif // !__WXUNIVERSAL__ - /** - 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. +// Overrides +protected: - So, for example, to set the selection for a character at position 5, use the - range (5,6). + /** + Currently this simply returns @c wxSize(10, 10). */ - void SetSelectionRange(const wxRichTextRange& range); + virtual wxSize DoGetBestSize() const ; - //@{ + virtual void DoSetValue(const wxString& value, int flags = 0); + + virtual void DoThaw(); + + +// Data members +protected: +#if wxRICHTEXT_BUFFERED_PAINTING + /// Buffer bitmap + wxBitmap m_bufferBitmap; +#endif + + /// Text buffer + wxRichTextBuffer m_buffer; + + wxMenu* m_contextMenu; + + /// Caret position (1 less than the character position, so -1 is the + /// first caret position). + long m_caretPosition; + + /// Caret position when the default formatting has been changed. As + /// soon as this position changes, we no longer reflect the default style + /// in the UI. + long m_caretPositionForDefaultStyle; + + /// Selection range in character positions. -2, -2 means no selection. + wxRichTextSelection m_selection; + + wxRichTextCtrlSelectionState m_selectionState; + + /// Anchor so we know how to extend the selection + /// It's a caret position since it's between two characters. + long m_selectionAnchor; + + /// Anchor object if selecting multiple container objects, such as grid cells. + wxRichTextObject* m_selectionAnchorObject; + + /// Are we editable? + bool m_editable; + + /// Are we showing the caret position at the start of a line + /// instead of at the end of the previous one? + bool m_caretAtLineStart; + + /// Are we dragging a selection? + bool m_dragging; + + /// Do we need full layout in idle? + bool m_fullLayoutRequired; + wxLongLong m_fullLayoutTime; + long m_fullLayoutSavedPosition; + + /// Threshold for doing delayed layout + long m_delayedLayoutThreshold; + + /// Cursors + wxCursor m_textCursor; + wxCursor m_urlCursor; + + static wxArrayString sm_availableFontNames; + + wxRichTextContextMenuPropertiesInfo m_contextMenuPropertiesInfo; + + /// The object that currently has the editing focus + wxRichTextParagraphLayoutBox* m_focusObject; +}; + +/** + @class wxRichTextEvent + + This is the event class for wxRichTextCtrl notifications. + + @beginEventTable{wxRichTextEvent} + @event{EVT_RICHTEXT_LEFT_CLICK(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_LEFT_CLICK event, generated when the user + releases the left mouse button over an object. + @event{EVT_RICHTEXT_RIGHT_CLICK(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_RIGHT_CLICK event, generated when the user + releases the right mouse button over an object. + @event{EVT_RICHTEXT_MIDDLE_CLICK(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_MIDDLE_CLICK event, generated when the user + releases the middle mouse button over an object. + @event{EVT_RICHTEXT_LEFT_DCLICK(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_LEFT_DCLICK event, generated when the user + double-clicks an object. + @event{EVT_RICHTEXT_RETURN(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_RETURN event, generated when the user + presses the return key. Valid event functions: GetFlags, GetPosition. + @event{EVT_RICHTEXT_CHARACTER(id, func)} + 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 @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 @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 @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 @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 @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 @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_PROPERTIES_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_PROPERTIES_CHANGED event, generated when + properties have been applied to the control. Valid event functions: GetPosition, GetRange. + @event{EVT_RICHTEXT_CONTENT_INSERTED(id, func)} + 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 @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 @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. + @event{EVT_RICHTEXT_SELECTION_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_SELECTION_CHANGED event, generated when the + selection range has changed. + @event{EVT_RICHTEXT_FOCUS_OBJECT_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_RICHTEXT_FOCUS_OBJECT_CHANGED event, generated when the + current focus object has changed. + @endEventTable + + @library{wxrichtext} + @category{events,richtext} +*/ + +class WXDLLIMPEXP_RICHTEXT wxRichTextEvent : public wxNotifyEvent +{ +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. + Constructor. - So, for example, to set the style for a character at position 5, use the range - (5,6). + @param commandType + The type of the event. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. */ - bool SetStyle(const wxRichTextRange& range, - const wxTextAttr& style); - bool SetStyle(long start, long end, const wxTextAttr& style); - //@} + wxRichTextEvent(wxEventType commandType = wxEVT_NULL, int winid = 0) + : wxNotifyEvent(commandType, winid), + m_flags(0), m_position(-1), m_oldStyleSheet(NULL), m_newStyleSheet(NULL), + m_char((wxChar) 0), m_container(NULL), m_oldContainer(NULL) + { } - //@{ /** - Sets the attributes for the given range, passing flags to determine how the - attributes are set. + Copy constructor. + */ + wxRichTextEvent(const wxRichTextEvent& event) + : wxNotifyEvent(event), + m_flags(event.m_flags), m_position(-1), + m_oldStyleSheet(event.m_oldStyleSheet), m_newStyleSheet(event.m_newStyleSheet), + m_char((wxChar) 0), m_container(event.m_container), m_oldContainer(event.m_oldContainer) + { } - 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). + /** + Returns the buffer position at which the event occurred. + */ + long GetPosition() const { return m_position; } - @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. - - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied - if the combined style at this point is already the style in question. - - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be - applied to paragraphs, and not the content. - This allows content styling to be preserved independently from that - of e.g. a named paragraph style. - - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be - applied to characters, and not the paragraph. - This allows content styling to be preserved independently from that - of e.g. a named paragraph style. - - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying - the new style. - - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags - are used in this operation. + /** + Sets the buffer position variable. */ - 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); - //@} + void SetPosition(long pos) { m_position = pos; } /** - Sets the style sheet associated with the control. - A style sheet allows named character and paragraph styles to be applied. + Returns flags indicating modifier keys pressed. + + Possible values are @c wxRICHTEXT_CTRL_DOWN, @c wxRICHTEXT_SHIFT_DOWN, and @c wxRICHTEXT_ALT_DOWN. */ - void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + int GetFlags() const { return m_flags; } /** - Replaces existing content with the given text. + Sets flags indicating modifier keys pressed. + + Possible values are @c wxRICHTEXT_CTRL_DOWN, @c wxRICHTEXT_SHIFT_DOWN, and @c wxRICHTEXT_ALT_DOWN. */ - virtual void SetValue(const wxString& value); + void SetFlags(int flags) { m_flags = flags; } /** - A helper function setting up scrollbars, for example after a resize. + Returns the old style sheet. + + Can be used in a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. */ - virtual void SetupScrollbars(bool atTop = false); + wxRichTextStyleSheet* GetOldStyleSheet() const { return m_oldStyleSheet; } /** - Scrolls the buffer so that the given position is in view. + Sets the old style sheet variable. */ - virtual void ShowPosition(long pos); + void SetOldStyleSheet(wxRichTextStyleSheet* sheet) { m_oldStyleSheet = sheet; } /** - Returns @true if undo history suppression is on. + Returns the new style sheet. + + Can be used in a @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + @c wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. */ - virtual bool SuppressingUndo() const; + wxRichTextStyleSheet* GetNewStyleSheet() const { return m_newStyleSheet; } /** - Call this function to end a Freeze and refresh the display. + Sets the new style sheet variable. */ - void Thaw(); + void SetNewStyleSheet(wxRichTextStyleSheet* sheet) { m_newStyleSheet = sheet; } /** - Undoes the command at the top of the command history, if there is one. + Gets the range for the current operation. */ - virtual void Undo(); + const wxRichTextRange& GetRange() const { return m_range; } /** - Moves a number of words to the left. + Sets the range variable. */ - virtual bool WordLeft(int noWords = 1, int flags = 0); + void SetRange(const wxRichTextRange& range) { m_range = range; } /** - Move a nuber of words to the right. + Returns the character pressed, within a @c wxEVT_COMMAND_RICHTEXT_CHARACTER event. */ - virtual bool WordRight(int noWords = 1, int flags = 0); + wxChar GetCharacter() const { return m_char; } /** - Loads an image from a file and writes it at the current insertion point. + Sets the character variable. */ - bool WriteImage(const wxString& filename, int bitmapType); + void SetCharacter(wxChar ch) { m_char = ch; } /** - Writes an image block at the current insertion point. + Returns the container for which the event is relevant. */ - virtual bool WriteImage(const wxRichTextImageBlock& imageBlock); + wxRichTextParagraphLayoutBox* GetContainer() const { return m_container; } - //@{ /** - Write a bitmap or image at the current insertion point. - Supply an optional type to use for internal and file storage of the raw data. + Sets the container for which the event is relevant. */ - bool WriteImage(const wxBitmap& bitmap, - int bitmapType = wxBITMAP_TYPE_PNG); - bool WriteImage(const wxImage& image, - int bitmapType = wxBITMAP_TYPE_PNG); - //@} + void SetContainer(wxRichTextParagraphLayoutBox* container) { m_container = container; } /** - Writes text at the current position. + Returns the old container, for a focus change event. */ - virtual void WriteText(const wxString& text); + wxRichTextParagraphLayoutBox* GetOldContainer() const { return m_oldContainer; } /** - Translates from column and line number to position. + Sets the old container, for a focus change event. */ - virtual long XYToPosition(long x, long y) const; -}; + void SetOldContainer(wxRichTextParagraphLayoutBox* container) { m_oldContainer = container; } + + virtual wxEvent *Clone() const { return new wxRichTextEvent(*this); } +protected: + int m_flags; + long m_position; + wxRichTextStyleSheet* m_oldStyleSheet; + wxRichTextStyleSheet* m_newStyleSheet; + wxRichTextRange m_range; + wxChar m_char; + wxRichTextParagraphLayoutBox* m_container; + wxRichTextParagraphLayoutBox* m_oldContainer; + +private: + DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxRichTextEvent) +};