]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/toolbar.h
Add the ability to trigger a print from JavaScript for the old wxWebKitCtrl.
[wxWidgets.git] / interface / wx / toolbar.h
index 93b844b26f30e470ede8f87b591c549fc7c79ff7..9bd3b169aeb7941598b43bcc24ae456736f6853c 100644 (file)
@@ -3,9 +3,146 @@
 // 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 wxToolBarToolBase
+
+    A toolbar tool represents one item on the 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);
+
+    virtual void SetDropdownMenu(wxMenu *menu);
+    wxMenu *GetDropdownMenu() const;
+};
+
+
+
+
 /**
     @class wxToolBar
 
     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,
@@ -228,10 +365,27 @@ public:
         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();
 
+    /**
+        Adds a stretchable space to the toolbar.
+
+        Any space not taken up by the fixed items (all items except for
+        stretchable spaces) is distributed in equal measure between the
+        stretchable spaces in the toolbar. The most common use for this method
+        is to add a single stretchable space before the items which should be
+        right-aligned in the toolbar, but more exotic possibilities are
+        possible, e.g. a stretchable space may be added in the beginning and
+        the end of the toolbar to centre all toolbar items.
+
+        @see AddTool(), AddSeparator(), InsertStretchableSpace()
+
+        @since 2.9.1
+     */
+    wxToolBarToolBase *AddStretchableSpace();
+
     //@{
     /**
         Adds a tool to the toolbar.
@@ -240,7 +394,7 @@ public:
             The tool to be added.
 
         @remarks After you have added tools to a toolbar, you must call
-            Realize() in order to have the tools appear.
+                 Realize() in order to have the tools appear.
 
         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
@@ -295,11 +449,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.
-        @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
@@ -308,6 +457,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.
+        @param shortHelpString
+            This string is used for the tools tooltip.
+        @param longHelpString
+            This string is shown in the statusbar (if any) of the parent frame
+            when the mouse pointer is inside the tool.
         @param clientData
             An optional pointer to client data which can be retrieved later
             using GetToolClientData().
@@ -320,7 +474,7 @@ public:
     */
     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
                                const wxBitmap& bitmap,
-                               const wxBitmap& bmpDisabled = wxNullBitmap,
+                               const wxBitmap& bmpDisabled,
                                wxItemKind kind = wxITEM_NORMAL,
                                const wxString& shortHelpString = wxEmptyString,
                                const wxString& longHelpString = wxEmptyString,
@@ -356,7 +510,7 @@ public:
         Enables or disables the tool.
 
         @param toolId
-            Tool to enable or disable.
+            ID of the tool to enable or disable, as passed to AddTool().
         @param enable
             If @true, enables the tool, otherwise disables it.
 
@@ -421,11 +575,22 @@ public:
     */
     virtual wxSize GetToolBitmapSize() const;
 
+    /**
+        Returns a pointer to the tool at ordinal position @a pos.
+
+        Don't confuse this with FindToolForPosition().
+
+        @since 2.9.1
+
+        @see GetToolsCount()
+    */
+    const wxToolBarToolBase *GetToolByPos(int pos) const;
+
     /**
         Get any client data associated with the tool.
 
         @param toolId
-            Id of the tool, as passed to AddTool().
+            ID of the tool in question, as passed to AddTool().
 
         @return Client data, or @NULL if there is none.
     */
@@ -435,7 +600,7 @@ public:
         Called to determine whether a tool is enabled (responds to user input).
 
         @param toolId
-            Id of the tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @return @true if the tool is enabled, @false otherwise.
 
@@ -447,7 +612,7 @@ public:
         Returns the long help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @see SetToolLongHelp(), SetToolShortHelp()
     */
@@ -463,6 +628,9 @@ public:
     /**
         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
         is not found.
+
+        @param toolId
+            ID of the tool in question, as passed to AddTool().
     */
     virtual int GetToolPos(int toolId) const;
 
@@ -477,7 +645,7 @@ public:
         Returns the short help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @see GetToolLongHelp(), SetToolShortHelp()
     */
@@ -495,7 +663,7 @@ public:
         Gets the on/off state of a toggle tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
 
         @return @true if the tool is toggled on, @false otherwise.
 
@@ -525,6 +693,17 @@ public:
     */
     virtual wxToolBarToolBase* InsertSeparator(size_t pos);
 
+    /**
+        Inserts a stretchable space at the given position.
+
+        See AddStretchableSpace() for details about stretchable spaces.
+
+        @see InsertTool(), InsertSeparator()
+
+        @since 2.9.1
+     */
+    wxToolBarToolBase *InsertStretchableSpace(size_t pos);
+
     //@{
     /**
         Inserts the tool with the specified attributes into the toolbar at the
@@ -533,14 +712,21 @@ public:
         You must call Realize() for the change to take place.
 
         @see AddTool(), InsertControl(), InsertSeparator()
+
+        @return The newly inserted tool or @NULL on failure. Notice that with
+            the overload taking @a tool parameter the caller is responsible for
+            deleting the tool in the latter case.
     */
-    wxToolBarToolBase* InsertTool(size_t pos, int toolId,
-                                  const wxBitmap& bitmap1,
-                                  const wxBitmap& bitmap2 = wxNullBitmap,
-                                  bool isToggle = false,
-                                  wxObject* clientData = NULL,
-                                  const wxString& shortHelpString = wxEmptyString,
-                                  const wxString& longHelpString = wxEmptyString);
+    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);
     //@}
@@ -623,7 +809,11 @@ public:
 
     /**
         Sets the bitmap resource identifier for specifying tool bitmaps as
-        indices into a custom bitmap. Windows CE only.
+        indices into a custom bitmap.
+
+        This is a Windows CE-specific method not available in the other ports.
+
+        @onlyfor{wxmsw_wince}
     */
     void SetBitmapResource(int resourceId);
 
@@ -685,6 +875,9 @@ public:
 
     /**
         Sets the client data associated with the tool.
+
+        @param id
+            ID of the tool in question, as passed to AddTool().
     */
     virtual void SetToolClientData(int id, wxObject* clientData);
 
@@ -693,6 +886,9 @@ public:
         is in a disabled state. This can only be used on Button tools, not
         controls.
 
+        @param id
+            ID of the tool in question, as passed to AddTool().
+
         @note The native toolbar classes on the main platforms all synthesize
             the disabled bitmap from the normal bitmap, so this function will
             have no effect on those platforms.
@@ -704,7 +900,7 @@ public:
         Sets the long help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
         @param helpString
             A string for the long help.
 
@@ -718,6 +914,9 @@ public:
     /**
         Sets the bitmap to be used by the tool with the given ID. This can only
         be used on Button tools, not controls.
+
+        @param id
+            ID of the tool in question, as passed to AddTool().
     */
     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 
@@ -749,7 +948,7 @@ public:
         Sets the short help for the given tool.
 
         @param toolId
-            The tool in question.
+            ID of the tool in question, as passed to AddTool().
         @param helpString
             The string for the short help.
 
@@ -765,7 +964,7 @@ public:
         Toggles a tool on or off. This does not cause any event to get emitted.
 
         @param toolId
-            Tool in question.
+            ID of the tool in question, as passed to AddTool().
         @param toggle
             If @true, toggles the tool on, otherwise toggles it off.
 
@@ -773,5 +972,28 @@ public:
             tool.
     */
     virtual void ToggleTool(int toolId, bool toggle);
+
+
+    /**
+       Factory function to create a new toolbar tool.
+    */
+    virtual wxToolBarToolBase *CreateTool(int toolId,
+                                          const wxString& label,
+                                          const wxBitmap& bmpNormal,
+                                          const wxBitmap& bmpDisabled = wxNullBitmap,
+                                          wxItemKind kind = wxITEM_NORMAL,
+                                          wxObject *clientData = NULL,
+                                          const wxString& shortHelp = wxEmptyString,
+                                          const wxString& longHelp = wxEmptyString);
+    /**
+       Factory function to create a new control toolbar tool.
+    */
+    virtual wxToolBarToolBase *CreateTool(wxControl *control,
+                                          const wxString& label);
+
+    /**
+       Factory function to create a new separator toolbar tool.
+    */
+    wxToolBarToolBase *CreateSeparator()
 };