More interface header reviews by Azriel Fasten, along with a simple item "add" group for wxSizer.

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

interface/defs.h

@@ -6,6 +6,49 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Item kinds for use with wxMenu, wxMenuItem, and wxToolBar.
+    
+    @see wxMenu::Append(), wxMenuItem::wxMenuItem(), wxToolBar::AddTool()
+*/
+enum wxItemKind
+{
+    wxITEM_SEPARATOR = -1,
+
+    /**
+        Normal tool button / menu item.
+
+        @see wxToolBar::AddTool(), wxMenu::AppendItem().
+    */
+    wxITEM_NORMAL,
+
+    /**
+        Check (or toggle) tool button / menu item.
+
+        @see wxToolBar::AddCheckTool(), wxMenu::AppendCheckItem().
+    */
+    wxITEM_CHECK,
+
+    /**
+        Radio tool button / menu item.
+
+        @see wxToolBar::AddRadioTool(), wxMenu::AppendRadioItem().
+    */
+    wxITEM_RADIO,
+
+    /**
+        Normal tool button with a dropdown arrow next to it. Clicking the
+        dropdown arrow sends a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event and may
+        also display the menu previously associated with the item with
+        wxToolBar::SetDropdownMenu(). Currently this type of tools is supported
+        under MSW and GTK.
+    */
+    wxITEM_DROPDOWN,
+
+    wxITEM_MAX
+};
+
+
 /**
     Paper size types for use with the printing framework.
 
@@ -316,3 +359,4 @@ void wxVaCopy(va_list argptrDst, va_list argptrSrc);
 
 //@}
 
+

interface/sizer.h

@@ -767,6 +767,9 @@ public:
     */
     ~wxSizer();
 
+    /** @name Item Management */
+    //@{
+
     /**
         Appends a child to the sizer.
 
@@ -940,6 +943,8 @@ public:
     */
     wxSizerItem* AddStretchSpacer(int prop = 1);
 
+    //@}
+
     /**
         This method is abstract and has to be overwritten by any derived class.
         Here, the sizer will do the actual calculation of its children's minimal sizes.

interface/toolbook.h

@@ -10,32 +10,34 @@
     @class wxToolbook
     @wxheader{toolbook.h}
 
-    wxToolbook is a class similar to wxNotebook but which
+    wxToolbook is a class similar to wxNotebook but which uses a wxToolBar to
-    uses a wxToolBar to show the labels instead of the
+    show the labels instead of the tabs.
-    tabs.
 
-    There is no documentation for this class yet but its usage is
+    There is no documentation for this class yet but its usage is identical to
-    identical to wxNotebook (except for the features clearly related to tabs
+    wxNotebook (except for the features clearly related to tabs only), so please
-    only), so please refer to that class documentation for now. You can also
+    refer to that class documentation for now. You can also use the
-    use the @ref overview_samplenotebook "notebook sample" to see wxToolbook in
+    @ref page_samples_notebook to see wxToolbook in action.
-    action.
 
     @beginStyleTable
     @style{wxTBK_BUTTONBAR}
-           Use wxButtonToolBar-based implementation under Mac OS (ignored
+        Use wxButtonToolBar-based implementation under Mac OS (ignored under
-           under other platforms.)
+        other platforms).
     @style{wxTBK_HORZ_LAYOUT}
-           Shows the text and the icons alongside, not vertically stacked
+        Shows the text and the icons alongside, not vertically stacked (only
-           (only implement under Windows and GTK 2 platforms as it relies on
+        implement under Windows and GTK 2 platforms as it relies on @c
-           wxTB_HORZ_LAYOUT flag support).
+        wxTB_HORZ_LAYOUT flag support).
     @endStyleTable
 
-    @library{wxcore}
+    The common wxBookCtrl styles described in the @ref overview_bookctrl are
-    @category{FIXME}
+    also supported.
 
-    @see wxBookCtrl(), wxNotebook, @ref overview_samplenotebook "notebook sample"
+    @library{wxcore}
+    @category{miscwnd}
+
+    @see @ref overview_bookctrl, wxBookCtrlBase, wxNotebook,
+         @ref page_samples_notebook
 */
-class wxToolbook : public wxBookCtrl overview
+class wxToolbook : public wxBookCtrlBase
 {
 public:
 

interface/tooltip.h

@@ -10,13 +10,11 @@
     @class wxToolTip
     @wxheader{tooltip.h}
 
-    This class holds information about a tooltip associated with a window
+    This class holds information about a tooltip associated with a window (see
-    (see wxWindow::SetToolTip).
+    wxWindow::SetToolTip()).
 
-    The four static methods, wxToolTip::Enable,
+    The four static methods, wxToolTip::Enable(), wxToolTip::SetDelay()
-    wxToolTip::SetDelay
+    wxToolTip::SetAutoPop() and wxToolTip::SetReshow() can be used to globally
-    wxToolTip::SetAutoPop and
-    wxToolTip::SetReshow can be used to globally
     alter tooltips behaviour.
 
     @library{wxcore}
@@ -32,7 +30,8 @@ public:
 
     /**
         Enable or disable tooltips globally.
-        May not be supported on all platforms (eg. wxCocoa).
+
+        @note May not be supported on all platforms (eg. wxCocoa).
     */
     static void Enable(bool flag);
 
@@ -47,21 +46,24 @@ public:
     wxWindow* GetWindow() const;
 
     /**
-        Set the delay after which the tooltip disappears or how long a
+        Set the delay after which the tooltip disappears or how long a tooltip
-        tooltip remains visible.
+        remains visible.
-        May not be supported on all platforms (eg. wxCocoa, GTK, Palmos).
+
+        @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos).
     */
     static void SetAutoPop(long msecs);
 
     /**
         Set the delay after which the tooltip appears.
-        May not be supported on all platforms (eg. wxCocoa).
+
+        @note May not be supported on all platforms (eg. wxCocoa).
     */
     static void SetDelay(long msecs);
 
     /**
         Set the delay between subsequent tooltips to appear.
-        May not be supported on all platforms (eg. wxCocoa, GTK, Palmos).
+
+        @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos).
     */
     static void SetReshow(long msecs);
 

interface/toplevel.h

@@ -6,19 +6,47 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Styles used with wxTopLevelWindow::RequestUserAttention().
+*/
+enum
+{
+    wxUSER_ATTENTION_INFO = 1,  ///< Requests user attention,
+    wxUSER_ATTENTION_ERROR = 2  ///< Results in a more drastic action.
+};
+
+/**
+    Styles used with wxTopLevelWindow::ShowFullScreen().
+*/
+enum
+{
+    wxFULLSCREEN_NOMENUBAR   = 0x0001,  ///< Don't display the menu bar.
+    wxFULLSCREEN_NOTOOLBAR   = 0x0002,  ///< Don't display toolbar bars.
+    wxFULLSCREEN_NOSTATUSBAR = 0x0004,  ///< Don't display the status bar.
+    wxFULLSCREEN_NOBORDER    = 0x0008,  ///< Don't display any border.
+    wxFULLSCREEN_NOCAPTION   = 0x0010,  ///< Don't display a caption.
+
+    /**
+        Combination of all above, will display the least possible.
+    */
+    wxFULLSCREEN_ALL    = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR |
+                          wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER |
+                          wxFULLSCREEN_NOCAPTION
+};
+
 /**
     @class wxTopLevelWindow
     @wxheader{toplevel.h}
 
-    wxTopLevelWindow is a common base class for wxDialog and
+    wxTopLevelWindow is a common base class for wxDialog and wxFrame. It is an
-    wxFrame. It is an abstract base class meaning that you never
+    abstract base class meaning that you never work with objects of this class
-    work with objects of this class directly, but all of its methods are also
+    directly, but all of its methods are also applicable for the two classes
-    applicable for the two classes above.
+    above.
 
     @library{wxcore}
     @category{managedwnd}
 
-    @see wxTopLevelWindow::SetTransparent
+    @see wxDialog, wxFrame
 */
 class wxTopLevelWindow : public wxWindow
 {
@@ -39,45 +67,45 @@ public:
         Centres the window on screen.
 
         @param direction
-            Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
+            Specifies the direction for the centering. May be @c wxHORIZONTAL,
-            or wxBOTH.
+            @c wxVERTICAL or @c wxBOTH.
 
-        @see wxWindow::CentreOnParent
+        @see wxWindow::CentreOnParent()
     */
     void CentreOnScreen(int direction = wxBOTH);
 
     /**
-        Enables or disables the Close button (most often in the right
+        Enables or disables the Close button (most often in the right upper
-        upper corner of a dialog) and the Close entry of the system
+        corner of a dialog) and the Close entry of the system menu (most often
-        menu (most often in the left upper corner of the dialog).
+        in the left upper corner of the dialog).
-        Currently only implemented for wxMSW and wxGTK. Returns
+
-        @true if operation was successful. This may be wrong on
+        Currently only implemented for wxMSW and wxGTK.
-        X11 (including GTK+) where the window manager may not support
+
-        this operation and there is no way to find out.
+        Returns @true if operation was successful. This may be wrong on X11
+        (including GTK+) where the window manager may not support this operation
+        and there is no way to find out.
     */
     bool EnableCloseButton(bool enable = true);
 
     /**
-        Returns a pointer to the button which is the default for this window, or @c
+        Returns a pointer to the button which is the default for this window, or
-        @NULL.
+        @c @NULL. The default button is the one activated by pressing the Enter
-        The default button is the one activated by pressing the Enter key.
+        key.
     */
     wxWindow* GetDefaultItem() const;
 
     /**
-        Returns the standard icon of the window. The icon will be invalid if it hadn't
+        Returns the standard icon of the window. The icon will be invalid if it
-        been previously set by SetIcon().
+        hadn't been previously set by SetIcon().
 
         @see GetIcons()
     */
     const wxIcon GetIcon() const;
 
     /**
-        Returns all icons associated with the window, there will be none of them if
+        Returns all icons associated with the window, there will be none of them
-        neither SetIcon() nor
+        if neither SetIcon() nor SetIcons() had been called before. Use
-        SetIcons() had been called before.
+        GetIcon() to get the main icon of the window.
-        Use GetIcon() to get the main icon of the
-        window.
 
         @see wxIconBundle
     */
@@ -91,10 +119,9 @@ public:
     wxString GetTitle() const;
 
     /**
-        Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel)
+        Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input
-        area and resize
+        panel) area and resize window accordingly. Override this if you want to
-        window accordingly. Override this if you want to avoid resizing or do additional
+        avoid resizing or do additional operations.
-        operations.
     */
     virtual bool HandleSettingChange(WXWPARAM wParam,
                                      WXLPARAM lParam);
@@ -111,15 +138,14 @@ public:
 
     /**
         Returns @true if this window is currently active, i.e. if the user is
-        currently
+        currently working with it.
-        working with it.
     */
     bool IsActive() const;
 
     /**
-        Returns @true if this window is expected to be always maximized, either due
+        Returns @true if this window is expected to be always maximized, either
-        to platform policy
+        due to platform policy or due to local policy regarding particular
-        or due to local policy regarding particular class.
+        class.
     */
     virtual bool IsAlwaysMaximized() const;
 
@@ -141,9 +167,10 @@ public:
     bool IsMaximized() const;
 
     /**
-        @b @c This method is specific to wxUniversal port
+        This method is specific to wxUniversal port.
-        Returns @true if this window is using native decorations, @false if we draw
+
-        them ourselves.
+        Returns @true if this window is using native decorations, @false if we
+        draw them ourselves.
 
         @see UseNativeDecorations(),
              UseNativeDecorationsByDefault()
@@ -161,15 +188,21 @@ public:
     void Maximize(bool maximize);
 
     /**
-        Use a system-dependent way to attract users attention to the window when it is
+        Use a system-dependent way to attract users attention to the window when
-        in background.
+        it is in background.
-        @a flags may have the value of either @c wxUSER_ATTENTION_INFO
+
-        (default) or @c wxUSER_ATTENTION_ERROR which results in a more drastic
+        @a flags may have the value of either @c ::wxUSER_ATTENTION_INFO
+        (default) or @c ::wxUSER_ATTENTION_ERROR which results in a more drastic
         action. When in doubt, use the default value.
-        Note that this function should normally be only used when the application is
+
-        not already in foreground.
+
-        This function is currently implemented for Win32 where it flashes the
+        @note This function should normally be only used when the application
-        window icon in the taskbar, and for wxGTK with task bars supporting it.
+              is not already in foreground.
+
+        This function is currently implemented for Win32 where it flashes
+        the window icon in the taskbar, and for wxGTK with task bars
+        supporting it.
+
     */
     void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO);
 
@@ -178,25 +211,27 @@ public:
 
         @see GetDefaultItem()
     */
-    void SetDefaultItem(wxWindow win);
+    void SetDefaultItem(wxWindow* win);
 
     /**
         Sets the icon for this window.
 
         @param icon
-            The icon to associate with this window.
+            The wxIcon to associate with this window.
 
-        @remarks The window takes a 'copy' of icon, but since it uses reference
+        @remarks The window takes a 'copy' of @a icon, but since it uses
-                 counting, the copy is very quick. It is safe to delete
+                 reference counting, the copy is very quick. It is safe to
-                 icon after calling this function.
+                 delete @a icon after calling this function.
+
+        @see wxIcon
     */
     void SetIcon(const wxIcon& icon);
 
     /**
-        Sets several icons of different sizes for this window: this allows to use
+        Sets several icons of different sizes for this window: this allows to
-        different icons for different situations (e.g. task switching bar, taskbar,
+        use different icons for different situations (e.g. task switching bar,
-        window title bar) instead of scaling, with possibly bad looking results, the
+        taskbar, window title bar) instead of scaling, with possibly bad looking
-        only icon set by SetIcon().
+        results, the only icon set by SetIcon().
 
         @param icons
             The icons to associate with this window.
@@ -206,14 +241,14 @@ public:
     void SetIcons(const wxIconBundle& icons);
 
     /**
-        Sets action or menu activated by pressing left hardware button on the smart
+        Sets action or menu activated by pressing left hardware button on the
-        phones.
+        smart phones. Unavailable on full keyboard machines.
-        Unavailable on full keyboard machines.
 
         @param id
             Identifier for this button.
         @param label
-            Text to be displayed on the screen area dedicated to this hardware button.
+            Text to be displayed on the screen area dedicated to this hardware
+            button.
         @param subMenu
             The menu to be opened after pressing this hardware button.
 
@@ -224,26 +259,24 @@ public:
                      wxMenu* subMenu = NULL);
 
     /**
-        A simpler interface for setting the size hints than
+        A simpler interface for setting the size hints than SetSizeHints().
-        SetSizeHints().
     */
     void SetMaxSize(const wxSize& size);
 
     /**
-        A simpler interface for setting the size hints than
+        A simpler interface for setting the size hints than SetSizeHints().
-        SetSizeHints().
     */
     void SetMinSize(const wxSize& size);
 
     /**
-        Sets action or menu activated by pressing right hardware button on the smart
+        Sets action or menu activated by pressing right hardware button on the
-        phones.
+        smart phones. Unavailable on full keyboard machines.
-        Unavailable on full keyboard machines.
 
         @param id
             Identifier for this button.
         @param label
-            Text to be displayed on the screen area dedicated to this hardware button.
+            Text to be displayed on the screen area dedicated to this hardware
+            button. 
         @param subMenu
             The menu to be opened after pressing this hardware button.
 
@@ -255,41 +288,51 @@ public:
 
     /**
         If the platform supports it, sets the shape of the window to that
-        depicted by @e region.  The system will not display or
+        depicted by @a region. The system will not display or respond to any
-        respond to any mouse event for the pixels that lie outside of the
+        mouse event for the pixels that lie outside of the region. To reset the
-        region.  To reset the window to the normal rectangular shape simply
+        window to the normal rectangular shape simply call SetShape() again with
-        call @e SetShape again with an empty region.  Returns @true if the
+        an empty wxRegion. Returns @true if the operation is successful.
-        operation is successful.
     */
     bool SetShape(const wxRegion& region);
 
-    //@{
     /**
-        Allows specification of minimum and maximum window sizes, and window size
+        Allows specification of minimum and maximum window sizes, and window
-        increments.
+        size increments. If a pair of values is not set (or set to -1), no
-        If a pair of values is not set (or set to -1), no constraints will be used.
+        constraints will be used.
 
         @param incW
             Specifies the increment for sizing the width (GTK/Motif/Xt only).
         @param incH
             Specifies the increment for sizing the height (GTK/Motif/Xt only).
-        @param incSize
-            Increment size (only taken into account under X11-based
-            ports such as wxGTK/wxMotif/wxX11).
 
         @remarks Notice that this function not only prevents the user from
-                 resizing the window outside the given bounds but it
+                 resizing the window outside the given bounds but it also
-                 also prevents the program itself from doing it using
+                 prevents the program itself from doing it using
-                 SetSize.
+                 wxWindow::SetSize().
+
     */
     virtual void SetSizeHints(int minW, int minH, int maxW = -1,
                               int maxH = -1,
                               int incW = -1,
                               int incH = -1);
+
+    /**
+        Allows specification of minimum and maximum window sizes, and window
+        size increments. If a pair of values is not set (or set to -1), no
+        constraints will be used.
+
+        @param incSize
+            Increment size (only taken into account under X11-based ports such
+            as wxGTK/wxMotif/wxX11).
+
+        @remarks Notice that this function not only prevents the user from
+                 resizing the window outside the given bounds but it also
+                 prevents the program itself from doing it using
+                 wxWindow::SetSize().
+    */
     void SetSizeHints(const wxSize& minSize,
                       const wxSize& maxSize = wxDefaultSize,
                       const wxSize& incSize = wxDefaultSize);
-    //@}
 
     /**
         Sets the window title.
@@ -302,49 +345,59 @@ public:
     virtual void SetTitle(const wxString& title);
 
     /**
-        If the platform supports it will set the window to be translucent
+        If the platform supports it will set the window to be translucent.
 
         @param alpha
-            Determines how opaque or transparent the window will
+            Determines how opaque or transparent the window will be, if the
-              be, if the platform supports the opreration.  A value of 0 sets the
+            platform supports the opreration. A value of 0 sets the window to be
-              window to be fully transparent, and a value of 255 sets the window
+            fully transparent, and a value of 255 sets the window to be fully
-              to be fully opaque.
+            opaque.
     */
     virtual bool SetTransparent(int alpha);
 
     /**
-        This virtual function is not meant to be called directly but can be overridden
+        This virtual function is not meant to be called directly but can be
-        to return @false (it returns @true by default) to allow the application to
+        overridden to return @false (it returns @true by default) to allow the
-        close even if this, presumably not very important, window is still opened.
+        application to close even if this, presumably not very important, window
-        By default, the application stays alive as long as there are any open top level
+        is still opened. By default, the application stays alive as long as
-        windows.
+        there are any open top level windows.
     */
     virtual bool ShouldPreventAppExit() const;
 
     /**
-        Depending on the value of @a show parameter the window is either shown full
+        Depending on the value of @a show parameter the window is either shown
-        screen or restored to its normal state. @a style is a bit list containing
+        full screen or restored to its normal state. @a style is a bit list
-        some or all of the following values, which indicate what elements of the window
+        containing some or all of the following values, which indicate what
-        to hide in full-screen mode:
+        elements of the window to hide in full-screen mode:
-         wxFULLSCREEN_NOMENUBAR
+
-         wxFULLSCREEN_NOTOOLBAR
+        - @c ::wxFULLSCREEN_NOMENUBAR
-         wxFULLSCREEN_NOSTATUSBAR
+        - @c ::wxFULLSCREEN_NOTOOLBAR
-         wxFULLSCREEN_NOBORDER
+        - @c ::wxFULLSCREEN_NOSTATUSBAR
-         wxFULLSCREEN_NOCAPTION
+        - @c ::wxFULLSCREEN_NOBORDER
-         wxFULLSCREEN_ALL (all of the above)
+        - @c ::wxFULLSCREEN_NOCAPTION
+        - @c ::wxFULLSCREEN_ALL (all of the above)
+
         This function has not been tested with MDI frames.
-        Note that showing a window full screen also actually
+
-        @ref wxWindow::show Show()s if it hadn't been shown yet.
+        @note Showing a window full screen also actually @ref wxWindow::Show()
+              "Show()"s the window if it isn't shown.
 
         @see IsFullScreen()
     */
     bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
 
     /**
-        @b @c This method is specific to wxUniversal port
+        This method is specific to wxUniversal port.
-        Use native or custom-drawn decorations for this window only. Notice that to
+
-        have any effect this method must be called before really creating the window,
+        Use native or custom-drawn decorations for this window only. Notice that
-        i.e. two step creation must be used:
+        to have any effect this method must be called before really creating the
+        window, i.e. two step creation must be used:
+
+        @code
+        MyFrame *frame = new MyFrame;       // use default ctor
+        frame->UseNativeDecorations(false); // change from default "true"
+        frame->Create(parent, title, ...);  // really create the frame
+        @endcode
 
         @see UseNativeDecorationsByDefault(),
              IsUsingNativeDecorations()
@@ -352,16 +405,21 @@ public:
     void UseNativeDecorations(bool native = true);
 
     /**
-        @b @c This method is specific to wxUniversal port
+        This method is specific to wxUniversal port.
-        Top level windows in wxUniversal port can use either system-provided window
+
-        decorations (i.e. title bar and various icons, buttons and menus in it) or draw
+        Top level windows in wxUniversal port can use either system-provided
-        the decorations themselves. By default the system decorations are used if they
+        window decorations (i.e. title bar and various icons, buttons and menus
-        are available, but this method can be called with @a native set to @false to
+        in it) or draw the decorations themselves. By default the system
-        change this for all windows created after this point.
+        decorations are used if they are available, but this method can be
+        called with @a native set to @false to change this for all windows
+        created after this point.
+
         Also note that if @c WXDECOR environment variable is set, then custom
-        decorations are used by default and so it may make sense to call this method
+        decorations are used by default and so it may make sense to call this
-        with default argument if the application can't use custom decorations at all
+        method with default argument if the application can't use custom
-        for some reason.
+        decorations at all for some reason.
+        
+        @see UseNativeDecorations()
     */
     void UseNativeDecorationsByDefault(bool native = true);
 };