X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ccf39540bb96a0e5d067451ad79c82397579aceb..427861bde09badef1a2950ad799e69fac6b4a48a:/interface/wx/toolbar.h

diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h
index cef105a0dc..90f2cab465 100644
--- a/interface/wx/toolbar.h
+++ b/interface/wx/toolbar.h
@@ -36,12 +36,12 @@
     bitmaps will inadvertently be mapped to system colours.
     To do this, set the msw.remap system option before creating the toolbar:
     @code
-    wxSystemOptions::SetOption(wxT("msw.remap"), 0);
+    wxSystemOptions::SetOption("msw.remap", 0);
     @endcode
     If you wish to use 32-bit images (which include an alpha channel for
     transparency) use:
     @code
-    wxSystemOptions::SetOption(wxT("msw.remap"), 2);
+    wxSystemOptions::SetOption("msw.remap", 2);
     @endcode
     Then colour remapping is switched off, and a transparent background
     used. But only use this option under Windows XP with true colour:
@@ -85,7 +85,7 @@
     ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only
     if the style was initially on.
 
-    @beginEventTable{wxCommandEvent}
+    @beginEventEmissionTable{wxCommandEvent}
     @event{EVT_TOOL(id, func)}
         Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c
         wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool.
@@ -98,14 +98,14 @@
         The same as EVT_TOOL_RANGE().
     @event{EVT_TOOL_RCLICKED(id, func)}
         Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the
-        tool.
+        tool.  (Not available on wxOSX.)
     @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
         Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass
-        the ids of the tools.
+        the ids of the tools.  (Not available on wxOSX.)
     @event{EVT_TOOL_ENTER(id, func)}
         Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar
         itself. The value of wxCommandEvent::GetSelection() is the tool id, or
-        -1 if the mouse cursor has moved off a tool.
+        -1 if the mouse cursor has moved off a tool.  (Not available on wxOSX.)
     @event{EVT_TOOL_DROPDOWN(id, func)}
         Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled,
         displays the default dropdown menu set using
@@ -224,13 +224,31 @@ public:
     /**
         Adds a separator for spacing groups of tools.
 
-        Note that the meaning of a "separator" is a vertical line under wxMSW and
-        a simple space under wxGTK.
+        Notice that the separator uses the look appropriate for the current
+        platform so it can be a vertical line (MSW, some versions of GTK) or
+        just an empty space or something else.
 
-        @see AddTool(), SetToolSeparation()
+        @see AddTool(), SetToolSeparation(), AddStretchableSpace()
     */
     virtual wxToolBarToolBase* AddSeparator();
 
+    /**
+        Adds a stretchable space to the toolbar.
+
+        Any space not taken up by the fixed items (all items except for
+        stretchable spaces) is distributed in equal measure between the
+        stretchable spaces in the toolbar. The most common use for this method
+        is to add a single stretchable space before the items which should be
+        right-aligned in the toolbar, but more exotic possibilities are
+        possible, e.g. a stretchable space may be added in the beginning and
+        the end of the toolbar to centre all toolbar items.
+
+        @see AddTool(), AddSeparator(), InsertStretchableSpace()
+
+        @since 2.9.1
+     */
+    wxToolBarToolBase *AddStretchableSpace();
+
     //@{
     /**
         Adds a tool to the toolbar.
@@ -239,7 +257,7 @@ public:
             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.
+                 Realize() in order to have the tools appear.
 
         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
@@ -294,11 +312,6 @@ public:
             The bitmap used when the tool is disabled. If it is equal to
             ::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
@@ -307,6 +320,11 @@ 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 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 clientData
             An optional pointer to client data which can be retrieved later
             using GetToolClientData().
@@ -403,8 +421,15 @@ public:
     wxSize GetMargins() const;
 
     /**
-        Returns the size of bitmap that the toolbar expects to have. The default
-        bitmap size is 16 by 15 pixels.
+        Returns the size of bitmap that the toolbar expects to have.
+
+        The default bitmap size is platform-dependent: for example, it is 16*15
+        for MSW and 24*24 for GTK. This size does @em not necessarily indicate
+        the best size to use for the toolbars on the given platform, for this
+        you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
+        in any case, as the bitmap size is deduced automatically from the size
+        of the bitmaps associated with the tools added to the toolbar, it is
+        usually unnecessary to call SetToolBitmapSize() explicitly.
 
         @remarks Note that this is the size of the bitmap you pass to AddTool(),
             and not the eventual size of the tool button.
@@ -413,6 +438,17 @@ public:
     */
     virtual wxSize GetToolBitmapSize() const;
 
+    /**
+        Returns a pointer to the tool at ordinal position @a pos.
+
+        Don't confuse this with FindToolForPosition().
+
+        @since 2.9.1
+
+        @see GetToolsCount()
+    */
+    const wxToolBarToolBase *GetToolByPos(int pos) const;
+
     /**
         Get any client data associated with the tool.
 
@@ -517,6 +553,17 @@ public:
     */
     virtual wxToolBarToolBase* InsertSeparator(size_t pos);
 
+    /**
+        Inserts a stretchable space at the given position.
+
+        See AddStretchableSpace() for details about stretchable spaces.
+
+        @see InsertTool(), InsertSeparator()
+
+        @since 2.9.1
+     */
+    wxToolBarToolBase *InsertStretchableSpace(size_t pos);
+
     //@{
     /**
         Inserts the tool with the specified attributes into the toolbar at the
@@ -525,6 +572,10 @@ public:
         You must call Realize() for the change to take place.
 
         @see AddTool(), InsertControl(), InsertSeparator()
+
+        @return The newly inserted tool or @NULL on failure. Notice that with
+            the overload taking @a tool parameter the caller is responsible for
+            deleting the tool in the latter case.
     */
     wxToolBarToolBase* InsertTool(size_t pos, int toolId,
                                   const wxBitmap& bitmap1,