final f*h interface header reviews

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

docs/doxygen/overviews/xrc_format.h

@@ -362,7 +362,7 @@ In most cases, specifying @c stock_client is not needed.
 Examples of stock bitmaps usage:
 @code
 <bitmap stock_id="fixed-width"/>        <!-- custom app-specific art -->
-<bitmap stock_id="wxART_FILE_OPEN"/>    <!-- standard art->
+<bitmap stock_id="wxART_FILE_OPEN"/>    <!-- standard art -->
 @endcode
 
 Specifying the bitmap directly and using @c stock_id are mutually exclusive.

interface/wx/filepicker.h

@@ -262,6 +262,13 @@ public:
     This event class is used for the events generated by
     wxFilePickerCtrl and by wxDirPickerCtrl.
 
+    @beginEventTable{wxFileDirPickerEvent}
+    @event{EVT_FILEPICKER_CHANGED(id, func)}
+        Generated whenever the selected file changes.
+    @event{EVT_DIRPICKER_CHANGED(id, func)}
+        Generated whenever the selected directory changes.
+    @endEventTable
+
     @library{wxcore}
     @category{events}
 

interface/wx/font.h

@@ -369,7 +369,7 @@ public:
     /**
         Destructor.
 
-        See @ref overview_refcountdestruct "reference-counted object destruction"
+        See @ref overview_refcount_destruct "reference-counted object destruction"
         for more info.
 
         @remarks Although all remaining fonts are deleted when the application
@@ -466,8 +466,9 @@ public:
 
     //@{
     /**
-        These functions take the same parameters as @ref ctor() wxFont
+        These functions take the same parameters as
-        constructor and return a new font object allocated on the heap.
+        @ref wxFont::wxFont "wxFont constructors" and return a new font
+        object allocated on the heap.
 
         Using @c New() is currently the only way to directly create a font with
         the given size in pixels on platforms other than wxMSW.
@@ -610,7 +611,7 @@ public:
     /**
         Inequality operator.
 
-        See @ref overview_refcountequality "reference-counted object comparison" for
+        See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */
     bool operator !=(const wxFont& font);
@@ -618,7 +619,7 @@ public:
     /**
         Equality operator.
 
-        See @ref overview_refcountequality "reference-counted object comparison" for
+        See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */
     bool operator ==(const wxFont& font);

interface/wx/fontdlg.h

@@ -14,7 +14,7 @@
     @library{wxcore}
     @category{cmndlg}
 
-    @see Overview(), wxFontData, wxGetFontFromUser()
+    @see overview_cmndlg_font, wxFontData, wxGetFontFromUser()
 */
 class wxFontDialog : public wxDialog
 {
@@ -32,7 +32,7 @@ public:
 
     /**
         Constructor.
-        Pass a parent window, and the @ref overview_wxfontdata "font data" object
+        Pass a parent window, and the @ref wxFontData "font data" object
         to be used to initialize the dialog controls.
     */
     wxFontDialog(wxWindow* parent, const wxFontData& data);
@@ -55,7 +55,7 @@ public:
 
     //@{
     /**
-        Returns the @ref overview_wxfontdata "font data" associated with the
+        Returns the @ref wxFontData "font data" associated with the
         font dialog.
     */
     const wxFontData& GetFontData() const;

interface/wx/fontenum.h

@@ -30,7 +30,7 @@
     @library{wxcore}
     @category{gdi}
 
-    @see @ref overview_fontencoding, @ref sample_font, wxFont, wxFontMapper
+    @see @ref overview_fontencoding, @ref page_samples_font, wxFont, wxFontMapper
 */
 class wxFontEnumerator
 {

interface/wx/fontmap.h

@@ -24,31 +24,60 @@
 
     In case everything else fails (i.e. there is no record in config file
     and "interactive" is @false or user denied to choose any replacement),
-    the class queries wxEncodingConverter
+    the class queries wxEncodingConverter for "equivalent" encodings
-    for "equivalent" encodings (e.g. iso8859-2 and cp1250) and tries them.
+    (e.g. iso8859-2 and cp1250) and tries them.
+
+
+    @section fontmapper_mbconv Using wxFontMapper in conjunction with wxMBConv classes
+
+    If you need to display text in encoding which is not available at host
+    system (see wxFontMapper::IsEncodingAvailable), you may use these two
+    classes to find font in some similar encoding (see wxFontMapper::GetAltForEncoding)
+    and convert the text to this encoding (wxMBConv classes).
+    Following code snippet demonstrates it:
+
+    @code
+    if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
+    {
+        wxFontEncoding alternative;
+        if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
+                                                    facename, false))
+        {
+            wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
+            wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
+            text = wxString(text.mb_str(convFrom), convTo);
+        }
+        else
+            ...failure (or we may try iso8859-1/7bit ASCII)...
+    }
+    ...display text...
+    @endcode
 
     @library{wxcore}
     @category{misc}
 
-    @see wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English
+    @see wxEncodingConverter, @ref overview_nonenglish "Writing non-English applications"
-    applications"
 */
 class wxFontMapper
 {
 public:
     /**
         Default ctor.
+
+        @note
+        The preferred way of creating a wxFontMapper instance is to call wxFontMapper::Get().
     */
     wxFontMapper();
 
     /**
-        Virtual dtor for a base class.
+        Virtual dtor.
     */
-    ~wxFontMapper();
+    virtual ~wxFontMapper();
 
     /**
         Returns the encoding for the given charset (in the form of RFC 2046) or
         @c wxFONTENCODING_SYSTEM if couldn't decode it.
+
         Be careful when using this function with @a interactive set to @true
         (default value) as the function then may show a dialog box to the user which
         may lead to unexpected reentrancies and may also take a significantly longer
@@ -60,17 +89,17 @@ public:
                                      bool interactive = true);
 
     /**
-        Get the current font mapper object. If there is no current object, creates
+        Get the current font mapper object. If there is no current object, creates one.
-        one.
 
         @see Set()
     */
     static wxFontMapper* Get();
 
     /**
-        Returns the array of all possible names for the given encoding. The array is
+        Returns the array of all possible names for the given encoding.
-        @NULL-terminated. IF it isn't empty, the first name in it is the canonical
+
-        encoding name, i.e. the same string as returned by
+        The array is @NULL-terminated. IF it isn't empty, the first name in it is
+        the canonical encoding name, i.e. the same string as returned by
         GetEncodingName().
     */
     static const wxChar** GetAllEncodingNames(wxFontEncoding encoding);
@@ -81,6 +110,7 @@ public:
         available on this system). If successful, return @true and fill info
         structure with the parameters required to create the font, otherwise
         return @false.
+
         The first form is for wxWidgets' internal use while the second one
         is better suitable for general use -- it returns wxFontEncoding which
         can consequently be passed to wxFont constructor.
@@ -96,9 +126,10 @@ public:
     //@}
 
     /**
-        Returns the @e n-th supported encoding. Together with
+        Returns the @e n-th supported encoding.
-        GetSupportedEncodingsCount()
+
-        this method may be used to get all supported encodings.
+        Together with GetSupportedEncodingsCount() this method may be used
+        to get all supported encodings.
     */
     static wxFontEncoding GetEncoding(size_t n);
 
@@ -108,27 +139,26 @@ public:
     static wxString GetEncodingDescription(wxFontEncoding encoding);
 
     /**
-        Return the encoding corresponding to the given internal name. This function is
+        Return the encoding corresponding to the given internal name.
-        the inverse of GetEncodingName() and is
+
-        intentionally less general than
+        This function is the inverse of GetEncodingName() and is intentionally
-        CharsetToEncoding(), i.e. it doesn't
+        less general than CharsetToEncoding(), i.e. it doesn't try to make any
-        try to make any guesses nor ever asks the user. It is meant just as a way of
+        guesses nor ever asks the user. It is meant just as a way of restoring
-        restoring objects previously serialized using
+        objects previously serialized using GetEncodingName().
-        GetEncodingName().
     */
     static wxFontEncoding GetEncodingFromName(const wxString& encoding);
 
     /**
         Return internal string identifier for the encoding (see also
-        wxFontMapper::GetEncodingDescription)
+        wxFontMapper::GetEncodingDescription).
 
         @see GetEncodingFromName()
     */
     static wxString GetEncodingName(wxFontEncoding encoding);
 
     /**
-        Returns the number of the font encodings supported by this class. Together with
+        Returns the number of the font encodings supported by this class.
-        GetEncoding() this method may be used to get
+        Together with GetEncoding() this method may be used to get
         all supported encodings.
     */
     static size_t GetSupportedEncodingsCount();
@@ -152,8 +182,8 @@ public:
     /**
         Set the config object to use (may be @NULL to use default).
         By default, the global one (from wxConfigBase::Get() will be used)
-        and the default root path for the config settings is the string returned by
+        and the default root path for the config settings is the string returned
-        GetDefaultConfigPath().
+        by GetDefaultConfigPath().
     */
     void SetConfig(wxConfigBase* config);
 

interface/wx/fontpicker.h

@@ -12,14 +12,12 @@
     This control allows the user to select a font. The generic implementation is
     a button which brings up a wxFontDialog when clicked. Native implementation
     may differ but this is usually a (small) widget which give access to the
-    font-chooser
+    font-chooser dialog.
-    dialog.
     It is only available if @c wxUSE_FONTPICKERCTRL is set to 1 (the default).
 
     @beginStyleTable
     @style{wxFNTP_DEFAULT_STYLE}
-           The default style: wxFNTP_FONTDESC_AS_LABEL |
+           The default style: wxFNTP_FONTDESC_AS_LABEL | wxFNTP_USEFONT_FOR_LABEL.
-           wxFNTP_USEFONT_FOR_LABEL.
     @style{wxFNTP_USE_TEXTCTRL}
            Creates a text control to the left of the picker button which is
            completely managed by the wxFontPickerCtrl and which can be used by
@@ -35,6 +33,13 @@
            Uses the currently selected font to draw the label of the button.
     @endStyleTable
 
+    @beginEventTable{wxFontPickerEvent}
+    @event{EVT_FONTPICKER_CHANGED(id, func)}
+        The user changed the font selected in the control either using the button
+        or using text control (see wxFNTP_USE_TEXTCTRL; note that in this case the
+        event is fired only if the user's input is valid, i.e. recognizable).
+    @endEventTable
+
     @library{wxcore}
     @category{pickers}
     <!-- @appearance{fontpickerctrl.png} -->
@@ -57,13 +62,15 @@ public:
                      const wxString& name = "fontpickerctrl");
 
     /**
+        Creates this widget with given parameters.
+
         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param font
-            The initial font shown in the control. If wxNullFont
+            The initial font shown in the control.
-            is given, the default font is used.
+            If ::wxNullFont is given, the default font is used.
         @param pos
             Initial position.
         @param size
@@ -99,13 +106,12 @@ public:
 
     /**
         Sets the maximum point size value allowed for the user-chosen font.
+
         The default value is 100. Note that big fonts can require a lot of memory and
-        CPU time
+        CPU time both for creation and for rendering; thus, specially because the user
-        both for creation and for rendering; thus, specially because the user has the
+        has the option to specify the fontsize through a text control
-        option to specify
+        (see wxFNTP_USE_TEXTCTRL), it's a good idea to put a limit to the maximum
-        the fontsize through a text control (see wxFNTP_USE_TEXTCTRL), it's a good idea
+        font size when huge fonts do not make much sense.
-        to put a limit
-        to the maximum font size when huge fonts do not make much sense.
     */
     void GetMaxPointSize(unsigned int max);
 
@@ -124,8 +130,13 @@ public:
     This event class is used for the events generated by
     wxFontPickerCtrl.
 
+    @beginEventTable{wxFontPickerEvent}
+    @event{EVT_FONTPICKER_CHANGED(id, func)}
+        Generated whenever the selected font changes.
+    @endEventTable
+
     @library{wxcore}
-    @category{FIXME}
+    @category{events}
 
     @see wxFontPickerCtrl
 */

interface/wx/frame.h

@@ -24,7 +24,7 @@
              data and subwindows can be cleaned up.
 
 
-    @section wxframe_defaultevent Default event processing
+    @section frame_defaultevent Default event processing
 
     wxFrame processes the following events:
 
@@ -36,6 +36,10 @@
         associated with the selected item in the first pane of the status bar, if there is one.
 
 
+    @section frame_styles
+
+    wxFrame supports the following styles:
+
     @beginStyleTable
     @style{wxDEFAULT_FRAME_STYLE}
            Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxRESIZE_BORDER |
@@ -114,7 +118,11 @@
 class wxFrame : public wxTopLevelWindow
 {
 public:
-    //@{
+    /**
+        Default constructor.
+    */
+    wxFrame();
+
     /**
         Constructor, creating the window.
 
@@ -122,39 +130,33 @@ public:
             The window parent. This may be @NULL. If it is non-@NULL, the frame will
             always be displayed on top of the parent window on Windows.
         @param id
-            The window identifier. It may take a value of -1 to indicate a default
+            The window identifier. It may take a value of -1 to indicate a default value.
-        value.
         @param title
             The caption to be displayed on the frame's title bar.
         @param pos
             The window position. The value wxDefaultPosition indicates a default position,
-        chosen by
+            chosen by either the windowing system or wxWidgets, depending on platform.
-            either the windowing system or wxWidgets, depending on platform.
         @param size
             The window size. The value wxDefaultSize indicates a default size, chosen by
             either the windowing system or wxWidgets, depending on platform.
         @param style
-            The window style. See wxFrame.
+            The window style. See wxFrame class description.
         @param name
-            The name of the window. This parameter is used to associate a name with the
+            The name of the window. This parameter is used to associate a name with
-        item,
+            the item, allowing the application user to set Motif resource values for
-            allowing the application user to set Motif resource values for
             individual windows.
 
         @remarks For Motif, MWM (the Motif Window Manager) should be running for
-                 any window styles to work (otherwise all styles take
+                 any window styles to work (otherwise all styles take effect).
-                 effect).
 
         @see Create()
     */
-    wxFrame();
     wxFrame(wxWindow* parent, wxWindowID id,
             const wxString& title,
             const wxPoint& pos = wxDefaultPosition,
             const wxSize& size = wxDefaultSize,
             long style = wxDEFAULT_FRAME_STYLE,
             const wxString& name = "frame");
-    //@}
 
     /**
         Destructor. Destroys all child windows and menu bar if present.
@@ -170,8 +172,8 @@ public:
     void Centre(int direction = wxBOTH);
 
     /**
-        Used in two-step frame construction. See wxFrame()
+        Used in two-step frame construction.
-        for further details.
+        See wxFrame() for further details.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& title,
@@ -187,16 +189,15 @@ public:
             The number of fields to create. Specify a
             value greater than 1 to create a multi-field status bar.
         @param style
-            The status bar style. See wxStatusBar for a list
+            The status bar style. See wxStatusBar for a list of valid styles.
-            of valid styles.
         @param id
-            The status bar window identifier. If -1, an identifier will be chosen by
+            The status bar window identifier. If -1, an identifier will be chosen
-            wxWidgets.
+            by wxWidgets.
         @param name
             The status bar window name.
 
         @return A pointer to the status bar if it was created successfully, @NULL
-                 otherwise.
+                otherwise.
 
         @remarks The width of the status bar is the whole width of the frame
                  (adjusted automatically when resizing), and the height
@@ -213,32 +214,39 @@ public:
         Creates a toolbar at the top or left of the frame.
 
         @param style
-            The toolbar style. See wxToolBar for a list
+            The toolbar style. See wxToolBar for a list of valid styles.
-            of valid styles.
         @param id
-            The toolbar window identifier. If -1, an identifier will be chosen by
+            The toolbar window identifier. If -1, an identifier will be chosen
-            wxWidgets.
+            by wxWidgets.
         @param name
             The toolbar window name.
 
         @return A pointer to the toolbar if it was created successfully, @NULL
-                 otherwise.
+                otherwise.
 
         @remarks By default, the toolbar is an instance of wxToolBar (which is
                  defined to be a suitable toolbar class on each
                  platform, such as wxToolBar95). To use a different
                  class, override OnCreateToolBar().
+                 When a toolbar has been created with this function, or made
+                 known to the frame with wxFrame::SetToolBar, the frame will
+                 manage the toolbar position and adjust the return value from
+                 wxWindow::GetClientSize to reflect the available space for
+                 application windows.
+                 Under Pocket PC, you should always use this function for creating
+                 the toolbar to be managed by the frame, so that wxWidgets can
+                 use a combined menubar and toolbar.
+                 Where you manage your own toolbars, create a wxToolBar as usual.
 
-        @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(),
+        @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar()
-             GetToolBar()
     */
     virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
                                      wxWindowID id = -1,
                                      const wxString& name = "toolBar");
 
     /**
-        Returns the origin of the frame client area (in client coordinates). It may be
+        Returns the origin of the frame client area (in client coordinates).
-        different from (0, 0) if the frame has a toolbar.
+        It may be different from (0, 0) if the frame has a toolbar.
     */
     wxPoint GetClientAreaOrigin() const;
 
@@ -250,8 +258,8 @@ public:
     wxMenuBar* GetMenuBar() const;
 
     /**
-        Returns a pointer to the status bar currently associated with the frame (if
+        Returns a pointer to the status bar currently associated with the frame
-        any).
+        (if any).
 
         @see CreateStatusBar(), wxStatusBar
     */
@@ -338,6 +346,10 @@ public:
                  destroyed also, so do not delete the menu bar
                  explicitly (except by resetting the frame's menu bar to
                  another frame or @NULL).
+                 Under Windows, a size event is generated, so be sure to
+                 initialize data members properly before calling SetMenuBar().
+                 Note that on some platforms, it is not possible to call this
+                 function twice for the same frame object.
 
         @see GetMenuBar(), wxMenuBar, wxMenu.
     */
@@ -379,14 +391,12 @@ public:
         @param widths
             Must contain an array of n integers, each of which is a status field width
             in pixels. A value of -1 indicates that the field is variable width; at
-        least one
+            least one field must be -1. You should delete this array after calling
-            field must be -1. You should delete this array after calling
+            SetStatusWidths().
-        SetStatusWidths.
 
         @remarks The widths of the variable fields are calculated from the total
                  width of all fields, minus the sum of widths of the
-                 non-variable fields, divided by the number of variable
+                 non-variable fields, divided by the number of variable fields.
-                 fields.
     */
     virtual void SetStatusWidths(int n, int* widths);