X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/15b6757b26a0277472a4f6b071b52050abd922da..7df4c51f6021fbf1b204db918a1cc5c4ddff31cc:/docs/doxygen/overviews/richtextctrl.h diff --git a/docs/doxygen/overviews/richtextctrl.h b/docs/doxygen/overviews/richtextctrl.h index 4993f630c7..6f3dd7ea4b 100644 --- a/docs/doxygen/overviews/richtextctrl.h +++ b/docs/doxygen/overviews/richtextctrl.h @@ -1,398 +1,455 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: richtextctrl +// Name: richtextctrl.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! - - @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); - - 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(); - @endcode - - - @ref topic19_overview - @ref richtextctrldialogs_overview - @ref topic22_overview - @ref topic23_overview - - - @section topic19 Programming with wxRichTextCtrl - - - @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. - - */ - - +/** + +@page overview_richtextctrl wxRichTextCtrl Overview + +@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_roadmap + + +
+ + +@section overview_richtextctrl_classes Related Classes + +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 + + +@section overview_richtextctrl_intro Introduction + +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. + + +@section overview_richtextctrl_example Code Example + +The following code is an example 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); + +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(); +@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. + +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, 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 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 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 RTF input and output +@li Conversion from HTML +@li Open Office input and output +@li Floating images, with content wrapping around them +@li A ruler control +@li Standard editing toolbars +@li Tables +@li Bitmap bullets +@li Borders +@li Text frames +@li 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. + +*/ +