wxRichTextCtrl

wxRichTextCtrl

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.

Functions/Procedures
Supertopics
Subtopics

wxRichTextCtrl

[func]
add_paragraph
( atom rich, sequence text )

Category: wxRichTextCtrl

Adds a new paragraph of text to the end of the buffer.


wxRichTextCtrl

[func]
add_rich_image
( atom rich, atom image )

Category: wxRichTextCtrl

Adds an image to the control's buffer.


wxRichTextCtrl

[proc]
apply_alignment_to_selection
( atom rich, atom alignment )

Category: wxRichTextCtrl

Applies the given alignment to the selection (undoable).

For alignment values, see wxTextAttrEx.


wxRichTextCtrl

[proc]
apply_bold_to_selection
( atom rich )

Category: wxRichTextCtrl

Apples bold to the selection (undoable).


wxRichTextCtrl

[proc]
apply_italic_to_selection
( atom rich )

Category: wxRichTextCtrl

Applies italic to the selection (undoable).


wxRichTextCtrl

[proc]
apply_rich_style
( atom rich, atom style_def )

Category: wxRichTextCtrl

Applies the given style to the selection.


wxRichTextCtrl

[proc]
apply_rich_style_sheet
( atom rich, atom style_sheet )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[proc]
apply_underline_to_selection
( atom rich )

Category: wxRichTextCtrl

Applies underline to the selection (undoable).


wxRichTextCtrl

[func]
batching_undo
( atom rich )

Category: wxRichTextCtrl

Returns true if undo commands are being batched.


wxRichTextCtrl

[proc]
begin_alignment
( atom rich, atom align )

Category: wxRichTextCtrl

Begins using alignment

For alignment values, see wxTextAttrEx.


wxRichTextCtrl

[proc]
begin_batch_undo
( atom rich, sequence cmd_name )

Category: wxRichTextCtrl

Starts batching undo history for commands.


wxRichTextCtrl

[proc]
begin_bold
( atom rich )

Category: wxRichTextCtrl

Begins using bold.


wxRichTextCtrl

[proc]
begin_char_style
( atom rich, sequence named_style )

Category: wxRichTextCtrl

Begins using the named character style.


wxRichTextCtrl

[proc]
begin_font
( atom rich, atom font )

Category: wxRichTextCtrl

Begins using this font.


wxRichTextCtrl

[proc]
begin_font_size
( atom rich, atom size )

Category: wxRichTextCtrl

Begins using the given point size.


wxRichTextCtrl

[proc]
begin_italic
( atom rich )

Category: wxRichTextCtrl

Begins using italic.


wxRichTextCtrl

[proc]
begin_left_indent
( atom rich, atom indent, atom sub_indent )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[proc]
begin_line_spacing
( atom rich, atom spacing )

Category: wxRichTextCtrl

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:


wxRichTextCtrl

[proc]
begin_list_style
( atom rich, sequence named_style, atom level, atom number )

Category: wxRichTextCtrl

Begins using a specified list style. Optionally, you can also pass a level and a number.


wxRichTextCtrl

[proc]
begin_numbered_bullet
( atom rich, atom number, atom indent, atom sub_indent, atom style )

Category: wxRichTextCtrl

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.

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.


wxRichTextCtrl

[proc]
begin_paragraph_spacing
( atom rich, atom before, atom after )

Category: wxRichTextCtrl

Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing in tenths of a millimetre.


wxRichTextCtrl

[proc]
begin_paragraph_style
( atom rich, sequence named_style )

Category: wxRichTextCtrl

Begins applying the named paragraph style.


wxRichTextCtrl

[proc]
begin_rich_style
( atom rich, atom style )

Category: wxRichTextCtrl

Begins applying a style.


wxRichTextCtrl

[proc]
begin_right_indent
( atom rich, atom indent )

Category: wxRichTextCtrl

Begins a right indent, specified in tenths of a millimetre.


wxRichTextCtrl

[proc]
begin_standard_bullet
( atom rich, sequence bullet_name, atom indent, atom sub_indent, atom style )

Category: wxRichTextCtrl

Begins applying a standard bullet. See begin_numbered_bullet for an explanation of how indentation is used to render the bulleted paragraph.


wxRichTextCtrl

[proc]
begin_suppress_undo
( atom rich )

Category: wxRichTextCtrl

Starts suppressing undo history for commands.


wxRichTextCtrl

[proc]
begin_symbol_bullet
( atom rich, sequence symbol, atom indent, atom sub_indent, atom style )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[proc]
begin_text_color
( atom rich, atom color )

Category: wxRichTextCtrl

Begins using this colour.


wxRichTextCtrl

[proc]
begin_underline
( atom rich )

Category: wxRichTextCtrl

Begins using underlining.


wxRichTextCtrl

[proc]
begin_url
( atom rich, sequence url, sequence style )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[proc]
end_alignment
( atom rich )

Category: wxRichTextCtrl

Ends alignment.


wxRichTextCtrl

[proc]
end_all_rich_styles
( atom rich )

Category: wxRichTextCtrl

Ends application of all styles in the current style stack.


wxRichTextCtrl

[proc]
end_batch_undo
( atom rich )

Category: wxRichTextCtrl

Ends batching undo command history.


wxRichTextCtrl

[proc]
end_bold
( atom rich )

Category: wxRichTextCtrl

Ends using bold.


wxRichTextCtrl

[proc]
end_char_style
( atom rich )

Category: wxRichTextCtrl

Ends application of a named character style.


wxRichTextCtrl

[proc]
end_font
( atom rich )

Category: wxRichTextCtrl

Ends using a font.


wxRichTextCtrl

[proc]
end_font_size
( atom rich )

Category: wxRichTextCtrl

Ends using a point size.


wxRichTextCtrl

[proc]
end_italic
( atom rich )

Category: wxRichTextCtrl

Ends using italic.


wxRichTextCtrl

[proc]
end_left_indent
( atom rich )

Category: wxRichTextCtrl

Ends left indent.


wxRichTextCtrl

[proc]
end_line_spacing
( atom rich )

Category: wxRichTextCtrl

Ends line spacing.


wxRichTextCtrl

[proc]
end_list_style
( atom rich )

Category: wxRichTextCtrl

Ends using a specified list style.


wxRichTextCtrl

[proc]
end_numbered_bullet
( atom rich )

Category: wxRichTextCtrl

Ends application of a numbered bullet.


wxRichTextCtrl

[proc]
end_paragraph_spacing
( atom rich )

Category: wxRichTextCtrl

Ends paragraph spacing.


wxRichTextCtrl

[proc]
end_paragraph_style
( atom rich )

Category: wxRichTextCtrl

Ends application of a named paragraph style.


wxRichTextCtrl

[proc]
end_rich_style
( atom rich )

Category: wxRichTextCtrl

Ends the current style.


wxRichTextCtrl

[proc]
end_right_indent
( atom rich )

Category: wxRichTextCtrl

Ends right indent.


wxRichTextCtrl

[proc]
end_standard_bullet
( atom rich )

Category: wxRichTextCtrl

Ends applying a standard bullet.


wxRichTextCtrl

[proc]
end_suppress_undo
( atom rich )

Category: wxRichTextCtrl

Ends suppressing undo command history.


wxRichTextCtrl

[proc]
end_symbol_bullet
( atom rich )

Category: wxRichTextCtrl

Ends applying a symbol bullet.


wxRichTextCtrl

[proc]
end_text_color
( atom rich )

Category: wxRichTextCtrl

Ends applying a text colour.


wxRichTextCtrl

[proc]
end_underline
( atom rich )

Category: wxRichTextCtrl

End applying underlining.


wxRichTextCtrl

[proc]
end_url
( atom rich )

Category: wxRichTextCtrl

Ends applying a URL.


wxRichTextCtrl

[func]
get_basic_rich_style
( atom rich )

Category: wxRichTextCtrl

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).


wxRichTextCtrl

[func]
get_rich_internal_selection_range
( atom rich )

Category: wxRichTextCtrl


wxRichTextCtrl

[func]
get_rich_selection_range
( atom rich )

Category: wxRichTextCtrl

Returns the selection range in character positions. {-1, -1} means no selection.


wxRichTextCtrl

[func]
get_rich_style_sheet
( atom rich )

Category: wxRichTextCtrl

Returns the style sheet associated with the control, if any. A style sheet allows named character and paragraph styles to be applied.


wxRichTextCtrl

[func]
has_char_rich_attr
( atom rich, atom first, atom last, atom rich_attr )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[func]
has_char_text_attr
( atom rich, atom first, atom last, atom text_attr_ex )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[func]
has_para_char_attr
( atom rich, atom first, atom last, atom rich_attr )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[func]
has_para_text_attr
( atom rich, atom first, atom last, atom text_attr_ex )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[func]
is_selection_aligned
( atom rich, atom alignment )

Category: wxRichTextCtrl

Returns true if all of the selection is aligned according to the specified flag.


wxRichTextCtrl

[func]
is_selection_bold
( atom rich )

Category: wxRichTextCtrl

Returns true if all of the selection is bold.


wxRichTextCtrl

[func]
is_selection_italics
( atom rich )

Category: wxRichTextCtrl

Returns true if all of the selection is italic.


wxRichTextCtrl

[func]
is_selection_underlined
( atom rich )

Category: wxRichTextCtrl

Returns true if all of the selection is underlined.


wxRichTextCtrl

[proc]
layout_rich_content
( atom rich, atom only_visible )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[proc]
line_break
( atom rich )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[proc]
move_down
( atom rich, atom n_pos, atom flags )

Category: wxRichTextCtrl

Moves down.


wxRichTextCtrl

[proc]
move_end
( atom rich, atom flags )

Category: wxRichTextCtrl

Moves to the end of the buffer.


wxRichTextCtrl

[proc]
move_home
( atom rich, atom flags )

Category: wxRichTextCtrl

Moves to the start of the buffer.


wxRichTextCtrl

[proc]
move_left
( atom rich, atom n_pos, atom flags )

Category: wxRichTextCtrl

Moves left.


wxRichTextCtrl

[proc]
move_rich_caret
( atom rich, atom pos, atom at_start )

Category: wxRichTextCtrl

Move the caret to the given character position.


wxRichTextCtrl

[proc]
move_right
( atom rich, atom n_pos, atom flags )

Category: wxRichTextCtrl

Moves right.


wxRichTextCtrl

[proc]
move_to_line_end
( atom rich, atom flags )

Category: wxRichTextCtrl

Moves to the end of the line.


wxRichTextCtrl

[proc]
move_to_line_start
( atom rich, atom flags )

Category: wxRichTextCtrl

Moves to the start of the line.


wxRichTextCtrl

[proc]
move_to_paragraph_end
( atom rich, atom flags )

Category: wxRichTextCtrl

Moves to the end of the paragraph.


wxRichTextCtrl

[proc]
move_to_paragraph_start
( atom rich, atom flags )

Category: wxRichTextCtrl

Moves to the start of the paragraph.


wxRichTextCtrl

[proc]
move_up
( atom rich, atom n_pos, atom flags )

Category: wxRichTextCtrl

Moves up.


wxRichTextCtrl

[proc]
page_down
( atom rich, atom pages, atom flags )

Category: wxRichTextCtrl

Moves one or more pages down.


wxRichTextCtrl

[proc]
page_up
( atom rich, atom pages, atom flags )

Category: wxRichTextCtrl

Moves one or more pages up.


wxRichTextCtrl

[func]
pop_rich_style_sheet
( atom rich )

Category: wxRichTextCtrl


wxRichTextCtrl

[proc]
push_rich_style_sheet
( atom rich, atom style_sheet )

Category: wxRichTextCtrl


wxRichTextCtrl

[proc]
select_none
( atom rich )

Category: wxRichTextCtrl

Cancels any selection.


wxRichTextCtrl

[proc]
select_word
( atom rich, atom pos )

Category: wxRichTextCtrl

Selects the word at pos.


wxRichTextCtrl

[proc]
set_basic_rich_style
( atom rich, atom style )

Category: wxRichTextCtrl

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


wxRichTextCtrl

[proc]
set_basic_rich_text_style
( atom rich, atom style )

Category: wxRichTextCtrl

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


wxRichTextCtrl

[proc]
set_default_style_to_cursor_style
( atom rich )

Category: wxRichTextCtrl

Sets the default style to the style under the cursor.


wxRichTextCtrl

[proc]
set_rich_internal_selection_range
( atom rich, atom start, atom finish )

Category: wxRichTextCtrl


wxRichTextCtrl

[proc]
set_rich_selection_range
( atom rich, atom start, atom finish )

Category: wxRichTextCtrl

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).


wxRichTextCtrl

[proc]
set_rich_style_sheet
( atom rich, atom style_sheet )

Category: wxRichTextCtrl

Sets the style sheet associated with the control. A style sheet allows named character and paragraph styles to be applied.


wxRichTextCtrl

[func]
suppressing_undo
( atom rich )

Category: wxRichTextCtrl

Returns true if undo history suppression is on.


wxRichTextCtrl

[proc]
word_left
( atom rich, atom words, atom flags )

Category: wxRichTextCtrl

Moves a number of words to the left.


wxRichTextCtrl

[proc]
word_right
( atom rich, atom words, atom flags )

Category: wxRichTextCtrl

Moves a number of words to the right.


wxRichTextCtrl

[func]
write_image
( atom rich, atom image, atom bitmap_type )

Category: wxRichTextCtrl

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.


wxRichTextCtrl

[func]
write_image_block
( atom rich, atom image_block )

Category: wxRichTextCtrl

Writes an image block at the current insertion point.


wxRichTextCtrl

[func]
write_image_from_file
( atom rich, sequence filename, atom bitmap_type )

Category: wxRichTextCtrl

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.