synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / toolbar.h

diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h
index bd4e4125ddfe817c7f7fa9ec6969ee91d4382040..9bd3b169aeb7941598b43bcc24ae456736f6853c 100644 (file)
--- a/interface/wx/toolbar.h
+++ b/interface/wx/toolbar.h
@@ -3,55 +3,188 @@
 // Purpose:     interface of wxToolBar
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // 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
     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:
     To do this, set the msw.remap system option before creating the toolbar:

-

     @code
     @code

-    wxSystemOptions::SetOption(wxT("msw.remap"), 0);
+    wxSystemOptions::SetOption("msw.remap", 0);

     @endcode
     @endcode

-

     If you wish to use 32-bit images (which include an alpha channel for
     transparency) use:
     If you wish to use 32-bit images (which include an alpha channel for
     transparency) use:

-

     @code
     @code

-    wxSystemOptions::SetOption(wxT("msw.remap"), 2);
+    wxSystemOptions::SetOption("msw.remap", 2);

     @endcode
     @endcode

-

     Then colour remapping is switched off, and a transparent background
     used. But only use this option under Windows XP with true colour:
     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
     @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}
 
     @beginStyleTable
     @style{wxTB_FLAT}


@@ -85,11 +218,11 @@
         Align the toolbar at the right side of parent window.
     @endStyleTable
 
         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.
 
     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.
     @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.


@@ -102,27 +235,27 @@
         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
         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
     @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
     @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
     @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
     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}
     system.
 
     @library{wxcore}


@@ -146,31 +279,31 @@ public:
         @param id
             Window identifier. If -1, will automatically create an identifier.
         @param pos
         @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
         @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
         @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
         @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,
     */
     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.
     */
 
     /**
         Toolbar destructor.
     */

-    ~wxToolBar();
+    virtual ~wxToolBar();

 
     /**
         Adds a new check (or toggle) tool to the toolbar. The parameters are the
 
     /**
         Adds a new check (or toggle) tool to the toolbar. The parameters are the


@@ -178,12 +311,11 @@ public:
 
         @see AddTool()
     */
 
         @see AddTool()
     */

-    wxToolBarToolBase* AddCheckTool(int toolId,
-                                    const wxString& label,
+    wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label,

                                     const wxBitmap& bitmap1,
                                     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);
 
     /**
                                     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
     */
             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
 
     /**
         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.
         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()
     */
         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& 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.
 
                                     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.
 
     /**
         Adds a tool to the toolbar.
 


@@ -240,22 +394,22 @@ public:
             The tool to be added.
 
         @remarks After you have added tools to a toolbar, you must call
             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()
     */
 
         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
     */

-    wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
+    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.
         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.
             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
             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.
             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 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
             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.
             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
         @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.
             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().
         @param clientData
             An optional pointer to client data which can be retrieved later
             using GetToolClientData().


@@ -320,16 +474,17 @@ public:
     */
     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
                                const wxBitmap& bitmap,
     */
     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);
                                wxItemKind kind = wxITEM_NORMAL,
                                const wxString& shortHelpString = wxEmptyString,
                                const wxString& longHelpString = wxEmptyString,
                                wxObject* clientData = NULL);

+    //@}

 
     /**
         Deletes all the tools in the toolbar.
     */
 
     /**
         Deletes all the tools in the toolbar.
     */

-    void ClearTools();
+    virtual void ClearTools();

 
     /**
         Removes the specified tool from the toolbar and deletes it. If you don't
 
     /**
         Removes the specified tool from the toolbar and deletes it. If you don't


@@ -343,19 +498,19 @@ public:
 
         @see DeleteToolByPos()
     */
 
         @see DeleteToolByPos()
     */

-    bool DeleteTool(int toolId);
+    virtual bool DeleteTool(int toolId);

 
     /**
         This function behaves like DeleteTool() but it deletes the tool at the
         specified position and not the one with the given id.
     */
 
     /**
         This function behaves like DeleteTool() but it deletes the tool at the
         specified position and not the one with the given id.
     */

-    bool DeleteToolByPos(size_t pos);
+    virtual bool DeleteToolByPos(size_t pos);

 
     /**
         Enables or disables the tool.
 
         @param toolId
 
     /**
         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.
 
         @param enable
             If @true, enables the tool, otherwise disables it.
 


@@ -365,19 +520,19 @@ public:
 
         @see GetToolEnabled(), ToggleTool()
     */
 
         @see GetToolEnabled(), ToggleTool()
     */

-    void EnableTool(int toolId, bool enable);
+    virtual void EnableTool(int toolId, bool enable);

 
     /**
         Returns a pointer to the tool identified by @a id or @NULL if no
         corresponding tool is found.
     */
 
     /**
         Returns a pointer to the tool identified by @a id or @NULL if no
         corresponding tool is found.
     */

-    wxToolBarToolBase* FindById(int id);
+    wxToolBarToolBase* FindById(int id) const;

 
     /**
         Returns a pointer to the control identified by @a id or @NULL if no
         corresponding control is found.
     */
 
     /**
         Returns a pointer to the control identified by @a id or @NULL if no
         corresponding control is found.
     */

-    wxControl* FindControl(int id);
+    virtual wxControl* FindControl(int id);

 
     /**
         Finds a tool for the given mouse position.
 
     /**
         Finds a tool for the given mouse position.


@@ -392,7 +547,7 @@ public:
         @remarks Currently not implemented in wxGTK (always returns @NULL
         there).
     */
         @remarks Currently not implemented in wxGTK (always returns @NULL
         there).
     */

-    wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;
+    virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;

 
     /**
         Returns the left/right and top/bottom margins, which are also used for
 
     /**
         Returns the left/right and top/bottom margins, which are also used for


@@ -403,77 +558,98 @@ public:
     wxSize GetMargins() const;
 
     /**
     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.
 
         @see SetToolBitmapSize(), GetToolSize()
     */
 
         @remarks Note that this is the size of the bitmap you pass to AddTool(),
             and not the eventual size of the tool button.
 
         @see SetToolBitmapSize(), GetToolSize()
     */

-    wxSize GetToolBitmapSize();
+    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
 
     /**
         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.
     */
 
         @return Client data, or @NULL if there is none.
     */

-    wxObject* GetToolClientData(int toolId) const;
+    virtual wxObject* GetToolClientData(int toolId) const;

 
     /**
         Called to determine whether a tool is enabled (responds to user input).
 
         @param toolId
 
     /**
         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.
 
         @see EnableTool()
     */
 
         @return @true if the tool is enabled, @false otherwise.
 
         @see EnableTool()
     */

-    bool GetToolEnabled(int toolId) const;
+    virtual bool GetToolEnabled(int toolId) const;

 
     /**
         Returns the long help for the given tool.
 
         @param toolId
 
     /**
         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()
     */
 
         @see SetToolLongHelp(), SetToolShortHelp()
     */

-    wxString GetToolLongHelp(int toolId) const;
+    virtual wxString GetToolLongHelp(int toolId) const;

 
     /**
         Returns the value used for packing tools.
 
         @see SetToolPacking()
     */
 
     /**
         Returns the value used for packing tools.
 
         @see SetToolPacking()
     */

-    int GetToolPacking() const;
+    virtual int GetToolPacking() const;

 
     /**
         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
         is not found.
 
     /**
         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().

     */
     */

-    int GetToolPos(int toolId) const;
+    virtual int GetToolPos(int toolId) const;

 
     /**
         Returns the default separator size.
 
         @see SetToolSeparation()
     */
 
     /**
         Returns the default separator size.
 
         @see SetToolSeparation()
     */

-    int GetToolSeparation() const;
+    virtual int GetToolSeparation() const;

 
     /**
         Returns the short help for the given tool.
 
         @param toolId
 
     /**
         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()
     */
 
         @see GetToolLongHelp(), SetToolShortHelp()
     */

-    wxString GetToolShortHelp(int toolId) const;
+    virtual wxString GetToolShortHelp(int toolId) const;

 
     /**
         Returns the size of a whole button, which is usually larger than a tool
 
     /**
         Returns the size of a whole button, which is usually larger than a tool


@@ -481,24 +657,24 @@ public:
 
         @see SetToolBitmapSize(), GetToolBitmapSize()
     */
 
         @see SetToolBitmapSize(), GetToolBitmapSize()
     */

-    wxSize GetToolSize();
+    virtual wxSize GetToolSize() const;

 
     /**
         Gets the on/off state of a toggle tool.
 
         @param toolId
 
     /**
         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.
 
         @see ToggleTool()
     */
 
         @return @true if the tool is toggled on, @false otherwise.
 
         @see ToggleTool()
     */

-    bool GetToolState(int toolId) const;
+    virtual bool GetToolState(int toolId) const;

 
     /**
         Returns the number of tools in the toolbar.
     */
 
     /**
         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
 
     /**
         Inserts the control into the toolbar at the given position. You must


@@ -506,7 +682,8 @@ public:
 
         @see AddControl(), InsertTool()
     */
 
         @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
 
     /**
         Inserts the separator into the toolbar at the given position. You must


@@ -514,7 +691,18 @@ public:
 
         @see AddSeparator(), InsertTool()
     */
 
         @see AddSeparator(), InsertTool()
     */

-    wxToolBarToolBase* InsertSeparator(size_t pos);
+    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);

 
     //@{
     /**
 
     //@{
     /**


@@ -524,14 +712,21 @@ public:
         You must call Realize() for the change to take place.
 
         @see AddTool(), InsertControl(), InsertSeparator()
         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);
     //@}
     wxToolBarToolBase* InsertTool(size_t pos,
                                   wxToolBarToolBase* tool);
     //@}


@@ -554,7 +749,7 @@ public:
 
         @see OnMouseEnter(), OnRightClick()
     */
 
         @see OnMouseEnter(), OnRightClick()
     */

-    bool OnLeftClick(int toolId, bool toggleDown);
+    virtual bool OnLeftClick(int toolId, bool toggleDown);

 
     /**
         This is called when the mouse cursor moves into a tool or out of the
 
     /**
         This is called when the mouse cursor moves into a tool or out of the


@@ -572,7 +767,7 @@ public:
                  out of the toolbar, wxWidgets may not be able to detect it.
                  Therefore this function may not always be called when expected.
     */
                  out of the toolbar, wxWidgets may not be able to detect it.
                  Therefore this function may not always be called when expected.
     */

-    void OnMouseEnter(int toolId);
+    virtual void OnMouseEnter(int toolId);

 
     /**
         @deprecated This is the old way of detecting tool right clicks;
 
     /**
         @deprecated This is the old way of detecting tool right clicks;


@@ -593,12 +788,12 @@ public:
 
         @see OnMouseEnter(), OnLeftClick()
     */
 
         @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.
     */
 
     /**
         This function should be called after you have added tools.
     */

-    bool Realize();
+    virtual bool Realize();

 
     /**
         Removes the given tool from the toolbar but doesn't delete it. This
 
     /**
         Removes the given tool from the toolbar but doesn't delete it. This


@@ -610,11 +805,15 @@ public:
 
         @see DeleteTool()
     */
 
         @see DeleteTool()
     */

-    wxToolBarToolBase* RemoveTool(int id);
+    virtual wxToolBarToolBase* RemoveTool(int id);

 
     /**
         Sets the bitmap resource identifier for specifying tool bitmaps as
 
     /**
         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);
 
     */
     void SetBitmapResource(int resourceId);
 


@@ -628,6 +827,7 @@ public:
     */
     bool SetDropdownMenu(int id, wxMenu* menu);
 
     */
     bool SetDropdownMenu(int id, wxMenu* menu);
 

+    //@{

     /**
         Set the values to be used as margins for the toolbar.
 
     /**
         Set the values to be used as margins for the toolbar.
 


@@ -642,7 +842,7 @@ public:
 
         @see GetMargins()
     */
 
         @see GetMargins()
     */

-    void SetMargins(int x, int y);
+    virtual void SetMargins(int x, int y);

 
     /**
         Set the margins for the toolbar.
 
     /**
         Set the margins for the toolbar.


@@ -657,6 +857,7 @@ public:
         @see GetMargins(), wxSize
     */
     void SetMargins(const wxSize& size);
         @see GetMargins(), wxSize
     */
     void SetMargins(const wxSize& size);

+    //@}

 
     /**
         Sets the default size of each tool bitmap. The default bitmap size is 16
 
     /**
         Sets the default size of each tool bitmap. The default bitmap size is 16


@@ -670,30 +871,36 @@ public:
 
         @see GetToolBitmapSize(), GetToolSize()
     */
 
         @see GetToolBitmapSize(), GetToolSize()
     */

-    void SetToolBitmapSize(const wxSize& size);
+    virtual void SetToolBitmapSize(const wxSize& size);

 
     /**
         Sets the client data associated with the tool.
 
     /**
         Sets the client data associated with the tool.

+
+        @param id
+            ID of the tool in question, as passed to AddTool().

     */
     */

-    void SetToolClientData(int id, wxObject* clientData);
+    virtual void SetToolClientData(int id, wxObject* clientData);

 
     /**
         Sets the bitmap to be used by the tool with the given ID when the tool
         is in a disabled state. This can only be used on Button tools, not
         controls.
 
 
     /**
         Sets the bitmap to be used by the tool with the given ID when the tool
         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.
 
     */
         @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.
 
     */

-    void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
+    virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);

 
     /**
         Sets the long help for the given tool.
 
         @param toolId
 
     /**
         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.
 
         @param helpString
             A string for the long help.
 


@@ -702,13 +909,16 @@ public:
 
         @see GetToolLongHelp(), SetToolShortHelp(),
     */
 
         @see GetToolLongHelp(), SetToolShortHelp(),
     */

-    void SetToolLongHelp(int toolId, const wxString& helpString);
+    virtual void SetToolLongHelp(int toolId, const wxString& helpString);

 
     /**
         Sets the bitmap to be used by the tool with the given ID. This can only
         be used on Button tools, not controls.
 
     /**
         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().

     */
     */

-    void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
+    virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);

 
     /**
         Sets the value used for spacing tools. The default value is 1.
 
     /**
         Sets the value used for spacing tools. The default value is 1.


@@ -716,13 +926,13 @@ public:
         @param packing
             The value for packing.
 
         @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.
 
         @see GetToolPacking()
     */
             the toolbar is horizontal, and for spacing in the horizontal
             direction if the toolbar is vertical.
 
         @see GetToolPacking()
     */

-    void SetToolPacking(int packing);
+    virtual void SetToolPacking(int packing);

 
     /**
         Sets the default separator size. The default value is 5.
 
     /**
         Sets the default separator size. The default value is 5.


@@ -732,13 +942,13 @@ public:
 
         @see AddSeparator()
     */
 
         @see AddSeparator()
     */

-    void SetToolSeparation(int separation);
+    virtual void SetToolSeparation(int separation);

 
     /**
         Sets the short help for the given tool.
 
         @param toolId
 
     /**
         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.
 
         @param helpString
             The string for the short help.
 


@@ -748,19 +958,42 @@ public:
 
         @see GetToolShortHelp(), SetToolLongHelp()
     */
 
         @see GetToolShortHelp(), SetToolLongHelp()
     */

-    void SetToolShortHelp(int toolId, const wxString& helpString);
+    virtual void SetToolShortHelp(int toolId, const wxString& helpString);

 
     /**
         Toggles a tool on or off. This does not cause any event to get emitted.
 
         @param toolId
 
     /**
         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.
 
         @remarks Only applies to a tool that has been specified as a toggle
             tool.
     */
         @param toggle
             If @true, toggles the tool on, otherwise toggles it off.
 
         @remarks Only applies to a tool that has been specified as a toggle
             tool.
     */

-    void ToggleTool(int toolId, bool toggle);
+    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()

 };
 
 };