]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/richtextctrl.h
Move wx/msw/gccpriv.h inclusion back to wx/platform.h from wx/compiler.h.
[wxWidgets.git] / docs / doxygen / overviews / richtextctrl.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
07fa8f78 2// Name: richtextctrl.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
15b6757b
FM
7/////////////////////////////////////////////////////////////////////////////
8
880efa2a 9/**
36c9828f 10
07fa8f78 11@page overview_richtextctrl wxRichTextCtrl Overview
36c9828f 12
831e1028 13@tableofcontents
36c9828f 14
07fa8f78
BP
15wxRichTextCtrl provides a generic implementation of a rich text editor that can
16handle different character styles, paragraph formatting, and images. It's aimed
17at editing 'natural' language text - if you need an editor that supports code
18editing, wxStyledTextCtrl is a better choice.
36c9828f 19
07fa8f78
BP
20Despite its name, it cannot currently read or write RTF (rich text format)
21files. Instead, it uses its own XML format, and can also read and write plain
831e1028
BP
22text. In future we expect to provide RTF or OpenDocument file capabilities.
23Custom file formats can be supported by creating additional file handlers and
24registering them with the control.
36c9828f 25
07fa8f78
BP
26wxRichTextCtrl is largely compatible with the wxTextCtrl API, but extends it
27where necessary. The control can be used where the native rich text
28capabilities of wxTextCtrl are not adequate (this is particularly true on
29Windows) and where more direct access to the content representation is
30required. It is difficult and inefficient to read the style information in a
31wxTextCtrl, whereas this information is readily available in wxRichTextCtrl.
32Since it's written in pure wxWidgets, any customizations you make to
33wxRichTextCtrl will be reflected on all platforms.
36c9828f 34
07fa8f78
BP
35wxRichTextCtrl supports basic printing via the easy-to-use wxRichTextPrinting
36class. Creating applications with simple word processing features is simplified
37with the inclusion of wxRichTextFormattingDialog, a tabbed dialog allowing
38interactive tailoring of paragraph and character styling. Also provided is the
39multi-purpose dialog wxRichTextStyleOrganiserDialog that can be used for
40managing style definitions, browsing styles and applying them, or selecting
41list styles with a renumber option.
36c9828f 42
07fa8f78
BP
43There are a few disadvantages to using wxRichTextCtrl. It is not native, so
44does not behave exactly as a native wxTextCtrl, although common editing
45conventions are followed. Users may miss the built-in spelling correction on
46Mac OS X, or any special character input that may be provided by the native
47control. It would also be a poor choice if intended users rely on screen
48readers that would be not work well with non-native text input implementation.
49You might mitigate this by providing the choice between wxTextCtrl and
50wxRichTextCtrl, with fewer features in the former case.
36c9828f 51
07fa8f78 52A good way to understand wxRichTextCtrl's capabilities is to compile and run
de2b67e6 53the sample, @c samples/richtext, and browse the code.
36c9828f 54
36c9828f 55
831e1028
BP
56
57@section overview_richtextctrl_classes Related Classes
58
59<b>Major classes:</b>
60wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent
61
62<b>Helper classes:</b>
63wxTextAttr, wxRichTextRange
64
65<b>File handler classes:</b>
66wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler
67
68<b>Style classes:</b>
69wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition,
70wxRichTextListStyleDefinition, wxRichTextStyleSheet
71
72<b>Additional controls:</b>
73wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl
74
75<b>Printing classes:</b>
76wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData
77
78<b>Dialog classes:</b>
79wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog,
80wxSymbolPickerDialog
81
82
07fa8f78 83@section overview_richtextctrl_example Code Example
36c9828f 84
07fa8f78
BP
85The following code is an example taken from the sample, and adds text and
86styles to a rich text control programmatically.
36c9828f 87
07fa8f78
BP
88@code
89wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(
90 splitter, wxID_ANY, wxEmptyString, wxDefaultPosition,
91 wxSize(200, 200), wxVSCROLL | wxHSCROLL | wxBORDER_NONE | wxWANTS_CHARS);
36c9828f 92
07fa8f78
BP
93wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
94wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);
95wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL);
36c9828f 96
07fa8f78 97wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL);
36c9828f 98
07fa8f78 99m_richTextCtrl->SetFont(font);
36c9828f 100
07fa8f78 101wxRichTextCtrl& r = richTextCtrl;
36c9828f 102
07fa8f78 103r.BeginSuppressUndo();
36c9828f 104
07fa8f78 105r.BeginParagraphSpacing(0, 20);
36c9828f 106
07fa8f78
BP
107r.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE);
108r.BeginBold();
36c9828f 109
07fa8f78
BP
110r.BeginFontSize(14);
111r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images"));
112r.EndFontSize();
113r.Newline();
36c9828f 114
07fa8f78
BP
115r.BeginItalic();
116r.WriteText(wxT("by Julian Smart"));
117r.EndItalic();
36c9828f 118
07fa8f78 119r.EndBold();
36c9828f 120
07fa8f78
BP
121r.Newline();
122r.WriteImage(wxBitmap(zebra_xpm));
36c9828f 123
07fa8f78 124r.EndAlignment();
36c9828f 125
07fa8f78
BP
126r.Newline();
127r.Newline();
36c9828f 128
07fa8f78
BP
129r.WriteText(wxT("What can you do with this thing? "));
130r.WriteImage(wxBitmap(smiley_xpm));
131r.WriteText(wxT(" Well, you can change text "));
36c9828f 132
07fa8f78
BP
133r.BeginTextColour(wxColour(255, 0, 0));
134r.WriteText(wxT("colour, like this red bit."));
135r.EndTextColour();
36c9828f 136
07fa8f78
BP
137r.BeginTextColour(wxColour(0, 0, 255));
138r.WriteText(wxT(" And this blue bit."));
139r.EndTextColour();
140
141r.WriteText(wxT(" Naturally you can make things "));
142r.BeginBold();
143r.WriteText(wxT("bold "));
144r.EndBold();
145r.BeginItalic();
146r.WriteText(wxT("or italic "));
147r.EndItalic();
148r.BeginUnderline();
149r.WriteText(wxT("or underlined."));
150r.EndUnderline();
151
152r.BeginFontSize(14);
153r.WriteText(wxT(" Different font sizes on the same line is allowed, too."));
154r.EndFontSize();
155
156r.WriteText(wxT(" Next we'll show an indented paragraph."));
157
158r.BeginLeftIndent(60);
159r.Newline();
160
161r.WriteText(wxT("Indented paragraph."));
162r.EndLeftIndent();
163
164r.Newline();
165
166r.WriteText(wxT("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40)."));
167
168r.BeginLeftIndent(100, -40);
169r.Newline();
170
171r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter."));
172r.EndLeftIndent();
173
174r.Newline();
175
176r.WriteText(wxT("Numbered bullets are possible, again using subindents:"));
177
178r.BeginNumberedBullet(1, 100, 60);
179r.Newline();
180
181r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later."));
182r.EndNumberedBullet();
183
184r.BeginNumberedBullet(2, 100, 60);
185r.Newline();
186
187r.WriteText(wxT("This is my second item."));
188r.EndNumberedBullet();
189
190r.Newline();
191
192r.WriteText(wxT("The following paragraph is right-indented:"));
193
194r.BeginRightIndent(200);
195r.Newline();
196
197r.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."));
198r.EndRightIndent();
199
200r.Newline();
201
202wxArrayInt tabs;
203tabs.Add(400);
204tabs.Add(600);
205tabs.Add(800);
206tabs.Add(1000);
207wxTextAttr attr;
208attr.SetFlags(wxTEXT_ATTR_TABS);
209attr.SetTabs(tabs);
210r.SetDefaultStyle(attr);
211
212r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab"));
213
214r.Newline();
215r.WriteText(wxT("Other notable features of wxRichTextCtrl include:"));
216
217r.BeginSymbolBullet(wxT('*'), 100, 60);
218r.Newline();
219r.WriteText(wxT("Compatibility with wxTextCtrl API"));
220r.EndSymbolBullet();
221
222r.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!"));
223
224r.EndSuppressUndo();
225@endcode
226
227
228@section overview_richtextctrl_starting Starting to Use wxRichTextCtrl
229
230You need to include @c @<wx/richtext/richtextctrl.h@> in your source, and link
231with the appropriate wxWidgets library with @c richtext suffix. Put the rich
232text library first in your link line to avoid unresolved symbols.
233
234Then you can create a wxRichTextCtrl, with the wxWANT_CHARS style if you want
235tabs to be processed by the control rather than being used for navigation
236between controls.
237
238
239@section overview_richtextctrl_styles Text Styles
240
71185527
JS
241Styling attributes are represented by wxTextAttr, or for more control over
242attributes such as margins and size, the derived class wxRichTextAttr.
07fa8f78
BP
243
244When setting a style, the flags of the attribute object determine which
245attributes are applied. When querying a style, the passed flags are ignored
246except (optionally) to determine whether attributes should be retrieved from
247character content or from the paragraph object.
248
249wxRichTextCtrl takes a layered approach to styles, so that different parts of
250the content may be responsible for contributing different attributes to the
251final style you see on the screen.
252
253There are four main notions of style within a control:
254
255@li <b>Basic style</b>: The fundamental style of a control, onto which any
256 other styles are layered. It provides default attributes, and changing the
257 basic style may immediately change the look of the content depending on
258 what other styles the content uses. Calling wxRichTextCtrl::SetFont changes
259 the font for the basic style. The basic style is set with
260 wxRichTextCtrl::SetBasicStyle.
261@li <b>Paragraph style</b>: Each paragraph has attributes that are set
262 independently from other paragraphs and independently from the content
263 within the paragraph. Normally, these attributes are paragraph-related,
264 such as alignment and indentation, but it is possible to set character
265 attributes too. The paragraph style can be set independently of its content
266 by passing wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY to
267 wxRichTextCtrl::SetStyleEx.
268@li <b>Character style</b>: Characters within each paragraph can have
269 attributes. A single character, or a run of characters, can have a
270 particular set of attributes. The character style can be with
271 wxRichTextCtrl::SetStyle or wxRichTextCtrl::SetStyleEx.
272@li <b>Default style</b>: This is the 'current' style that determines the style
273 of content that is subsequently typed, pasted or programmatically inserted.
274 The default style is set with wxRichTextCtrl::SetDefaultStyle.
275
276What you see on the screen is the dynamically @e combined style, found by
277merging the first three of the above style types (the fourth is only a guide
278for future content insertion and therefore does not affect the currently
279displayed content).
280
281To make all this more concrete, here are examples of where you might set these
282different styles:
283
284@li You might set the <em>basic style</em> to have a Times Roman font in 12
285 point, left-aligned, with two millimetres of spacing after each paragraph.
286@li You might set the <em>paragraph style</em> (for one particular paragraph)
287 to be centred.
288@li You might set the <em>character style</em> of one particular word to bold.
289@li You might set the <em>default style</em> to be underlined, for subsequent
290 inserted text.
291
292Naturally you can do any of these things either using your own UI, or
293programmatically.
294
295The basic wxTextCtrl doesn't make the same distinctions as wxRichTextCtrl
296regarding attribute storage. So we need finer control when setting and
297retrieving attributes. wxRichTextCtrl::SetStyleEx takes a @e flags parameter:
298
299@li wxRICHTEXT_SETSTYLE_OPTIMIZE specifies that the style should be changed
300 only if the combined attributes are different from the attributes for the
301 current object. This is important when applying styling that has been
302 edited by the user, because he has just edited the @e combined (visible)
303 style, and wxRichTextCtrl wants to leave unchanged attributes associated
304 with their original objects instead of applying them to both paragraph and
305 content objects.
306@li wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY specifies that only paragraph objects
307 within the given range should take on the attributes.
308@li wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects
309 (text or images) within the given range should take on the attributes.
310@li wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be
311 undoable.
312
313It's great to be able to change arbitrary attributes in a wxRichTextCtrl, but
314it can be unwieldy for the user or programmer to set attributes separately.
315Word processors have collections of styles that you can tailor or use as-is,
316and this means that you can set a heading with one click instead of marking
317text in bold, specifying a large font size, and applying a certain paragraph
318spacing and alignment for every such heading. Similarly, wxWidgets provides a
319class called wxRichTextStyleSheet which manages style definitions
320(wxRichTextParagraphStyleDefinition, wxRichTextListStyleDefinition and
321wxRichTextCharacterStyleDefinition). Once you have added definitions to a style
322sheet and associated it with a wxRichTextCtrl, you can apply a named definition
323to a range of text. The classes wxRichTextStyleComboCtrl and
324wxRichTextStyleListBox can be used to present the user with a list of styles in
325a sheet, and apply them to the selected text.
326
327You can reapply a style sheet to the contents of the control, by calling
328wxRichTextCtrl::ApplyStyleSheet. This is useful if the style definitions have
329changed, and you want the content to reflect this. It relies on the fact that
330when you apply a named style, the style definition name is recorded in the
331content. So ApplyStyleSheet works by finding the paragraph attributes with
332style names and re-applying the definition's attributes to the paragraph.
333Currently, this works with paragraph and list style definitions only.
334
335
336@section overview_richtextctrl_dialogs Included Dialogs
337
338wxRichTextCtrl comes with standard dialogs to make it easier to implement text
339editing functionality.
340
341wxRichTextFormattingDialog can be used for character or paragraph formatting,
342or a combination of both. It's a wxPropertySheetDialog with the following
71185527
JS
343available tabs: Font, Indents @& Spacing, Tabs, Bullets, Style, Borders,
344Margins, Background, Size, and List Style.
07fa8f78
BP
345You can select which pages will be shown by supplying flags to the dialog
346constructor. In a character formatting dialog, typically only the Font page
347will be shown. In a paragraph formatting dialog, you'll show the Indents @&
348Spacing, Tabs and Bullets pages. The Style tab is useful when editing a style
349definition.
350
351You can customize this dialog by providing your own
352wxRichTextFormattingDialogFactory object, which tells the formatting dialog how
353many pages are supported, what their identifiers are, and how to creates the
354pages.
355
356wxRichTextStyleOrganiserDialog is a multi-purpose dialog that can be used for
357managing style definitions, browsing styles and applying them, or selecting
358list styles with a renumber option. See the sample for usage - it is used for
359the "Manage Styles" and "Bullets and Numbering" menu commands.
360
361wxSymbolPickerDialog lets the user insert a symbol from a specified font. It
362has no wxRichTextCtrl dependencies besides being included in the rich text
363library.
364
365
366@section overview_richtextctrl_impl How wxRichTextCtrl is Implemented
367
368Data representation is handled by wxRichTextBuffer, and a wxRichTextCtrl always
369has one such buffer.
370
371The content is represented by a hierarchy of objects, all derived from
372wxRichTextObject. An object might be an image, a fragment of text, a paragraph,
71185527 373or a further composite object. Objects store a wxRichTextAttr containing style information; a
07fa8f78
BP
374paragraph object can contain both paragraph and character information, but
375content objects such as text can only store character information. The final
376style displayed in the control or in a printout is a combination of base style,
377paragraph style and content (character) style.
378
379The top of the hierarchy is the buffer, a kind of wxRichTextParagraphLayoutBox,
380containing further wxRichTextParagraph objects, each of which can include text,
381images and potentially other types of object.
382
383Each object maintains a range (start and end position) measured from the start
384of the main parent object.
385
386When Layout is called on an object, it is given a size which the object must
387limit itself to, or one or more flexible directions (vertical or horizontal).
388So, for example, a centred paragraph is given the page width to play with
389(minus any margins), but can extend indefinitely in the vertical direction.
390The implementation of Layout caches the calculated size and position.
391
392When the buffer is modified, a range is invalidated (marked as requiring
393layout), so that only the minimum amount of layout is performed.
394
395A paragraph of pure text with the same style contains just one further object,
396a wxRichTextPlainText object. When styling is applied to part of this object,
397the object is decomposed into separate objects, one object for each different
398character style. So each object within a paragraph always has just one
399wxTextAttr object to denote its character style. Of course, this can lead to
400fragmentation after a lot of edit operations, potentially leading to several
401objects with the same style where just one would do. So a Defragment function
402is called when updating the control's display, to ensure that the minimum
403number of objects is used.
404
831e1028 405
71185527
JS
406@section overview_richtextctrl_nested_object Nested Objects
407
831e1028
BP
408wxRichTextCtrl supports nested objects such as text boxes and tables. To
409achieve compatibility with the existing API, there is the concept of @e object
410@e focus. When the user clicks on a nested text box, the object focus is set to
411that container object so all keyboard input and API functions apply to that
412container. The application can change the focus using
413wxRichTextCtrl::SetObjectFocus. Call this function with a @c null parameter to
414set the focus back to the top-level object.
71185527
JS
415
416An event will be sent to the control when the focus changes.
417
831e1028
BP
418When the user clicks on the control, wxRichTextCtrl determines which container
419to set as the current object focus by calling the found container's overrided
420wxRichTextObject::AcceptsFocus function. For example, although a table is a
421container, it must not itself be the object focus because there is no text
422editing at the table level. Instead, a cell within the table must accept the
423focus.
71185527
JS
424
425Since with nested objects it is not possible to represent a section with merely
426a start position and an end position, the class wxRichTextSelection is provided
831e1028
BP
427which stores multiple ranges (for non-contiguous selections such as table
428cells) and a pointer to the container object in question. You can pass
429wxRichTextSelection to wxRichTextCtrl::SetSelection or get an instance of it
430from wxRichTextCtrl::GetSelection.
431
432When selecting multiple objects, such as cell tables, the wxRichTextCtrl
433dragging handler code calls the function
434wxRichTextObject::HandlesChildSelections to determine whether the children can
435be individual selections. Currently only table cells can be multiply-selected
71185527
JS
436in this way.
437
71185527 438
831e1028 439@section overview_richtextctrl_context_menus Context Menus and Property Dialogs
71185527 440
831e1028
BP
441There are three ways you can make use of context menus: you can let
442wxRichTextCtrl handle everything and provide a basic menu; you can set your own
443context menu using wxRichTextCtrl::SetContextMenu but let wxRichTextCtrl handle
444showing it and adding property items; or you can override the default context
445menu behaviour by adding a context menu event handler to your class in the
446normal way.
71185527 447
831e1028
BP
448If you right-click over a text box in cell in a table, you may want to edit the
449properties of one of these objects - but which properties will you be editing?
450
451Well, the default behaviour allows up to three property-editing menu items
452simultaneously - for the object clicked on, the container of that object, and
453the container's parent (depending on whether any of these objects return @true
454from their wxRichTextObject::CanEditProperties functions). If you supply a
455context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1
456identifier, so that wxRichTextCtrl can find the position to add command items.
457The object should tell the control what label to use by returning a string from
458wxRichTextObject::GetPropertiesMenuLabel.
459
460Since there may be several property-editing commands showing, it is recommended
461that you don't include the word Properties - just the name of the object, such
462as Text Box or Table.
71185527 463
07fa8f78
BP
464
465@section overview_richtextctrl_roadmap Development Roadmap
466
467@subsection overview_richtextctrl_roadmap_bugs Bugs
468
469This is an incomplete list of bugs.
470
471@li Moving the caret up at the beginning of a line sometimes incorrectly
472 positions the caret.
473@li As the selection is expanded, the text jumps slightly due to kerning
474 differences between drawing a single text string versus drawing several
475 fragments separately. This could be improved by using
476 wxDC::GetPartialTextExtents to calculate exactly where the separate
477 fragments should be drawn. Note that this problem also applies to
478 separation of text fragments due to difference in their attributes.
479
480@subsection overview_richtextctrl_roadmap_features Features
481
482This is a list of some of the features that have yet to be implemented. Help
483with them will be appreciated.
484
71185527
JS
485@li support for composite objects in some functions where it's not yet implemented, for example ApplyStyleSheet
486@li Table API enhancements and dialogs; improved table layout especially row spans and fitting
487@li Conversion from HTML, and a rewrite of the HTML output handler that includes CSS,
488tables, text boxes, and floating images, in addition to a simplified-HTML mode for wxHTML compatibility
07fa8f78 489@li Open Office input and output
71185527 490@li RTF input and output
07fa8f78
BP
491@li A ruler control
492@li Standard editing toolbars
07fa8f78 493@li Bitmap bullets
07fa8f78 494@li Justified text, in print/preview at least
71185527 495@li scaling: either everything scaled, or rendering using a custom reference point size and an optional dimension scale
07fa8f78
BP
496
497There are also things that could be done to take advantage of the underlying
498text capabilities of the platform; higher-level text formatting APIs are
499available on some platforms, such as Mac OS X, and some of translation from
500high level to low level wxDC API is unnecessary. However this would require
501additions to the wxWidgets API.
502
503*/