Minor fixes to wxDateTime documentation.

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

diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h
index 02698a9b39b280d42c49c0292c7fcbf35685e7d0..ee96ddda049bc11ce1b7b7b934db98702867714a 100644 (file)
--- a/interface/wx/toolbar.h
+++ b/interface/wx/toolbar.h
@@ -3,7 +3,7 @@
 // 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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -28,7 +28,7 @@
     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
     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 the tool bar.
+    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,
 
     <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,


@@ -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
         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
     @event{EVT_TOOL_DROPDOWN(id, func)}
         Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled,
         displays the default dropdown menu set using


@@ -228,10 +228,27 @@ public:
         platform so it can be a vertical line (MSW, some versions of GTK) or
         just an empty space or something else.
 
         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();
 
     */
     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,7 +257,7 @@ 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()


@@ -295,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.
             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
         @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


@@ -308,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.
             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().


@@ -356,7 +373,7 @@ public:
         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.
 


@@ -421,11 +438,22 @@ public:
     */
     virtual wxSize GetToolBitmapSize() const;
 
     */
     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.
     */


@@ -435,7 +463,7 @@ public:
         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.
 
 
         @return @true if the tool is enabled, @false otherwise.
 


@@ -447,7 +475,7 @@ public:
         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()
     */


@@ -463,6 +491,9 @@ public:
     /**
         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().

     */
     virtual int GetToolPos(int toolId) const;
 
     */
     virtual int GetToolPos(int toolId) const;
 


@@ -477,7 +508,7 @@ public:
         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()
     */


@@ -495,7 +526,7 @@ public:
         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.
 
 
         @return @true if the tool is toggled on, @false otherwise.
 


@@ -525,6 +556,17 @@ public:
     */
     virtual 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);
+

     //@{
     /**
         Inserts the tool with the specified attributes into the toolbar at the
     //@{
     /**
         Inserts the tool with the specified attributes into the toolbar at the


@@ -533,6 +575,10 @@ 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,
     */
     wxToolBarToolBase* InsertTool(size_t pos, int toolId,
                                   const wxBitmap& bitmap1,


@@ -623,7 +669,11 @@ public:
 
     /**
         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{wxWinCE}

     */
     void SetBitmapResource(int resourceId);
 
     */
     void SetBitmapResource(int resourceId);
 


@@ -685,6 +735,9 @@ public:
 
     /**
         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().

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


@@ -693,6 +746,9 @@ public:
         is in a disabled state. This can only be used on Button tools, not
         controls.
 
         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.


@@ -704,7 +760,7 @@ public:
         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.
 


@@ -718,6 +774,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.
     /**
         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);
 
     */
     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 


@@ -749,7 +808,7 @@ public:
         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.
 


@@ -765,7 +824,7 @@ public:
         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.
 
         @param toggle
             If @true, toggles the tool on, otherwise toggles it off.