add SetCharIncludes and SetCharExcludes utilities to wxTextValidator; use iterators...

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

diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h
index 45705ce73572a73b3f2ef2d75f015d2949b45160..a7ccb783a747ee8a171490bb607bedb55ef309d5 100644 (file)
--- a/interface/wx/toolbar.h
+++ b/interface/wx/toolbar.h
@@ -12,14 +12,23 @@
     A toolbar is a bar of buttons and/or other controls usually placed below
     the menu bar in a wxFrame.
 
     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 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.
+    own toolbars, create wxToolBar as usual.

 
 

-    The meaning of a "separator" is a vertical line under Windows and simple
-    space under GTK+.
+    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,
 
     <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,


@@ -27,12 +36,12 @@
     bitmaps will inadvertently be mapped to system colours.
     To do this, set the msw.remap system option before creating the toolbar:
     @code
     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
     @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:
     @endcode
     Then colour remapping is switched off, and a transparent background
     used. But only use this option under Windows XP with true colour:


@@ -40,9 +49,6 @@
     if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
     @endcode
 
     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}
         Gives the toolbar a flat look (Windows and GTK only).
     @beginStyleTable
     @style{wxTB_FLAT}
         Gives the toolbar a flat look (Windows and GTK only).


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


@@ -111,8 +117,8 @@
     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
     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}


@@ -136,25 +142,25 @@ 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,
+              long style = wxTB_HORIZONTAL,

               const wxString& name = wxToolBarNameStr);
 
     /**
               const wxString& name = wxToolBarNameStr);
 
     /**


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


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


@@ -520,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);
     //@}


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


@@ -647,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