revised richtext headers

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

interface/wx/richtext/richtextbuffer.h

@@ -6,6 +6,130 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+
+/*!
+ * File types in wxRichText context.
+ */
+enum wxRichTextFileType
+{
+    wxRICHTEXT_TYPE_ANY = 0,
+    wxRICHTEXT_TYPE_TEXT,
+    wxRICHTEXT_TYPE_XML,
+    wxRICHTEXT_TYPE_HTML,
+    wxRICHTEXT_TYPE_RTF,
+    wxRICHTEXT_TYPE_PDF
+};
+
+/*!
+ * Flags determining the available space, passed to Layout
+ */
+
+#define wxRICHTEXT_FIXED_WIDTH      0x01
+#define wxRICHTEXT_FIXED_HEIGHT     0x02
+#define wxRICHTEXT_VARIABLE_WIDTH   0x04
+#define wxRICHTEXT_VARIABLE_HEIGHT  0x08
+
+// Only lay out the part of the buffer that lies within
+// the rect passed to Layout.
+#define wxRICHTEXT_LAYOUT_SPECIFIED_RECT 0x10
+
+/*!
+ * Flags to pass to Draw
+ */
+
+// Ignore paragraph cache optimization, e.g. for printing purposes
+// where one line may be drawn higher (on the next page) compared
+// with the previous line
+#define wxRICHTEXT_DRAW_IGNORE_CACHE    0x01
+
+/*!
+ * Flags returned from hit-testing
+ */
+enum wxRichTextHitTestFlags
+{
+    /// The point was not on this object
+    wxRICHTEXT_HITTEST_NONE =    0x01,
+
+    /// The point was before the position returned from HitTest
+    wxRICHTEXT_HITTEST_BEFORE =  0x02,
+
+    /// The point was after the position returned from HitTest
+    wxRICHTEXT_HITTEST_AFTER =   0x04,
+
+    /// The point was on the position returned from HitTest
+    wxRICHTEXT_HITTEST_ON =      0x08,
+
+    /// The point was on space outside content
+    wxRICHTEXT_HITTEST_OUTSIDE = 0x10
+};
+
+/*!
+ * Flags for GetRangeSize
+ */
+
+#define wxRICHTEXT_FORMATTED        0x01
+#define wxRICHTEXT_UNFORMATTED      0x02
+#define wxRICHTEXT_CACHE_SIZE       0x04
+#define wxRICHTEXT_HEIGHT_ONLY      0x08
+
+/*!
+ * Flags for SetStyle/SetListStyle
+ */
+
+#define wxRICHTEXT_SETSTYLE_NONE            0x00
+
+// Specifies that this operation should be undoable
+#define wxRICHTEXT_SETSTYLE_WITH_UNDO       0x01
+
+// Specifies that the style should not be applied if the
+// combined style at this point is already the style in question.
+#define wxRICHTEXT_SETSTYLE_OPTIMIZE        0x02
+
+// Specifies that the style should only be applied to paragraphs,
+// and not the content. This allows content styling to be
+// preserved independently from that of e.g. a named paragraph style.
+#define wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY 0x04
+
+// Specifies that the style should only be applied to characters,
+// and not the paragraph. This allows content styling to be
+// preserved independently from that of e.g. a named paragraph style.
+#define wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY 0x08
+
+// For SetListStyle only: specifies starting from the given number, otherwise
+// deduces number from existing attributes
+#define wxRICHTEXT_SETSTYLE_RENUMBER        0x10
+
+// For SetListStyle only: specifies the list level for all paragraphs, otherwise
+// the current indentation will be used
+#define wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL   0x20
+
+// Resets the existing style before applying the new style
+#define wxRICHTEXT_SETSTYLE_RESET           0x40
+
+// Removes the given style instead of applying it
+#define wxRICHTEXT_SETSTYLE_REMOVE          0x80
+
+/*!
+ * Flags for text insertion
+ */
+
+#define wxRICHTEXT_INSERT_NONE                              0x00
+#define wxRICHTEXT_INSERT_WITH_PREVIOUS_PARAGRAPH_STYLE     0x01
+#define wxRICHTEXT_INSERT_INTERACTIVE                       0x02
+
+// A special flag telling the buffer to keep the first paragraph style
+// as-is, when deleting a paragraph marker. In future we might pass a
+// flag to InsertFragment and DeleteRange to indicate the appropriate mode.
+#define wxTEXT_ATTR_KEEP_FIRST_PARA_STYLE   0x10000000
+
+/*!
+ * Default superscript/subscript font multiplication factor
+ */
+
+#define wxSCRIPT_MUL_FACTOR             1.5
+
+
 /**
     @class wxRichTextBuffer
 
@@ -16,16 +140,18 @@
 
     @see wxTextAttr, wxRichTextCtrl
 */
-class wxRichTextBuffer
+class wxRichTextBuffer : public wxRichTextParagraphLayoutBox
 {
 public:
-    //@{
     /**
-        Default constructors.
+        Default constructor.
+    */
+    wxRichTextBuffer();
+
+    /**
+        Copy ctor.
     */
     wxRichTextBuffer(const wxRichTextBuffer& obj);
-    wxRichTextBuffer();
-    //@}
 
     /**
         Destructor.
@@ -33,14 +159,15 @@ public:
     virtual ~wxRichTextBuffer();
 
     /**
-        Adds an event handler to the buffer's list of handlers. A buffer associated with
+        Adds an event handler to the buffer's list of handlers.
-        a contol has the control as the only event handler, but the application is free
+
-        to add more if further notification is required. All handlers are notified
+        A buffer associated with a control has the control as the only event handler,
-        of an event originating from the buffer, such as the replacement of a style
+        but the application is free to add more if further notification is required.
-        sheet
+        All handlers are notified of an event originating from the buffer, such as
-        during loading. The buffer never deletes any of the event handlers, unless
+        the replacement of a style sheet during loading.
-        RemoveEventHandler() is
+
-        called with @true as the second argument.
+        The buffer never deletes any of the event handlers, unless RemoveEventHandler()
+        is called with @true as the second argument.
     */
     bool AddEventHandler(wxEvtHandler* handler);
 
@@ -69,6 +196,7 @@ public:
         Begins collapsing undo/redo commands. Note that this may not work properly
         if combining commands that delete or insert content, changing ranges for
         subsequent actions.
+
         @a cmdName should be the name of the combined command that will appear
         next to Undo and Redo in the edit menu.
     */
@@ -100,48 +228,46 @@ public:
     bool BeginItalic();
 
     /**
-        Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent
+        Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent for
-        for
         the sub-indent. Both are expressed in tenths of a millimetre.
+
         The sub-indent is an offset from the left of the paragraph, and is used for all
-        but the
+        but the first line in a paragraph. A positive value will cause the first line to appear
-        first line in a paragraph. A positive value will cause the first line to appear
+        to the left of the subsequent lines, and a negative value will cause the first line to be
-        to the left
+        indented relative to the subsequent lines.
-        of the subsequent lines, and a negative value will cause the first line to be
-        indented
-        relative to the subsequent lines.
     */
     bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0);
 
     /**
         Begins line spacing using the specified value. @e spacing is a multiple, where
-        10 means single-spacing,
+        10 means single-spacing, 15 means 1.5 spacing, and 20 means double spacing.
-        15 means 1.5 spacing, and 20 means double spacing. The following constants are
+
-        defined for convenience:
+        The ::wxTextAttrLineSpacing enumeration values are defined for convenience.
     */
     bool BeginLineSpacing(int lineSpacing);
 
     /**
-        Begins using a specified list style. Optionally, you can also pass a level and
+        Begins using a specified list style.
-        a number.
+        Optionally, you can also pass a level and a number.
     */
     bool BeginListStyle(const wxString& listStyle, int level = 1,
                         int number = 1);
 
     /**
-        Begins a numbered bullet. This call will be needed for each item in the list,
+        Begins a numbered bullet.
-        and the
+
+        This call will be needed for each item in the list, and the
         application should take care of incrementing the numbering.
+
         @a bulletNumber is a number, usually starting with 1.
         @a leftIndent and @a leftSubIndent are values in tenths of a millimetre.
         @a bulletStyle is a bitlist of the following values:
 
-        wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
+        wxRichTextBuffer uses indentation to render a bulleted item.
-        the distance between
+        The left indent is the distance between the margin and the bullet.
-        the margin and the bullet. The content of the paragraph, including the first
+        The content of the paragraph, including the first line, starts
-        line, starts
+        at leftMargin + leftSubIndent.
-        at leftMargin + leftSubIndent. So the distance between the left edge of the
+        So the distance between the left edge of the bullet and the
-        bullet and the
         left of the actual paragraph is leftSubIndent.
     */
     bool BeginNumberedBullet(int bulletNumber, int leftIndent,
@@ -150,8 +276,7 @@ public:
 
     /**
         Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing
-        in tenths of
+        in tenths of a millimetre.
-        a millimetre.
     */
     bool BeginParagraphSpacing(int before, int after);
 
@@ -168,6 +293,7 @@ public:
     /**
         Begins applying a standard bullet, using one of the standard bullet names
         (currently @c standard/circle or @c standard/square.
+
         See BeginNumberedBullet() for an explanation of how indentation is used to
         render the bulleted paragraph.
     */
@@ -183,18 +309,18 @@ public:
 
     /**
         Begins suppressing undo/redo commands. The way undo is suppressed may be
-        implemented
+        implemented differently by each command.
-        differently by each command. If not dealt with by a command implementation, then
+        If not dealt with by a command implementation, then it will be implemented
-        it will be implemented automatically by not storing the command in the undo
+        automatically by not storing the command in the undo history when the
-        history
+        action is submitted to the command processor.
-        when the action is submitted to the command processor.
     */
     virtual bool BeginSuppressUndo();
 
     /**
-        Begins applying a symbol bullet, using a character from the current font. See
+        Begins applying a symbol bullet, using a character from the current font.
-        BeginNumberedBullet() for
+
-        an explanation of how indentation is used to render the bulleted paragraph.
+        See BeginNumberedBullet() for an explanation of how indentation is used
+        to render the bulleted paragraph.
     */
     bool BeginSymbolBullet(wxChar symbol, int leftIndent,
                            int leftSubIndent,
@@ -206,10 +332,10 @@ public:
     bool BeginTextColour(const wxColour& colour);
 
     /**
-        Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a
+        Begins applying wxTEXT_ATTR_URL to the content.
-        character style to apply,
+
-        since it is common to mark a URL with a familiar style such as blue text with
+        Pass a URL and optionally, a character style to apply, since it is common
-        underlining.
+        to mark a URL with a familiar style such as blue text with underlining.
     */
     bool BeginURL(const wxString& url,
                   const wxString& characterStyle = wxEmptyString);
@@ -238,9 +364,11 @@ public:
     /**
         Clears the list style from the given range, clearing list-related attributes
         and applying any named paragraph style associated with each paragraph.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-        See also SetListStyle(), PromoteList(), NumberList().
+
+        @see SetListStyle(), PromoteList(), NumberList()
     */
     bool ClearListStyle(const wxRichTextRange& range,
                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
@@ -392,15 +520,21 @@ public:
     */
     bool EndUnderline();
 
-    //@{
+    /**
+        Finds a handler by type.
+    */
+    wxRichTextFileHandler* FindHandler(int imageType);
+
+    /**
+        Finds a handler by extension and type.
+    */
+    wxRichTextFileHandler* FindHandler(const wxString& extension,
+                                       int imageType);
+
     /**
         Finds a handler by name.
     */
-    wxRichTextFileHandler* FindHandler(int imageType);
-    wxRichTextFileHandler* FindHandler(const wxString& extension,
-                                       int imageType);
     wxRichTextFileHandler* FindHandler(const wxString& name);
-    //@}
 
     /**
         Finds a handler by filename or, if supplied, type.
@@ -409,10 +543,12 @@ public:
                                                      int imageType);
 
     /**
-        Gets the basic (overall) style. This is the style of the whole
+        Gets the basic (overall) style.
-        buffer before further styles are applied, unlike the default style, which
+
-        only affects the style currently being applied (for example, setting the default
+        This is the style of the whole buffer before further styles are applied,
-        style to bold will cause subsequently inserted text to be bold).
+        unlike the default style, which only affects the style currently being
+        applied (for example, setting the default style to bold will cause
+        subsequently inserted text to be bold).
     */
     const wxTextAttr GetBasicStyle() const;
 
@@ -422,24 +558,23 @@ public:
     virtual wxRichTextCommand* GetBatchedCommand() const;
 
     /**
-        Gets the command processor. A text buffer always creates its own command
+        Gets the command processor.
-        processor when it is
+        A text buffer always creates its own command processor when it is initialized.
-        initialized.
     */
     wxCommandProcessor* GetCommandProcessor() const;
 
     /**
         Returns the current default style, affecting the style currently being applied
-        (for example, setting the default
+        (for example, setting the default style to bold will cause subsequently
-        style to bold will cause subsequently inserted text to be bold).
+        inserted text to be bold).
     */
     const wxTextAttr GetDefaultStyle() const;
 
     /**
-        Gets a wildcard incorporating all visible handlers. If @a types is present,
+        Gets a wildcard incorporating all visible handlers.
-        it will be filled with the file type corresponding to each filter. This can be
+        If @a types is present, it will be filled with the file type corresponding
-        used to determine the type to pass to @ref getextwildcard() LoadFile given a
+        to each filter. This can be used to determine the type to pass to LoadFile()
-        selected filter.
+        given a selected filter.
     */
     wxString GetExtWildcard(bool combine = false, bool save = false,
                             wxArrayInt* types = NULL);
@@ -457,11 +592,11 @@ public:
 
     /**
         Gets the attributes at the given position.
+
         This function gets the combined style - that is, the style you see on the
-        screen as a result
+        screen as a result of combining base style, paragraph style and character
-        of combining base style, paragraph style and character style attributes. To get
+        style attributes. To get the character or paragraph style alone,
-        the character
+        use GetUncombinedStyle().
-        or paragraph style alone, use GetUncombinedStyle().
     */
     bool GetStyle(long position, wxTextAttr& style);
 
@@ -469,29 +604,24 @@ public:
         This function gets a style representing the common, combined attributes in the
         given range.
         Attributes which have different values within the specified range will not be
-        included the style
+        included the style flags.
-        flags.
+
         The function is used to get the attributes to display in the formatting dialog:
-        the user
+        the user can edit the attributes common to the selection, and optionally specify the
-        can edit the attributes common to the selection, and optionally specify the
+        values of further attributes to be applied uniformly.
-        values of further
+
-        attributes to be applied uniformly.
         To apply the edited attributes, you can use SetStyle() specifying
         the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that
-        are different
+        are different from the @e combined attributes within the range.
-        from the @e combined attributes within the range. So, the user edits the
+        So, the user edits the effective, displayed attributes for the range,
-        effective, displayed attributes
+        but his choice won't be applied unnecessarily to content. As an example,
-        for the range, but his choice won't be applied unnecessarily to content. As an
-        example,
         say the style for a paragraph specifies bold, but the paragraph text doesn't
-        specify a weight. The
+        specify a weight.
-        combined style is bold, and this is what the user will see on-screen and in the
+        The combined style is bold, and this is what the user will see on-screen and
-        formatting
+        in the formatting dialog. The user now specifies red text, in addition to bold.
-        dialog. The user now specifies red text, in addition to bold. When applying with
+        When applying with SetStyle(), the content font weight attributes won't be
-        SetStyle, the content font weight attributes won't be changed to bold because
+        changed to bold because this is already specified by the paragraph.
-        this is already specified
+        However the text colour attributes @e will be changed to show red.
-        by the paragraph. However the text colour attributes @e will be changed to
-        show red.
     */
     bool GetStyleForRange(const wxRichTextRange& range,
                           wxTextAttr& style);
@@ -508,23 +638,22 @@ public:
 
     /**
         Gets the attributes at the given position.
+
         This function gets the @e uncombined style - that is, the attributes associated
-        with the
+        with the paragraph or character content, and not necessarily the combined
-        paragraph or character content, and not necessarily the combined attributes you
+        attributes you see on the screen. To get the combined attributes, use GetStyle().
-        see on the
-        screen. To get the combined attributes, use GetStyle().
         If you specify (any) paragraph attribute in @e style's flags, this function
-        will fetch
+        will fetch the paragraph attributes.
-        the paragraph attributes. Otherwise, it will return the character attributes.
+        Otherwise, it will return the character attributes.
     */
     bool GetUncombinedStyle(long position, wxTextAttr& style);
 
     /**
-        Finds the text position for the given position, putting the position in @a
+        Finds the text position for the given position, putting the position in
-        textPosition if
+        @a textPosition if one is found.
-        one is found. @a pt is in logical units (a zero y position is
+        @a pt is in logical units (a zero y position is at the beginning of the buffer).
-        at the beginning of the buffer).
+
-        The function returns one of the following values:
+        @return One of the ::wxRichTextHitTestFlags values.
     */
     int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition);
 
@@ -534,9 +663,8 @@ public:
     void Init();
 
     /**
-        Initialises the standard handlers. Currently, only the plain text
+        Initialises the standard handlers.
-        loading/saving handler
+        Currently, only the plain text loading/saving handler is initialised by default.
-        is initialised by default.
     */
     static void InitStandardHandlers();
 
@@ -568,15 +696,17 @@ public:
     */
     bool IsModified() const;
 
-    //@{
     /**
-        Loads content from a file.
+        Loads content from a stream.
     */
     bool LoadFile(wxInputStream& stream,
                   int type = wxRICHTEXT_TYPE_ANY);
+
+    /**
+        Loads content from a file.
+    */
     bool LoadFile(const wxString& filename,
                   int type = wxRICHTEXT_TYPE_ANY);
-    //@}
 
     /**
         Marks the buffer as modified or unmodified.
@@ -585,17 +715,20 @@ public:
 
     //@{
     /**
-        Numbers the paragraphs in the given range. Pass flags to determine how the
+        Numbers the paragraphs in the given range.
-        attributes are set.
+
+        Pass flags to determine how the attributes are set.
         Either the style definition or the name of the style definition (in the current
         sheet) can be passed.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-         wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
+        - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
-        startFrom, otherwise existing attributes are used.
+          @a startFrom, otherwise existing attributes are used.
-         wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
+        - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
           as the level for all paragraphs, otherwise the current indentation will be used.
-        See also SetListStyle(), PromoteList(), ClearListStyle().
+
+        @see SetListStyle(), PromoteList(), ClearListStyle()
     */
     bool NumberList(const wxRichTextRange& range,
                     const wxRichTextListStyleDefinition* style,
@@ -616,18 +749,21 @@ public:
 
     //@{
     /**
-        Promotes or demotes the paragraphs in the given range. A positive @a promoteBy
+        Promotes or demotes the paragraphs in the given range.
-        produces a smaller indent, and a negative number
+
+        A positive @a promoteBy produces a smaller indent, and a negative number
         produces a larger indent. Pass flags to determine how the attributes are set.
         Either the style definition or the name of the style definition (in the current
         sheet) can be passed.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-         wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
+        - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
-        startFrom, otherwise existing attributes are used.
+          @a startFrom, otherwise existing attributes are used.
-         wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
+        - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
           as the level for all paragraphs, otherwise the current indentation will be used.
-        See also SetListStyle(), See also SetListStyle(), ClearListStyle().
+
+        @see SetListStyle(), SetListStyle(), ClearListStyle()
     */
     bool PromoteList(int promoteBy, const wxRichTextRange& range,
                      const wxRichTextListStyleDefinition* style,
@@ -656,15 +792,17 @@ public:
     */
     virtual void ResetAndClearCommands();
 
-    //@{
     /**
-        Saves content to a file.
+        Saves content to a stream.
     */
     bool SaveFile(wxOutputStream& stream,
                   int type = wxRICHTEXT_TYPE_ANY);
+
+    /**
+        Saves content to a file.
+    */
     bool SaveFile(const wxString& filename,
                   int type = wxRICHTEXT_TYPE_ANY);
-    //@}
 
     /**
         Sets the basic (overall) style. This is the style of the whole
@@ -675,9 +813,10 @@ public:
     void SetBasicStyle(const wxTextAttr& style);
 
     /**
-        Sets the default style, affecting the style currently being applied (for
+        Sets the default style, affecting the style currently being applied
-        example, setting the default
+        (for example, setting the default style to bold will cause subsequently
-        style to bold will cause subsequently inserted text to be bold).
+        inserted text to be bold).
+
         This is not cumulative - setting the default style will replace the previous
         default style.
     */
@@ -689,13 +828,15 @@ public:
         the attributes are set.
         Either the style definition or the name of the style definition (in the current
         sheet) can be passed.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-         wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
+        - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
-        startFrom, otherwise existing attributes are used.
+          @a startFrom, otherwise existing attributes are used.
-         wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
+        - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
           as the level for all paragraphs, otherwise the current indentation will be used.
-        See also NumberList(), PromoteList(), ClearListStyle().
+
+        @see NumberList(), PromoteList(), ClearListStyle().
     */
     bool SetListStyle(const wxRichTextRange& range,
                       const wxRichTextListStyleDefinition* style,
@@ -712,48 +853,50 @@ public:
     /**
         Sets @a renderer as the object to be used to render certain aspects of the
         content, such as bullets.
+
         You can override default rendering by deriving a new class from
-        wxRichTextRenderer or wxRichTextStdRenderer,
+        wxRichTextRenderer or wxRichTextStdRenderer, overriding one or more
-        overriding one or more virtual functions, and setting an instance of the class
+        virtual functions, and setting an instance of the class using this function.
-        using this function.
     */
     static void SetRenderer(wxRichTextRenderer* renderer);
 
     /**
         Sets the attributes for the given range. Pass flags to determine how the
         attributes are set.
+
         The end point of range is specified as the last character position of the span
-        of text.
+        of text. So, for example, to set the style for a character at position 5,
-        So, for example, to set the style for a character at position 5, use the range
+        use the range (5,5).
-        (5,5).
         This differs from the wxRichTextCtrl API, where you would specify (5,6).
+
         @a flags may contain a bit list of the following values:
-         wxRICHTEXT_SETSTYLE_NONE: no style flag.
+        - wxRICHTEXT_SETSTYLE_NONE: no style flag.
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
           undoable.
-         wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
+        - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
-        if the
+          if the combined style at this point is already the style in question.
-        combined style at this point is already the style in question.
+        - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
-         wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
+          applied to paragraphs, and not the content.
-        applied to paragraphs,
+          This allows content styling to be preserved independently from that
-        and not the content. This allows content styling to be preserved independently
+          of e.g. a named paragraph style.
-        from that of e.g. a named paragraph style.
+        - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
-         wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
+          applied to characters, and not the paragraph.
-        applied to characters,
+          This allows content styling to be preserved independently from that
-        and not the paragraph. This allows content styling to be preserved
+          of e.g. a named paragraph style.
-        independently from that of e.g. a named paragraph style.
+        - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
-         wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
           the new style.
-         wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags
+        - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style.
-        are used in this operation.
+          Only the style flags are used in this operation.
     */
     bool SetStyle(const wxRichTextRange& range,
                   const wxTextAttr& style,
                   int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
 
     /**
-        Sets the current style sheet, if any. This will allow the application to use
+        Sets the current style sheet, if any.
-        named character and paragraph styles found in the style sheet.
+
+        This will allow the application to use named character and paragraph
+        styles found in the style sheet.
     */
     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 
@@ -790,9 +933,10 @@ public:
                           int type = 0);
 
     /**
-        Override this function and return @true if this handler can we handle @e
+        Override this function and return @true if this handler can we handle
-        filename. By default,
+        @a filename.
-        this function checks the extension.
+
+        By default, this function checks the extension.
     */
     virtual bool CanHandle(const wxString& filename) const;
 
@@ -807,12 +951,12 @@ public:
     virtual bool CanSave() const;
 
     /**
-        Override to load content from @a stream into @e buffer.
+        Override to load content from @a stream into @a buffer.
     */
     bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream);
 
     /**
-        Override to save content to @a stream from @e buffer.
+        Override to save content to @a stream from @a buffer.
     */
     bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream);
 
@@ -827,9 +971,10 @@ public:
     wxString GetExtension() const;
 
     /**
-        Returns flags that change the behaviour of loading or saving. See the
+        Returns flags that change the behaviour of loading or saving.
-        documentation for each
+
-        handler class to see what flags are relevant for each handler.
+        See the documentation for each handler class to see what flags are
+        relevant for each handler.
     */
     int GetFlags() const;
 
@@ -850,26 +995,25 @@ public:
 
     //@{
     /**
-        Loads content from a stream or file. Not all handlers will implement file
+        Loads content from a stream or file.
-        loading.
+        Not all handlers will implement file loading.
     */
     bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream);
-    bool LoadFile(wxRichTextBuffer* buffer,
+    bool LoadFile(wxRichTextBuffer* buffer, const wxString& filename);
-                  const wxString& filename);
     //@}
 
     //@{
     /**
-        Saves content to a stream or file. Not all handlers will implement file saving.
+        Saves content to a stream or file.
+        Not all handlers will implement file saving.
     */
     bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream);
-    bool SaveFile(wxRichTextBuffer* buffer,
+    bool SaveFile(wxRichTextBuffer* buffer, const wxString& filename);
-                  const wxString& filename);
     //@}
 
     /**
-        Sets the encoding to use when saving a file. If empty, a suitable encoding is
+        Sets the encoding to use when saving a file.
-        chosen.
+        If empty, a suitable encoding is chosen.
     */
     void SetEncoding(const wxString& encoding);
 
@@ -879,14 +1023,14 @@ public:
     void SetExtension(const wxString& ext);
 
     /**
-        Sets flags that change the behaviour of loading or saving. See the
+        Sets flags that change the behaviour of loading or saving.
-        documentation for each
+        See the documentation for each handler class to see what flags are relevant
-        handler class to see what flags are relevant for each handler.
+        for each handler.
+
         You call this function directly if you are using a file handler explicitly
-        (without
+        (without going through the text control or buffer LoadFile/SaveFile API).
-        going through the text control or buffer LoadFile/SaveFile API). Or, you can
+        Or, you can call the control or buffer's SetHandlerFlags function to set
-        call the control or buffer's SetHandlerFlags function to set the flags that will
+        the flags that will be used for subsequent load and save operations.
-        be used for subsequent load and save operations.
     */
     void SetFlags(int flags);
 
@@ -902,8 +1046,7 @@ public:
 
     /**
         Sets whether the handler should be visible to the user (via the application's
-        load and save
+        load and save dialogs).
-        dialogs).
     */
     virtual void SetVisible(bool visible);
 };
@@ -936,16 +1079,15 @@ public:
     ~wxRichTextRange();
 
     /**
-        Returns @true if the given position is within this range. Does not
+        Returns @true if the given position is within this range.
-        match if the range is empty.
+        Does not match if the range is empty.
     */
     bool Contains(long pos) const;
 
     /**
         Converts the internal range, which uses the first and last character positions
-        of the range,
+        of the range, to the API-standard range, whose end is one past the last
-        to the API-standard range, whose end is one past the last character in the
+        character in the range.
-        range.
         In other words, one is added to the end position.
     */
     wxRichTextRange FromInternal() const;
@@ -1002,9 +1144,8 @@ public:
 
     /**
         Converts the API-standard range, whose end is one past the last character in
-        the range,
+        the range, to the internal form, which uses the first and last character
-        to the internal form, which uses the first and last character positions of the
+        positions of the range.
-        range.
         In other words, one is subtracted from the end position.
     */
     wxRichTextRange ToInternal() const;

interface/wx/richtext/richtextctrl.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        richtext/richtextctrl.h
-// Purpose:     interface of wxRichTextEvent
+// Purpose:     interface of wxRichTextCtrl and wxRichTextEvent
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -11,8 +11,49 @@
 
     This is the event class for wxRichTextCtrl notifications.
 
+    @beginEventTable{wxRichTextEvent}
+    @event{EVT_RICHTEXT_CHARACTER(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_CHARACTER event, generated when the user
+        presses a character key. Valid event functions: GetFlags, GetPosition, GetCharacter.
+    @event{EVT_RICHTEXT_DELETE(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_DELETE event, generated when the user
+        presses the backspace or delete key. Valid event functions: GetFlags, GetPosition.
+    @event{EVT_RICHTEXT_RETURN(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_RETURN event, generated when the user
+        presses the return key. Valid event functions: GetFlags, GetPosition.
+    @event{EVT_RICHTEXT_STYLE_CHANGED(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_STYLE_CHANGED event, generated when
+        styling has been applied to the control. Valid event functions: GetPosition, GetRange.
+    @event{EVT_RICHTEXT_STYLESHEET_CHANGED(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING event, generated
+        when the control's stylesheet has changed, for example the user added,
+        edited or deleted a style. Valid event functions: GetRange, GetPosition.
+    @event{EVT_RICHTEXT_STYLESHEET_REPLACING(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACING event, generated
+        when the control's stylesheet is about to be replaced, for example when
+        a file is loaded into the control.
+        Valid event functions: Veto, GetOldStyleSheet, GetNewStyleSheet.
+    @event{EVT_RICHTEXT_STYLESHEET_REPLACED(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACED event, generated
+        when the control's stylesheet has been replaced, for example when a file
+        is loaded into the control.
+        Valid event functions: GetOldStyleSheet, GetNewStyleSheet.
+    @event{EVT_RICHTEXT_CONTENT_INSERTED(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_CONTENT_INSERTED event, generated when
+        content has been inserted into the control.
+        Valid event functions: GetPosition, GetRange.
+    @event{EVT_RICHTEXT_CONTENT_DELETED(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_CONTENT_DELETED event, generated when
+        content has been deleted from the control.
+        Valid event functions: GetPosition, GetRange.
+    @event{EVT_RICHTEXT_BUFFER_RESET(id, func)}
+        Process a wxEVT_COMMAND_RICHTEXT_BUFFER_RESET event, generated when the
+        buffer has been reset by deleting all content.
+        You can use this to set a default style for the first new paragraph.
+    @endEventTable
+
     @library{wxrichtext}
-    @category{richtext}
+    @category{events,richtext}
 */
 class wxRichTextEvent : public wxNotifyEvent
 {
@@ -25,6 +66,8 @@ public:
     /**
         Constructor.
 
+        @param commandType
+            The type of the event.
         @param id
             Window identifier. The value @c wxID_ANY indicates a default value.
     */
@@ -41,22 +84,24 @@ public:
     wxChar GetCharacter() const;
 
     /**
-        Returns flags indicating modifier keys pressed. Possible values are
+        Returns flags indicating modifier keys pressed.
-        wxRICHTEXT_CTRL_DOWN,
+
-        wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN.
+        Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN.
     */
     int GetFlags() const;
 
     /**
-        Returns the new style sheet. Can be used in a
+        Returns the new style sheet.
-        wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or
+
+        Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or
         wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler.
     */
     wxRichTextStyleSheet* GetNewStyleSheet() const;
 
     /**
-        Returns the old style sheet. Can be used in a
+        Returns the old style sheet.
-        wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or
+
+        Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or
         wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler.
     */
     wxRichTextStyleSheet* GetOldStyleSheet() const;
@@ -77,9 +122,9 @@ public:
     void SetCharacter(wxChar ch);
 
     /**
-        Sets flags indicating modifier keys pressed. Possible values are
+        Sets flags indicating modifier keys pressed.
-        wxRICHTEXT_CTRL_DOWN,
+
-        wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN.
+        Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN.
     */
     void SetFlags(int flags);
 
@@ -113,9 +158,9 @@ public:
     capable of showing multiple styles and images.
 
     wxRichTextCtrl sends notification events: see wxRichTextEvent.
+
     It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and
-    wxEVT_COMMAND_TEXT_UPDATED,
+    wxEVT_COMMAND_TEXT_UPDATED, and wxTextUrlEvent when URL content is clicked.
-    and wxTextUrlEvent when URL content is clicked.
 
     For more information, see the @ref overview_richtextctrl.
 
@@ -203,10 +248,10 @@ public:
 
     /**
         Applies the style sheet to the buffer, matching paragraph styles in the sheet
-        against named styles
+        against named styles in the buffer.
-        in the buffer. This might be useful if the styles have changed. If @a sheet is
+
-        @NULL, the
+        This might be useful if the styles have changed.
-        sheet set with SetStyleSheet is used.
+        If @a sheet is @NULL, the sheet set with SetStyleSheet() is used.
         Currently this applies paragraph styles only.
     */
     bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL);
@@ -222,7 +267,7 @@ public:
     virtual bool BatchingUndo() const;
 
     /**
-        Begins using alignment
+        Begins using alignment.
         For alignment values, see wxTextAttr.
     */
     bool BeginAlignment(wxTextAttrAlignment alignment);
@@ -279,33 +324,34 @@ public:
 
     /**
         Begins appling line spacing. @e spacing is a multiple, where 10 means
-        single-spacing,
+        single-spacing, 15 means 1.5 spacing, and 20 means double spacing.
-        15 means 1.5 spacing, and 20 means double spacing. The following constants are
+
-        defined for convenience:
+        The ::wxTextAttrLineSpacing constants are defined for convenience.
     */
     bool BeginLineSpacing(int lineSpacing);
 
     /**
-        Begins using a specified list style. Optionally, you can also pass a level and
+        Begins using a specified list style.
-        a number.
+        Optionally, you can also pass a level and a number.
     */
     bool BeginListStyle(const wxString& listStyle, int level = 1,
                         int number = 1);
 
     /**
-        Begins a numbered bullet. This call will be needed for each item in the list,
+        Begins a numbered bullet.
-        and the
+
+        This call will be needed for each item in the list, and the
         application should take care of incrementing the numbering.
+
         @a bulletNumber is a number, usually starting with 1.
         @a leftIndent and @a leftSubIndent are values in tenths of a millimetre.
-        @a bulletStyle is a bitlist of the following values:
+        @a bulletStyle is a bitlist of the  ::wxTextAttrBulletStyle values.
 
-        wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
+        wxRichTextBuffer uses indentation to render a bulleted item.
-        the distance between
+        The left indent is the distance between the margin and the bullet.
-        the margin and the bullet. The content of the paragraph, including the first
+        The content of the paragraph, including the first line, starts
-        line, starts
+        at leftMargin + leftSubIndent.
-        at leftMargin + leftSubIndent. So the distance between the left edge of the
+        So the distance between the left edge of the bullet and the
-        bullet and the
         left of the actual paragraph is leftSubIndent.
     */
     bool BeginNumberedBullet(int bulletNumber, int leftIndent,
@@ -314,8 +360,7 @@ public:
 
     /**
         Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing
-        in tenths of
+        in tenths of a millimetre.
-        a millimetre.
     */
     bool BeginParagraphSpacing(int before, int after);
 
@@ -340,9 +385,9 @@ public:
     virtual bool BeginSuppressUndo();
 
     /**
-        Begins applying a symbol bullet, using a character from the current font. See
+        Begins applying a symbol bullet, using a character from the current font.
-        BeginNumberedBullet() for
+        See BeginNumberedBullet() for an explanation of how indentation is used
-        an explanation of how indentation is used to render the bulleted paragraph.
+        to render the bulleted paragraph.
     */
     bool BeginSymbolBullet(wxChar symbol, int leftIndent,
                            int leftSubIndent,
@@ -354,10 +399,10 @@ public:
     bool BeginTextColour(const wxColour& colour);
 
     /**
-        Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a
+        Begins applying wxTEXT_ATTR_URL to the content.
-        character style to apply,
+
-        since it is common to mark a URL with a familiar style such as blue text with
+        Pass a URL and optionally, a character style to apply, since it is common
-        underlining.
+        to mark a URL with a familiar style such as blue text with underlining.
     */
     bool BeginURL(const wxString& url,
                   const wxString& characterStyle = wxEmptyString);
@@ -406,9 +451,11 @@ public:
     /**
         Clears the list style from the given range, clearing list-related attributes
         and applying any named paragraph style associated with each paragraph.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-        See also SetListStyle(), PromoteList(), NumberList().
+
+        @see SetListStyle(), PromoteList(), NumberList().
     */
     bool ClearListStyle(const wxRichTextRange& range,
                         int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO);
@@ -578,15 +625,14 @@ public:
 
     /**
         Helper function for extending the selection, returning @true if the selection
-        was
+        was changed. Selections are in caret positions.
-        changed. Selections are in caret positions.
     */
     bool ExtendSelection(long oldPosition, long newPosition,
                          int flags);
 
     /**
-        Helper function for finding the caret position for the next word. Direction
+        Helper function for finding the caret position for the next word.
-        is 1 (forward) or -1 (backwards).
+        Direction is 1 (forward) or -1 (backwards).
     */
     virtual long FindNextWordPosition(int direction = 1) const;
 
@@ -597,10 +643,12 @@ public:
     void Freeze();
 
     /**
-        Gets the basic (overall) style. This is the style of the whole
+        Gets the basic (overall) style.
-        buffer before further styles are applied, unlike the default style, which
+
-        only affects the style currently being applied (for example, setting the default
+        This is the style of the whole buffer before further styles are applied,
-        style to bold will cause subsequently inserted text to be bold).
+        unlike the default style, which only affects the style currently being
+        applied (for example, setting the default style to bold will cause
+        subsequently inserted text to be bold).
     */
     const wxTextAttr GetBasicStyle() const;
 
@@ -618,7 +666,7 @@ public:
     long GetCaretPosition() const;
 
     /**
-        Returns the caret height and position for the given character position
+        Returns the caret height and position for the given character position.
     */
     bool GetCaretPositionForIndex(long position, wxRect& rect);
 
@@ -629,8 +677,7 @@ public:
 
     /**
         Returns the current default style, which can be used to change how subsequently
-        inserted
+        inserted text is displayed.
-        text is displayed.
     */
     const wxTextAttr GetDefaultStyle() const;
 
@@ -651,9 +698,9 @@ public:
     long GetFirstVisiblePosition() const;
 
     /**
-        Returns flags that change the behaviour of loading or saving. See the
+        Returns flags that change the behaviour of loading or saving.
-        documentation for each
+        See the documentation for each handler class to see what flags are
-        handler class to see what flags are relevant for each handler.
+        relevant for each handler.
     */
     int GetHandlerFlags() const;
 
@@ -694,8 +741,8 @@ public:
 
     /**
         Gets the text for the given range.
-        The end point of range is specified as the last character position of the span
+        The end point of range is specified as the last character position of
-        of text, plus one.
+        the span of text, plus one.
     */
     virtual wxString GetRange(long from, long to) const;
 
@@ -720,38 +767,37 @@ public:
     /**
         Gets the attributes at the given position.
         This function gets the combined style - that is, the style you see on the
-        screen as a result
+        screen as a result of combining base style, paragraph style and character
-        of combining base style, paragraph style and character style attributes. To get
+        style attributes.
-        the character
+
-        or paragraph style alone, use GetUncombinedStyle().
+        To get the character or paragraph style alone, use GetUncombinedStyle().
     */
     virtual bool GetStyle(long position, wxTextAttr& style);
 
     /**
-        Gets the attributes common to the specified range. Attributes that differ in
+        Gets the attributes common to the specified range.
-        value within the range will
+        Attributes that differ in value within the range will not be included
-        not be included in @e style's flags.
+        in @a style flags.
     */
     bool GetStyleForRange(const wxRichTextRange& range,
                           wxTextAttr& style);
 
     /**
-        Returns the style sheet associated with the control, if any. A style sheet
+        Returns the style sheet associated with the control, if any.
-        allows named
+        A style sheet allows named character and paragraph styles to be applied.
-        character and paragraph styles to be applied.
     */
     wxRichTextStyleSheet* GetStyleSheet() const;
 
     /**
         Gets the attributes at the given position.
         This function gets the @e uncombined style - that is, the attributes associated
-        with the
+        with the paragraph or character content, and not necessarily the combined
-        paragraph or character content, and not necessarily the combined attributes you
+        attributes you see on the screen.
-        see on the
+        To get the combined attributes, use GetStyle().
-        screen. To get the combined attributes, use GetStyle().
+
         If you specify (any) paragraph attribute in @e style's flags, this function
-        will fetch
+        will fetch the paragraph attributes.
-        the paragraph attributes. Otherwise, it will return the character attributes.
+        Otherwise, it will return the character attributes.
     */
     virtual bool GetUncombinedStyle(long position, wxTextAttr& style);
 
@@ -761,29 +807,28 @@ public:
     virtual wxString GetValue() const;
 
     /**
-        Internal helper function returning the line for the visible caret position. If
+        Internal helper function returning the line for the visible caret position.
-        the caret is
+        If the caret is shown at the very end of the line, it means the next character
-        shown at the very end of the line, it means the next character is actually
+        is actually on the following line.
-        on the following line. So this function gets the line we're expecting to find
+        So this function gets the line we're expecting to find if this is the case.
-        if this is the case.
     */
     wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const;
 
     /**
-        Test if this whole range has character attributes of the specified kind. If any
+        Test if this whole range has character attributes of the specified kind.
-        of the attributes are different within the range, the test fails. You
+        If any of the attributes are different within the range, the test fails.
-        can use this to implement, for example, bold button updating. @a style must have
+
-        flags indicating which attributes are of interest.
+        You can use this to implement, for example, bold button updating.
+        @a style must have flags indicating which attributes are of interest.
     */
     bool HasCharacterAttributes(const wxRichTextRange& range,
                                 const wxTextAttr& style) const;
 
     /**
-        Test if this whole range has paragraph attributes of the specified kind. If any
+        Test if this whole range has paragraph attributes of the specified kind.
-        of the attributes are different within the range, the test fails. You
+        If any of the attributes are different within the range, the test fails.
-        can use this to implement, for example, centering button updating. @a style
+        You can use this to implement, for example, centering button updating.
-        must have
+        @a style must have flags indicating which attributes are of interest.
-        flags indicating which attributes are of interest.
     */
     bool HasParagraphAttributes(const wxRichTextRange& range,
                                 const wxTextAttr& style) const;
@@ -817,13 +862,13 @@ public:
 
     /**
         Returns @true if the user has recently set the default style without moving
-        the caret,
+        the caret, and therefore the UI needs to reflect the default style and not
-        and therefore the UI needs to reflect the default style and not the style at
+        the style at the caret.
-        the caret.
+
         Below is an example of code that uses this function to determine whether the UI
         should show that the current style is bold.
 
-        See also SetAndShowDefaultStyle().
+        @see SetAndShowDefaultStyle().
     */
     bool IsDefaultStyleShowing() const;
 
@@ -853,8 +898,7 @@ public:
     bool IsPositionVisible(long pos) const;
 
     /**
-        Returns @true if all of the selection is aligned according to the specified
+        Returns @true if all of the selection is aligned according to the specified flag.
-        flag.
     */
     virtual bool IsSelectionAligned(wxTextAttrAlignment alignment);
 
@@ -874,8 +918,8 @@ public:
     virtual bool IsSelectionUnderlined();
 
     /**
-        Returns @true if the control is single-line. Currently wxRichTextCtrl does not
+        Returns @true if the control is single-line.
-        support single-line editing.
+        Currently wxRichTextCtrl does not support single-line editing.
     */
     bool IsSingleLine() const;
 
@@ -886,24 +930,26 @@ public:
 
     /**
         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
+        setting the caret position.
-        application.
+        This function should not normally be required by the application.
     */
     virtual bool LayoutContent(bool onlyVisibleRect = false);
 
     /**
-        Inserts a line break at the current insertion point. A line break forces
+        Inserts a line break at the current insertion point.
-        wrapping within a paragraph, and
+
-        can be introduced by using this function, by appending the wxChar value @b
+        A line break forces wrapping within a paragraph, and can be introduced by
-        wxRichTextLineBreakChar to text content,
+        using this function, by appending the wxChar value @b  wxRichTextLineBreakChar
-        or by typing Shift-Return.
+        to text content, or by typing Shift-Return.
     */
     virtual bool LineBreak();
 
     /**
-        Loads content into the control's buffer using the given type. If the specified
+        Loads content into the control's buffer using the given type.
-        type
+
-        is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension.
+        If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from
+        the filename extension.
+
         This function looks for a suitable wxRichTextFileHandler object.
     */
     bool LoadFile(const wxString& file,
@@ -984,23 +1030,26 @@ public:
     virtual bool MoveUp(int noLines = 1, int flags = 0);
 
     /**
-        Inserts a new paragraph at the current insertion point. See also LineBreak().
+        Inserts a new paragraph at the current insertion point. @see LineBreak().
     */
     virtual bool Newline();
 
     //@{
     /**
-        Numbers the paragraphs in the given range. Pass flags to determine how the
+        Numbers the paragraphs in the given range.
-        attributes are set.
+        Pass flags to determine how the attributes are set.
+
         Either the style definition or the name of the style definition (in the current
         sheet) can be passed.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-         wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
+        - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
-        startFrom, otherwise existing attributes are used.
+          @a startFrom, otherwise existing attributes are used.
-         wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
+        - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
           as the level for all paragraphs, otherwise the current indentation will be used.
-        See also SetListStyle(), PromoteList(), ClearListStyle().
+
+        @see SetListStyle(), PromoteList(), ClearListStyle().
     */
     bool NumberList(const wxRichTextRange& range,
                     const wxRichTextListStyleDefinition* style,
@@ -1128,18 +1177,20 @@ public:
 
     //@{
     /**
-        Promotes or demotes the paragraphs in the given range. A positive @a promoteBy
+        Promotes or demotes the paragraphs in the given range.
-        produces a smaller indent, and a negative number
+        A positive @a promoteBy produces a smaller indent, and a negative number
         produces a larger indent. Pass flags to determine how the attributes are set.
         Either the style definition or the name of the style definition (in the current
         sheet) can be passed.
+
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-         wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
+        - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
-        startFrom, otherwise existing attributes are used.
+          @a startFrom, otherwise existing attributes are used.
-         wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
+        - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
         as the level for all paragraphs, otherwise the current indentation will be used.
-        See also SetListStyle(), See also SetListStyle(), ClearListStyle().
+
+        @see SetListStyle(), @see SetListStyle(), ClearListStyle().
     */
     bool PromoteList(int promoteBy, const wxRichTextRange& range,
                      const wxRichTextListStyleDefinition* style,
@@ -1162,14 +1213,17 @@ public:
     virtual void Remove(long from, long to);
 
     /**
-        Replaces the content in the specified range with the string specified by @e
+        Replaces the content in the specified range with the string specified by
-        value.
+        @a value.
     */
     virtual void Replace(long from, long to, const wxString& value);
 
     /**
-        Saves the buffer content using the given type. If the specified type
+        Saves the buffer content using the given type.
-        is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension.
+
+        If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from
+        the filename extension.
+
         This function looks for a suitable wxRichTextFileHandler object.
     */
     bool SaveFile(const wxString& file = wxEmptyString,
@@ -1192,17 +1246,19 @@ public:
 
     /**
         Sets @a attr as the default style and tells the control that the UI should
-        reflect
+        reflect this attribute until the user moves the caret.
-        this attribute until the user moves the caret.
+
-        See also IsDefaultStyleShowing().
+        @see IsDefaultStyleShowing().
     */
     void SetAndShowDefaultStyle(const wxTextAttr& attr);
 
     /**
-        Sets the basic (overall) style. This is the style of the whole
+        Sets the basic (overall) style.
-        buffer before further styles are applied, unlike the default style, which
+
-        only affects the style currently being applied (for example, setting the default
+        This is the style of the whole buffer before further styles are applied,
-        style to bold will cause subsequently inserted text to be bold).
+        unlike the default style, which only affects the style currently being
+        applied (for example, setting the default style to bold will cause
+        subsequently inserted text to be bold).
     */
     virtual void SetBasicStyle(const wxTextAttr& style);
 
@@ -1215,8 +1271,7 @@ public:
 
     /**
         Sets the current default style, which can be used to change how subsequently
-        inserted
+        inserted text is displayed.
-        text is displayed.
     */
     virtual bool SetDefaultStyle(const wxTextAttr& style);
 
@@ -1242,15 +1297,16 @@ public:
     void SetFilename(const wxString& filename);
 
     /**
-        Sets the font, and also the basic and default attributes (see
+        Sets the font, and also the basic and default attributes
-        wxRichTextCtrl::SetDefaultStyle).
+        (see wxRichTextCtrl::SetDefaultStyle).
     */
     virtual bool SetFont(const wxFont& font);
 
     /**
-        Sets flags that change the behaviour of loading or saving. See the
+        Sets flags that change the behaviour of loading or saving.
-        documentation for each
+
-        handler class to see what flags are relevant for each handler.
+        See the documentation for each handler class to see what flags are
+        relevant for each handler.
     */
     void SetHandlerFlags(int flags);
 
@@ -1268,15 +1324,17 @@ public:
     /**
         Sets the list attributes for the given range, passing flags to determine how
         the attributes are set.
+
         Either the style definition or the name of the style definition (in the current
         sheet) can be passed.
         @a flags is a bit list of the following:
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable.
-         wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e
+        - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from
-        startFrom, otherwise existing attributes are used.
+          @a startFrom, otherwise existing attributes are used.
-         wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
+        - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used
           as the level for all paragraphs, otherwise the current indentation will be used.
-        See also NumberList(), PromoteList(), ClearListStyle().
+
+        @see NumberList(), PromoteList(), ClearListStyle().
     */
     bool SetListStyle(const wxRichTextRange& range,
                       const wxRichTextListStyleDefinition* style,
@@ -1294,6 +1352,7 @@ public:
         Sets the selection to the given range.
         The end point of range is specified as the last character position of the span
         of text, plus one.
+
         So, for example, to set the selection for a character at position 5, use the
         range (5,6).
     */
@@ -1303,6 +1362,7 @@ public:
         Sets the selection to the given range.
         The end point of range is specified as the last character position of the span
         of text, plus one.
+
         So, for example, to set the selection for a character at position 5, use the
         range (5,6).
     */
@@ -1313,6 +1373,7 @@ public:
         Sets the attributes for the given range.
         The end point of range is specified as the last character position of the span
         of text, plus one.
+
         So, for example, to set the style for a character at position 5, use the range
         (5,6).
     */
@@ -1325,28 +1386,28 @@ public:
     /**
         Sets the attributes for the given range, passing flags to determine how the
         attributes are set.
+
         The end point of range is specified as the last character position of the span
-        of text, plus one.
+        of text, plus one. So, for example, to set the style for a character at
-        So, for example, to set the style for a character at position 5, use the range
+        position 5, use the range (5,6).
-        (5,6).
+
         @a flags may contain a bit list of the following values:
-         wxRICHTEXT_SETSTYLE_NONE: no style flag.
+        - wxRICHTEXT_SETSTYLE_NONE: no style flag.
-         wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
+        - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be
           undoable.
-         wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
+        - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied
-        if the
+          if the combined style at this point is already the style in question.
-        combined style at this point is already the style in question.
+        - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
-         wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be
+          applied to paragraphs, and not the content.
-        applied to paragraphs,
+          This allows content styling to be preserved independently from that
-        and not the content. This allows content styling to be preserved independently
+          of e.g. a named paragraph style.
-        from that of e.g. a named paragraph style.
+        - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
-         wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be
+          applied to characters, and not the paragraph.
-        applied to characters,
+          This allows content styling to be preserved independently from that
-        and not the paragraph. This allows content styling to be preserved
+          of e.g. a named paragraph style.
-        independently from that of e.g. a named paragraph style.
+        - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
-         wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying
           the new style.
-         wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags
+        - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags
           are used in this operation.
     */
     bool SetStyleEx(const wxRichTextRange& range,
@@ -1358,8 +1419,8 @@ public:
     //@}
 
     /**
-        Sets the style sheet associated with the control. A style sheet allows named
+        Sets the style sheet associated with the control.
-        character and paragraph styles to be applied.
+        A style sheet allows named character and paragraph styles to be applied.
     */
     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 
@@ -1403,14 +1464,21 @@ public:
     */
     virtual bool WordRight(int noWords = 1, int flags = 0);
 
-    //@{
     /**
-        Write a bitmap or image at the current insertion point. Supply an optional type
+        Loads an image from a file and writes it at the current insertion point.
-        to use
-        for internal and file storage of the raw data.
     */
     bool WriteImage(const wxString& filename, int bitmapType);
+
+    /**
+        Writes an image block at the current insertion point.
+    */
     bool WriteImage(const wxRichTextImageBlock& imageBlock);
+
+    //@{
+    /**
+        Write a bitmap or image at the current insertion point.
+        Supply an optional type to use for internal and file storage of the raw data.
+    */
     bool WriteImage(const wxBitmap& bitmap,
                     int bitmapType = wxBITMAP_TYPE_PNG);
     bool WriteImage(const wxImage& image,

interface/wx/richtext/richtextformatdlg.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        richtext/richtextformatdlg.h
-// Purpose:     interface of wxRichTextFormattingDialogFactory
+// Purpose:     interface of wxRichTextFormattingDialog*
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -11,15 +11,15 @@
 
     This class provides pages for wxRichTextFormattingDialog, and allows other
     customization of the dialog.
-    A default instance of this class is provided automatically. If you wish to
+
-    change the behaviour of the
+    A default instance of this class is provided automatically.
-    formatting dialog (for example add or replace a page), you may derive from this
+    If you wish to change the behaviour of the formatting dialog (for example add
-    class,
+    or replace a page), you may derive from this class, override one or more
-    override one or more functions, and call the static function
+    functions, and call the static function
     wxRichTextFormattingDialog::SetFormattingDialogFactory.
 
     @library{wxrichtext}
-    @category{FIXME}
+    @category{richtext}
 */
 class wxRichTextFormattingDialogFactory : public wxObject
 {
@@ -46,7 +46,7 @@ public:
                                 wxRichTextFormattingDialog* dialog);
 
     /**
-        Creates all pages under the dialog's book control, also calling AddPage.
+        Creates all pages under the dialog's book control, also calling AddPage().
     */
     virtual bool CreatePages(long pages,
                              wxRichTextFormattingDialog* dialog);
@@ -81,15 +81,23 @@ public:
 
 
 
+#define wxRICHTEXT_FORMAT_STYLE_EDITOR      0x0001
+#define wxRICHTEXT_FORMAT_FONT              0x0002
+#define wxRICHTEXT_FORMAT_TABS              0x0004
+#define wxRICHTEXT_FORMAT_BULLETS           0x0008
+#define wxRICHTEXT_FORMAT_INDENTS_SPACING   0x0010
+
 /**
     @class wxRichTextFormattingDialog
 
     This dialog allows the user to edit a character and/or paragraph style.
 
-    In the constructor, specify the pages that will be created. Use GetStyle
+    In the constructor, specify the pages that will be created.
-    to retrieve the common style for a given range, and then use ApplyStyle
+    Use wxRichTextFormattingDialog::GetStyle() to retrieve the common style
-    to apply the user-selected formatting to a control. For example:
+    for a given range, and then use wxRichTextFormattingDialog::ApplyStyle()
+    to apply the user-selected formatting to a control.
 
+    For example:
     @code
         wxRichTextRange range;
         if (m_richTextCtrl-HasSelection())
@@ -97,8 +105,8 @@ public:
         else
             range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1);
 
-        int pages =
+        int pages = wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING| \
-    wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS;
+                    wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS;
 
         wxRichTextFormattingDialog formatDlg(pages, this);
         formatDlg.GetStyle(m_richTextCtrl, range);
@@ -115,7 +123,11 @@ public:
 class wxRichTextFormattingDialog : public wxPropertySheetDialog
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxRichTextFormattingDialog();
+
     /**
         Constructors.
 
@@ -123,21 +135,17 @@ public:
             The pages to show.
         @param parent
             The dialog's parent.
-        @param id
-            The dialog's identifier.
-        @param title
-            The dialog's caption.
         @param pos
             The dialog's position.
-        @param size
+        @param sz
             The dialog's size.
         @param style
             The dialog's window style.
     */
-    wxRichTextFormattingDialog(long flags, wxWindow* parent);
+    wxRichTextFormattingDialog(long flags, wxWindow* parent,
-    const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE)
+                               const wxPoint& pos = wxDefaultPosition,
-    wxRichTextFormattingDialog();
+                               const wxSize& sz = wxDefaultSize,
-    //@}
+                               long style = wxDEFAULT_DIALOG_STYLE);
 
     /**
         Destructor.
@@ -145,29 +153,27 @@ public:
     virtual ~wxRichTextFormattingDialog();
 
     /**
-        Apply attributes to the given range, only changing attributes that need to be
+        Apply attributes to the given range, only changing attributes that
-        changed.
+        need to be changed.
     */
     bool ApplyStyle(wxRichTextCtrl* ctrl,
                     const wxRichTextRange& range,
                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE);
 
     /**
-        Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for
+        Creation: see wxRichTextFormattingDialog() "the constructor" for
         details about the parameters.
     */
     bool Create(long flags, wxWindow* parent, const wxString& title,
-                wxWindowID id,
+                wxWindowID id, const wxPoint& pos = wxDefaultPosition,
-                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE);
-                                     const wxSize& sz = wxDefaultSize,
-                                                        long style = wxDEFAULT_DIALOG_STYLE);
 
     //@{
     /**
         Gets the attributes being edited.
     */
-    const wxTextAttr GetAttributes();
+    const wxTextAttr& GetAttributes() const;
-    const wxTextAttr&  GetAttributes();
+    wxTextAttr& GetAttributes();
     //@}
 
     /**
@@ -197,8 +203,8 @@ public:
     wxImageList* GetImageList() const;
 
     /**
-        Gets common attributes from the given range and calls SetAttributes. Attributes
+        Gets common attributes from the given range and calls SetAttributes().
-        that do not have common values in the given range
+        Attributes that do not have common values in the given range
         will be omitted from the style's flags.
     */
     virtual bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range);
@@ -221,6 +227,7 @@ public:
     /**
         Sets the formatting factory object to be used for customization and page
         creation.
+
         It deletes the existing factory object.
     */
     static void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory);
@@ -236,8 +243,8 @@ public:
     virtual bool SetStyle(const wxTextAttr& style, bool update = true);
 
     /**
-        Sets the style definition and optionally update the display, if @a update is @c
+        Sets the style definition and optionally update the display,
-        @true.
+        if @a update is @true.
     */
     virtual bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef,
                                     wxRichTextStyleSheet* sheet,

interface/wx/richtext/richtexthtml.h

@@ -16,21 +16,41 @@
     wxRichTextCtrl::SaveFile.
 
     Image handling requires a little extra work from the application, to choose an
-    appropriate image format for the target HTML viewer and to clean up the
+    appropriate image format for the target HTML viewer and to clean up the temporary
-    temporary images
+    images later.
-    later. If you are planning to load the HTML into a standard web browser, you can
+    If you are planning to load the HTML into a standard web browser, you can
     specify the handler flag wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64 (the default)
     and no extra work is required: the images will be written with the HTML.
 
     However, if you want wxHTML compatibility, you will need to use
-    wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY
+    @c wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY or
-    or wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES. In this case, you must either call
+    @c wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES.
-    wxRichTextHTMLHandler::DeleteTemporaryImages before
+
-    the next load operation, or you must store the image
+    In this case, you must either call wxRichTextHTMLHandler::DeleteTemporaryImages
-    locations and delete them yourself when appropriate. You can call
+    before the next load operation, or you must store the image locations and
-    wxRichTextHTMLHandler::GetTemporaryImageLocations to
+    delete them yourself when appropriate.
+
+    You can call wxRichTextHTMLHandler::GetTemporaryImageLocations to
     get the array of temporary image names.
 
+
+    @section richtexthtmlhandler_flags Handler flags
+
+    The following flags can be used with this handler, via the handler's SetFlags()
+    function or the buffer or control's SetHandlerFlags() function:
+
+    - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY
+      Images are saved to the memory filesystem: suitable for showing wxHTML windows.
+    - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES
+      Images are saved to temporary files: suitable for showing in wxHTML windows.
+    - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64
+      Images are written with the HTML files in Base 64 format: suitable for showing
+      in web browsers.
+    - wxRICHTEXT_HANDLER_NO_HEADER_FOOTER
+      Don't include header and footer tags (HTML, HEAD, BODY), so that the HTML
+      can be used as part of a larger document.
+
+
     @library{wxrichtext}
     @category{richtext}
 */
@@ -38,28 +58,29 @@ class wxRichTextHTMLHandler : public wxRichTextFileHandler
 {
 public:
     /**
-        ,  wxString&@e ext = wxT("html"), @b int@e type = wxRICHTEXT_TYPE_HTML)
         Constructor.
     */
-    wxRichTextHTMLHandler() const;
+    wxRichTextHTMLHandler(const wxString& name = wxT("HTML"),
+                          const wxString& ext = wxT("html"),
+                          int type = wxRICHTEXT_TYPE_HTML);
 
     /**
         Clears the image locations generated by the last operation.
     */
     void ClearTemporaryImageLocations();
 
-    //@{
     /**
-        Delete the in-memory or temporary files generated by the last operation. This
+        Deletes the in-memory or temporary files generated by the last operation.
-        is a static
-        function that can be used to delete the saved locations from an earlier
-        operation,
-        for example after the user has viewed the HTML file.
     */
     bool DeleteTemporaryImages();
+
+    /**
+        Delete the in-memory or temporary files generated by the last operation.
+        This is a static function that can be used to delete the saved locations
+        from an earlier operation, for example after the user has viewed the HTML file.
+    */
     bool DeleteTemporaryImages(int flags,
                                const wxArrayString& imageLocations);
-    //@}
 
     /**
         Saves the buffer content to the HTML stream.
@@ -83,22 +104,34 @@ public:
 
     /**
         Reset the file counter, in case, for example, the same names are required each
-        time
+        time.
     */
     static void SetFileCounter(int counter);
 
     /**
         Sets the mapping for converting point sizes to HTML font sizes.
+
         There should be 7 elements, one for each HTML font size, each element
-        specifying the maximum point size for that
+        specifying the maximum point size for that HTML font size.
-        HTML font size.
         For example:
+        @code
+        wxArrayInt fontSizeMapping;
+        fontSizeMapping.Add(7);
+        fontSizeMapping.Add(9);
+        fontSizeMapping.Add(11);
+        fontSizeMapping.Add(12);
+        fontSizeMapping.Add(14);
+        fontSizeMapping.Add(22);
+        fontSizeMapping.Add(100);
+
+        htmlHandler.SetFontSizeMapping(fontSizeMapping);
+        @endcode
     */
     void SetFontSizeMapping(const wxArrayInt& fontSizeMapping);
 
     /**
-        Sets the directory for storing temporary files. If empty, the system
+        Sets the directory for storing temporary files.
-        temporary directory will be used.
+        If empty, the system temporary directory will be used.
     */
     void SetTempDir(const wxString& tempDir);
 

interface/wx/richtext/richtextprint.h

@@ -6,27 +6,50 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+/**
+    These are the header and footer page identifiers, passed to functions such
+    as wxRichTextHeaderFooterData::SetFooterText to specify the odd or even page
+    for the text.
+*/
+enum wxRichTextOddEvenPage {
+    wxRICHTEXT_PAGE_ODD,
+    wxRICHTEXT_PAGE_EVEN,
+    wxRICHTEXT_PAGE_ALL,
+};
+
+
+/**
+    These are the location identifiers for passing to functions such as
+    wxRichTextHeaderFooterData::SetFooterText(), to specify whether the text
+    is on the left, centre or right of the page.
+*/
+enum wxRichTextPageLocation {
+    wxRICHTEXT_PAGE_LEFT,
+    wxRICHTEXT_PAGE_CENTRE,
+    wxRICHTEXT_PAGE_RIGHT
+};
+
+
 /**
     @class wxRichTextHeaderFooterData
 
 
     This class represents header and footer data to be passed to the
-    wxRichTextPrinting and
+    wxRichTextPrinting and wxRichTextPrintout classes.
-    wxRichTextPrintout classes.
 
     Headers and footers can be specified independently for odd, even or both page
-    sides. Different text can be specified
+    sides. Different text can be specified for left, centre and right locations
-    for left, centre and right locations on the page, and the font and text colour
+    on the page, and the font and text colour can also be specified.
-    can also
+
-    be specified. You can specify the following keywords in header and footer text,
+    You can specify the following keywords in header and footer text, which will
-    which will
     be substituted for the actual values during printing and preview.
 
-     @@DATE@: the current date.
+    - @@DATE@: the current date.
-     @@PAGESCNT@: the total number of pages.
+    - @@PAGESCNT@: the total number of pages.
-     @@PAGENUM@: the current page number.
+    - @@PAGENUM@: the current page number.
-     @@TIME@: the current time.
+    - @@TIME@: the current time.
-     @@TITLE@: the title of the document, as passed to the wxRichTextPrinting or
+    - @@TITLE@: the title of the document, as passed to the wxRichTextPrinting or
       wxRichTextLayout constructor.
 
     @library{wxrichtext}
@@ -56,7 +79,7 @@ public:
     /**
         Returns the font specified for printing the header and footer.
     */
-    const wxFont GetFont() const;
+    const wxFont& GetFont() const;
 
     /**
         Returns the margin between the text and the footer.
@@ -159,9 +182,8 @@ public:
 /**
     @class wxRichTextPrintout
 
-    This class implements print layout for wxRichTextBuffer. Instead of using it
+    This class implements print layout for wxRichTextBuffer.
-    directly, you
+    Instead of using it directly, you should normally use the wxRichTextPrinting class.
-    should normally use the wxRichTextPrinting class.
 
     @library{wxrichtext}
     @category{richtext}
@@ -170,10 +192,9 @@ class wxRichTextPrintout : public wxPrintout
 {
 public:
     /**
-        )
         Constructor.
     */
-    wxRichTextPrintout();
+    wxRichTextPrintout(const wxString& title = wxT("Printout"));
 
     /**
         Calculates scaling and text, header and footer rectangles.
@@ -225,9 +246,8 @@ public:
                     int right = 252);
 
     /**
-        Sets the buffer to print. wxRichTextPrintout does not manage this pointer; it
+        Sets the buffer to print. wxRichTextPrintout does not manage this pointer;
-        should
+        it should be managed by the calling code, such as wxRichTextPrinting.
-        be managed by the calling code, such as wxRichTextPrinting.
     */
     void SetRichTextBuffer(wxRichTextBuffer* buffer);
 };
@@ -247,16 +267,17 @@ class wxRichTextPrinting : public wxObject
 {
 public:
     /**
-        , @b wxWindow*@e parentWindow = @NULL)
+        Constructor.
-        Constructor. Optionally pass a title to be used in the preview frame and
+
-        printing wait dialog, and
+        Optionally pass a title to be used in the preview frame and printing wait
-        also a parent window for these windows.
+        dialog, and also a parent window for these windows.
     */
-    wxRichTextPrinting();
+    wxRichTextPrinting(const wxString& name = wxT("Printing"),
+                       wxWindow* parentWindow = NULL);
 
     /**
-        A convenience function to get the footer text. See wxRichTextHeaderFooterData
+        A convenience function to get the footer text.
-        for details.
+        See wxRichTextHeaderFooterData for details.
     */
     wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN,
                            wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const;
@@ -267,8 +288,8 @@ public:
     const wxRichTextHeaderFooterData GetHeaderFooterData() const;
 
     /**
-        A convenience function to get the header text. See wxRichTextHeaderFooterData
+        A convenience function to get the header text.
-        for details.
+        See wxRichTextHeaderFooterData for details.
     */
     wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN,
                            wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const;
@@ -279,8 +300,8 @@ public:
     wxPageSetupDialogData* GetPageSetupData();
 
     /**
-        Returns the parent window to be used for the preview window and printing wait
+        Returns the parent window to be used for the preview window and printing
-        dialog.
+        wait dialog.
     */
     wxWindow* GetParentWindow() const;
 
@@ -305,33 +326,33 @@ public:
     void PageSetup();
 
     /**
-        Shows a preview window for the given buffer. The function takes its own copy of
+        Shows a preview window for the given buffer.
-        @e buffer.
+        The function takes its own copy of @a buffer.
     */
     bool PreviewBuffer(const wxRichTextBuffer& buffer);
 
     /**
-        Shows a preview window for the given file. @a richTextFile can be a text file
+        Shows a preview window for the given file.
-        or XML file, or other file
+
+        @a richTextFile can be a text file or XML file, or other file
         depending on the available file handlers.
     */
     bool PreviewFile(const wxString& richTextFile);
 
     /**
-        Prints the given buffer. The function takes its own copy of @e buffer.
+        Prints the given buffer. The function takes its own copy of @a buffer.
     */
     bool PrintBuffer(const wxRichTextBuffer& buffer);
 
     /**
-        Prints the given file. @a richTextFile can be a text file or XML file, or other
+        Prints the given file. @a richTextFile can be a text file or XML file,
-        file
+        or other file depending on the available file handlers.
-        depending on the available file handlers.
     */
     bool PrintFile(const wxString& richTextFile);
 
     /**
-        A convenience function to set the footer text. See wxRichTextHeaderFooterData
+        A convenience function to set the footer text.
-        for details.
+        See wxRichTextHeaderFooterData for details.
     */
     void SetFooterText(const wxString& text,
                        wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL,
@@ -353,8 +374,8 @@ public:
     void SetHeaderFooterTextColour(const wxColour& colour);
 
     /**
-        A convenience function to set the header text. See wxRichTextHeaderFooterData
+        A convenience function to set the header text.
-        for details.
+        See wxRichTextHeaderFooterData for details.
     */
     void SetHeaderText(const wxString& text,
                        wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL,
@@ -366,8 +387,8 @@ public:
     void SetPageSetupData(const wxPageSetupData& pageSetupData);
 
     /**
-        Sets the parent window to be used for the preview window and printing wait
+        Sets the parent window to be used for the preview window and printing
-        dialog.
+        wait dialog.
     */
     void SetParentWindow(wxWindow* parent);
 

interface/wx/richtext/richtextstyledlg.h

@@ -9,8 +9,8 @@
 /**
     @class wxRichTextStyleOrganiserDialog
 
-    This class shows a style sheet and allows the user to edit, add and remove
+    This class shows a style sheet and allows the user to edit, add and remove styles.
-    styles.
+
     It can also be used as a style browser, for example if the application is not
     using a permanent wxRichTextStyleComboCtrl or wxRichTextStyleListCtrl to
     present styles.
@@ -21,85 +21,58 @@
 class wxRichTextStyleOrganiserDialog : public wxDialog
 {
 public:
-    //@{
     /**
-        Constructors.
+        Default ctor.
+    */
+    wxRichTextStyleOrganiserDialog();
+
+    /**
+        Constructor.
+
         To create a dialog, pass a bitlist of @a flags (see below), a style sheet, a
-        text control to apply a selected style to (or @NULL), followed by the usual window parameters.
+        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 @e flags:
 
-        @b wxRICHTEXT_ORGANISER_DELETE_STYLES
+        - @b wxRICHTEXT_ORGANISER_DELETE_STYLES: Provides a button for deleting styles.
-        
+        - @b wxRICHTEXT_ORGANISER_CREATE_STYLES: Provides buttons for creating styles.
-        Provides a button for deleting styles.
+        - @b wxRICHTEXT_ORGANISER_APPLY_STYLES: Provides a button for applying the
-        
+                                                currently selected style to the selection.
-        @b wxRICHTEXT_ORGANISER_CREATE_STYLES
+        - @b wxRICHTEXT_ORGANISER_EDIT_STYLES: Provides a button for editing styles.
-        
+        - @b wxRICHTEXT_ORGANISER_RENAME_STYLES: Provides a button for renaming styles.
-        Provides buttons for creating styles.
+        - @b wxRICHTEXT_ORGANISER_OK_CANCEL: Provides OK and Cancel buttons.
-        
+        - @b wxRICHTEXT_ORGANISER_RENUMBER: Provides a checkbox for specifying that
-        @b wxRICHTEXT_ORGANISER_APPLY_STYLES
+                                            the selection should be renumbered.
-        
-        Provides a button for applying the currently selected style to the selection.
-        
-        @b wxRICHTEXT_ORGANISER_EDIT_STYLES
-        
-        Provides a button for editing styles.
-        
-        @b wxRICHTEXT_ORGANISER_RENAME_STYLES
-        
-        Provides a button for renaming styles.
-        
-        @b wxRICHTEXT_ORGANISER_OK_CANCEL
-        
-        Provides OK and Cancel buttons.
-        
-        @b wxRICHTEXT_ORGANISER_RENUMBER
-        
-        Provides a checkbox for specifying that the selection should be renumbered.
 
         The following flags determine what will be displayed in the style list:
 
-        @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER
+        - @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER: Displays character styles only.
-        
+        - @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH: Displays paragraph styles only.
-        Displays character styles only.
+        - @b wxRICHTEXT_ORGANISER_SHOW_LIST: Displays list styles only.
-        
+        - @b wxRICHTEXT_ORGANISER_SHOW_ALL: Displays all styles.
-        @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH
-        
-        Displays paragraph styles only.
-        
-        @b wxRICHTEXT_ORGANISER_SHOW_LIST
-        
-        Displays list styles only.
-        
-        @b wxRICHTEXT_ORGANISER_SHOW_ALL
-        
-        Displays all styles.
 
         The following symbols define commonly-used combinations of flags:
 
-        @b wxRICHTEXT_ORGANISER_ORGANISE
+        - @b wxRICHTEXT_ORGANISER_ORGANISE:
-        
           Enable all style editing operations so the dialog behaves as a style organiser.
-        
+        - @b wxRICHTEXT_ORGANISER_BROWSE:
-        @b wxRICHTEXT_ORGANISER_BROWSE
-        
           Show a list of all styles and their previews, but only allow application of a
-        style or
+          style or cancellation of the dialog. This makes the dialog behave as a style browser.
-        cancellation of the dialog. This makes the dialog behave as a style browser.
+        - @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING:
-        
+          Enables only list style browsing, plus a control to specify renumbering.
-        @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING
+          This allows the dialog to be used for applying list styles to the selection.
-        
-        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.
     */
     wxRichTextStyleOrganiserDialog(int flags,
                                    wxRichTextStyleSheet* sheet,
                                    wxRichTextCtrl* ctrl,
                                    wxWindow* parent,
-                                   wxWindowID id = wxID_ANY);
+                                   wxWindowID id = wxID_ANY,
-    const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX)
+                                   const wxString& caption = _("Style Organiser"),
-    wxRichTextStyleOrganiserDialog();
+                                   const wxPoint& pos = wxDefaultPosition,
-    //@}
+                                   const wxSize& size = wxDefaultSize,
+                                   long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX);
 
     /**
         Applies the selected style to selection in the given control or the control
@@ -108,14 +81,17 @@ public:
     bool ApplyStyle(wxRichTextCtrl* ctrl = NULL);
 
     /**
-        ,  wxPoint&@e pos = wxDefaultPosition,  wxSize&@e size = wxDefaultSize, @b
+        Creates the dialog. See the ctor.
-        long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX)
-        Creates the dialog. See
     */
-    bool Create(int flags, wxRichTextStyleSheet* sheet,
+    bool Create(int flags,
+                wxRichTextStyleSheet* sheet,
                 wxRichTextCtrl* ctrl,
                 wxWindow* parent,
-                wxWindowID id = wxID_ANY) const;
+                wxWindowID id = wxID_ANY,
+                const wxString& caption = _("Style Organiser"),
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX);
 
     /**
         Returns @true if the user has opted to restart numbering.

interface/wx/richtext/richtextstyles.h

@@ -9,19 +9,21 @@
 /**
     @class wxRichTextStyleListCtrl
 
-    This class incorporates a wxRichTextStyleListBox and
+    This class incorporates a wxRichTextStyleListBox and a choice control that
-    a choice control that allows the user to select the category of style to view.
+    allows the user to select the category of style to view.
+
     It is demonstrated in the wxRichTextCtrl sample in @c samples/richtext.
 
     To use wxRichTextStyleListCtrl, add the control to your window hierarchy and
-    call wxRichTextStyleListCtrl::SetStyleType with
+    call wxRichTextStyleListCtrl::SetStyleType with one of
-    one of wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
+    wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
     wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
     wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and
     wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST to set the current view.
+
     Associate the control with a style sheet and rich text control with
-    SetStyleSheet and SetRichTextCtrl,
+    SetStyleSheet and SetRichTextCtrl, so that when a style is double-clicked,
-    so that when a style is double-clicked, it is applied to the selection.
+    it is applied to the selection.
 
     @beginStyleTable
     @style{wxRICHTEXTSTYLELIST_HIDE_TYPE_SELECTOR}
@@ -29,7 +31,7 @@
     @endStyleTable
 
     @library{wxrichtext}
-    @category{FIXME}
+    @category{richtext}
 */
 class wxRichTextStyleListCtrl : public wxControl
 {
@@ -90,10 +92,13 @@ public:
     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 
     /**
-        Sets the style type to display. One of
+        Sets the style type to display.
-        wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
+
-        wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and
+        One of
-        wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
     */
     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 
@@ -111,7 +116,7 @@ public:
     This is a base class for paragraph and character styles.
 
     @library{wxrichtext}
-    @category{FIXME}
+    @category{richtext}
 */
 class wxRichTextStyleDefinition : public wxObject
 {
@@ -224,8 +229,7 @@ public:
     @library{wxrichtext}
     @category{richtext}
 
-    @see wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview
+    @see wxRichTextStyleComboCtrl, @ref overview_richtextctrl
-    "wxRichTextCtrl overview"
 */
 class wxRichTextStyleListBox : public wxHtmlListBox
 {
@@ -261,8 +265,7 @@ public:
 
     /**
         If the return value is @true, clicking on a style name in the list will
-        immediately
+        immediately apply the style to the associated rich text control.
-        apply the style to the associated rich text control.
     */
     bool GetApplyOnSelection() const;
 
@@ -304,8 +307,7 @@ public:
 
     /**
         If @a applyOnSelection is @true, clicking on a style name in the list will
-        immediately
+        immediately apply the style to the associated rich text control.
-        apply the style to the associated rich text control.
     */
     void SetApplyOnSelection(bool applyOnSelection);
 
@@ -321,9 +323,10 @@ public:
 
     /**
         Sets the style type to display. One of
-        wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
-        wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
-        wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER
+        - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
     */
     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 
@@ -346,8 +349,7 @@ public:
     @library{wxrichtext}
     @category{richtext}
 
-    @see wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview
+    @see wxRichTextStyleListBox, @ref overview_richtextctrl
-    "wxRichTextCtrl overview"
 */
 class wxRichTextStyleComboCtrl : public wxComboCtrl
 {
@@ -425,18 +427,16 @@ public:
     This class represents a list style definition, usually added to a
     wxRichTextStyleSheet.
 
-    The class inherits paragraph attributes from
+    The class inherits paragraph attributes from wxRichTextStyleParagraphDefinition,
-    wxRichTextStyleParagraphDefinition, and adds 10 further attribute objects, one for each level of a list.
+    and adds 10 further attribute objects, one for each level of a list.
     When applying a list style to a paragraph, the list style's base and
-    appropriate level attributes are merged with the
+    appropriate level attributes are merged with the paragraph's existing attributes.
-    paragraph's existing attributes.
 
-    You can apply a list style to one or more paragraphs using
+    You can apply a list style to one or more paragraphs using wxRichTextCtrl::SetListStyle.
-    wxRichTextCtrl::SetListStyle. You
+    You can also use the functions wxRichTextCtrl::NumberList, wxRichTextCtrl::PromoteList and
-    can also use the functions wxRichTextCtrl::NumberList,
+    wxRichTextCtrl::ClearListStyle.
-    wxRichTextCtrl::PromoteList and
+
-    wxRichTextCtrl::ClearListStyle. As usual, there are wxRichTextBuffer versions
+    As usual, there are wxRichTextBuffer versions of these functions
-    of these functions
     so that you can apply them directly to a buffer without requiring a control.
 
     @library{wxrichtext}
@@ -458,6 +458,7 @@ public:
     /**
         This function combines the given paragraph style with the list style's base
         attributes and level style matching the given indent, returning the combined attributes.
+
         If @a styleSheet is specified, the base style for this definition will also be
         included in the result.
     */
@@ -474,6 +475,7 @@ public:
     /**
         This function combines the list style's base attributes and the level style
         matching the given indent, returning the combined attributes.
+
         If @a styleSheet is specified, the base style for this definition will also be
         included in the result.
     */
@@ -483,6 +485,7 @@ public:
     /**
         This function combines the list style's base attributes and the style for the
         specified level, returning the combined attributes.
+
         If @a styleSheet is specified, the base style for this definition will also be
         included in the result.
     */
@@ -527,9 +530,8 @@ public:
     A style sheet contains named paragraph and character styles that make it
     easy for a user to apply combinations of attributes to a wxRichTextCtrl.
 
-    You can use a wxRichTextStyleListBox in your
+    You can use a wxRichTextStyleListBox in your user interface to show available
-    user interface to show available styles to the user, and allow application
+    styles to the user, and allow application of styles to the control.
-    of styles to the control.
 
     @library{wxrichtext}
     @category{richtext}

interface/wx/richtext/richtextsymboldlg.h

@@ -17,20 +17,19 @@
     is generic and can be used in other contexts.
 
     To use the dialog, pass a default symbol specified as a string, an initial font
-    name,
+    name, and a current font name. The difference between the initial font and
-    and a current font name. The difference between the initial font and
     current font is that the initial font determines what the font control will be
-    set to when the dialog shows - an empty string will show the selection @e
+    set to when the dialog shows - an empty string will show the selection
-    normal text.
+    @e normal text.
     The current font, on the other hand, is used by the dialog to determine what
-    font
+    font to display the characters in, even when no initial font is selected.
-    to display the characters in, even when no initial font is selected.
     This allows the user (and application) to distinguish between inserting a
     symbol in the current font, and inserting it with a specified font.
 
     When the dialog is dismissed, the application can get the selected symbol
-    with GetSymbol and test whether a font was specified with UseNormalFont,
+    with wxSymbolPickerDialog::GetSymbol and test whether a font was specified
-    fetching the specified font with GetFontName.
+    with wxSymbolPickerDialog::UseNormalFont,fetching the specified font with
+    wxSymbolPickerDialog::GetFontName.
 
     Here's a realistic example, inserting the supplied symbol into a
     rich text control in either the current font or specified font.
@@ -40,7 +39,7 @@
 
         wxTextAttr attr;
         attr.SetFlags(wxTEXT_ATTR_FONT);
-        ctrl-GetStyle(ctrl-GetInsertionPoint(), attr);
+        ctrl-GetStyle(ctrl->GetInsertionPoint(), attr);
 
         wxString currentFontName;
         if (attr.HasFont() && attr.GetFont().Ok())
@@ -58,7 +57,7 @@
             {
                 long insertionPoint = ctrl-GetInsertionPoint();
 
-                ctrl-WriteText(dlg.GetSymbol());
+                ctrl->WriteText(dlg.GetSymbol());
 
                 if (!dlg.UseNormalFont())
                 {
@@ -77,19 +76,23 @@
 class wxSymbolPickerDialog : public wxDialog
 {
 public:
-    //@{
     /**
-        Constructors.
+        Default ctor.
+    */
+    wxSymbolPickerDialog();
+
+    /**
+        Constructor.
 
         @param symbol
-            The initial symbol to show. Specify a single character in a string, or an
+            The initial symbol to show.
-        empty string.
+            Specify a single character in a string, or an empty string.
         @param initialFont
-            The initial font to be displayed in the font list. If empty, the item
+            The initial font to be displayed in the font list.
-        normal text will be selected.
+            If empty, the item normal text will be selected.
         @param normalTextFont
-            The font the dialog will use to display the symbols if the initial font is
+            The font the dialog will use to display the symbols if the
-        empty.
+            initial font is empty.
         @param parent
             The dialog's parent.
         @param id
@@ -107,21 +110,25 @@ public:
                          const wxString& initialFont,
                          const wxString& normalTextFont,
                          wxWindow* parent,
-                         wxWindowID id = wxID_ANY);
+                         wxWindowID id = wxID_ANY,
-    const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX)
+                         const wxString& title = _("Symbols"),
-    wxSymbolPickerDialog();
+                         const wxPoint& pos = wxDefaultPosition,
-    //@}
+                         const wxSize& size = wxDefaultSize,
+                         long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX);
 
     /**
-        ,  wxPoint&@e pos = wxDefaultPosition,  wxSize&@e size = wxDefaultSize, @b
+        Creation: see @ref wxSymbolPickerDialog() "the constructor" for details about
-        long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX)
-        Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about
         the parameters.
     */
-    bool Create(const wxString& symbol, const wxString& initialFont,
+    bool Create(const wxString& symbol,
+                const wxString& initialFont,
                 const wxString& normalTextFont,
                 wxWindow* parent,
-                wxWindowID id = wxID_ANY) const;
+                wxWindowID id = wxID_ANY,
+                const wxString& title = _("Symbols"),
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX);
 
     /**
         Returns the font name (the font reflected in the font list).
@@ -134,8 +141,7 @@ public:
     bool GetFromUnicode() const;
 
     /**
-        Gets the font name used for displaying symbols in the absence of a selected
+        Gets the font name used for displaying symbols in the absence of a selected font.
-        font.
     */
     wxString GetNormalTextFontName() const;
 
@@ -181,8 +187,7 @@ public:
     void SetUnicodeMode(bool unicodeMode);
 
     /**
-        Returns @true if the has specified normal text - that is, there is no selected
+        Returns @true if the has specified normal text - that is, there is no selected font.
-        font.
     */
     bool UseNormalFont() const;
 };

interface/wx/richtext/richtextxml.h

@@ -10,10 +10,21 @@
     @class wxRichTextXMLHandler
 
     A handler for loading and saving content in an XML format specific
-    to wxRichTextBuffer. You can either add the handler to the buffer
+    to wxRichTextBuffer.
-    and load and save through the buffer or control API, or you can
+
-    create an instance of the handler on the stack and call its
+    You can either add the handler to the buffer and load and save through
-    functions directly.
+    the buffer or control API, or you can create an instance of the handler
+    on the stack and call its functions directly.
+
+
+    @section richtextxmlhandler_flags Handler flags
+
+    The following flags can be used with this handler, via the handler's SetFlags()
+    function or the buffer or control's SetHandlerFlags() function:
+
+    - wxRICHTEXT_HANDLER_INCLUDE_STYLESHEET
+      Include the style sheet in loading and saving operations.
+
 
     @library{wxrichtext}
     @category{richtext}
@@ -22,10 +33,11 @@ class wxRichTextXMLHandler : public wxRichTextFileHandler
 {
 public:
     /**
-        ,  wxString&@e ext = wxT("xml"), @b int@e type = wxRICHTEXT_TYPE_XML)
         Constructor.
     */
-    wxRichTextXMLHandler() const;
+    wxRichTextXMLHandler(const wxString& name = wxT("XML"),
+                         const wxString& ext = wxT("xml"),
+                         int type = wxRICHTEXT_TYPE_XML) const;
 
     /**
         Returns @true.