X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/de2b67e6996decc38233075cb803cce0cfe80168..7dbb435338bce3b3747dcef615e13f80fbff5389:/docs/doxygen/overviews/richtextctrl.h diff --git a/docs/doxygen/overviews/richtextctrl.h b/docs/doxygen/overviews/richtextctrl.h index c48d0578c3..43cd1436a6 100644 --- a/docs/doxygen/overviews/richtextctrl.h +++ b/docs/doxygen/overviews/richtextctrl.h @@ -2,54 +2,14 @@ // Name: richtextctrl.h // Purpose: topic overview // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! +/** @page overview_richtextctrl wxRichTextCtrl Overview -@li @ref overview_richtextctrl_classes -@li @ref overview_richtextctrl_intro -@li @ref overview_richtextctrl_example -@li @ref overview_richtextctrl_starting -@li @ref overview_richtextctrl_styles -@li @ref overview_richtextctrl_dialogs -@li @ref overview_richtextctrl_impl -@li @ref overview_richtextctrl_roadmap - - -
- - -@section overview_richtextctrl_classes Related Classes - -Major classes: -wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent - -Helper classes: -wxTextAttr, wxRichTextRange - -File handler classes: -wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler - -Style classes: -wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition, -wxRichTextListStyleDefinition, wxRichTextStyleSheet - -Additional controls: -wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl - -Printing classes: -wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData - -Dialog classes: -wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog, -wxSymbolPickerDialog - - -@section overview_richtextctrl_intro Introduction +@tableofcontents wxRichTextCtrl provides a generic implementation of a rich text editor that can handle different character styles, paragraph formatting, and images. It's aimed @@ -58,9 +18,9 @@ editing, wxStyledTextCtrl is a better choice. Despite its name, it cannot currently read or write RTF (rich text format) files. Instead, it uses its own XML format, and can also read and write plain -text. In future we expect to provide RTF file capabilities. Custom file formats -can be supported by creating additional file handlers and registering them with -the control. +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. wxRichTextCtrl is largely compatible with the wxTextCtrl API, but extends it where necessary. The control can be used where the native rich text @@ -92,6 +52,33 @@ A good way to understand wxRichTextCtrl's capabilities is to compile and run the sample, @c samples/richtext, and browse the code. + +@section overview_richtextctrl_classes Related Classes + +Major classes: +wxRichTextCtrl, wxRichTextBuffer, wxRichTextEvent + +Helper classes: +wxTextAttr, wxRichTextRange + +File handler classes: +wxRichTextFileHandler, wxRichTextHTMLHandler, wxRichTextXMLHandler + +Style classes: +wxRichTextCharacterStyleDefinition, wxRichTextParagraphStyleDefinition, +wxRichTextListStyleDefinition, wxRichTextStyleSheet + +Additional controls: +wxRichTextStyleComboCtrl, wxRichTextStyleListBox, wxRichTextStyleListCtrl + +Printing classes: +wxRichTextPrinting, wxRichTextPrintout, wxRichTextHeaderFooterData + +Dialog classes: +wxRichTextStyleOrganiserDialog, wxRichTextFormattingDialog, +wxSymbolPickerDialog + + @section overview_richtextctrl_example Code Example The following code is an example taken from the sample, and adds text and @@ -250,7 +237,8 @@ between controls. @section overview_richtextctrl_styles Text Styles -Styling attributes are represented by wxTextAttr. +Styling attributes are represented by wxTextAttr, or for more control over +attributes such as margins and size, the derived class wxRichTextAttr. When setting a style, the flags of the attribute object determine which attributes are applied. When querying a style, the passed flags are ignored @@ -351,7 +339,8 @@ editing functionality. wxRichTextFormattingDialog can be used for character or paragraph formatting, or a combination of both. It's a wxPropertySheetDialog with the following -available tabs: Font, Indents @& Spacing, Tabs, Bullets, Style, and List Style. +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 @& @@ -380,7 +369,7 @@ has one such buffer. The content is represented by a hierarchy of objects, all derived from wxRichTextObject. An object might be an image, a fragment of text, a paragraph, -or a whole buffer. Objects store a wxTextAttr containing style information; a +or a further composite object. Objects store a wxRichTextAttr 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, @@ -413,6 +402,65 @@ is called when updating the control's display, to ensure that the minimum number of objects is used. +@section overview_richtextctrl_nested_object Nested Objects + +wxRichTextCtrl supports nested objects such as text boxes and tables. To +achieve compatibility with the existing API, there is the concept of @e object +@e focus. 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 @c null parameter to +set the focus back to the top-level object. + +An event will be sent to the control when the focus changes. + +When the user clicks on the control, wxRichTextCtrl determines which container +to set as the current object focus by calling the found container's overrided +wxRichTextObject::AcceptsFocus 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. + +Since with nested objects it is not possible to represent a section with merely +a start position and an end position, the class wxRichTextSelection 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 +wxRichTextSelection to wxRichTextCtrl::SetSelection or get an instance of it +from wxRichTextCtrl::GetSelection. + +When selecting multiple objects, such as cell tables, the wxRichTextCtrl +dragging handler code calls the function +wxRichTextObject::HandlesChildSelections to determine whether the children can +be individual selections. Currently only table cells can be multiply-selected +in this way. + + +@section overview_richtextctrl_context_menus Context Menus and Property Dialogs + +There are three ways you can make use of context menus: you can let +wxRichTextCtrl handle everything and provide a basic menu; you can set your own +context menu using wxRichTextCtrl::SetContextMenu but let wxRichTextCtrl 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. + +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? + +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 @true +from their wxRichTextObject::CanEditProperties functions). If you supply a +context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1 +identifier, so that wxRichTextCtrl can find the position to add command items. +The object should tell the control what label to use by returning a string from +wxRichTextObject::GetPropertiesMenuLabel. + +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. + + @section overview_richtextctrl_roadmap Development Roadmap @subsection overview_richtextctrl_roadmap_bugs Bugs @@ -433,17 +481,17 @@ This is an incomplete list of bugs. This is a list of some of the features that have yet to be implemented. Help with them will be appreciated. -@li RTF input and output -@li Conversion from HTML +@li support for composite objects in some functions where it's not yet implemented, for example ApplyStyleSheet +@li Table API enhancements and dialogs; improved table layout especially row spans and fitting +@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 Open Office input and output -@li Floating images, with content wrapping around them +@li RTF input and output @li A ruler control @li Standard editing toolbars -@li Tables @li Bitmap bullets -@li Borders -@li Text frames @li Justified text, in print/preview at least +@li scaling: either everything scaled, or rendering using a custom reference point size and an optional dimension scale 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 @@ -452,4 +500,3 @@ high level to low level wxDC API is unnecessary. However this would require additions to the wxWidgets API. */ -