X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ccf39540bb96a0e5d067451ad79c82397579aceb..f54c646fb0561e54bca0ee2c17847bb9e7123304:/interface/wx/toolbar.h diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h index cef105a0dc..c85bdcf919 100644 --- a/interface/wx/toolbar.h +++ b/interface/wx/toolbar.h @@ -2,10 +2,149 @@ // Name: toolbar.h // 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 = wxHORIZONTAL, + wxTB_TOP = wxTB_HORIZONTAL, + + /** lay out the toolbar vertically */ + wxTB_VERTICAL = wxVERTICAL, + wxTB_LEFT = wxTB_VERTICAL, + + /** 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 = wxTB_HORZ_LAYOUT | wxTB_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, + + /** flags that are closest to the native look*/ + wxTB_DEFAULT_STYLE = wxTB_HORIZONTAL | wxTB_FLAT +}; + + + +/** + @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 @@ -28,7 +167,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 - the visible state of the item within the the tool bar. + the visible state of the item within the tool bar. wxMSW note: Note that under wxMSW toolbar paints tools to reflect system-wide colours. If you use more than 16 colours in your tool bitmaps, @@ -36,12 +175,12 @@ 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 - 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: @@ -79,35 +218,38 @@ Align the toolbar at the bottom of parent window. @style{wxTB_RIGHT} Align the toolbar at the right side of parent window. + @style{wxTB_DEFAULT_STYLE} + Combination of @c wxTB_HORIZONTAL and @c wxTB_FLAT. This style is new + since wxWidgets 2.9.5. @endStyleTable 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. - @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. + Process a @c wxEVT_TOOL event (a synonym for @c + wxEVT_MENU). Pass the id of the tool. @event{EVT_MENU(id, func)} The same as EVT_TOOL(). @event{EVT_TOOL_RANGE(id1, id2, func)} - Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of + Process a @c wxEVT_TOOL event for a range of identifiers. Pass the ids of the tools. @event{EVT_MENU_RANGE(id1, id2, func)} 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. + Process a @c wxEVT_TOOL_RCLICKED event. Pass the id of the + 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 - the ids of the tools. + Process a @c wxEVT_TOOL_RCLICKED event for a range of ids. Pass + 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 + Process a @c wxEVT_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, + Process a @c wxEVT_TOOL_DROPDOWN event. If unhandled, displays the default dropdown menu set using wxToolBar::SetDropdownMenu(). @endEventTable @@ -182,7 +324,7 @@ public: wxObject* clientData = NULL); /** - Adds any control to the toolbar, typically e.g. a wxComboBox. + Adds any control to the toolbar, typically e.g.\ a wxComboBox. @param control The control to be added. @@ -224,13 +366,31 @@ public: /** 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. + 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() + @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. @@ -239,7 +399,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() @@ -294,11 +454,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 @@ -307,6 +462,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(). @@ -319,7 +479,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, @@ -355,7 +515,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. @@ -403,8 +563,15 @@ public: 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. @@ -413,11 +580,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. */ @@ -427,7 +605,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. @@ -439,7 +617,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() */ @@ -455,6 +633,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; @@ -469,7 +650,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() */ @@ -487,7 +668,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. @@ -517,6 +698,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 @@ -525,14 +717,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); //@} @@ -615,7 +814,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); @@ -677,6 +880,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); @@ -685,6 +891,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. @@ -696,7 +905,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. @@ -710,6 +919,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); @@ -741,7 +953,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. @@ -757,7 +969,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. @@ -765,5 +977,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() };