wxRichTextCtrl provides a generic implementation of a rich text editor that can handle different character styles, paragraph formatting, and images. It's aimed at editing 'natural' language text - if you need an editor that supports code editing, wxStyledTextCtrl is a better choice.
Despite its name, it cannot currently read or write RTF (rich text format) files. Instead, it uses its own XML format, and can also read and write plain text. In future we expect to provide RTF file capabilities. Custom file formats can be supported by creating additional file handlers and registering them with the control.
wxRichTextCtrl is largely compatible with the wxTextCtrl API, but extends it where necessary. The control can be used where the native rich text capabilities of wxTextCtrl are not adequate (this is particularly true on Windows) and where more direct access to the content representation is required. It is difficult and inefficient to read the style information in a wxTextCtrl, whereas this information is readily available in wxRichTextCtrl. Since it's written in pure wxWidgets, any customizations you make to wxRichTextCtrl will be reflected on all platforms.
wxRichTextCtrl supports basic printing via the easy-to-use wxRichTextPrinting class. Creating applications with simple word processing features is simplified with the inclusion of wxRichTextFormattingDialog, a tabbed dialog allowing interactive tailoring of paragraph and character styling. Also provided is the multi-purpose dialog wxRichTextStyleOrganiserDialog that can be used for managing style definitions, browsing styles and applying them, or selecting list styles with a renumber option.
There are a few disadvantages to using wxRichTextCtrl. It is not native, so does not behave exactly as a native wxTextCtrl, although common editing conventions are followed. Users may miss the built-in spelling correction on Mac OS X, or any special character input that may be provided by the native control. It would also be a poor choice if intended users rely on screen readers that would be not work well with non-native text input implementation. You might mitigate this by providing the choice between wxTextCtrl and wxRichTextCtrl, with fewer features in the former case.
Adds a new paragraph of text to the end of the buffer.
Adds an image to the control's buffer.
Applies the given alignment to the selection (undoable).
For alignment values, see wxTextAttrEx.
Apples bold to the selection (undoable).
Applies italic to the selection (undoable).
Applies the given style to the selection.
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 sheet is NULL, the sheet set with set_rich_style_sheet is used.
Currently this applies paragraph styles only.
Applies underline to the selection (undoable).
Returns true if undo commands are being batched.
Begins using alignment
For alignment values, see wxTextAttrEx.
Starts batching undo history for commands.
Begins using bold.
Begins using the named character style.
Begins using this font.
Begins using the given point size.
Begins using italic.
Begins applying a left indent and subindent in tenths of a millimetre.
The sub-indent is an offset from the left of the paragraph, and is used for all but the first line in a paragraph. A positive value will cause the first line to appear to the left of the subsequent lines, and a negative value will cause the first line to be indented relative to the subsequent lines.
wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between the margin and the bullet. The content of the paragraph, including the first line, starts at leftMargin + leftSubIndent. So the distance between the left edge of the bullet and the left of the actual paragraph is leftSubIndent.
Begins appling line spacing. spacing is a multiple, where 10 means single-spacing, 15 means 1.5 spacing, and 20 means double spacing. The following constants are defined for convenience:
#define wxTEXT_ATTR_LINE_SPACING_NORMAL 10 #define wxTEXT_ATTR_LINE_SPACING_HALF 15 #define wxTEXT_ATTR_LINE_SPACING_TWICE 20
Begins using a specified list style. Optionally, you can also pass a level and a number.
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.
#define wxTEXT_ATTR_BULLET_STYLE_NONE 0x00000000 #define wxTEXT_ATTR_BULLET_STYLE_ARABIC 0x00000001 #define wxTEXT_ATTR_BULLET_STYLE_LETTERS_UPPER 0x00000002 #define wxTEXT_ATTR_BULLET_STYLE_LETTERS_LOWER 0x00000004 #define wxTEXT_ATTR_BULLET_STYLE_ROMAN_UPPER 0x00000008 #define wxTEXT_ATTR_BULLET_STYLE_ROMAN_LOWER 0x00000010 #define wxTEXT_ATTR_BULLET_STYLE_SYMBOL 0x00000020 #define wxTEXT_ATTR_BULLET_STYLE_BITMAP 0x00000040 #define wxTEXT_ATTR_BULLET_STYLE_PARENTHESES 0x00000080 #define wxTEXT_ATTR_BULLET_STYLE_PERIOD 0x00000100 #define wxTEXT_ATTR_BULLET_STYLE_STANDARD 0x00000200 #define wxTEXT_ATTR_BULLET_STYLE_RIGHT_PARENTHESIS 0x00000400 #define wxTEXT_ATTR_BULLET_STYLE_OUTLINE 0x00000800 #define wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT 0x00000000 #define wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT 0x00001000 #define wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE 0x00002000
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 + sub_indent. So the distance between the left edge of the bullet and the left of the actual paragraph is sub_indent.
Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing in tenths of a millimetre.
Begins applying the named paragraph style.
Begins applying a style.
Begins a right indent, specified in tenths of a millimetre.
Begins applying a standard bullet. See begin_numbered_bullet for an explanation of how indentation is used to render the bulleted paragraph.
Starts suppressing undo history for commands.
Begins applying a symbol bullet, using a character from the current font. See begin_numbered_bullet for an explanation of how indentation is used to render the bulleted paragraph.
Begins using this colour.
Begins using underlining.
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.
Ends alignment.
Ends application of all styles in the current style stack.
Ends batching undo command history.
Ends using bold.
Ends application of a named character style.
Ends using a font.
Ends using a point size.
Ends using italic.
Ends left indent.
Ends line spacing.
Ends using a specified list style.
Ends application of a numbered bullet.
Ends paragraph spacing.
Ends application of a named paragraph style.
Ends the current style.
Ends right indent.
Ends applying a standard bullet.
Ends suppressing undo command history.
Ends applying a symbol bullet.
Ends applying a text colour.
End applying underlining.
Ends applying a URL.
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).
Returns the selection range in character positions. {-1, -1} means no selection.
Returns the style sheet associated with the control, if any. A style sheet allows named character and paragraph styles to be applied.
Test if this whole range has character attributes of the specified kind. If any of the attributes are different within the range, the test fails. You can use this to implement, for example, bold button updating. style must have flags indicating which attributes are of interest.
Test if this whole range has character attributes of the specified kind. If any of the attributes are different within the range, the test fails. You can use this to implement, for example, bold button updating. style must have flags indicating which attributes are of interest.
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. style must have flags indicating which attributes are of interest.
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. style must have flags indicating which attributes are of interest.
Returns true if all of the selection is aligned according to the specified flag.
Returns true if all of the selection is bold.
Returns true if all of the selection is italic.
Returns true if all of the selection is underlined.
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.
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, or by typing Shift-Return.
Moves down.
Moves to the end of the buffer.
Moves to the start of the buffer.
Moves left.
Move the caret to the given character position.
Moves right.
Moves to the end of the line.
Moves to the start of the line.
Moves to the end of the paragraph.
Moves to the start of the paragraph.
Moves up.
Moves one or more pages down.
Moves one or more pages up.
Cancels any selection.
Selects the word at pos.
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).
style is a wxTextAttrEx
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).
style is a wxRichAttrEx
Sets the default style to the style under the cursor.
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).
Sets the style sheet associated with the control. A style sheet allows named character and paragraph styles to be applied.
Returns true if undo history suppression is on.
Moves a number of words to the left.
Moves a number of words to the right.
Write a bitmap or image at the current insertion point. Supply an optional type (see wxBitmap) to use for internal and file storage of the raw data.
Writes an image block at the current insertion point.
Write a bitmap or image from a file at the current insertion point. Supply an optional type (see wxBitmap) to use for internal and file storage of the raw data.