+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 @<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 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 <b>Basic style</b>: 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 <b>Paragraph style</b>: 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 <b>Character style</b>: 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 <b>Default style</b>: 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 <em>basic style</em> to have a Times Roman font in 12
+ point, left-aligned, with two millimetres of spacing after each paragraph.
+@li You might set the <em>paragraph style</em> (for one particular paragraph)
+ to be centred.
+@li You might set the <em>character style</em> of one particular word to bold.
+@li You might set the <em>default style</em> 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.
+
+*/
projects / wxWidgets.git / blobdiff