X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/36c9828f702fb504b07968703bcd82f04196070a..6d6de9f10f812d5e375d1283b12db490a6477b08:/docs/doxygen/overviews/richtextctrl.h diff --git a/docs/doxygen/overviews/richtextctrl.h b/docs/doxygen/overviews/richtextctrl.h index cf7c1b2ddc..9203214d50 100644 --- a/docs/doxygen/overviews/richtextctrl.h +++ b/docs/doxygen/overviews/richtextctrl.h @@ -1,398 +1,507 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: richtextctrl +// Name: richtextctrl.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @page richtextctrl_overview wxRichTextCtrl overview - - @b Major classes: #wxRichTextCtrl, #wxRichTextBuffer, #wxRichTextEvent - @b Helper classes: #wxTextAttr, #wxRichTextRange - @b File handler classes: #wxRichTextFileHandler, #wxRichTextHTMLHandler, - #wxRichTextXMLHandler - @b Style classes: #wxRichTextCharacterStyleDefinition, - #wxRichTextParagraphStyleDefinition, - #wxRichTextListStyleDefinition, - #wxRichTextStyleSheet - @b Additional controls: #wxRichTextStyleComboCtrl, - #wxRichTextStyleListBox, - #wxRichTextStyleListCtrl - @b Printing classes: #wxRichTextPrinting, - #wxRichTextPrintout, - #wxRichTextHeaderFooterData - @b 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 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, @c samples/richtext, and browse the code. The following screenshot shows the sample in action: - - @b Example - The following code is taken from the sample, and adds text and styles to a rich text control programmatically. - - - @code - 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); +@page overview_richtextctrl wxRichTextCtrl Overview - m_richTextCtrl-SetFont(font); +@li @ref overview_richtextctrl_classes +@li @ref overview_richtextctrl_intro +@li @ref overview_richtextctrl_example +@li @ref overview_richtextctrl_starting +@li @ref overview_richtextctrl_styles +@li @ref overview_richtextctrl_dialogs +@li @ref overview_richtextctrl_impl +@li @ref overview_richtextctrl_nested_object +@li @ref overview_richtextctrl_context_menus +@li @ref overview_richtextctrl_roadmap - 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(); +@section overview_richtextctrl_classes Related Classes - r.BeginItalic(); - r.WriteText(wxT("by Julian Smart")); - r.EndItalic(); +Major classes: +wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent - r.EndBold(); - - r.Newline(); - r.WriteImage(wxBitmap(zebra_xpm)); +Helper classes: +wxTextAttr, wxRichTextRange - r.EndAlignment(); +File handler classes: +wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler - r.Newline(); - r.Newline(); +Style classes: +wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition, +wxRichTextListStyleDefinition, wxRichTextStyleSheet - r.WriteText(wxT("What can you do with this thing? ")); - r.WriteImage(wxBitmap(smiley_xpm)); - r.WriteText(wxT(" Well, you can change text ")); +Additional controls: +wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl - r.BeginTextColour(wxColour(255, 0, 0)); - r.WriteText(wxT("colour, like this red bit.")); - r.EndTextColour(); +Printing classes: +wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData - r.BeginTextColour(wxColour(0, 0, 255)); - r.WriteText(wxT(" And this blue bit.")); - r.EndTextColour(); +Dialog classes: +wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog, +wxSymbolPickerDialog - 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(); +@section overview_richtextctrl_intro Introduction - r.WriteText(wxT(" Next we'll show an indented paragraph.")); +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. - r.BeginLeftIndent(60); - r.Newline(); +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. - r.WriteText(wxT("Indented paragraph.")); - r.EndLeftIndent(); +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. - r.Newline(); +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. - r.WriteText(wxT("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40).")); +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. - r.BeginLeftIndent(100, -40); - r.Newline(); +A good way to understand wxRichTextCtrl's capabilities is to compile and run +the sample, @c samples/richtext, and browse the code. - r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter.")); - r.EndLeftIndent(); - r.Newline(); +@section overview_richtextctrl_example Code Example - r.WriteText(wxT("Numbered bullets are possible, again using subindents:")); +The following code is an example taken from the sample, and adds text and +styles to a rich text control programmatically. - r.BeginNumberedBullet(1, 100, 60); - r.Newline(); +@code +wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl( + splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, + wxSize(200, 200), wxVSCROLL | wxHSCROLL | wxBORDER_NONE | wxWANTS_CHARS); - r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later.")); - r.EndNumberedBullet(); +wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL); +wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD); +wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL); - r.BeginNumberedBullet(2, 100, 60); - r.Newline(); +wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL); - r.WriteText(wxT("This is my second item.")); - r.EndNumberedBullet(); +m_richTextCtrl->SetFont(font); - r.Newline(); +wxRichTextCtrl& r = richTextCtrl; - r.WriteText(wxT("The following paragraph is right-indented:")); +r.BeginSuppressUndo(); - r.BeginRightIndent(200); - r.Newline(); +r.BeginParagraphSpacing(0, 20); - 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.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE); +r.BeginBold(); - r.Newline(); +r.BeginFontSize(14); +r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images")); +r.EndFontSize(); +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.BeginItalic(); +r.WriteText(wxT("by Julian Smart")); +r.EndItalic(); - r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab")); +r.EndBold(); - r.Newline(); - r.WriteText(wxT("Other notable features of wxRichTextCtrl include:")); +r.Newline(); +r.WriteImage(wxBitmap(zebra_xpm)); - r.BeginSymbolBullet(wxT('*'), 100, 60); - r.Newline(); - r.WriteText(wxT("Compatibility with wxTextCtrl API")); - r.EndSymbolBullet(); +r.EndAlignment(); - 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.Newline(); +r.Newline(); - r.EndSuppressUndo(); - @endcode +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(); - @ref topic19_overview - @ref richtextctrldialogs_overview - @ref topic22_overview - @ref topic23_overview +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(); - @section topic19 Programming with wxRichTextCtrl +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.")); - @section topic20 Starting to use wxRichTextCtrl - - You need to include @c wx/richtext/richtextctrl.h in your source, and link - with the appropriate wxWidgets library with @c 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. - - @section topic21 wxRichTextCtrl and styles - - Styling attributes are represented by #wxTextAttr. - 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: - - - @b Basic style: the fundamental style of a control, onto which any other - styles are layered. It provides default attributes, and changing the basic style - may immediately change the look of the content depending on what other styles - the content uses. Calling wxRichTextCtrl::SetFont changes the font for the basic style. - The basic style is set with wxRichTextCtrl::SetBasicStyle. - @b Paragraph style: each paragraph has attributes that are set independently - from other paragraphs and independently from the content within the paragraph. - Normally, these attributes are paragraph-related, such as alignment and indentation, - but it is possible to set character attributes too. - The paragraph style can be set independently of its content by passing wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY - to wxRichTextCtrl::SetStyleEx. - @b Character style: characters within each paragraph can have attributes. - A single character, or a run of characters, can have a particular set of attributes. - The character style can be with wxRichTextCtrl::SetStyle or - wxRichTextCtrl::SetStyleEx. - @b Default style: this is the 'current' style that determines the - style of content that is subsequently typed, pasted or programmatically inserted. - The default style is set with wxRichTextCtrl::SetDefaultStyle. - - - What you see on the screen is the dynamically @e 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: - - - You might set the @b basic style to have a Times Roman font in 12 point, - left-aligned, with two millimetres of spacing after each paragraph. - You might set the @b paragraph style (for one particular paragraph) to - be centred. - You might set the @b character style of one particular word to bold. - You might set the @b default style to be underlined, for subsequent - inserted text. - - - 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 @e flags parameter: - - - wxRICHTEXT_SETSTYLE_OPTIMIZE specifies that the style should be changed only if - the combined attributes are different from the attributes for the current object. This is important when - applying styling that has been edited by the user, because he has just edited the @e combined (visible) - style, and wxRichTextCtrl wants to leave unchanged attributes associated with their original objects - instead of applying them to both paragraph and content objects. - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY specifies that only paragraph objects within the given range - should take on the attributes. - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects (text or images) within the given range - should take on the attributes. - wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be undoable. - - - 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. - - @section wxrichtextctrldialogs wxRichTextCtrl dialogs - - 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, 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. - - @section topic22 How wxRichTextCtrl is implemented - - 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 whole buffer. Objects store a wxTextAttr 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. - - @section topic23 wxRichTextCtrl roadmap - - @b Bugs - This is an incomplete list of bugs. - - - Moving the caret up at the beginning of a line sometimes incorrectly positions the - caret. - As the selection is expanded, the text jumps slightly due to kerning differences between - drawing a single text string versus drawing several fragments separately. This could - be improved by using wxDC::GetPartialTextExtents to calculate exactly where the separate fragments - should be drawn. Note that this problem also applies to separation of text fragments due to difference in their attributes. - - - @b Features - This is a list of some of the features that have yet to be implemented. Help with them will be appreciated. - - - RTF input and output - Conversion from HTML - Open Office input and output - Floating images, with content wrapping around them - A ruler control - Standard editing toolbars - Tables - Bitmap bullets - Borders - Text frames - Justified text, in print/preview at least - - - 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. - - */ +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(); +@endcode + + +@section overview_richtextctrl_starting Starting to Use wxRichTextCtrl + +You need to include @c @ in your source, and link +with the appropriate wxWidgets library with @c 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. + + +@section overview_richtextctrl_styles Text Styles + +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: + +@li Basic style: The fundamental style of a control, onto which any + other styles are layered. It provides default attributes, and changing the + basic style may immediately change the look of the content depending on + what other styles the content uses. Calling wxRichTextCtrl::SetFont changes + the font for the basic style. The basic style is set with + wxRichTextCtrl::SetBasicStyle. +@li Paragraph style: Each paragraph has attributes that are set + independently from other paragraphs and independently from the content + within the paragraph. Normally, these attributes are paragraph-related, + such as alignment and indentation, but it is possible to set character + attributes too. The paragraph style can be set independently of its content + by passing wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY to + wxRichTextCtrl::SetStyleEx. +@li Character style: Characters within each paragraph can have + attributes. A single character, or a run of characters, can have a + particular set of attributes. The character style can be with + wxRichTextCtrl::SetStyle or wxRichTextCtrl::SetStyleEx. +@li Default style: This is the 'current' style that determines the style + of content that is subsequently typed, pasted or programmatically inserted. + The default style is set with wxRichTextCtrl::SetDefaultStyle. + +What you see on the screen is the dynamically @e 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: + +@li You might set the basic style to have a Times Roman font in 12 + point, left-aligned, with two millimetres of spacing after each paragraph. +@li You might set the paragraph style (for one particular paragraph) + to be centred. +@li You might set the character style of one particular word to bold. +@li You might set the default style to be underlined, for subsequent + inserted text. + +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 @e flags parameter: + +@li wxRICHTEXT_SETSTYLE_OPTIMIZE specifies that the style should be changed + only if the combined attributes are different from the attributes for the + current object. This is important when applying styling that has been + edited by the user, because he has just edited the @e combined (visible) + style, and wxRichTextCtrl wants to leave unchanged attributes associated + with their original objects instead of applying them to both paragraph and + content objects. +@li wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY specifies that only paragraph objects + within the given range should take on the attributes. +@li wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects + (text or images) within the given range should take on the attributes. +@li wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be + undoable. + +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. + + +@section overview_richtextctrl_dialogs Included Dialogs + +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. + + +@section overview_richtextctrl_impl How wxRichTextCtrl is Implemented + +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. + +@section overview_richtextctrl_nested_object Nested Objects + +wxRichTextCtrl supports nested objects such as text boxes and tables. To achieve +compatibility with the existing API, there is the concept of @e object @e 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 @null 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. + +@section overview_richtextctrl_context_menus Context menus and property dialogs + +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. + +@section overview_richtextctrl_roadmap Development Roadmap + +@subsection overview_richtextctrl_roadmap_bugs Bugs + +This is an incomplete list of bugs. + +@li Moving the caret up at the beginning of a line sometimes incorrectly + positions the caret. +@li As the selection is expanded, the text jumps slightly due to kerning + differences between drawing a single text string versus drawing several + fragments separately. This could be improved by using + wxDC::GetPartialTextExtents to calculate exactly where the separate + fragments should be drawn. Note that this problem also applies to + separation of text fragments due to difference in their attributes. + +@subsection overview_richtextctrl_roadmap_features Features + +This is a list of some of the features that have yet to be implemented. Help +with them will be appreciated. + +@li support for composite objects in some functions where it's not yet implemented, for example ApplyStyleSheet +@li Table API enhancements and dialogs; improved table layout especially row spans and fitting +@li Conversion from HTML, and a rewrite of the HTML output handler that includes CSS, +tables, text boxes, and floating images, in addition to a simplified-HTML mode for wxHTML compatibility +@li Open Office input and output +@li RTF input and output +@li A ruler control +@li Standard editing toolbars +@li Bitmap bullets +@li Justified text, in print/preview at least +@li scaling: either everything scaled, or rendering using a custom reference point size and an optional dimension scale + +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. + +*/