suppress warnings about missing_semicolons file not existing

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

diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h
index fc50cb0b3cbfbee2384ab946d1a8270284e67204..cef105a0dc669c819d9926f695853859a5923ce3 100644 (file)
--- a/interface/wx/toolbar.h
+++ b/interface/wx/toolbar.h
@@ -9,49 +9,45 @@
 /**
     @class wxToolBar
 
 /**
     @class wxToolBar
 

-    The name wxToolBar is defined to be a synonym for one of the following
-    classes:
+    A toolbar is a bar of buttons and/or other controls usually placed below
+    the menu bar in a wxFrame.

 
 

-    - @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.
-
-    You may also create a toolbar that is managed by the frame, by calling
+    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 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
     wxSystemOptions::SetOption(wxT("msw.remap"), 0);
     @endcode
     @code
     wxSystemOptions::SetOption(wxT("msw.remap"), 0);
     @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
     wxSystemOptions::SetOption(wxT("msw.remap"), 2);
     @endcode
     @code
     wxSystemOptions::SetOption(wxT("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:
     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,7 +81,7 @@
         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.
 


@@ -115,14 +111,14 @@
         displays the default dropdown menu set using
         wxToolBar::SetDropdownMenu().
     @endEventTable
         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,26 +142,26 @@ 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.


@@ -211,7 +207,7 @@ 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.
 
         By default, the first button in the radio group is initially pressed,
         the others are not.
 


@@ -228,10 +224,14 @@ public:
     /**
         Adds a separator for spacing groups of tools.
 
     /**
         Adds a separator for spacing groups of tools.
 

+        Note that the meaning of a "separator" is a vertical line under wxMSW and
+        a simple space under wxGTK.
+

         @see AddTool(), SetToolSeparation()
     */
     virtual wxToolBarToolBase* AddSeparator();
 
         @see AddTool(), SetToolSeparation()
     */
     virtual wxToolBarToolBase* AddSeparator();
 

+    //@{

     /**
         Adds a tool to the toolbar.
 
     /**
         Adds a tool to the toolbar.
 


@@ -247,14 +247,14 @@ public:
     virtual 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.


@@ -264,7 +264,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.


@@ -286,13 +286,13 @@ 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.
         @param shortHelpString
             This string is used for the tools tooltip.
             generated by greying the normal one.
         @param shortHelpString
             This string is used for the tools tooltip.


@@ -303,7 +303,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.


@@ -324,6 +324,7 @@ public:
                                const wxString& shortHelpString = wxEmptyString,
                                const wxString& longHelpString = wxEmptyString,
                                wxObject* clientData = NULL);
                                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.


@@ -530,8 +531,8 @@ public:
                                   const wxBitmap& bitmap2 = wxNullBitmap,
                                   bool isToggle = false,
                                   wxObject* clientData = NULL,
                                   const wxBitmap& bitmap2 = wxNullBitmap,
                                   bool isToggle = false,
                                   wxObject* clientData = NULL,

-                                  const wxString& shortHelpString = "",
-                                  const wxString& longHelpString = "");
+                                  const wxString& shortHelpString = wxEmptyString,
+                                  const wxString& longHelpString = wxEmptyString);

     wxToolBarToolBase* InsertTool(size_t pos,
                                   wxToolBarToolBase* tool);
     //@}
     wxToolBarToolBase* InsertTool(size_t pos,
                                   wxToolBarToolBase* tool);
     //@}


@@ -628,6 +629,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.
 


@@ -657,6 +659,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


@@ -716,7 +719,7 @@ 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.
 
             the toolbar is horizontal, and for spacing in the horizontal
             direction if the toolbar is vertical.