Further wxRTC doc additions

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@43542 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -617,6 +617,7 @@ and paragraph formatting.
 \twocolitem{\helpref{wxRichTextStyleSheet}{wxrichtextstylesheet}}{A set of style definitions.}
 \twocolitem{\helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}}{A drop-down control for applying styles.}
 \twocolitem{\helpref{wxRichTextStyleListBox}{wxrichtextstylelistbox}}{A listbox for applying styles.}
+\twocolitem{\helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog}}{A dialog that can be used for managing or browsing styles.}
 \twocolitem{\helpref{wxRichTextEvent}{wxrichtextevent}}{A rich text event.}
 \twocolitem{\helpref{wxRichTextRange}{wxrichtextrange}}{Specification for ranges in a rich text control or buffer.}
 \twocolitem{\helpref{wxRichTextFileHandler}{wxrichtextfilehandler}}{File handler base class.}

docs/latex/wx/classes.tex

@@ -330,6 +330,7 @@
 \input richtextrange.tex
 \input richtextstyledefinition.tex
 \input richtextstylelistbox.tex
+\input richtextstyleorganiserdialog.tex
 \input richtextstylesheet.tex
 \input richtextxmlhandler.tex
 

docs/latex/wx/richtextbuffer.tex

@@ -311,7 +311,7 @@ Copy the given range to the clipboard.
 
 \membersection{wxRichTextBuffer::DeleteRangeWithUndo}\label{wxrichtextbufferdeleterangewithundo}
 
-\func{bool}{DeleteRangeWithUndo}{\param{const wxRichTextRange\& }{range}, \param{long }{initialCaretPosition}, \param{long }{newCaretPositon}, \param{wxRichTextCtrl* }{ctrl}}
+\func{bool}{DeleteRangeWithUndo}{\param{const wxRichTextRange\& }{range}, \param{wxRichTextCtrl* }{ctrl}}
 
 Submits a command to delete the given range.
 

docs/latex/wx/richtextctrl.tex

@@ -360,6 +360,12 @@ Creates the underlying window.
 Copies the selected content (if any) to the clipboard and deletes the selection.
 This is undoable.
 
+\membersection{wxRichTextCtrl::Delete}\label{wxrichtextctrldelete}
+
+\func{bool}{Delete}{\param{const wxRichTextRange\&}{ range}}
+
+Deletes the content within the given range.
+
 \membersection{wxRichTextCtrl::DeleteSelectedContent}\label{wxrichtextctrldeleteselectedcontent}
 
 \func{bool}{DeleteSelectedContent}{\param{long* }{newPos = NULL}}
@@ -689,6 +695,15 @@ This function gets the combined style - that is, the style you see on the screen
 of combining base style, paragraph style and character style attributes. To get the character
 or paragraph style alone, use \helpref{GetUncombinedStyle}{wxrichtextctrlgetuncombinedstyle}.
 
+\membersection{wxRichTextCtrl::GetStyleForRange}\label{wxrichtextctrlgetstyleforrange}
+
+\func{bool}{GetStyleForRange}{\param{const wxRichTextRange\& }{range}, \param{wxRichTextAttr\& }{style}}
+
+\func{bool}{GetStyleForRange}{\param{const wxRichTextRange\& }{range}, \param{wxTextAttrEx\& }{style}}
+
+Gets the attributes common to the specified range. Attributes that differ in value within the range will
+not be included in {\it style}'s flags.
+
 \membersection{wxRichTextCtrl::GetStyleSheet}\label{wxrichtextctrlgetstylesheet}
 
 \constfunc{wxRichTextStyleSheet*}{GetStyleSheet}{\void}
@@ -898,6 +913,14 @@ Lays out the buffer, which must be done before certain operations, such as
 setting the caret position. This function should not normally be required by the
 application.
 
+\membersection{wxRichTextCtrl::LineBreak}\label{wxrichtextctrllinebreak}
+
+\func{bool}{LineBreak}{\void}
+
+Inserts a line break at the current insertion point. A line break forces wrapping within a paragraph, and
+can be introduced by using this function, by appending the wxChar value {\bf wxRichTextLineBreakChar} to text content,
+or by typing Shift-Return.
+
 \membersection{wxRichTextCtrl::LoadFile}\label{wxrichtextctrlloadfile}
 
 \func{bool}{LoadFile}{\param{const wxString\& }{file}, \param{int }{type = wxRICHTEXT\_TYPE\_ANY}}
@@ -999,7 +1022,7 @@ Moves up.
 
 \func{bool}{Newline}{\void}
 
-Insert a newline (actually paragraph) at the current insertion point.
+Inserts a new paragraph at the current insertion point. See also \helpref{wxRichTextCtrl::LineBreak}{wxrichtextctrllinebreak}.
 
 \membersection{wxRichTextCtrl::NumberList}\label{wxrichtextctrlnumberlist}
 

docs/latex/wx/richtextoverview.tex

@@ -9,6 +9,7 @@ Classes: \helpref{wxRichTextCtrl}{wxrichtextctrl}, \helpref{wxRichTextBuffer}{wx
 \helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl}, 
 \helpref{wxRichTextStyleListBox}{wxrichtextstylelistbox}, 
 \helpref{wxRichTextStyleListCtrl}{wxrichtextstylelistctrl}, 
+\helpref{wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialog}, 
 \helpref{wxRichTextEvent}{wxrichtextevent}, \helpref{wxRichTextRange}{wxrichtextrange}, 
 \helpref{wxRichTextFileHandler}{wxrichtextfilehandler}, \helpref{wxRichTextHTMLHandler}{wxrichtexthtmlhandler}, 
 \helpref{wxRichTextXMLHandler}{wxrichtextxmlhandler}, 
@@ -19,8 +20,8 @@ Classes: \helpref{wxRichTextCtrl}{wxrichtextctrl}, \helpref{wxRichTextBuffer}{wx
 \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,7 +36,15 @@ 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
@@ -44,10 +53,8 @@ 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}$$
 
@@ -309,7 +316,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 +326,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.

docs/latex/wx/richtextstyleorganiserdialog.tex

@@ -0,0 +1,139 @@
+\section{\class{wxRichTextStyleOrganiserDialog}}\label{wxrichtextstyleorganiserdialog}
+
+This class shows a style sheet and allows the user to edit, add and remove styles.
+It can also be used as a style browser, for example if the application is not
+using a permanent \helpref{wxRichTextStyleComboCtrl}{wxrichtextstylecomboctrl} or \helpref{wxRichTextStyleListCtrl}{wxrichtextstylelistctrl} to
+present styles.
+ 
+\wxheading{Derived from}
+
+\helpref{wxDialog}{wxdialog}
+
+\wxheading{Include files}
+
+<wx/richtext/richtextstyledlg.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxRichTextStyleOrganiserDialog::wxRichTextStyleOrganiserDialog}\label{wxrichtextstyleorganiserdialogwxrichtextstyleorganiserdialog}
+
+\func{}{wxRichTextStyleOrganiserDialog}{\param{int }{flags}, \param{wxRichTextStyleSheet* }{sheet}, \param{wxRichTextCtrl* }{ctrl}, \param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxString\& }{caption = \_("Style Organiser")}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX}}
+
+\func{}{wxRichTextStyleOrganiserDialog}{\void}
+
+Constructors.
+
+To create a dialog, pass a bitlist of {\it flags} (see below), a style sheet, a text control to apply a selected style to (or NULL), followed by the usual window parameters.
+
+To specify the operations available to the user, pass a combination of these values to {\it flags}:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_DELETE\_STYLES}}{Provides a button for deleting styles.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_CREATE\_STYLES}}{Provides buttons for creating styles.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_APPLY\_STYLES}}{Provides a button for applying the currently selected style to the selection.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_EDIT\_STYLES}}{Provides a button for editing styles.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_RENAME\_STYLES}}{Provides a button for renaming styles.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_OK\_CANCEL}}{Provides OK can Cancel buttons.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_RENUMBER}}{Provides a checkbox for specifying that the selection should be renumbered.}
+\end{twocollist}
+
+The following flags determine what will be displayed in the style list:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_SHOW\_CHARACTER}}{Displays character styles only.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_SHOW\_PARAGRAPH}}{Displays paragraph styles only.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_SHOW\_LIST}}{Displays list styles only.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_SHOW\_ALL}}{Displays all styles.}
+\end{twocollist}
+
+The following symbols define commonly-used combinations of flags:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_ORGANISE}}{Enable all style editing operations so the dialog behaves as a style organiser.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_BROWSE}}{Show a list of all styles and their previews, but only allow application of a style or
+cancellation of the dialog. This makes the dialog behave as a style browser.}
+\twocolitem{\windowstyle{wxRICHTEXT\_ORGANISER\_BROWSE\_NUMBERING}}{Enables only list style browsing, plus a control to specify renumbering. This
+allows the dialog to be used for applying list styles to the selection.}
+\end{twocollist}
+
+\membersection{wxRichTextStyleOrganiserDialog::ApplyStyle}\label{wxrichtextstyleorganiserdialogapplystyle}
+
+\func{bool}{ApplyStyle}{\param{wxRichTextCtrl* }{ctrl = NULL}}
+
+Applies the selected style to selection in the given control or the control passed to the constructor.
+
+\membersection{wxRichTextStyleOrganiserDialog::Create}\label{wxrichtextstyleorganiserdialogcreate}
+
+\func{bool}{Create}{\param{int }{flags}, \param{wxRichTextStyleSheet* }{sheet}, \param{wxRichTextCtrl* }{ctrl}, \param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxString\& }{caption = \_("Style Organiser")}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX}}
+
+Creates the dialog. See \membersection{wxRichTextStyleOrganiserDialog::wxRichTextStyleOrganiserDialog}{wxrichtextstyleorganiserdialogwxrichtextstyleorganiserdialog} for details.
+
+\membersection{wxRichTextStyleOrganiserDialog::GetFlags}\label{wxrichtextstyleorganiserdialoggetflags}
+
+\constfunc{int}{GetFlags}{\void}
+
+Returns the flags used to control the interface presented to the user.
+
+\membersection{wxRichTextStyleOrganiserDialog::GetRestartNumbering}\label{wxrichtextstyleorganiserdialoggetrestartnumbering}
+
+\constfunc{bool}{GetRestartNumbering}{\void}
+
+Returns \true if the user has opted to restart numbering.
+
+\membersection{wxRichTextStyleOrganiserDialog::GetRichTextCtrl}\label{wxrichtextstyleorganiserdialoggetrichtextctrl}
+
+\constfunc{wxRichTextCtrl*}{GetRichTextCtrl}{\void}
+
+Returns the associated rich text control (if any).
+
+\membersection{wxRichTextStyleOrganiserDialog::GetSelectedStyle}\label{wxrichtextstyleorganiserdialoggetselectedstyle}
+
+\constfunc{wxString}{GetSelectedStyle}{\void}
+
+Returns selected style name.
+
+\membersection{wxRichTextStyleOrganiserDialog::GetSelectedStyleDefinition}\label{wxrichtextstyleorganiserdialoggetselectedstyledefinition}
+
+\constfunc{wxRichTextStyleDefinition*}{GetSelectedStyleDefinition}{\void}
+
+Returns selected style definition.
+
+\membersection{wxRichTextStyleOrganiserDialog::GetStyleSheet}\label{wxrichtextstyleorganiserdialoggetstylesheet}
+
+\constfunc{wxRichTextStyleSheet*}{GetStyleSheet}{\void}
+
+Returns the associated style sheet.
+
+\membersection{wxRichTextStyleOrganiserDialog::SetFlags}\label{wxrichtextstyleorganiserdialogsetflags}
+
+\func{void}{SetFlags}{\param{int }{flags}}
+
+Sets the flags used to control the interface presented to the user.
+
+\membersection{wxRichTextStyleOrganiserDialog::SetRestartNumbering}\label{wxrichtextstyleorganiserdialogsetrestartnumbering}
+
+\func{void}{SetRestartNumbering}{\param{bool }{restartNumbering}}
+
+Checks or unchecks the restart numbering checkbox.
+
+\membersection{wxRichTextStyleOrganiserDialog::SetRichTextCtrl}\label{wxrichtextstyleorganiserdialogsetrichtextctrl}
+
+\func{void}{SetRichTextCtrl}{\param{wxRichTextCtrl* }{ctrl}}
+
+Sets the control to be associated with the dialog, for the purposes of applying a style to the selection.
+
+\membersection{wxRichTextStyleOrganiserDialog::SetShowToolTips}\label{wxrichtextstyleorganiserdialogsetshowtooltips}
+
+\func{void}{SetShowToolTips}{\param{bool }{show}}
+
+Determines whether tooltips will be shown.
+
+\membersection{wxRichTextStyleOrganiserDialog::SetStyleSheet}\label{wxrichtextstyleorganiserdialogsetstylesheet}
+
+\func{void}{SetStyleSheet}{\param{wxRichTextStyleSheet* }{sheet}}
+
+Sets the associated style sheet.
+