]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/toolbar.h
Make wxHelpControllerBase::SetFrameParameters() title more clear.
[wxWidgets.git] / interface / wx / toolbar.h
index d423ce473a072e5692b6ea9e40c18be7f434fab7..9bd3b169aeb7941598b43bcc24ae456736f6853c 100644 (file)
 // Purpose:     interface of wxToolBar
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+enum wxToolBarToolStyle
+{
+    wxTOOL_STYLE_BUTTON    = 1,
+    wxTOOL_STYLE_SEPARATOR = 2,
+    wxTOOL_STYLE_CONTROL
+};
+
+
+/** wxToolBar style flags */
+enum
+{
+    /** lay out the toolbar horizontally */
+    wxTB_HORIZONTAL,
+    wxTB_TOP,
+
+    /** lay out the toolbar vertically */
+    wxTB_VERTICAL,
+    wxTB_LEFT,
+
+    /** show 3D buttons (wxToolBarSimple only) */
+    wxTB_3DBUTTONS,
+
+    /** "flat" buttons (Win32/GTK only) */
+    wxTB_FLAT,
+
+    /** dockable toolbar (GTK only) */
+    wxTB_DOCKABLE,
+
+    /** don't show the icons (they're shown by default) */
+    wxTB_NOICONS,
+
+    /** show the text (not shown by default) */
+    wxTB_TEXT,
+
+    /** don't show the divider between toolbar and the window (Win32 only) */
+    wxTB_NODIVIDER,
+
+    /** no automatic alignment (Win32 only, useless) */
+    wxTB_NOALIGN,
+
+    /** show the text and the icons alongside, not vertically stacked (Win32/GTK) */
+    wxTB_HORZ_LAYOUT,
+    wxTB_HORZ_TEXT,
+
+    /** don't show the toolbar short help tooltips */
+    wxTB_NO_TOOLTIPS,
+
+    /** lay out toolbar at the bottom of the window */
+    wxTB_BOTTOM,
+
+    /** lay out toolbar at the right edge of the window */
+    wxTB_RIGHT
+};
+
+
+
 /**
-    @class wxToolBar
+    @class wxToolBarToolBase
 
-    The name wxToolBar is defined to be a synonym for one of the following
-    classes:
+    A toolbar tool represents one item on the toolbar.
 
-    - @b wxToolBar95 - The native Windows 95 toolbar. Used on Windows 95, NT 4
-      and above.
-    - @b wxToolBarMSW - A Windows implementation. Used on 16-bit Windows.
-    - @b wxToolBarGTK - The GTK toolbar.
+    It has a unique id (except for the separators), the style (telling whether
+    it is a normal button, separator or a control), the state (toggled or not,
+    enabled or not) and short and long help strings. The default
+    implementations use the short help string for the tooltip text which is
+    popped up when the mouse pointer enters the tool and the long help string
+    for the applications status bar.
+*/
+class wxToolBarToolBase : public wxObject
+{
+public:
+    wxToolBarToolBase(wxToolBarBase *tbar = NULL,
+                      int toolid = wxID_SEPARATOR,
+                      const wxString& label = wxEmptyString,
+                      const wxBitmap& bmpNormal = wxNullBitmap,
+                      const wxBitmap& bmpDisabled = wxNullBitmap,
+                      wxItemKind kind = wxITEM_NORMAL,
+                      wxObject *clientData = NULL,
+                      const wxString& shortHelpString = wxEmptyString,
+                      const wxString& longHelpString = wxEmptyString);
+
+    wxToolBarToolBase(wxToolBarBase *tbar,
+                      wxControl *control,
+                      const wxString& label);
+
+    virtual ~wxToolBarToolBase();
+
+    int GetId() const;
+
+    wxControl *GetControl() const;
+    wxToolBarBase *GetToolBar() const;
+
+    bool IsStretchable() const;
+    bool IsButton() const;
+    bool IsControl() const;
+    bool IsSeparator() const;
+    bool IsStretchableSpace() const;
+    int GetStyle() const;
+    wxItemKind GetKind() const;
+    void MakeStretchable();
+
+    bool IsEnabled() const;
+    bool IsToggled() const;
+    bool CanBeToggled() const;
+
+    const wxBitmap& GetNormalBitmap() const;
+    const wxBitmap& GetDisabledBitmap() const;
+
+    const wxBitmap& GetBitmap() const;
+    const wxString& GetLabel() const;
+
+    const wxString& GetShortHelp() const;
+    const wxString& GetLongHelp() const;
+
+    wxObject *GetClientData() const;
+
+    virtual bool Enable(bool enable);
+    virtual bool Toggle(bool toggle);
+    virtual bool SetToggle(bool toggle);
+    virtual bool SetShortHelp(const wxString& help);
+    virtual bool SetLongHelp(const wxString& help);
+    void Toggle();
+    virtual void SetNormalBitmap(const wxBitmap& bmp);
+    virtual void SetDisabledBitmap(const wxBitmap& bmp);
+    virtual void SetLabel(const wxString& label);
+    void SetClientData(wxObject *clientData);
+    
+    virtual void Detach();
+    virtual void Attach(wxToolBarBase *tbar);
 
-    You may also create a toolbar that is managed by the frame, by calling
+    virtual void SetDropdownMenu(wxMenu *menu);
+    wxMenu *GetDropdownMenu() const;
+};
+
+
+
+
+/**
+    @class wxToolBar
+
+    A toolbar is a bar of buttons and/or other controls usually placed below
+    the menu bar in a wxFrame.
+
+    You may create a toolbar that is managed by a frame calling
     wxFrame::CreateToolBar(). 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.
-
-    The meaning of a "separator" is a vertical line under Windows and simple
-    space under GTK+.
-
-    @b wxToolBar95: Note that this toolbar paints tools to reflect
-    system-wide colours. If you use more than 16 colours in your tool
-    bitmaps, you may wish to suppress this behaviour, otherwise system
-    colours in your bitmaps will inadvertently be mapped to system colours.
+    own toolbars, create wxToolBar as usual.
+
+    There are several different types of tools you can add to a toolbar.
+    These types are controlled by the ::wxItemKind enumeration.
+
+    Note that many methods in wxToolBar such as wxToolBar::AddTool return a
+    @c wxToolBarToolBase* object.
+    This should be regarded as an opaque handle representing the newly added
+    toolbar item, providing access to its id and position within the toolbar.
+    Changes to the item's state should be made through calls to wxToolBar methods,
+    for example wxToolBar::EnableTool.
+    Calls to @c wxToolBarToolBase methods (undocumented by purpose) will not change
+    the visible state of the item within the tool bar.
+
+    <b>wxMSW note</b>: Note that under wxMSW toolbar paints tools to reflect
+    system-wide colours. If you use more than 16 colours in your tool bitmaps,
+    you may wish to suppress this behaviour, otherwise system colours in your
+    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:
-
     @code
     if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
     @endcode
-    
-    There are several different types of tools you can add to a toolbar. These
-    types are controlled by the ::wxItemKind enumeration.
 
     @beginStyleTable
     @style{wxTB_FLAT}
         Align the toolbar at the right side of parent window.
     @endStyleTable
 
-    See also @ref overview_windowstyles. Note that the Win32 native toolbar
+    See also @ref overview_windowstyles. Note that the wxMSW native toolbar
     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.
         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
         wxToolBar::SetDropdownMenu().
     @endEventTable
-    
+
     The toolbar class emits menu commands in the same way that a frame menubar
     does, so you can use one EVT_MENU() macro for both a menu item and a toolbar
     button. The event handler functions take a wxCommandEvent argument. For most
     event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER()
     the toolbar window identifier is passed and the tool identifier is retrieved
-    from the wxCommandEvent. This is because the identifier may be -1 when the
-    mouse moves off a tool, and -1 is not allowed as an identifier in the event
+    from the wxCommandEvent. This is because the identifier may be @c wxID_ANY when the
+    mouse moves off a tool, and @c wxID_ANY is not allowed as an identifier in the event
     system.
 
     @library{wxcore}
@@ -146,26 +279,26 @@ public:
         @param id
             Window identifier. If -1, will automatically create an identifier.
         @param pos
-            Window position. ::wxDefaultPosition is (-1, -1) which indicates that
-            wxWidgets should generate a default position for the window. If
-            using the wxWindow class directly, supply an actual position.
+            Window position. ::wxDefaultPosition indicates that wxWidgets should
+            generate a default position for the window.
+            If using the wxWindow class directly, supply an actual position.
         @param size
-            Window size. ::wxDefaultSize is (-1, -1) which indicates that
-            wxWidgets should generate a default size for the window.
+            Window size. ::wxDefaultSize indicates that wxWidgets should generate
+            a default size for the window.
         @param style
-            Window style. See wxToolBar for details.
+            Window style. See wxToolBar initial description for details.
         @param name
             Window name.
 
         @remarks After a toolbar is created, you use AddTool() and perhaps
-            AddSeparator(), and then you must call Realize() to construct and
-            display the toolbar tools.
+                 AddSeparator(), and then you must call Realize() to construct
+                 and display the toolbar tools.
     */
     wxToolBar(wxWindow* parent, wxWindowID id,
               const wxPoint& pos = wxDefaultPosition,
               const wxSize& size = wxDefaultSize,
-              long style = wxTB_HORIZONTAL | wxBORDER_NONE,
-              const wxString& name = wxPanelNameStr);
+              long style = wxTB_HORIZONTAL,
+              const wxString& name = wxToolBarNameStr);
 
     /**
         Toolbar destructor.
@@ -178,12 +311,11 @@ public:
 
         @see AddTool()
     */
-    wxToolBarToolBase* AddCheckTool(int toolId,
-                                    const wxString& label,
+    wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label,
                                     const wxBitmap& bitmap1,
-                                    const wxBitmap& bitmap2,
-                                    const wxString& shortHelpString = "",
-                                    const wxString& longHelpString = "",
+                                    const wxBitmap& bmpDisabled = wxNullBitmap,
+                                    const wxString& shortHelp = wxEmptyString,
+                                    const wxString& longHelp = wxEmptyString,
                                     wxObject* clientData = NULL);
 
     /**
@@ -202,7 +334,8 @@ public:
             wxMac: labels are only displayed if wxWidgets is built with @c
             wxMAC_USE_NATIVE_TOOLBAR set to 1
     */
-    bool AddControl(wxControl* control, const wxString label = "");
+    virtual wxToolBarToolBase* AddControl(wxControl* control,
+                                          const wxString& label = wxEmptyString);
 
     /**
         Adds a new radio tool to the toolbar. Consecutive radio tools form a
@@ -211,28 +344,49 @@ public:
         previously pressed button is automatically released. You should avoid
         having the radio groups of only one element as it would be impossible
         for the user to use such button.
-        
+
         By default, the first button in the radio group is initially pressed,
         the others are not.
 
 
         @see AddTool()
     */
-    wxToolBarToolBase* AddRadioTool(int toolId,
-                                    const wxString& label,
+    wxToolBarToolBase* AddRadioTool(int toolId, const wxString& label,
                                     const wxBitmap& bitmap1,
-                                    const wxBitmap& bitmap2,
-                                    const wxString& shortHelpString = "",
-                                    const wxString& longHelpString = "",
+                                    const wxBitmap& bmpDisabled = wxNullBitmap,
+                                    const wxString& shortHelp = wxEmptyString,
+                                    const wxString& longHelp = wxEmptyString,
                                     wxObject* clientData = NULL);
 
     /**
         Adds a separator for spacing groups of tools.
 
-        @see AddTool(), SetToolSeparation()
+        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(), AddStretchableSpace()
     */
-    void AddSeparator();
+    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.
 
@@ -240,7 +394,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()
@@ -248,14 +402,14 @@ public:
     virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
 
     /**
-        Adds a tool to the toolbar. This most commonly used version has fewer 
+        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        
+        @param label
             The string to be displayed with the tool.
         @param bitmap
             The primary tool bitmap.
@@ -265,7 +419,7 @@ public:
             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 
+            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.
@@ -287,27 +441,27 @@ public:
         @param toolId
             An integer by which the tool may be identified in subsequent
             operations.
-        @param label  
+        @param label
             The string to be displayed with the tool.
         @param bitmap
             The primary tool bitmap.
         @param bmpDisabled
             The bitmap used when the tool is disabled. If it is equal to
-            ::wxNullBitmap (default), the disabled bitmap is automatically 
+            ::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 
+            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 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().
@@ -320,11 +474,12 @@ public:
     */
     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
                                const wxBitmap& bitmap,
-                               const wxBitmap& bmpDisabled = wxNullBitmap,
+                               const wxBitmap& bmpDisabled,
                                wxItemKind kind = wxITEM_NORMAL,
                                const wxString& shortHelpString = wxEmptyString,
                                const wxString& longHelpString = wxEmptyString,
                                wxObject* clientData = NULL);
+    //@}
 
     /**
         Deletes all the tools in the toolbar.
@@ -355,7 +510,7 @@ public:
         Enables or disables the tool.
 
         @param toolId
-            Tool to enable or disable.
+            ID of the tool to enable or disable, as passed to AddTool().
         @param enable
             If @true, enables the tool, otherwise disables it.
 
@@ -403,8 +558,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,11 +575,22 @@ 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.
 
         @param toolId
-            Id of the tool, as passed to AddTool().
+            ID of the tool in question, as passed to AddTool().
 
         @return Client data, or @NULL if there is none.
     */
@@ -427,7 +600,7 @@ public:
         Called to determine whether a tool is enabled (responds to user input).
 
         @param toolId
-            Id of the tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @return @true if the tool is enabled, @false otherwise.
 
@@ -439,7 +612,7 @@ public:
         Returns the long help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @see SetToolLongHelp(), SetToolShortHelp()
     */
@@ -455,6 +628,9 @@ public:
     /**
         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
         is not found.
+
+        @param toolId
+            ID of the tool in question, as passed to AddTool().
     */
     virtual int GetToolPos(int toolId) const;
 
@@ -469,7 +645,7 @@ public:
         Returns the short help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @see GetToolLongHelp(), SetToolShortHelp()
     */
@@ -487,7 +663,7 @@ public:
         Gets the on/off state of a toggle tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @return @true if the tool is toggled on, @false otherwise.
 
@@ -498,7 +674,7 @@ public:
     /**
         Returns the number of tools in the toolbar.
     */
-    int GetToolsCount() const;
+    size_t GetToolsCount() const;
 
     /**
         Inserts the control into the toolbar at the given position. You must
@@ -506,7 +682,8 @@ public:
 
         @see AddControl(), InsertTool()
     */
-    wxToolBarToolBase* InsertControl(size_t pos, wxControl* control);
+    virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control,
+                                             const wxString& label = wxEmptyString);
 
     /**
         Inserts the separator into the toolbar at the given position. You must
@@ -516,6 +693,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
@@ -524,14 +712,21 @@ 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,
-                                  const wxBitmap& bitmap2 = wxNullBitmap,
-                                  bool isToggle = false,
-                                  wxObject* clientData = NULL,
-                                  const wxString& shortHelpString = "",
-                                  const wxString& longHelpString = "");
+    wxToolBarToolBase* InsertTool(  size_t pos,
+                                    int toolId,
+                                    const wxString& label,
+                                    const wxBitmap& bitmap,
+                                    const wxBitmap& bmpDisabled = wxNullBitmap,
+                                    wxItemKind kind = wxITEM_NORMAL,
+                                    const wxString& shortHelp = wxEmptyString,
+                                    const wxString& longHelp = wxEmptyString,
+                                    wxObject *clientData = NULL);
+
     wxToolBarToolBase* InsertTool(size_t pos,
                                   wxToolBarToolBase* tool);
     //@}
@@ -593,7 +788,7 @@ public:
 
         @see OnMouseEnter(), OnLeftClick()
     */
-    void OnRightClick(int toolId, float x, float y);
+    virtual void OnRightClick(int toolId, long x, long y);
 
     /**
         This function should be called after you have added tools.
@@ -614,7 +809,11 @@ public:
 
     /**
         Sets the bitmap resource identifier for specifying tool bitmaps as
-        indices into a custom bitmap. Windows CE only.
+        indices into a custom bitmap.
+
+        This is a Windows CE-specific method not available in the other ports.
+
+        @onlyfor{wxmsw_wince}
     */
     void SetBitmapResource(int resourceId);
 
@@ -628,6 +827,7 @@ public:
     */
     bool SetDropdownMenu(int id, wxMenu* menu);
 
+    //@{
     /**
         Set the values to be used as margins for the toolbar.
 
@@ -657,6 +857,7 @@ public:
         @see GetMargins(), wxSize
     */
     void SetMargins(const wxSize& size);
+    //@}
 
     /**
         Sets the default size of each tool bitmap. The default bitmap size is 16
@@ -674,6 +875,9 @@ public:
 
     /**
         Sets the client data associated with the tool.
+
+        @param id
+            ID of the tool in question, as passed to AddTool().
     */
     virtual void SetToolClientData(int id, wxObject* clientData);
 
@@ -682,6 +886,9 @@ public:
         is in a disabled state. This can only be used on Button tools, not
         controls.
 
+        @param id
+            ID of the tool in question, as passed to AddTool().
+
         @note The native toolbar classes on the main platforms all synthesize
             the disabled bitmap from the normal bitmap, so this function will
             have no effect on those platforms.
@@ -693,7 +900,7 @@ public:
         Sets the long help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
         @param helpString
             A string for the long help.
 
@@ -707,6 +914,9 @@ public:
     /**
         Sets the bitmap to be used by the tool with the given ID. This can only
         be used on Button tools, not controls.
+
+        @param id
+            ID of the tool in question, as passed to AddTool().
     */
     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 
@@ -716,7 +926,7 @@ public:
         @param packing
             The value for packing.
 
-        @remarks The packing is used for spacing in the vertical direction if 
+        @remarks The packing is used for spacing in the vertical direction if
             the toolbar is horizontal, and for spacing in the horizontal
             direction if the toolbar is vertical.
 
@@ -738,7 +948,7 @@ public:
         Sets the short help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
         @param helpString
             The string for the short help.
 
@@ -754,7 +964,7 @@ public:
         Toggles a tool on or off. This does not cause any event to get emitted.
 
         @param toolId
-            Tool in question.
+            ID of the tool in question, as passed to AddTool().
         @param toggle
             If @true, toggles the tool on, otherwise toggles it off.
 
@@ -762,5 +972,28 @@ public:
             tool.
     */
     virtual void ToggleTool(int toolId, bool toggle);
+
+
+    /**
+       Factory function to create a new toolbar tool.
+    */
+    virtual wxToolBarToolBase *CreateTool(int toolId,
+                                          const wxString& label,
+                                          const wxBitmap& bmpNormal,
+                                          const wxBitmap& bmpDisabled = wxNullBitmap,
+                                          wxItemKind kind = wxITEM_NORMAL,
+                                          wxObject *clientData = NULL,
+                                          const wxString& shortHelp = wxEmptyString,
+                                          const wxString& longHelp = wxEmptyString);
+    /**
+       Factory function to create a new control toolbar tool.
+    */
+    virtual wxToolBarToolBase *CreateTool(wxControl *control,
+                                          const wxString& label);
+
+    /**
+       Factory function to create a new separator toolbar tool.
+    */
+    wxToolBarToolBase *CreateSeparator()
 };