Separated out function grouping for less confusing parameter docs. (#9651)

[wxWidgets.git] / interface / toolbar.h

diff --git a/interface/toolbar.h b/interface/toolbar.h
index 860e8f00e5d7cbb827ea5cdfc4dd836f40dc8894..c7deafc8bc4c10841cfece5f2d065c5bf9d7fd2c 100644 (file)
--- a/interface/toolbar.h
+++ b/interface/toolbar.h
@@ -234,16 +234,34 @@ public:
     */
     void AddSeparator();
 
-    //@{
     /**
-        Adds a tool to the toolbar. The first (short and most commonly used)
-        version has fewer parameters than the full version at the price of not
-        being able to specify some of the more rarely used button features. The
-        last version allows you to add an existing tool.
+        Adds a tool to the toolbar.
+
+        @param tool
+            The tool to be added.
+
+        @remarks After you have added tools to a toolbar, you must call
+            Realize() in order to have the tools appear.
+
+        @see AddSeparator(), AddCheckTool(), AddRadioTool(),
+             InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
+    */
+    wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
+
+    /**
+        Adds a tool to the toolbar. This most commonly used version has fewer 
+        parameters than the full version below which specifies the more rarely
+        used button features.
 
         @param toolId
             An integer by which the tool may be identified in subsequent
             operations.
+        @param label        
+            The string to be displayed with the tool.
+        @param bitmap
+            The primary tool bitmap.
+        @param shortHelp
+            This string is used for the tools tooltip.
         @param kind
             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
             for a checkable tool (such tool stays pressed after it had been
@@ -252,22 +270,48 @@ public:
             whenever another button in the group is checked. ::wxITEM_DROPDOWN
             specifies that a drop-down menu button will appear next to the
             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
-        @param bitmap1
+
+        @remarks After you have added tools to a toolbar, you must call
+            Realize() in order to have the tools appear.
+
+        @see AddSeparator(), AddCheckTool(), AddRadioTool(),
+             InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
+    */
+    wxToolBarToolBase* AddTool(int toolId, const wxString& label,
+                               const wxBitmap& bitmap,
+                               const wxString& shortHelp = wxEmptyString,
+                               wxItemKind kind = wxITEM_NORMAL);
+
+    /**
+        Adds a tool to the toolbar.
+
+        @param toolId
+            An integer by which the tool may be identified in subsequent
+            operations.
+        @param label  
+            The string to be displayed with the tool.
+        @param bitmap
             The primary tool bitmap.
-        @param bitmap2
+        @param bmpDisabled
             The bitmap used when the tool is disabled. If it is equal to
-            ::wxNullBitmap, the disabled bitmap is automatically generated by
-            greying the normal one.
+            ::wxNullBitmap (default), the disabled bitmap is automatically 
+            generated by greying the normal one.
         @param shortHelpString
             This string is used for the tools tooltip.
         @param longHelpString
             This string is shown in the statusbar (if any) of the parent frame
             when the mouse pointer is inside the tool.
+        @param kind
+            May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
+            for a checkable tool (such tool stays pressed after it had been
+            toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
+            a radio group of tools each of which is automatically unchecked 
+            whenever another button in the group is checked. ::wxITEM_DROPDOWN
+            specifies that a drop-down menu button will appear next to the
+            tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
         @param clientData
             An optional pointer to client data which can be retrieved later
             using GetToolClientData().
-        @param tool
-            The tool to be added.
 
         @remarks After you have added tools to a toolbar, you must call
             Realize() in order to have the tools appear.
@@ -276,18 +320,12 @@ public:
              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
     */
     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
-                               const wxBitmap& bitmap1,
-                               const wxString& shortHelpString = "",
-                               wxItemKind kind = wxITEM_NORMAL);
-    wxToolBarToolBase* AddTool(int toolId, const wxString& label,
-                               const wxBitmap& bitmap1,
-                               const wxBitmap& bitmap2 = wxNullBitmap,
+                               const wxBitmap& bitmap,
+                               const wxBitmap& bmpDisabled = wxNullBitmap,
                                wxItemKind kind = wxITEM_NORMAL,
-                               const wxString& shortHelpString = "",
-                               const wxString& longHelpString = "",
+                               const wxString& shortHelpString = wxEmptyString,
+                               const wxString& longHelpString = wxEmptyString,
                                wxObject* clientData = NULL);
-    wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
-    //@}
 
     /**
         Deletes all the tools in the toolbar.
@@ -591,12 +629,9 @@ public:
     */
     bool SetDropdownMenu(int id, wxMenu* menu);
 
-    //@{
     /**
         Set the values to be used as margins for the toolbar.
 
-        @param size
-            Margin size.
         @param x
             Left margin, right margin and inter-tool separation value.
         @param y
@@ -606,11 +641,23 @@ public:
             positioning is to be used, and the default (zero-size) margins are
             to be overridden.
 
+        @see GetMargins()
+    */
+    void SetMargins(int x, int y);
+
+    /**
+        Set the margins for the toolbar.
+
+        @param size
+            Margin size.
+
+        @remarks This must be called before the tools are added if absolute
+            positioning is to be used, and the default (zero-size) margins are
+            to be overridden.
+
         @see GetMargins(), wxSize
     */
     void SetMargins(const wxSize& size);
-    void SetMargins(int x, int y);
-    //@}
 
     /**
         Sets the default size of each tool bitmap. The default bitmap size is 16