X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1f65137f8de90aba96242d5e44b00dfd0efa4b67..19f6bff4484b97ef036a793820eb30c0a6df92b5:/docs/latex/wx/richtextoverview.tex diff --git a/docs/latex/wx/richtextoverview.tex b/docs/latex/wx/richtextoverview.tex index 481319eecb..cb7e946f75 100644 --- a/docs/latex/wx/richtextoverview.tex +++ b/docs/latex/wx/richtextoverview.tex @@ -1,26 +1,33 @@ \section{wxRichTextCtrl overview}\label{wxrichtextctrloverview} -Classes: \helpref{wxRichTextCtrl}{wxrichtextctrl}, \helpref{wxRichTextBuffer}{wxrichtextbuffer}, -\helpref{wxRichTextAttr}{wxrichtextattr}, \helpref{wxTextAttrEx}{wxtextattrex}, -\helpref{wxRichTextCharacterStyleDefinition}{wxrichtextcharacterstyledefinition}, +{\bf Major classes:} \helpref{wxRichTextCtrl}{wxrichtextctrl}, \helpref{wxRichTextBuffer}{wxrichtextbuffer}, \helpref{wxRichTextEvent}{wxrichtextevent} + +{\bf Helper classes:} \helpref{wxRichTextAttr}{wxrichtextattr}, \helpref{wxTextAttrEx}{wxtextattrex}, +\helpref{wxRichTextRange}{wxrichtextrange} + +{\bf File handler classes:} \helpref{wxRichTextFileHandler}{wxrichtextfilehandler}, \helpref{wxRichTextHTMLHandler}{wxrichtexthtmlhandler}, +\helpref{wxRichTextXMLHandler}{wxrichtextxmlhandler} + +{\bf Style classes:} \helpref{wxRichTextCharacterStyleDefinition}{wxrichtextcharacterstyledefinition}, \helpref{wxRichTextParagraphStyleDefinition}{wxrichtextparagraphstyledefinition}, \helpref{wxRichTextListStyleDefinition}{wxrichtextliststyledefinition}, -\helpref{wxRichTextStyleSheet}{wxrichtextstylesheet}, -\helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}, +\helpref{wxRichTextStyleSheet}{wxrichtextstylesheet} + +{\bf Additional controls:} \helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}, \helpref{wxRichTextStyleListBox}{wxrichtextstylelistbox}, -\helpref{wxRichTextStyleListCtrl}{wxrichtextstylelistctrl}, -\helpref{wxRichTextEvent}{wxrichtextevent}, \helpref{wxRichTextRange}{wxrichtextrange}, -\helpref{wxRichTextFileHandler}{wxrichtextfilehandler}, \helpref{wxRichTextHTMLHandler}{wxrichtexthtmlhandler}, -\helpref{wxRichTextXMLHandler}{wxrichtextxmlhandler}, -\helpref{wxRichTextFormattingDialog}{wxrichtextformattingdialog}, -\helpref{wxRichTextPrinting}{wxrichtextprinting}, +\helpref{wxRichTextStyleListCtrl}{wxrichtextstylelistctrl} + +{\bf Printing classes:} \helpref{wxRichTextPrinting}{wxrichtextprinting}, \helpref{wxRichTextPrintout}{wxrichtextprintout}, -\helpref{wxRichTextHeaderFooterData}{wxrichtextheaderfooterdata}, +\helpref{wxRichTextHeaderFooterData}{wxrichtextheaderfooterdata} + +{\bf Dialog classes:} \helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog}, +\helpref{wxRichTextFormattingDialog}{wxrichtextformattingdialog}, \helpref{wxSymbolPickerDialog}{wxsymbolpickerdialog} wxRichTextCtrl provides a generic implementation of a rich text editor that can handle different character -styles, paragraph formatting, and images. It's aimed at editing 'natural' language text - if you need an editor that supports code editing, -wxStyledTextCtrl is a better choice. +styles, paragraph formatting, and images. It's aimed at editing 'natural' language text - if you need an editor +that supports code editing, wxStyledTextCtrl is a better choice. Despite its name, it cannot currently read or write RTF (rich text format) files. Instead, it uses its own XML format, and can also read and write plain text. In future we expect to provide @@ -35,19 +42,25 @@ the style information in a wxTextCtrl, whereas this information is readily available in wxRichTextCtrl. Since it's written in pure wxWidgets, any customizations you make to wxRichTextCtrl will be reflected on all platforms. -There are of course a few disadvantages to using wxRichTextCtrl. It is not native, +wxRichTextCtrl supports basic printing via the easy-to-use \helpref{wxRichTextPrinting}{wxrichtextprinting} class. +Creating applications with simple word processing features is simplified with the inclusion of\rtfsp +\helpref{wxRichTextFormattingDialog}{wxrichtextformattingdialog}, a tabbed dialog allowing +interactive tailoring of paragraph and character styling. Also provided is the multi-purpose dialog\rtfsp +\helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog} that can be used for +managing style definitions, browsing styles and applying them, or selecting list styles with +a renumber option. + +There are a few disadvantages to using wxRichTextCtrl. It is not native, so does not behave exactly as a native wxTextCtrl, although common editing conventions are followed. Users may miss the built-in spelling correction on Mac OS X, or any special character input that may be provided by the native control. It would also -be a bad choice if intended users rely on screen readers that would be unhappy +be a poor choice if intended users rely on screen readers that would be not work well with non-native text input implementation. You might mitigate this by providing the choice between wxTextCtrl and wxRichTextCtrl, with fewer features in the former case. -wxRichTextCtrl does not yet support printing directly, but content can be converted -to HTML which can then be used with \helpref{wxHtmlEasyPrinting}{wxhtmleasyprinting}. - -The following screenshot shows the wxRichTextCtrl sample in action: +A good way to understand wxRichTextCtrl's capabilities is to compile and run the +sample, {\tt samples/richtext}, and browse the code. The following screenshot shows the sample in action: $$\image{8cm;0cm}{richtextctrl.gif}$$ @@ -207,8 +220,8 @@ be processed by the control rather than being used for navigation between contro \subsubsection{wxRichTextCtrl and styles} -Styling attributes are represented by one of three classes: \helpref{wxTextAttr}{wxtextattr}, \helpref{wxTextAttrEx}{wxtextattrex} and \helpref{wxRichTextAttr}{wxrichtextattr}. -wxTextAttr is shared across all controls that are derived from wxTextCtrl and +Styling attributes are represented by three classes: \helpref{wxTextAttr}{wxtextattr}, \helpref{wxTextAttrEx}{wxtextattrex} and \helpref{wxRichTextAttr}{wxrichtextattr}. +wxTextAttr is shared across all controls that are derived from wxTextCtrlBase and can store basic character and paragraph attributes. wxTextAttrEx derives from wxTextAttr and adds some further attributes that are only supported by wxRichTextCtrl. Finally, wxRichTextAttr is a more efficient version @@ -309,7 +322,7 @@ text editing functionality. \helpref{wxRichTextFormattingDialog}{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, and Style. +with the following available tabs: Font, Indents \& Spacing, Tabs, Bullets, Style, 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 @@ -319,6 +332,11 @@ You can customize this dialog by providing your own wxRichTextFormattingDialogFa object, which tells the formatting dialog how many pages are supported, what their identifiers are, and how to creates the pages. +\helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog} is a multi-purpose dialog +that can be used for managing style definitions, browsing styles and applying them, or selecting list styles with +a renumber option. See the sample for usage - it is used for the "Manage Styles" and "Bullets and Numbering" +menu commands. + \helpref{wxSymbolPickerDialog}{wxsymbolpickerdialog} lets the user insert a symbol from a specified font. It has no wxRichTextCtrl dependencies besides being included in the rich text library. @@ -330,17 +348,18 @@ always 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 wxRichTextAttr containing style information; -although it contains both paragraph formatting and character style, the -paragraph style information is ignored by children of a paragraph (only -character style is relevant to these objects). +or a whole buffer. Objects store a wxTextAttrEx containing style information; +a paragraph object can contain both paragraph and character information, but +content objects such as text can only store character information. The final +style displayed in the control or in a printout is a combination of base +style, paragraph style and content (character) style. The top of the hierarchy is the buffer, a kind of wxRichTextParagraphLayoutBox. containing further wxRichTextParagraph objects, each of which can include text, images and potentially other types of object. Each object maintains a range (start and end position) measured -from the start of the main parent box. +from the start of the main parent object. When Layout is called on an object, it is given a size which the object must limit itself to, or one or more flexible directions (vertical @@ -356,7 +375,7 @@ A paragraph of pure text with the same style contains just one further object, a wxRichTextPlainText object. When styling is applied to part of this object, the object is decomposed into separate objects, one object for each different character style. So each object within a paragraph always has -just one wxRichTextAttr object to denote its character style. Of course, this can +just one wxTextAttrEx 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