Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52132 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-02-27 04:40:10 +00:00
parent 2a8c8b35f8
commit 07fa8f78f8
2 changed files with 524 additions and 460 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
docs/doxygen/overviews/resyntax.h
View File

@@ -408,125 +408,129 @@ as a literal string rather than as an RE.
@section overview_resyntax_matching Matching @section overview_resyntax_matching Matching
In the event that an RE could match more than In the event that an RE could match more than one substring of a given string,
one substring of a given string, the RE matches the one starting earliest the RE matches the one starting earliest in the string. If the RE could match
in the string. If the RE could match more than one substring starting at more than one substring starting at that point, the choice is determined by
that point, its choice is determined by its @e preference: either the longest it's @e preference: either the longest substring, or the shortest.
substring, or the shortest.
Most atoms, and all constraints, have no preference. Most atoms, and all constraints, have no preference. A parenthesized RE has the
A parenthesized RE has the same preference (possibly none) as the RE. A same preference (possibly none) as the RE. A quantified atom with quantifier
quantified atom with quantifier @b {m} or @b {m}? has the same preference (possibly <tt>{m}</tt> or <tt>{m}?</tt> has the same preference (possibly none) as the
none) as the atom itself. A quantified atom with other normal quantifiers atom itself. A quantified atom with other normal quantifiers (including
(including @b {m,n} with @e m equal to @e n) prefers longest match. A quantified <tt>{m,n}</tt> 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 atom with other non-greedy quantifiers (including <tt>{m,n}?</tt> with @e m
@e n) prefers shortest match. A branch has the same preference as the first equal to @e n) prefers shortest match. A branch has the same preference as the
quantified atom in it which has a preference. An RE consisting of two or 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. 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 Subject to the constraints imposed by the rules for matching the whole RE,
preferences, with subexpressions starting earlier in the RE taking priority subexpressions also match the longest or shortest possible substrings, based on
over ones starting later. Note that outer subexpressions thus take priority their preferences, with subexpressions starting earlier in the RE taking
over their component subexpressions. priority over ones starting later. Note that outer subexpressions thus take
Note that the quantifiers @b {1,1} and priority over their component subexpressions.
@b {1,1}? can be used to force longest and shortest preference, respectively,
on a subexpression or a whole RE. Note that the quantifiers <tt>{1,1}</tt> and <tt>{1,1}?</tt> can be used to
Match lengths are measured in characters, force longest and shortest preference, respectively, on a subexpression or a
not collating elements. An empty string is considered longer than no match whole RE.
at all. For example, @b bb* matches the three middle characters
of '@b abbbc', @b (week|wee)(night|knights) Match lengths are measured in characters, not collating elements. An empty
matches all ten characters of '@b weeknights', when @b (.*).* is matched against string is considered longer than no match at all. For example, <tt>bb*</tt>
@b abc the parenthesized subexpression matches all three characters, and when matches the three middle characters of "abbbc",
@b (a*)* is matched against @b bc both the whole RE and the parenthesized subexpression <tt>(week|wee)(night|knights)</tt> matches all ten characters of "weeknights",
match an empty string. when <tt>(.*).*</tt> is matched against "abc" the parenthesized subexpression
If case-independent matching is specified, the effect matches all three characters, and when <tt>(a*)*</tt> is matched against "bc"
is much as if all case distinctions had vanished from the alphabet. When both the whole RE and the parenthesized subexpression match an empty string.
an alphabetic that exists in multiple cases appears as an ordinary character
outside a bracket expression, it is effectively transformed into a bracket If case-independent matching is specified, the effect is much as if all case
expression containing both cases, so that @b x becomes '@b [xX]'. When it appears distinctions had vanished from the alphabet. When an alphabetic that exists in
inside a bracket expression, all case counterparts of it are added to the multiple cases appears as an ordinary character outside a bracket expression,
bracket expression, so that @b [x] becomes @b [xX] and @b [^x] becomes '@b [^xX]'. it is effectively transformed into a bracket expression containing both cases,
If newline-sensitive so that @c x becomes @c [xX]. When it appears inside a bracket expression, all
matching is specified, @b . and bracket expressions using @b ^ will never match case counterparts of it are added to the bracket expression, so that @c [x]
the newline character (so that matches will never cross newlines unless becomes @c [xX] and @c [^x] becomes @c [^xX].
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 If newline-sensitive matching is specified, "." and bracket expressions using
and end of string respectively. ARE @b \A and @b \Z continue to match beginning "^" will never match the newline character (so that matches will never cross
or end of string @e only. newlines unless the RE explicitly arranges it) and "^" and "$" will match the
If partial newline-sensitive matching is specified, empty string after and before a newline respectively, in addition to matching
this affects @b . and bracket expressions as with newline-sensitive matching, at beginning and end of string respectively. ARE <tt>@\A</tt> and <tt>@\Z</tt>
but not @b ^ and '@b $'. continue to match beginning or end of string @e only.
If inverse partial newline-sensitive matching is specified,
this affects @b ^ and @b $ as with newline-sensitive matching, but not @b . and bracket 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. expressions. This isn't very useful but is provided for symmetry.
@section overview_resyntax_limits Limits and Compatibility @section overview_resyntax_limits Limits and Compatibility
No particular limit is imposed on the length of REs. Programs No particular limit is imposed on the length of REs. Programs intended to be
intended to be highly portable should not employ REs longer than 256 bytes, highly portable should not employ REs longer than 256 bytes, as a
as a POSIX-compliant implementation can refuse to accept such REs. 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.)
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 The only feature of AREs that is actually incompatible with POSIX EREs is that
an error, while in RREs, it was just another way of writing the alphanumeric. <tt>@\</tt> does not lose its special significance inside bracket expressions.
This should not be a problem because there was no reason to write such All other ARE features use syntax which is illegal or has undefined or
a sequence in RREs. unspecified effects in POSIX EREs; the <tt>***</tt> syntax of directors
@b { followed by a digit in an ARE is the beginning of likewise is outside the POSIX syntax for both BREs and EREs.
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 Many of the ARE extensions are borrowed from Perl, but some have been changed
will not look like a valid bound. to clean them up, and a few Perl extensions are not present. Incompatibilities
In AREs, @b \ remains a special character of note include <tt>@\b</tt>, <tt>@\B</tt>, the lack of special treatment for a
within '@b []', so a literal @b \ within @b [] must be trailing newline, the addition of complemented bracket expressions to the
written '@b \\'. @b \\ also gives a literal things affected by newline-sensitive matching, the restrictions on parentheses
@b \ within @b [] in RREs, but only truly paranoid programmers routinely doubled and back references in lookahead constraints, and the longest/shortest-match
the backslash. (rather than first-match) matching semantics.
AREs report the longest/shortest match for the RE, rather
than the first found in a specified search order. This may affect some RREs The matching rules for REs containing both normal and non-greedy quantifiers
which were written in the expectation that the first match would be reported. have changed since early beta-test versions of this package. The new rules are
(The careful crafting of RREs to optimize the search order for fast matching much simpler and cleaner, but don't work as hard at guessing the user's real
is obsolete (AREs examine all possible matches in parallel, and their performance intentions.
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 Henry Spencer's original 1986 @e regexp package, still in widespread use,
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 @section overview_resyntax_bre Basic Regular Expressions
BREs differ from EREs in BREs differ from EREs in several respects. @c |, @c +, and @c ? are ordinary
several respects. '@b |', '@b +', and @b ? are ordinary characters and there is no equivalent characters and there is no equivalent for their functionality. The delimiters
for their functionality. The delimiters for bounds for bounds are @c @\{ and @c @\}, with @c { and @c } by themselves ordinary
are @b \{ and '@b \}', with @b { and characters. The parentheses for nested subexpressions are @c @\( and @c @\),
@b } by themselves ordinary characters. The parentheses for nested subexpressions with @c ( and @c ) by themselves ordinary characters. @c ^ is an ordinary
are @b \( and '@b \)', with @b ( and @b ) by themselves
ordinary characters. @b ^ is an ordinary
character except at the beginning of the RE or the beginning of a parenthesized 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 subexpression, @c $ is an ordinary character except at the end of the RE or the
the end of a parenthesized subexpression, and @b * is an ordinary character end of a parenthesized subexpression, and @c * is an ordinary character if it
if it appears at the beginning of the RE or the beginning of a parenthesized appears at the beginning of the RE or the beginning of a parenthesized
subexpression (after a possible leading '@b ^'). Finally, single-digit back references subexpression (after a possible leading <tt>^</tt>). Finally, single-digit back
are available, and @b \ and @b \ are synonyms references are available, and @c @\@< and @c @\@> are synonyms for
for <tt>[[:@<:]]</tt> and <tt>[[:@>:]]</tt> respectively; <tt>[[:@<:]]</tt> and <tt>[[:@>:]]</tt> respectively; no other escapes are
no other escapes are available. available.
@section overview_resyntax_characters Regular Expression Character Names @section overview_resyntax_characters Regular Expression Character Names

752
docs/doxygen/overviews/richtextctrl.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: richtextctrl // Name: richtextctrl.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,391 +8,451 @@
/*! /*!
@page richtextctrl_overview wxRichTextCtrl overview @page overview_richtextctrl wxRichTextCtrl Overview
@b Major classes: #wxRichTextCtrl, #wxRichTextBuffer, #wxRichTextEvent @li @ref overview_richtextctrl_classes
@b Helper classes: #wxTextAttr, #wxRichTextRange @li @ref overview_richtextctrl_intro
@b File handler classes: #wxRichTextFileHandler, #wxRichTextHTMLHandler, @li @ref overview_richtextctrl_example
#wxRichTextXMLHandler @li @ref overview_richtextctrl_starting
@b Style classes: #wxRichTextCharacterStyleDefinition, @li @ref overview_richtextctrl_styles
#wxRichTextParagraphStyleDefinition, @li @ref overview_richtextctrl_dialogs
#wxRichTextListStyleDefinition, @li @ref overview_richtextctrl_impl
#wxRichTextStyleSheet @li @ref overview_richtextctrl_roadmap
@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 <hr>
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 @section overview_richtextctrl_classes Related Classes
@ref richtextctrldialogs_overview
@ref topic22_overview <b>Major classes:</b>
@ref topic23_overview wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent
<b>Helper classes:</b>
wxTextAttr, wxRichTextRange
<b>File handler classes:</b>
wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler
<b>Style classes:</b>
wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition,
wxRichTextListStyleDefinition, wxRichTextStyleSheet
<b>Additional controls:</b>
wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl
<b>Printing classes:</b>
wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData
<b>Dialog classes:</b>
wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog,
wxSymbolPickerDialog
@section topic19 Programming with wxRichTextCtrl @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. The following screenshot
shows the sample in action:
@image html richtextctrl.bmp
@section topic20 Starting to use wxRichTextCtrl @section overview_richtextctrl_example Code Example
You need to include @c wx/richtext/richtextctrl.h in your source, and link The following code is an example taken from the sample, and adds text and
with the appropriate wxWidgets library with @c richtext suffix. Put the rich text styles to a rich text control programmatically.
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 @code
wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(
splitter, wxID_ANY, wxEmptyString, wxDefaultPosition,
wxSize(200, 200), wxVSCROLL | wxHSCROLL | wxBORDER_NONE | wxWANTS_CHARS);
Styling attributes are represented by #wxTextAttr. wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
When setting a style, the flags of the attribute object determine which wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);
attributes are applied. When querying a style, the passed flags are ignored wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL);
except (optionally) to determine whether attributes should be retrieved from
character content or from the paragraph object. wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL);
wxRichTextCtrl takes a layered approach to styles, so that different parts of
the content may be responsible for contributing different attributes to the final m_richTextCtrl->SetFont(font);
style you see on the screen.
There are four main notions of style within a control: 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
@b Basic style: the fundamental style of a control, onto which any other @section overview_richtextctrl_starting Starting to Use wxRichTextCtrl
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 You need to include @c @<wx/richtext/richtextctrl.h@> in your source, and link
the content uses. Calling wxRichTextCtrl::SetFont changes the font for the basic style. with the appropriate wxWidgets library with @c richtext suffix. Put the rich
The basic style is set with wxRichTextCtrl::SetBasicStyle. text library first in your link line to avoid unresolved symbols.
@b Paragraph style: each paragraph has attributes that are set independently
from other paragraphs and independently from the content within the paragraph. Then you can create a wxRichTextCtrl, with the wxWANT_CHARS style if you want
Normally, these attributes are paragraph-related, such as alignment and indentation, tabs to be processed by the control rather than being used for navigation
but it is possible to set character attributes too. between controls.
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. @section overview_richtextctrl_styles Text Styles
A single character, or a run of characters, can have a particular set of attributes.
The character style can be with wxRichTextCtrl::SetStyle or 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. wxRichTextCtrl::SetStyleEx.
@b Default style: this is the 'current' style that determines the @li <b>Character style</b>: Characters within each paragraph can have
style of content that is subsequently typed, pasted or programmatically inserted. 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. 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).
What you see on the screen is the dynamically @e combined style, found by merging To make all this more concrete, here are examples of where you might set these
the first three of the above style types (the fourth is only a guide for future content different styles:
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
You might set the @b basic style to have a Times Roman font in 12 point, point, left-aligned, with two millimetres of spacing after each paragraph.
left-aligned, with two millimetres of spacing after each paragraph. @li You might set the <em>paragraph style</em> (for one particular paragraph)
You might set the @b paragraph style (for one particular paragraph) to to be centred.
be centred. @li You might set the <em>character style</em> of one particular word to bold.
You might set the @b character style of one particular word to bold. @li You might set the <em>default style</em> to be underlined, for subsequent
You might set the @b default style to be underlined, for subsequent
inserted text. inserted text.
Naturally you can do any of these things either using your own UI, or
programmatically.
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
The basic wxTextCtrl doesn't make the same distinctions as wxRichTextCtrl regarding regarding attribute storage. So we need finer control when setting and
attribute storage. So we need finer control when setting and retrieving retrieving attributes. wxRichTextCtrl::SetStyleEx takes a @e flags parameter:
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.
wxRICHTEXT_SETSTYLE_OPTIMIZE specifies that the style should be changed only if @section overview_richtextctrl_dialogs Included Dialogs
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) wxRichTextCtrl comes with standard dialogs to make it easier to implement text
style, and wxRichTextCtrl wants to leave unchanged attributes associated with their original objects editing functionality.
instead of applying them to both paragraph and content objects.
wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY specifies that only paragraph objects within the given range wxRichTextFormattingDialog can be used for character or paragraph formatting,
should take on the attributes. or a combination of both. It's a wxPropertySheetDialog with the following
wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects (text or images) within the given range available tabs: Font, Indents @& Spacing, Tabs, Bullets, Style, and List Style.
should take on the attributes. You can select which pages will be shown by supplying flags to the dialog
wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be undoable. 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.
It's great to be able to change arbitrary attributes in a wxRichTextCtrl, but @section overview_richtextctrl_impl How wxRichTextCtrl is Implemented
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 Data representation is handled by wxRichTextBuffer, and a wxRichTextCtrl always
has one such buffer.
wxRichTextCtrl comes with standard dialogs to make it easier to implement The content is represented by a hierarchy of objects, all derived from
text editing functionality. wxRichTextObject. An object might be an image, a fragment of text, a paragraph,
#wxRichTextFormattingDialog can be used or a whole buffer. Objects store a wxTextAttr containing style information; a
for character or paragraph formatting, or a combination of both. It's a wxPropertySheetDialog paragraph object can contain both paragraph and character information, but
with the following available tabs: Font, Indents Spacing, Tabs, Bullets, Style, and List Style. content objects such as text can only store character information. The final
You can select which pages will be shown by supplying flags to the dialog constructor. style displayed in the control or in a printout is a combination of base style,
In a character formatting dialog, typically only the Font page will be shown. paragraph style and content (character) style.
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 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.
Data representation is handled by wxRichTextBuffer, and a wxRichTextCtrl Each object maintains a range (start and end position) measured from the start
always has one such buffer. of the main parent object.
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 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.
@b Bugs When the buffer is modified, a range is invalidated (marked as requiring
This is an incomplete list of bugs. 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.
Moving the caret up at the beginning of a line sometimes incorrectly positions the @section overview_richtextctrl_roadmap Development Roadmap
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.
@subsection overview_richtextctrl_roadmap_bugs Bugs
@b Features This is an incomplete list of bugs.
This is a list of some of the features that have yet to be implemented. Help with them will be appreciated.
@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.
RTF input and output @subsection overview_richtextctrl_roadmap_features Features
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
This is a list of some of the features that have yet to be implemented. Help
with them will be appreciated.
There are also things that could be done to take advantage of the underlying text capabilities of the platform; @li RTF input and output
higher-level text formatting APIs are available on some platforms, such as Mac OS X, and some of translation from @li Conversion from HTML
high level to low level wxDC API is unnecessary. However this would require additions to the wxWidgets API. @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.
*/