 |
Version: 2.9.4 |
Major classes: wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent
Helper classes: wxTextAttr, wxRichTextRange
File handler classes: wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler
Style classes: wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition, wxRichTextListStyleDefinition, wxRichTextStyleSheet
Additional controls: wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl
Printing classes: wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData
Dialog classes: wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog, wxSymbolPickerDialog
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 or OpenDocument 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.
A good way to understand wxRichTextCtrl's capabilities is to compile and run the sample, samples/richtext, and browse the code.
The following code is an example taken from the sample, and adds text and styles to a rich text control programmatically.
wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl( splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(200, 200), wxVSCROLL | wxHSCROLL | wxBORDER_NONE | wxWANTS_CHARS); wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL); wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD); wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL); wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL); m_richTextCtrl->SetFont(font); wxRichTextCtrl& r = richTextCtrl; r.BeginSuppressUndo(); r.BeginParagraphSpacing(0, 20); r.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE); r.BeginBold(); r.BeginFontSize(14); r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images")); r.EndFontSize(); r.Newline(); r.BeginItalic(); r.WriteText(wxT("by Julian Smart")); r.EndItalic(); r.EndBold(); r.Newline(); r.WriteImage(wxBitmap(zebra_xpm)); r.EndAlignment(); r.Newline(); r.Newline(); r.WriteText(wxT("What can you do with this thing? ")); r.WriteImage(wxBitmap(smiley_xpm)); r.WriteText(wxT(" Well, you can change text ")); r.BeginTextColour(wxColour(255, 0, 0)); r.WriteText(wxT("colour, like this red bit.")); r.EndTextColour(); r.BeginTextColour(wxColour(0, 0, 255)); r.WriteText(wxT(" And this blue bit.")); r.EndTextColour(); r.WriteText(wxT(" Naturally you can make things ")); r.BeginBold(); r.WriteText(wxT("bold ")); r.EndBold(); r.BeginItalic(); r.WriteText(wxT("or italic ")); r.EndItalic(); r.BeginUnderline(); r.WriteText(wxT("or underlined.")); r.EndUnderline(); r.BeginFontSize(14); r.WriteText(wxT(" Different font sizes on the same line is allowed, too.")); r.EndFontSize(); r.WriteText(wxT(" Next we'll show an indented paragraph.")); r.BeginLeftIndent(60); r.Newline(); r.WriteText(wxT("Indented paragraph.")); r.EndLeftIndent(); r.Newline(); r.WriteText(wxT("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40).")); r.BeginLeftIndent(100, -40); r.Newline(); r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter.")); r.EndLeftIndent(); r.Newline(); r.WriteText(wxT("Numbered bullets are possible, again using subindents:")); r.BeginNumberedBullet(1, 100, 60); r.Newline(); r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later.")); r.EndNumberedBullet(); r.BeginNumberedBullet(2, 100, 60); r.Newline(); r.WriteText(wxT("This is my second item.")); r.EndNumberedBullet(); r.Newline(); r.WriteText(wxT("The following paragraph is right-indented:")); r.BeginRightIndent(200); r.Newline(); r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter. An attractive woman came into the cafe, which is nothing remarkable.")); r.EndRightIndent(); r.Newline(); wxArrayInt tabs; tabs.Add(400); tabs.Add(600); tabs.Add(800); tabs.Add(1000); wxTextAttr attr; attr.SetFlags(wxTEXT_ATTR_TABS); attr.SetTabs(tabs); r.SetDefaultStyle(attr); r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab")); r.Newline(); r.WriteText(wxT("Other notable features of wxRichTextCtrl include:")); r.BeginSymbolBullet(wxT('*'), 100, 60); r.Newline(); r.WriteText(wxT("Compatibility with wxTextCtrl API")); r.EndSymbolBullet(); r.WriteText(wxT("Note: this sample content was generated programmatically from within the MyFrame constructor in the demo. The images were loaded from inline XPMs. Enjoy wxRichTextCtrl!")); r.EndSuppressUndo();
You need to include <wx/richtext/richtextctrl.h> in your source, and link with the appropriate wxWidgets library with richtext suffix. Put the rich text library first in your link line to avoid unresolved symbols.
Then you can create a wxRichTextCtrl, with the wxWANT_CHARS style if you want tabs to be processed by the control rather than being used for navigation between controls.
Styling attributes are represented by wxTextAttr, or for more control over attributes such as margins and size, the derived class wxRichTextAttr.
When setting a style, the flags of the attribute object determine which attributes are applied. When querying a style, the passed flags are ignored except (optionally) to determine whether attributes should be retrieved from character content or from the paragraph object.
wxRichTextCtrl takes a layered approach to styles, so that different parts of the content may be responsible for contributing different attributes to the final style you see on the screen.
There are four main notions of style within a control:
What you see on the screen is the dynamically combined style, found by merging the first three of the above style types (the fourth is only a guide for future content insertion and therefore does not affect the currently displayed content).
To make all this more concrete, here are examples of where you might set these different styles:
Naturally you can do any of these things either using your own UI, or programmatically.
The basic wxTextCtrl doesn't make the same distinctions as wxRichTextCtrl regarding attribute storage. So we need finer control when setting and retrieving attributes. wxRichTextCtrl::SetStyleEx takes a flags parameter:
It's great to be able to change arbitrary attributes in a wxRichTextCtrl, but it can be unwieldy for the user or programmer to set attributes separately. Word processors have collections of styles that you can tailor or use as-is, and this means that you can set a heading with one click instead of marking text in bold, specifying a large font size, and applying a certain paragraph spacing and alignment for every such heading. Similarly, wxWidgets provides a class called wxRichTextStyleSheet which manages style definitions (wxRichTextParagraphStyleDefinition, wxRichTextListStyleDefinition and wxRichTextCharacterStyleDefinition). Once you have added definitions to a style sheet and associated it with a wxRichTextCtrl, you can apply a named definition to a range of text. The classes wxRichTextStyleComboCtrl and wxRichTextStyleListBox can be used to present the user with a list of styles in a sheet, and apply them to the selected text.
You can reapply a style sheet to the contents of the control, by calling wxRichTextCtrl::ApplyStyleSheet. This is useful if the style definitions have changed, and you want the content to reflect this. It relies on the fact that when you apply a named style, the style definition name is recorded in the content. So ApplyStyleSheet works by finding the paragraph attributes with style names and re-applying the definition's attributes to the paragraph. Currently, this works with paragraph and list style definitions only.
wxRichTextCtrl comes with standard dialogs to make it easier to implement text editing functionality.
wxRichTextFormattingDialog can be used for character or paragraph formatting, or a combination of both. It's a wxPropertySheetDialog with the following available tabs: Font, Indents & Spacing, Tabs, Bullets, Style, Borders, Margins, Background, Size, and List Style. You can select which pages will be shown by supplying flags to the dialog constructor. In a character formatting dialog, typically only the Font page will be shown. In a paragraph formatting dialog, you'll show the Indents & Spacing, Tabs and Bullets pages. The Style tab is useful when editing a style definition.
You can customize this dialog by providing your own wxRichTextFormattingDialogFactory object, which tells the formatting dialog how many pages are supported, what their identifiers are, and how to creates the pages.
wxRichTextStyleOrganiserDialog is a multi-purpose dialog that can be used for managing style definitions, browsing styles and applying them, or selecting list styles with a renumber option. See the sample for usage - it is used for the "Manage Styles" and "Bullets and Numbering" menu commands.
wxSymbolPickerDialog lets the user insert a symbol from a specified font. It has no wxRichTextCtrl dependencies besides being included in the rich text library.
Data representation is handled by wxRichTextBuffer, and a wxRichTextCtrl always has one such buffer.
The content is represented by a hierarchy of objects, all derived from wxRichTextObject. An object might be an image, a fragment of text, a paragraph, or a further composite object. Objects store a wxRichTextAttr containing style information; a paragraph object can contain both paragraph and character information, but content objects such as text can only store character information. The final style displayed in the control or in a printout is a combination of base style, paragraph style and content (character) style.
The top of the hierarchy is the buffer, a kind of wxRichTextParagraphLayoutBox, containing further wxRichTextParagraph objects, each of which can include text, images and potentially other types of object.
Each object maintains a range (start and end position) measured from the start of the main parent object.
When Layout is called on an object, it is given a size which the object must limit itself to, or one or more flexible directions (vertical or horizontal). So, for example, a centred paragraph is given the page width to play with (minus any margins), but can extend indefinitely in the vertical direction. The implementation of Layout caches the calculated size and position.
When the buffer is modified, a range is invalidated (marked as requiring layout), so that only the minimum amount of layout is performed.
A paragraph of pure text with the same style contains just one further object, a wxRichTextPlainText object. When styling is applied to part of this object, the object is decomposed into separate objects, one object for each different character style. So each object within a paragraph always has just one wxTextAttr object to denote its character style. Of course, this can lead to fragmentation after a lot of edit operations, potentially leading to several objects with the same style where just one would do. So a Defragment function is called when updating the control's display, to ensure that the minimum number of objects is used.
wxRichTextCtrl supports nested objects such as text boxes and tables. To achieve compatibility with the existing API, there is the concept of object focus. When the user clicks on a nested text box, the object focus is set to that container object so all keyboard input and API functions apply to that container. The application can change the focus using wxRichTextCtrl::SetObjectFocus. Call this function with a parameter to set the focus back to the top-level object.
An event will be sent to the control when the focus changes.
When the user clicks on the control, wxRichTextCtrl determines which container to set as the current object focus by calling the found container's overrided wxRichTextObject::AcceptsFocus function. For example, although a table is a container, it must not itself be the object focus because there is no text editing at the table level. Instead, a cell within the table must accept the focus.
Since with nested objects it is not possible to represent a section with merely a start position and an end position, the class wxRichTextSelection is provided which stores multiple ranges (for non-contiguous selections such as table cells) and a pointer to the container object in question. You can pass wxRichTextSelection to wxRichTextCtrl::SetSelection or get an instance of it from wxRichTextCtrl::GetSelection.
When selecting multiple objects, such as cell tables, the wxRichTextCtrl dragging handler code calls the function wxRichTextObject::HandlesChildSelections to determine whether the children can be individual selections. Currently only table cells can be multiply-selected in this way.
There are three ways you can make use of context menus: you can let wxRichTextCtrl handle everything and provide a basic menu; you can set your own context menu using wxRichTextCtrl::SetContextMenu but let wxRichTextCtrl handle showing it and adding property items; or you can override the default context menu behaviour by adding a context menu event handler to your class in the normal way.
If you right-click over a text box in cell in a table, you may want to edit the properties of one of these objects - but which properties will you be editing?
Well, the default behaviour allows up to three property-editing menu items simultaneously - for the object clicked on, the container of that object, and the container's parent (depending on whether any of these objects return true from their wxRichTextObject::CanEditProperties functions). If you supply a context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1 identifier, so that wxRichTextCtrl can find the position to add command items. The object should tell the control what label to use by returning a string from wxRichTextObject::GetPropertiesMenuLabel.
Since there may be several property-editing commands showing, it is recommended that you don't include the word Properties - just the name of the object, such as Text Box or Table.
This is an incomplete list of bugs.
This is a list of some of the features that have yet to be implemented. Help with them will be appreciated.
There are also things that could be done to take advantage of the underlying text capabilities of the platform; higher-level text formatting APIs are available on some platforms, such as Mac OS X, and some of translation from high level to low level wxDC API is unnecessary. However this would require additions to the wxWidgets API.
