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