@section overview_resyntax_matching Matching
-In the event that an RE could match more than
-one substring of a given string, the RE matches the one starting earliest
-in the string. If the RE could match more than one substring starting at
-that point, its choice is determined by its @e preference: either the longest
-substring, or the shortest.
-Most atoms, and all constraints, have no preference.
-A parenthesized RE has the same preference (possibly none) as the RE. A
-quantified atom with quantifier @b {m} or @b {m}? has the same preference (possibly
-none) as the atom itself. A quantified atom with other normal quantifiers
-(including @b {m,n} with @e m equal to @e n) prefers longest match. A quantified
-atom with other non-greedy quantifiers (including @b {m,n}? with @e m equal to
-@e n) prefers shortest match. A branch has the same preference as the first
-quantified atom in it which has a preference. An RE consisting of two or
-more branches connected by the @b | operator prefers longest match.
-Subject to the constraints imposed by the rules for matching the whole RE, subexpressions
-also match the longest or shortest possible substrings, based on their
-preferences, with subexpressions starting earlier in the RE taking priority
-over ones starting later. Note that outer subexpressions thus take priority
-over their component subexpressions.
-Note that the quantifiers @b {1,1} and
-@b {1,1}? can be used to force longest and shortest preference, respectively,
-on a subexpression or a whole RE.
-Match lengths are measured in characters,
-not collating elements. An empty string is considered longer than no match
-at all. For example, @b bb* matches the three middle characters
-of '@b abbbc', @b (week|wee)(night|knights)
-matches all ten characters of '@b weeknights', when @b (.*).* is matched against
-@b abc the parenthesized subexpression matches all three characters, and when
-@b (a*)* is matched against @b bc both the whole RE and the parenthesized subexpression
-match an empty string.
-If case-independent matching is specified, the effect
-is much as if all case distinctions had vanished from the alphabet. When
-an alphabetic that exists in multiple cases appears as an ordinary character
-outside a bracket expression, it is effectively transformed into a bracket
-expression containing both cases, so that @b x becomes '@b [xX]'. When it appears
-inside a bracket expression, all case counterparts of it are added to the
-bracket expression, so that @b [x] becomes @b [xX] and @b [^x] becomes '@b [^xX]'.
-If newline-sensitive
-matching is specified, @b . and bracket expressions using @b ^ will never match
-the newline character (so that matches will never cross newlines unless
-the RE explicitly arranges it) and @b ^ and @b $ will match the empty string after
-and before a newline respectively, in addition to matching at beginning
-and end of string respectively. ARE @b \A and @b \Z continue to match beginning
-or end of string @e only.
-If partial newline-sensitive matching is specified,
-this affects @b . and bracket expressions as with newline-sensitive matching,
-but not @b ^ and '@b $'.
-If inverse partial newline-sensitive matching is specified,
-this affects @b ^ and @b $ as with newline-sensitive matching, but not @b . and bracket
+In the event that an RE could match more than one substring of a given string,
+the RE matches the one starting earliest in the string. If the RE could match
+more than one substring starting at that point, the choice is determined by
+it's @e preference: either the longest substring, or the shortest.
+
+Most atoms, and all constraints, have no preference. A parenthesized RE has the
+same preference (possibly none) as the RE. A quantified atom with quantifier
+<tt>{m}</tt> or <tt>{m}?</tt> has the same preference (possibly none) as the
+atom itself. A quantified atom with other normal quantifiers (including
+<tt>{m,n}</tt> with @e m equal to @e n) prefers longest match. A quantified
+atom with other non-greedy quantifiers (including <tt>{m,n}?</tt> with @e m
+equal to @e n) prefers shortest match. A branch has the same preference as the
+first quantified atom in it which has a preference. An RE consisting of two or
+more branches connected by the @c | operator prefers longest match.
+
+Subject to the constraints imposed by the rules for matching the whole RE,
+subexpressions also match the longest or shortest possible substrings, based on
+their preferences, with subexpressions starting earlier in the RE taking
+priority over ones starting later. Note that outer subexpressions thus take
+priority over their component subexpressions.
+
+Note that the quantifiers <tt>{1,1}</tt> and <tt>{1,1}?</tt> can be used to
+force longest and shortest preference, respectively, on a subexpression or a
+whole RE.
+
+Match lengths are measured in characters, not collating elements. An empty
+string is considered longer than no match at all. For example, <tt>bb*</tt>
+matches the three middle characters of "abbbc",
+<tt>(week|wee)(night|knights)</tt> matches all ten characters of "weeknights",
+when <tt>(.*).*</tt> is matched against "abc" the parenthesized subexpression
+matches all three characters, and when <tt>(a*)*</tt> is matched against "bc"
+both the whole RE and the parenthesized subexpression match an empty string.
+
+If case-independent matching is specified, the effect is much as if all case
+distinctions had vanished from the alphabet. When an alphabetic that exists in
+multiple cases appears as an ordinary character outside a bracket expression,
+it is effectively transformed into a bracket expression containing both cases,
+so that @c x becomes @c [xX]. When it appears inside a bracket expression, all
+case counterparts of it are added to the bracket expression, so that @c [x]
+becomes @c [xX] and @c [^x] becomes @c [^xX].
+
+If newline-sensitive matching is specified, "." and bracket expressions using
+"^" will never match the newline character (so that matches will never cross
+newlines unless the RE explicitly arranges it) and "^" and "$" will match the
+empty string after and before a newline respectively, in addition to matching
+at beginning and end of string respectively. ARE <tt>@\A</tt> and <tt>@\Z</tt>
+continue to match beginning or end of string @e only.
+
+If partial newline-sensitive matching is specified, this affects "." and
+bracket expressions as with newline-sensitive matching, but not "^" and "$".
+
+If inverse partial newline-sensitive matching is specified, this affects "^"
+and "$" as with newline-sensitive matching, but not "." and bracket
expressions. This isn't very useful but is provided for symmetry.
@section overview_resyntax_limits Limits and Compatibility
-No particular limit is imposed on the length of REs. Programs
-intended to be highly portable should not employ REs longer than 256 bytes,
-as a POSIX-compliant implementation can refuse to accept such REs.
-The only
-feature of AREs that is actually incompatible with POSIX EREs is that @b \
-does not lose its special significance inside bracket expressions. All other
-ARE features use syntax which is illegal or has undefined or unspecified
-effects in POSIX EREs; the @b *** syntax of directors likewise is outside
-the POSIX syntax for both BREs and EREs.
-Many of the ARE extensions are
-borrowed from Perl, but some have been changed to clean them up, and a
-few Perl extensions are not present. Incompatibilities of note include '@b \b',
-'@b \B', the lack of special treatment for a trailing newline, the addition of
-complemented bracket expressions to the things affected by newline-sensitive
-matching, the restrictions on parentheses and back references in lookahead
-constraints, and the longest/shortest-match (rather than first-match) matching
-semantics.
-The matching rules for REs containing both normal and non-greedy
-quantifiers have changed since early beta-test versions of this package.
-(The new rules are much simpler and cleaner, but don't work as hard at guessing
-the user's real intentions.)
+No particular limit is imposed on the length of REs. Programs intended to be
+highly portable should not employ REs longer than 256 bytes, as a
+POSIX-compliant implementation can refuse to accept such REs.
+
+The only feature of AREs that is actually incompatible with POSIX EREs is that
+<tt>@\</tt> does not lose its special significance inside bracket expressions.
+All other ARE features use syntax which is illegal or has undefined or
+unspecified effects in POSIX EREs; the <tt>***</tt> syntax of directors
+likewise is outside the POSIX syntax for both BREs and EREs.
+
+Many of the ARE extensions are borrowed from Perl, but some have been changed
+to clean them up, and a few Perl extensions are not present. Incompatibilities
+of note include <tt>@\b</tt>, <tt>@\B</tt>, the lack of special treatment for a
+trailing newline, the addition of complemented bracket expressions to the
+things affected by newline-sensitive matching, the restrictions on parentheses
+and back references in lookahead constraints, and the longest/shortest-match
+(rather than first-match) matching semantics.
+
+The matching rules for REs containing both normal and non-greedy quantifiers
+have changed since early beta-test versions of this package. The new rules are
+much simpler and cleaner, but don't work as hard at guessing the user's real
+intentions.
+
Henry Spencer's original 1986 @e regexp package, still in widespread use,
-implemented an early version of today's EREs. There are four incompatibilities between @e regexp's
-near-EREs ('RREs' for short) and AREs. In roughly increasing order of significance:
-
-In AREs, @b \ followed by an alphanumeric character is either an escape or
-an error, while in RREs, it was just another way of writing the alphanumeric.
-This should not be a problem because there was no reason to write such
-a sequence in RREs.
-@b { followed by a digit in an ARE is the beginning of
-a bound, while in RREs, @b { was always an ordinary character. Such sequences
-should be rare, and will often result in an error because following characters
-will not look like a valid bound.
-In AREs, @b \ remains a special character
-within '@b []', so a literal @b \ within @b [] must be
-written '@b \\'. @b \\ also gives a literal
-@b \ within @b [] in RREs, but only truly paranoid programmers routinely doubled
-the backslash.
-AREs report the longest/shortest match for the RE, rather
-than the first found in a specified search order. This may affect some RREs
-which were written in the expectation that the first match would be reported.
-(The careful crafting of RREs to optimize the search order for fast matching
-is obsolete (AREs examine all possible matches in parallel, and their performance
-is largely insensitive to their complexity) but cases where the search
-order was exploited to deliberately find a match which was @e not the longest/shortest
-will need rewriting.)
+implemented an early version of today's EREs. There are four incompatibilities
+between @e regexp's near-EREs (RREs for short) and AREs. In roughly increasing
+order of significance:
+
+@li In AREs, <tt>@\</tt> followed by an alphanumeric character is either an
+ escape or an error, while in RREs, it was just another way of writing the
+ alphanumeric. This should not be a problem because there was no reason to
+ write such a sequence in RREs.
+@li @c { followed by a digit in an ARE is the beginning of a bound, while in
+ RREs, @c { was always an ordinary character. Such sequences should be rare,
+ and will often result in an error because following characters will not
+ look like a valid bound.
+@li In AREs, @c @\ remains a special character within @c [], so a literal @c @\
+ within @c [] must be written as <tt>@\@\</tt>. <tt>@\@\</tt> also gives a
+ literal @c @\ within @c [] in RREs, but only truly paranoid programmers
+ routinely doubled the backslash.
+@li AREs report the longest/shortest match for the RE, rather than the first
+ found in a specified search order. This may affect some RREs which were
+ written in the expectation that the first match would be reported. The
+ careful crafting of RREs to optimize the search order for fast matching is
+ obsolete (AREs examine all possible matches in parallel, and their
+ performance is largely insensitive to their complexity) but cases where the
+ search order was exploited to deliberately find a match which was @e not
+ the longest/shortest will need rewriting.
@section overview_resyntax_bre Basic Regular Expressions
-BREs differ from EREs in
-several respects. '@b |', '@b +', and @b ? are ordinary characters and there is no equivalent
-for their functionality. The delimiters for bounds
-are @b \{ and '@b \}', with @b { and
-@b } by themselves ordinary characters. The parentheses for nested subexpressions
-are @b \( and '@b \)', with @b ( and @b ) by themselves
-ordinary characters. @b ^ is an ordinary
+BREs differ from EREs in several respects. @c |, @c +, and @c ? are ordinary
+characters and there is no equivalent for their functionality. The delimiters
+for bounds are @c @\{ and @c @\}, with @c { and @c } by themselves ordinary
+characters. The parentheses for nested subexpressions are @c @\( and @c @\),
+with @c ( and @c ) by themselves ordinary characters. @c ^ is an ordinary
character except at the beginning of the RE or the beginning of a parenthesized
-subexpression, @b $ is an ordinary character except at the end of the RE or
-the end of a parenthesized subexpression, and @b * is an ordinary character
-if it appears at the beginning of the RE or the beginning of a parenthesized
-subexpression (after a possible leading '@b ^'). Finally, single-digit back references
-are available, and @b \ and @b \ are synonyms
-for <tt>[[:@<:]]</tt> and <tt>[[:@>:]]</tt> respectively;
-no other escapes are available.
+subexpression, @c $ is an ordinary character except at the end of the RE or the
+end of a parenthesized subexpression, and @c * is an ordinary character if it
+appears at the beginning of the RE or the beginning of a parenthesized
+subexpression (after a possible leading <tt>^</tt>). Finally, single-digit back
+references are available, and @c @\@< and @c @\@> are synonyms for
+<tt>[[:@<:]]</tt> and <tt>[[:@>:]]</tt> respectively; no other escapes are
+available.
@section overview_resyntax_characters Regular Expression Character Names
/////////////////////////////////////////////////////////////////////////////
-// Name: richtextctrl
+// Name: richtextctrl.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @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);
+@page overview_richtextctrl wxRichTextCtrl Overview
- wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL);
-
- 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_roadmap
- wxRichTextCtrl& r = richTextCtrl;
- r.BeginSuppressUndo();
+<hr>
- 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();
+@section overview_richtextctrl_classes Related Classes
- r.WriteText(wxT("What can you do with this thing? "));
- r.WriteImage(wxBitmap(smiley_xpm));
- r.WriteText(wxT(" Well, you can change text "));
+<b>Major classes:</b>
+wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent
- r.BeginTextColour(wxColour(255, 0, 0));
- r.WriteText(wxT("colour, like this red bit."));
- r.EndTextColour();
+<b>Helper classes:</b>
+wxTextAttr, wxRichTextRange
- r.BeginTextColour(wxColour(0, 0, 255));
- r.WriteText(wxT(" And this blue bit."));
- r.EndTextColour();
+<b>File handler classes:</b>
+wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler
- 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();
+<b>Style classes:</b>
+wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition,
+wxRichTextListStyleDefinition, wxRichTextStyleSheet
- r.BeginFontSize(14);
- r.WriteText(wxT(" Different font sizes on the same line is allowed, too."));
- r.EndFontSize();
+<b>Additional controls:</b>
+wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl
- r.WriteText(wxT(" Next we'll show an indented paragraph."));
+<b>Printing classes:</b>
+wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData
- r.BeginLeftIndent(60);
- r.Newline();
+<b>Dialog classes:</b>
+wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog,
+wxSymbolPickerDialog
- r.WriteText(wxT("Indented paragraph."));
- r.EndLeftIndent();
- r.Newline();
+@section overview_richtextctrl_intro Introduction
- r.WriteText(wxT("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40)."));
+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(100, -40);
- 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 file capabilities. Custom file formats
+can be supported by creating additional file handlers and registering them with
+the control.
- r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter."));
- 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("Numbered bullets are possible, again using subindents:"));
+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.BeginNumberedBullet(1, 100, 60);
- r.Newline();
+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:
- r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later."));
- r.EndNumberedBullet();
+@image html richtextctrl.bmp
- r.BeginNumberedBullet(2, 100, 60);
- r.Newline();
- r.WriteText(wxT("This is my second item."));
- r.EndNumberedBullet();
+@section overview_richtextctrl_example Code Example
- r.Newline();
+The following code is an example taken from the sample, and adds text and
+styles to a rich text control programmatically.
- r.WriteText(wxT("The following paragraph is right-indented:"));
+@code
+wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(
+ splitter, wxID_ANY, wxEmptyString, wxDefaultPosition,
+ wxSize(200, 200), wxVSCROLL | wxHSCROLL | wxBORDER_NONE | wxWANTS_CHARS);
- r.BeginRightIndent(200);
- r.Newline();
+wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
+wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);
+wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL);
- 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();
+wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL);
- r.Newline();
+m_richTextCtrl->SetFont(font);
- 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);
+wxRichTextCtrl& r = richTextCtrl;
- r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab"));
+r.BeginSuppressUndo();
- r.Newline();
- r.WriteText(wxT("Other notable features of wxRichTextCtrl include:"));
+r.BeginParagraphSpacing(0, 20);
- r.BeginSymbolBullet(wxT('*'), 100, 60);
- r.Newline();
- r.WriteText(wxT("Compatibility with wxTextCtrl API"));
- r.EndSymbolBullet();
+r.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE);
+r.BeginBold();
- 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.BeginFontSize(14);
+r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images"));
+r.EndFontSize();
+r.Newline();
- r.EndSuppressUndo();
- @endcode
+r.BeginItalic();
+r.WriteText(wxT("by Julian Smart"));
+r.EndItalic();
+r.EndBold();
- @ref topic19_overview
- @ref richtextctrldialogs_overview
- @ref topic22_overview
- @ref topic23_overview
+r.Newline();
+r.WriteImage(wxBitmap(zebra_xpm));
+r.EndAlignment();
- @section topic19 Programming with wxRichTextCtrl
+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 "));
- @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.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 @<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 / commitdiff
