Commit correct docs for wxwxScopedPtr

[wxWidgets.git] / docs / latex / wx / richtextoverview.tex

diff --git a/docs/latex/wx/richtextoverview.tex b/docs/latex/wx/richtextoverview.tex
index e7ca1e2d76c9d7f0500d119a054488635361b178..8d88108db87851794a9fe11f740184620ea96fad 100644 (file)
--- a/docs/latex/wx/richtextoverview.tex
+++ b/docs/latex/wx/richtextoverview.tex
@@ -1,25 +1,32 @@
 \section{wxRichTextCtrl overview}\label{wxrichtextctrloverview}
 
 \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{wxTextAttr}{wxtextattr}, \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{wxRichTextParagraphStyleDefinition}{wxrichtextparagraphstyledefinition}, 
 \helpref{wxRichTextListStyleDefinition}{wxrichtextliststyledefinition}, 

-\helpref{wxRichTextStyleSheet}{wxrichtextstylesheet}, 
-\helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}, 
+\helpref{wxRichTextStyleSheet}{wxrichtextstylesheet}
+
+{\bf Additional controls:} \helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}, 

 \helpref{wxRichTextStyleListBox}{wxrichtextstylelistbox}, 
 \helpref{wxRichTextStyleListBox}{wxrichtextstylelistbox}, 

-\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{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
 \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
 
 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


@@ -34,19 +41,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.
 
 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
 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.
 
 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}$$
 
 
 $$\image{8cm;0cm}{richtextctrl.gif}$$
 


@@ -56,7 +69,7 @@ The following code is taken from the sample, and adds text and styles to a rich
 
 {\small
 \begin{verbatim}
 
 {\small
 \begin{verbatim}

-    wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(200, 200), wxVSCROLL|wxHSCROLL|wxNO_BORDER|wxWANTS_CHARS);
+    wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(200, 200), wxVSCROLL|wxHSCROLL|wxBORDER_NONE|wxWANTS_CHARS);

 
     wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
     wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);
 
     wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
     wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);


@@ -172,7 +185,7 @@ The following code is taken from the sample, and adds text and styles to a rich
     tabs.Add(600);
     tabs.Add(800);
     tabs.Add(1000);
     tabs.Add(600);
     tabs.Add(800);
     tabs.Add(1000);

-    wxTextAttrEx attr;
+    wxTextAttr attr;

     attr.SetFlags(wxTEXT_ATTR_TABS);
     attr.SetTabs(tabs);
     r.SetDefaultStyle(attr);
     attr.SetFlags(wxTEXT_ATTR_TABS);
     attr.SetTabs(tabs);
     r.SetDefaultStyle(attr);


@@ -206,14 +219,7 @@ be processed by the control rather than being used for navigation between contro
 
 \subsubsection{wxRichTextCtrl and styles}
 
 
 \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
-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
-of wxTextAttrEx that doesn't use a wxFont object and can be used to
-query styles more quickly. wxTextAttrEx and wxRichTextAttr are largely
-interchangeable and have suitable conversion operators between them.
+Styling attributes are represented by \helpref{wxTextAttr}{wxtextattr}.

 
 When setting a style, the flags of the attribute object determine which
 attributes are applied. When querying a style, the passed flags are ignored
 
 When setting a style, the flags of the attribute object determine which
 attributes are applied. When querying a style, the passed flags are ignored


@@ -308,7 +314,7 @@ text editing functionality.
 
 \helpref{wxRichTextFormattingDialog}{wxrichtextformattingdialog} can be used
 for character or paragraph formatting, or a combination of both. It's a wxPropertySheetDialog
 
 \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
 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


@@ -318,6 +324,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.
 
 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.
 \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.


@@ -329,17 +340,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,
 
 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 wxTextAttr 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
 
 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
 
 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


@@ -355,7 +367,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
 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 wxTextAttr 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
 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


@@ -373,11 +385,7 @@ caret.
 \item 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 wxDC::GetPartialTextExtents to calculate exactly where the separate fragments
 \item 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 wxDC::GetPartialTextExtents to calculate exactly where the separate fragments

-should be drawn.
-Alternatively, it might be possible to use the difference between the width of text from
-a to b+1, versus the width of the text from a to b added to the width of b to b+1.
-Note that this problem also applies to separation of text fragments due to difference in their attributes.
-\item Selection doesn't work properly for text that contains tabs.
+should be drawn. Note that this problem also applies to separation of text fragments due to difference in their attributes.

 \end{itemize}
 
 \wxheading{Features}
 \end{itemize}
 
 \wxheading{Features}


@@ -386,6 +394,8 @@ This is a list of some of the features that have yet to be implemented. Help wit
 
 \begin{itemize}\itemsep=0pt
 \item RTF input and output
 
 \begin{itemize}\itemsep=0pt
 \item RTF input and output

+\item Conversion from HTML
+\item Open Office input and output

 \item Floating images, with content wrapping around them
 \item A ruler control
 \item Standard editing toolbars
 \item Floating images, with content wrapping around them
 \item A ruler control
 \item Standard editing toolbars


@@ -393,6 +403,7 @@ This is a list of some of the features that have yet to be implemented. Help wit
 \item Bitmap bullets
 \item Borders
 \item Text frames
 \item Bitmap bullets
 \item Borders
 \item Text frames

+\item Justified text, in print/preview at least

 \end{itemize}
 
 There are also things that could be done to take advantage of the underlying text capabilities of the platform;
 \end{itemize}
 
 There are also things that could be done to take advantage of the underlying text capabilities of the platform;