// 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
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,
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:
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
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.
/**
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.
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()
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
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().
*/
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,
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.
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.
*/
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.
*/
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.
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()
*/
/**
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;
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()
*/
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.
*/
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
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);
//@}
/**
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);
/**
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);
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.
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.
/**
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);
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.
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.
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()
};
projects / wxWidgets.git / blobdiff