1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxRichTextCtrl Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_richtextctrl_classes">Related Classes</a></li>
<li class="level1"><a href="#overview_richtextctrl_example">Code Example</a></li>
<li class="level1"><a href="#overview_richtextctrl_starting">Starting to Use wxRichTextCtrl</a></li>
<li class="level1"><a href="#overview_richtextctrl_styles">Text Styles</a></li>
<li class="level1"><a href="#overview_richtextctrl_dialogs">Included Dialogs</a></li>
<li class="level1"><a href="#overview_richtextctrl_impl">How wxRichTextCtrl is Implemented</a></li>
<li class="level1"><a href="#overview_richtextctrl_nested_object">Nested Objects</a></li>
<li class="level1"><a href="#overview_richtextctrl_context_menus">Context Menus and Property Dialogs</a></li>
<li class="level1"><a href="#overview_richtextctrl_roadmap">Development Roadmap</a><ul><li class="level2"><a href="#overview_richtextctrl_roadmap_bugs">Bugs</a></li>
<li class="level2"><a href="#overview_richtextctrl_roadmap_features">Features</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> provides a generic implementation of a rich text editor that can handle different character styles, paragraph formatting, and images.</p>
<p>It's aimed at editing 'natural' language text - if you need an editor that supports code editing, <a class="el" href="classwx_styled_text_ctrl.html" title="A wxWidgets implementation of the Scintilla source code editing component.">wxStyledTextCtrl</a> is a better choice.</p>
<p>Despite its name, it cannot currently read or write RTF (rich text format) files. Instead, it uses its own XML format, and can also read and write plain text. In future we expect to provide RTF or OpenDocument file capabilities. Custom file formats can be supported by creating additional file handlers and registering them with the control.</p>
<p><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> is largely compatible with the <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> API, but extends it where necessary. The control can be used where the native rich text capabilities of <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> 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 <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a>, whereas this information is readily available in <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>. Since it's written in pure wxWidgets, any customizations you make to <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> will be reflected on all platforms.</p>
<p><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> supports basic printing via the easy-to-use <a class="el" href="classwx_rich_text_printing.html" title="This class provides a simple interface for performing wxRichTextBuffer printing and previewing...">wxRichTextPrinting</a> class. Creating applications with simple word processing features is simplified with the inclusion of <a class="el" href="classwx_rich_text_formatting_dialog.html" title="This dialog allows the user to edit a character and/or paragraph style.">wxRichTextFormattingDialog</a>, a tabbed dialog allowing interactive tailoring of paragraph and character styling. Also provided is the multi-purpose dialog <a class="el" href="classwx_rich_text_style_organiser_dialog.html" title="This class shows a style sheet and allows the user to edit, add and remove styles.">wxRichTextStyleOrganiserDialog</a> that can be used for managing style definitions, browsing styles and applying them, or selecting list styles with a renumber option.</p>
<p>There are a few disadvantages to using <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>. It is not native, so does not behave exactly as a native <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a>, 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 <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> and <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>, with fewer features in the former case.</p>
<p>A good way to understand <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>'s capabilities is to compile and run the sample, <code>samples/richtext</code>, and browse the code.</p>
<h1><a class="anchor" id="overview_richtextctrl_classes"></a>
Related Classes</h1>
<p><b>Major classes:</b> <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>, <a class="el" href="classwx_rich_text_buffer.html" title="This is a kind of paragraph layout box, used to represent the whole buffer.">wxRichTextBuffer</a>, <a class="el" href="classwx_rich_text_event.html" title="This is the event class for wxRichTextCtrl notifications.">wxRichTextEvent</a></p>
<p><b>Helper classes:</b> <a class="el" href="classwx_text_attr.html" title="wxTextAttr represents the character and paragraph attributes, or style, for a range of text in a wxTe...">wxTextAttr</a>, <a class="el" href="classwx_rich_text_range.html" title="This stores beginning and end positions for a range of data.">wxRichTextRange</a></p>
<p><b>File handler classes:</b> <a class="el" href="classwx_rich_text_file_handler.html" title="The base class for file handlers.">wxRichTextFileHandler</a>, <a class="el" href="classwx_rich_text_h_t_m_l_handler.html" title="Handles HTML output (only) for wxRichTextCtrl content.">wxRichTextHTMLHandler</a>, <a class="el" href="classwx_rich_text_x_m_l_handler.html" title="A handler for loading and saving content in an XML format specific to wxRichTextBuffer.">wxRichTextXMLHandler</a></p>
<p><b>Style classes:</b> <a class="el" href="classwx_rich_text_character_style_definition.html" title="This class represents a character style definition, usually added to a wxRichTextStyleSheet.">wxRichTextCharacterStyleDefinition</a>, <a class="el" href="classwx_rich_text_paragraph_style_definition.html" title="This class represents a paragraph style definition, usually added to a wxRichTextStyleSheet.">wxRichTextParagraphStyleDefinition</a>, <a class="el" href="classwx_rich_text_list_style_definition.html" title="This class represents a list style definition, usually added to a wxRichTextStyleSheet.">wxRichTextListStyleDefinition</a>, <a class="el" href="classwx_rich_text_style_sheet.html" title="A style sheet contains named paragraph and character styles that make it easy for a user to apply com...">wxRichTextStyleSheet</a></p>
<p><b>Additional controls:</b> <a class="el" href="classwx_rich_text_style_combo_ctrl.html" title="This is a combo control that can display the styles in a wxRichTextStyleSheet, and apply the selectio...">wxRichTextStyleComboCtrl</a>, <a class="el" href="classwx_rich_text_style_list_box.html" title="This is a listbox that can display the styles in a wxRichTextStyleSheet, and apply the selection to a...">wxRichTextStyleListBox</a>, <a class="el" href="classwx_rich_text_style_list_ctrl.html" title="This class incorporates a wxRichTextStyleListBox and a choice control that allows the user to select ...">wxRichTextStyleListCtrl</a></p>
<p><b>Printing classes:</b> <a class="el" href="classwx_rich_text_printing.html" title="This class provides a simple interface for performing wxRichTextBuffer printing and previewing...">wxRichTextPrinting</a>, <a class="el" href="classwx_rich_text_printout.html" title="This class implements print layout for wxRichTextBuffer.">wxRichTextPrintout</a>, <a class="el" href="classwx_rich_text_header_footer_data.html" title="This class represents header and footer data to be passed to the wxRichTextPrinting and wxRichTextPri...">wxRichTextHeaderFooterData</a></p>
<p><b>Dialog classes:</b> <a class="el" href="classwx_rich_text_style_organiser_dialog.html" title="This class shows a style sheet and allows the user to edit, add and remove styles.">wxRichTextStyleOrganiserDialog</a>, <a class="el" href="classwx_rich_text_formatting_dialog.html" title="This dialog allows the user to edit a character and/or paragraph style.">wxRichTextFormattingDialog</a>, <a class="el" href="classwx_symbol_picker_dialog.html" title="wxSymbolPickerDialog presents the user with a choice of fonts and a grid of available characters...">wxSymbolPickerDialog</a></p>
<h1><a class="anchor" id="overview_richtextctrl_example"></a>
Code Example</h1>
<p>The following code is an example taken from the sample, and adds text and styles to a rich text control programmatically.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>* richTextCtrl = <span class="keyword">new</span> <a class="code" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>(</div>
<div class="line"> splitter, <a class="code" href="defs_8h.html#ac66d0a09761e7d86b2ac0b2e0c6a8cbba1f375b01ea03a713bbb7e32a36a2589c" title="Any id: means that we don't care about the id, whether when installing an event handler or when creat...">wxID_ANY</a>, <a class="code" href="interface_2wx_2string_8h.html#a9a321d587166a30017b608dd2d234033" title="The global wxString instance of an empty string.">wxEmptyString</a>, <a class="code" href="gdicmn_8h.html#af5a90c753eaf3d3e3e5068a19ec3c1d0" title="Global instance of a wxPoint initialized with values (-1,-1).">wxDefaultPosition</a>,</div>
<div class="line"> <a class="code" href="classwx_size.html" title="A wxSize is a useful data structure for graphics operations.">wxSize</a>(200, 200), <a class="code" href="defs_8h.html#a78a1371cbc8c3b8bb36f27b9d3c47ba9">wxVSCROLL</a> | <a class="code" href="defs_8h.html#a138eed616dd15fd021e8cc838e26d589">wxHSCROLL</a> | <a class="code" href="defs_8h.html#af63c94dff4e3f25a3c5e9d2874456edfaefc06a089c4d7317026613fd8bdf3e22">wxBORDER_NONE</a> | <a class="code" href="defs_8h.html#a9fefaef352af381851b2b78eb5979a95">wxWANTS_CHARS</a>);</div>
<div class="line"></div>
<div class="line"><a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a> textFont = <a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a>(12, wxROMAN, wxNORMAL, wxNORMAL);</div>
<div class="line"><a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a> boldFont = <a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a>(12, wxROMAN, wxNORMAL, wxBOLD);</div>
<div class="line"><a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a> italicFont = <a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a>(12, wxROMAN, wxITALIC, wxNORMAL);</div>
<div class="line"></div>
<div class="line"><a class="code" href="classwx_font.html" title="A font is an object which determines the appearance of text.">wxFont</a> font(12, wxROMAN, wxNORMAL, wxNORMAL);</div>
<div class="line"></div>
<div class="line">m_richTextCtrl->SetFont(font);</div>
<div class="line"></div>
<div class="line"><a class="code" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>& r = richTextCtrl;</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a307060a7027047925188e1088f68c884" title="Starts suppressing undo history for commands.">BeginSuppressUndo</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#af7c2d1c0b33b6875df176a876c011583" title="Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing in tenths of a millim...">BeginParagraphSpacing</a>(0, 20);</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ae1f6f09dad00eb28d01c652826977f5f" title="Begins using alignment.">BeginAlignment</a>(<a class="code" href="textctrl_8h.html#acf93ad4eb51199602dc2af60ca78b4e5a44f21beb45aab0d65e987023f2edfbcf">wxTEXT_ALIGNMENT_CENTRE</a>);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a002052b559e3816c112ab338e9747f0c" title="Begins using bold.">BeginBold</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ac6a91a68493f2b00cbdc018992f0be7a" title="Begins using the given point size.">BeginFontSize</a>(14);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images"</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a90de1fbcf177563f610617ba69ead0ea" title="Ends using a point size.">EndFontSize</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ae0b04f3a15482a58d3fdfd0257bd7d48" title="Begins using italic.">BeginItalic</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"by Julian Smart"</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a63ecaab126a52f72fc4cbf05bbf22ec5" title="Ends using italic.">EndItalic</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a9adc96400a3f4573d8d2e3a78acd6b74" title="Ends using bold.">EndBold</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a1315611c0741d03e852ee26eba3a9d94" title="Write a bitmap or image at the current insertion point.">WriteImage</a>(<a class="code" href="classwx_bitmap.html" title="This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or co...">wxBitmap</a>(zebra_xpm));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a9a41c8bf160e2b06b5b6f22c64c2211f" title="Ends alignment.">EndAlignment</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"What can you do with this thing? "</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a1315611c0741d03e852ee26eba3a9d94" title="Write a bitmap or image at the current insertion point.">WriteImage</a>(<a class="code" href="classwx_bitmap.html" title="This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or co...">wxBitmap</a>(smiley_xpm));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">" Well, you can change text "</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a59618fdff1032e843d47a05b21c23d93" title="Begins using this colour.">BeginTextColour</a>(<a class="code" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a>(255, 0, 0));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"colour, like this red bit."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a789792f7bf805aff5eaef8efcf2e75f0" title="Ends applying a text colour.">EndTextColour</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a59618fdff1032e843d47a05b21c23d93" title="Begins using this colour.">BeginTextColour</a>(<a class="code" href="classwx_colour.html" title="A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values...">wxColour</a>(0, 0, 255));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">" And this blue bit."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a789792f7bf805aff5eaef8efcf2e75f0" title="Ends applying a text colour.">EndTextColour</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">" Naturally you can make things "</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a002052b559e3816c112ab338e9747f0c" title="Begins using bold.">BeginBold</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"bold "</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a9adc96400a3f4573d8d2e3a78acd6b74" title="Ends using bold.">EndBold</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ae0b04f3a15482a58d3fdfd0257bd7d48" title="Begins using italic.">BeginItalic</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"or italic "</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a63ecaab126a52f72fc4cbf05bbf22ec5" title="Ends using italic.">EndItalic</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a333b2e675617ed2299cf91e7c0dbd0d8" title="Begins using underlining.">BeginUnderline</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"or underlined."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a9f44e85782c447e6eb4e82fd877ead15" title="End applying underlining.">EndUnderline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ac6a91a68493f2b00cbdc018992f0be7a" title="Begins using the given point size.">BeginFontSize</a>(14);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">" Different font sizes on the same line is allowed, too."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a90de1fbcf177563f610617ba69ead0ea" title="Ends using a point size.">EndFontSize</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">" Next we'll show an indented paragraph."</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#aa287dc84fa062b8b8f33e26d8050d9fc" title="Begins applying a left indent and subindent in tenths of a millimetre.">BeginLeftIndent</a>(60);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Indented paragraph."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a53111d236d0db253c809320e9657a7d4" title="Ends left indent.">EndLeftIndent</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40)."</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#aa287dc84fa062b8b8f33e26d8050d9fc" title="Begins applying a left indent and subindent in tenths of a millimetre.">BeginLeftIndent</a>(100, -40);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"It was in January, the most down-trodden month of an Edinburgh winter."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a53111d236d0db253c809320e9657a7d4" title="Ends left indent.">EndLeftIndent</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Numbered bullets are possible, again using subindents:"</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a320aa0d999e75bda7673914a66474512" title="Begins a numbered bullet.">BeginNumberedBullet</a>(1, 100, 60);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ae4b1394329c35c980d0fcded6b5155b5" title="Ends application of a numbered bullet.">EndNumberedBullet</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a320aa0d999e75bda7673914a66474512" title="Begins a numbered bullet.">BeginNumberedBullet</a>(2, 100, 60);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"This is my second item."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#ae4b1394329c35c980d0fcded6b5155b5" title="Ends application of a numbered bullet.">EndNumberedBullet</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"The following paragraph is right-indented:"</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#acf0f84f0ef18618009f4d20ebcda8096" title="Begins a right indent, specified in tenths of a millimetre.">BeginRightIndent</a>(200);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"It was in January, the most down-trodden month of an Edinburgh winter. An attractive woman came into the cafe, which is nothing remarkable."</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a42c4ef3ba8b2fc76a7425de0d9d0a798" title="Ends right indent.">EndRightIndent</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line"></div>
<div class="line"><a class="code" href="dynarray_8h.html#add87f199292e36ee87efd6d7f0d4ee66" title="Predefined specialization of wxArray<T> for standard types.">wxArrayInt</a> tabs;</div>
<div class="line">tabs.Add(400);</div>
<div class="line">tabs.Add(600);</div>
<div class="line">tabs.Add(800);</div>
<div class="line">tabs.Add(1000);</div>
<div class="line"><a class="code" href="classwx_text_attr.html" title="wxTextAttr represents the character and paragraph attributes, or style, for a range of text in a wxTe...">wxTextAttr</a> attr;</div>
<div class="line">attr.<a class="code" href="classwx_text_attr.html#a315ebbc5a41840a0777a7716fc19f5f0" title="Sets the flags determining which styles are being specified.">SetFlags</a>(<a class="code" href="textctrl_8h.html#a5544b853914845e9d6453501951d60c2a15c4756ed27d78788e60f53121f4aef5">wxTEXT_ATTR_TABS</a>);</div>
<div class="line">attr.<a class="code" href="classwx_text_attr.html#ad21e66c498c5a60e3603d71938b8c772" title="Sets the tab stops, expressed in tenths of a millimetre.">SetTabs</a>(tabs);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a6397391edcc22594e92f046f2d99a06f" title="Sets the current default style, which can be used to change how subsequently inserted text is display...">SetDefaultStyle</a>(attr);</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"This line contains tabs:\tFirst tab\tSecond tab\tThird tab"</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Other notable features of wxRichTextCtrl include:"</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#afb7a6b5794ba2081c17a04a0811f56b4" title="Begins applying a symbol bullet, using a character from the current font.">BeginSymbolBullet</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="charliteral">'*'</span>), 100, 60);</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a5016a69296d7a9f42f5562d0a7b46332" title="Inserts a new paragraph at the current insertion point.">Newline</a>();</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Compatibility with wxTextCtrl API"</span>));</div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a47edd72f17682bdacbf0f91ab43d9e0f" title="Ends applying a symbol bullet.">EndSymbolBullet</a>();</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a083b9d2b3a04f192080e143897b4bf89" title="Writes text at the current position.">WriteText</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"Note: this sample content was generated programmatically from within the MyFrame constructor in the demo. The images were loaded from inline XPMs. Enjoy wxRichTextCtrl!"</span>));</div>
<div class="line"></div>
<div class="line">r.<a class="code" href="classwx_rich_text_ctrl.html#a1e6f7ac3c1ee26d49abcc9408e9a3e5c" title="Ends suppressing undo command history.">EndSuppressUndo</a>();</div>
</div><!-- fragment --><h1><a class="anchor" id="overview_richtextctrl_starting"></a>
Starting to Use wxRichTextCtrl</h1>
<p>You need to include <code><<a class="el" href="interface_2wx_2richtext_2richtextctrl_8h.html">wx/richtext/richtextctrl.h</a>></code> in your source, and link with the appropriate wxWidgets library with <code>richtext</code> suffix. Put the rich text library first in your link line to avoid unresolved symbols.</p>
<p>Then you can create a <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>, with the wxWANT_CHARS style if you want tabs to be processed by the control rather than being used for navigation between controls.</p>
<h1><a class="anchor" id="overview_richtextctrl_styles"></a>
Text Styles</h1>
<p>Styling attributes are represented by <a class="el" href="classwx_text_attr.html" title="wxTextAttr represents the character and paragraph attributes, or style, for a range of text in a wxTe...">wxTextAttr</a>, or for more control over attributes such as margins and size, the derived class <a class="el" href="classwx_rich_text_attr.html" title="A class representing enhanced attributes for rich text objects.">wxRichTextAttr</a>.</p>
<p>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.</p>
<p><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> 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.</p>
<p>There are four main notions of style within a control:</p>
<ul>
<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 <a class="el" href="classwx_rich_text_ctrl.html#ad1e86c9e0daa943945f2fe82954092c6" title="Sets the font, and also the basic and default attributes (see wxRichTextCtrl::SetDefaultStyle).">wxRichTextCtrl::SetFont</a> changes the font for the basic style. The basic style is set with <a class="el" href="classwx_rich_text_ctrl.html#a994f95fd91df10f3110edbc68dc7112d" title="Sets the basic (overall) style.">wxRichTextCtrl::SetBasicStyle</a>. </li>
<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 <a class="el" href="classwx_rich_text_ctrl.html#ad0bc0f8dfad4d929a532f748e1930c4b" title="Sets the attributes for the given range, passing flags to determine how the attributes are set...">wxRichTextCtrl::SetStyleEx</a>. </li>
<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 <a class="el" href="classwx_rich_text_ctrl.html#a019caef1a5e254ae3496e74de1c41fd4" title="Sets the attributes for the given range.">wxRichTextCtrl::SetStyle</a> or <a class="el" href="classwx_rich_text_ctrl.html#ad0bc0f8dfad4d929a532f748e1930c4b" title="Sets the attributes for the given range, passing flags to determine how the attributes are set...">wxRichTextCtrl::SetStyleEx</a>. </li>
<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 <a class="el" href="classwx_rich_text_ctrl.html#a6397391edcc22594e92f046f2d99a06f" title="Sets the current default style, which can be used to change how subsequently inserted text is display...">wxRichTextCtrl::SetDefaultStyle</a>.</li>
</ul>
<p>What you see on the screen is the dynamically <em>combined</em> 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).</p>
<p>To make all this more concrete, here are examples of where you might set these different styles:</p>
<ul>
<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>
<li>You might set the <em>paragraph style</em> (for one particular paragraph) to be centred. </li>
<li>You might set the <em>character style</em> of one particular word to bold. </li>
<li>You might set the <em>default style</em> to be underlined, for subsequent inserted text.</li>
</ul>
<p>Naturally you can do any of these things either using your own UI, or programmatically.</p>
<p>The basic <a class="el" href="classwx_text_ctrl.html" title="A text control allows text to be displayed and edited.">wxTextCtrl</a> doesn't make the same distinctions as <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> regarding attribute storage. So we need finer control when setting and retrieving attributes. <a class="el" href="classwx_rich_text_ctrl.html#ad0bc0f8dfad4d929a532f748e1930c4b" title="Sets the attributes for the given range, passing flags to determine how the attributes are set...">wxRichTextCtrl::SetStyleEx</a> takes a <em>flags</em> parameter:</p>
<ul>
<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 <em>combined</em> (visible) style, and <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> wants to leave unchanged attributes associated with their original objects instead of applying them to both paragraph and content objects. </li>
<li>wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY specifies that only paragraph objects within the given range should take on the attributes. </li>
<li>wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects (text or images) within the given range should take on the attributes. </li>
<li>wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be undoable.</li>
</ul>
<p>It's great to be able to change arbitrary attributes in a <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>, 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 <a class="el" href="classwx_rich_text_style_sheet.html" title="A style sheet contains named paragraph and character styles that make it easy for a user to apply com...">wxRichTextStyleSheet</a> which manages style definitions (<a class="el" href="classwx_rich_text_paragraph_style_definition.html" title="This class represents a paragraph style definition, usually added to a wxRichTextStyleSheet.">wxRichTextParagraphStyleDefinition</a>, <a class="el" href="classwx_rich_text_list_style_definition.html" title="This class represents a list style definition, usually added to a wxRichTextStyleSheet.">wxRichTextListStyleDefinition</a> and <a class="el" href="classwx_rich_text_character_style_definition.html" title="This class represents a character style definition, usually added to a wxRichTextStyleSheet.">wxRichTextCharacterStyleDefinition</a>). Once you have added definitions to a style sheet and associated it with a <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a>, you can apply a named definition to a range of text. The classes <a class="el" href="classwx_rich_text_style_combo_ctrl.html" title="This is a combo control that can display the styles in a wxRichTextStyleSheet, and apply the selectio...">wxRichTextStyleComboCtrl</a> and <a class="el" href="classwx_rich_text_style_list_box.html" title="This is a listbox that can display the styles in a wxRichTextStyleSheet, and apply the selection to a...">wxRichTextStyleListBox</a> can be used to present the user with a list of styles in a sheet, and apply them to the selected text.</p>
<p>You can reapply a style sheet to the contents of the control, by calling <a class="el" href="classwx_rich_text_ctrl.html#ab4dd025a2ad34eb31cc604cf6411b352" title="Applies the style sheet to the buffer, for example if the styles have changed.">wxRichTextCtrl::ApplyStyleSheet</a>. 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.</p>
<h1><a class="anchor" id="overview_richtextctrl_dialogs"></a>
Included Dialogs</h1>
<p><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> comes with standard dialogs to make it easier to implement text editing functionality.</p>
<p><a class="el" href="classwx_rich_text_formatting_dialog.html" title="This dialog allows the user to edit a character and/or paragraph style.">wxRichTextFormattingDialog</a> can be used for character or paragraph formatting, or a combination of both. It's a <a class="el" href="classwx_property_sheet_dialog.html" title="This class represents a property sheet dialog: a tabbed dialog for showing settings.">wxPropertySheetDialog</a> with the following available tabs: Font, Indents & Spacing, Tabs, Bullets, Style, Borders, Margins, Background, Size, and List Style. You can select which pages will be shown by supplying flags to the dialog constructor. In a character formatting dialog, typically only the Font page will be shown. In a paragraph formatting dialog, you'll show the Indents & Spacing, Tabs and Bullets pages. The Style tab is useful when editing a style definition.</p>
<p>You can customize this dialog by providing your own <a class="el" href="classwx_rich_text_formatting_dialog_factory.html" title="This class provides pages for wxRichTextFormattingDialog, and allows other customization of the dialo...">wxRichTextFormattingDialogFactory</a> object, which tells the formatting dialog how many pages are supported, what their identifiers are, and how to creates the pages.</p>
<p><a class="el" href="classwx_rich_text_style_organiser_dialog.html" title="This class shows a style sheet and allows the user to edit, add and remove styles.">wxRichTextStyleOrganiserDialog</a> 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.</p>
<p><a class="el" href="classwx_symbol_picker_dialog.html" title="wxSymbolPickerDialog presents the user with a choice of fonts and a grid of available characters...">wxSymbolPickerDialog</a> lets the user insert a symbol from a specified font. It has no <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> dependencies besides being included in the rich text library.</p>
<h1><a class="anchor" id="overview_richtextctrl_impl"></a>
How wxRichTextCtrl is Implemented</h1>
<p>Data representation is handled by <a class="el" href="classwx_rich_text_buffer.html" title="This is a kind of paragraph layout box, used to represent the whole buffer.">wxRichTextBuffer</a>, and a <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> always has one such buffer.</p>
<p>The content is represented by a hierarchy of objects, all derived from <a class="el" href="classwx_rich_text_object.html" title="This is the base for drawable rich text objects.">wxRichTextObject</a>. An object might be an image, a fragment of text, a paragraph, or a further composite object. Objects store a <a class="el" href="classwx_rich_text_attr.html" title="A class representing enhanced attributes for rich text objects.">wxRichTextAttr</a> 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.</p>
<p>The top of the hierarchy is the buffer, a kind of <a class="el" href="classwx_rich_text_paragraph_layout_box.html" title="This class knows how to lay out paragraphs.">wxRichTextParagraphLayoutBox</a>, containing further <a class="el" href="classwx_rich_text_paragraph.html" title="This object represents a single paragraph containing various objects such as text content...">wxRichTextParagraph</a> objects, each of which can include text, images and potentially other types of object.</p>
<p>Each object maintains a range (start and end position) measured from the start of the main parent object.</p>
<p>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.</p>
<p>When the buffer is modified, a range is invalidated (marked as requiring layout), so that only the minimum amount of layout is performed.</p>
<p>A paragraph of pure text with the same style contains just one further object, a <a class="el" href="classwx_rich_text_plain_text.html" title="This object represents a single piece of text.">wxRichTextPlainText</a> 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 <a class="el" href="classwx_text_attr.html" title="wxTextAttr represents the character and paragraph attributes, or style, for a range of text in a wxTe...">wxTextAttr</a> 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.</p>
<h1><a class="anchor" id="overview_richtextctrl_nested_object"></a>
Nested Objects</h1>
<p><a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> supports nested objects such as text boxes and tables. To achieve compatibility with the existing API, there is the concept of <em>object</em> <em>focus</em>. When the user clicks on a nested text box, the object focus is set to that container object so all keyboard input and API functions apply to that container. The application can change the focus using wxRichTextCtrl::SetObjectFocus. Call this function with a <code>null</code> parameter to set the focus back to the top-level object.</p>
<p>An event will be sent to the control when the focus changes.</p>
<p>When the user clicks on the control, <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> determines which container to set as the current object focus by calling the found container's overrided <a class="el" href="classwx_rich_text_object.html#ae42498f572d7a1859748605dbeb4a2a2" title="Returns true if objects of this class can accept the focus, i.e. a call to SetFocusObject is possible...">wxRichTextObject::AcceptsFocus</a> function. For example, although a table is a container, it must not itself be the object focus because there is no text editing at the table level. Instead, a cell within the table must accept the focus.</p>
<p>Since with nested objects it is not possible to represent a section with merely a start position and an end position, the class <a class="el" href="classwx_rich_text_selection.html" title="Stores selection information.">wxRichTextSelection</a> is provided which stores multiple ranges (for non-contiguous selections such as table cells) and a pointer to the container object in question. You can pass <a class="el" href="classwx_rich_text_selection.html" title="Stores selection information.">wxRichTextSelection</a> to <a class="el" href="classwx_rich_text_ctrl.html#a6c03432e13fb42c87df867f18252e10e" title="Sets the selection to the given range.">wxRichTextCtrl::SetSelection</a> or get an instance of it from <a class="el" href="classwx_rich_text_ctrl.html#a7d83b1a753beade27d09cf3905f28975" title="Returns the range of the current selection.">wxRichTextCtrl::GetSelection</a>.</p>
<p>When selecting multiple objects, such as cell tables, the <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> dragging handler code calls the function <a class="el" href="classwx_rich_text_object.html#a747d48c460a7a6d73742479a9fb08d14" title="Returns true if this object can handle the selections of its children, fOr example a table...">wxRichTextObject::HandlesChildSelections</a> to determine whether the children can be individual selections. Currently only table cells can be multiply-selected in this way.</p>
<h1><a class="anchor" id="overview_richtextctrl_context_menus"></a>
Context Menus and Property Dialogs</h1>
<p>There are three ways you can make use of context menus: you can let <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> handle everything and provide a basic menu; you can set your own context menu using <a class="el" href="classwx_rich_text_ctrl.html#a220fd0f4032fa7c0a1b1c2ed5c85a7aa" title="Sets the current context menu.">wxRichTextCtrl::SetContextMenu</a> but let <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> handle showing it and adding property items; or you can override the default context menu behaviour by adding a context menu event handler to your class in the normal way.</p>
<p>If you right-click over a text box in cell in a table, you may want to edit the properties of one of these objects - but which properties will you be editing?</p>
<p>Well, the default behaviour allows up to three property-editing menu items simultaneously - for the object clicked on, the container of that object, and the container's parent (depending on whether any of these objects return <span class="literal">true</span> from their <a class="el" href="classwx_rich_text_object.html#a86ceb93a7e960fecf5239a814c88be7d" title="Returns true if we can edit the object's properties via a GUI.">wxRichTextObject::CanEditProperties</a> functions). If you supply a context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1 identifier, so that <a class="el" href="classwx_rich_text_ctrl.html" title="wxRichTextCtrl provides a generic, ground-up implementation of a text control capable of showing mult...">wxRichTextCtrl</a> can find the position to add command items. The object should tell the control what label to use by returning a string from <a class="el" href="classwx_rich_text_object.html#ae28b43263d92734c5893c87ee11167ee" title="Returns the label to be used for the properties context menu item.">wxRichTextObject::GetPropertiesMenuLabel</a>.</p>
<p>Since there may be several property-editing commands showing, it is recommended that you don't include the word Properties - just the name of the object, such as Text Box or Table.</p>
<h1><a class="anchor" id="overview_richtextctrl_roadmap"></a>
Development Roadmap</h1>
<h2><a class="anchor" id="overview_richtextctrl_roadmap_bugs"></a>
Bugs</h2>
<p>This is an incomplete list of bugs.</p>
<ul>
<li>Moving the caret up at the beginning of a line sometimes incorrectly positions the caret. </li>
<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 <a class="el" href="classwx_d_c.html#aa0dd5cdd1ce56ff3d1c23d233711653d" title="Fills the widths array with the widths from the beginning of text to the corresponding character of t...">wxDC::GetPartialTextExtents</a> 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.</li>
</ul>
<h2><a class="anchor" id="overview_richtextctrl_roadmap_features"></a>
Features</h2>
<p>This is a list of some of the features that have yet to be implemented. Help with them will be appreciated.</p>
<ul>
<li>support for composite objects in some functions where it's not yet implemented, for example ApplyStyleSheet </li>
<li>Table API enhancements and dialogs; improved table layout especially row spans and fitting </li>
<li>Conversion from HTML, and a rewrite of the HTML output handler that includes CSS, tables, text boxes, and floating images, in addition to a simplified-HTML mode for wxHTML compatibility </li>
<li>Open Office input and output </li>
<li>RTF input and output </li>
<li>A ruler control </li>
<li>Standard editing toolbars </li>
<li>Bitmap bullets </li>
<li>Justified text, in print/preview at least </li>
<li>scaling: either everything scaled, or rendering using a custom reference point size and an optional dimension scale</li>
</ul>
<p>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 <a class="el" href="classwx_d_c.html" title="A wxDC is a "device context" onto which graphics and text can be drawn.">wxDC</a> API is unnecessary. However this would require additions to the wxWidgets API. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
