The name wxToolBar is defined to be a synonym for one of the following classes:
Note that the base class wxToolBarBase defines automatic scrolling management functionality which is identical to wxScrolledWindow, so please refer to this class also. Not all toolbars support scrolling, but wxToolBarSimple does.
Derived from
wxToolBarBase
wxControl
wxWindow
wxEvtHandler
wxObject
Include files
<wx/toolbar.h> (to allow wxWindows to select an appropriate toolbar class)
<wx/tbarbase.h> (the base class)
<wx/tbarmsw.h> (the non-Windows 95 Windows toolbar class)
<wx/tbar95.h> (the Windows 95/98 toolbar class)
<wx/tbarsmpl.h> (the generic simple toolbar class)
Remarks
You may also create a toolbar that is managed by the frame, by calling wxFrame::CreateToolBar.
wxToolBar95: Note that this toolbar paints tools to reflect user-selected colours. The toolbar orientation must always be wxVERTICAL.
Window styles
wxTB_FLAT | Gives the toolbar a flat look ('coolbar' or 'flatbar' style). Windows 95 only. |
wxTB_HORIZONTAL | Specifies horizontal layout. |
wxTB_VERTICAL | Specifies vertical layout (not available for the Windows 95 toolbar). |
wxTB_3DBUTTONS | Gives wxToolBarSimple a mild 3D look to its buttons. |
See also window styles overview.
Event handling
The toolbar class emits menu commands in the same was 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 is passed and the tool id is retrieved from the wxCommandEvent. This is because the id may be -1 when the mouse moves off a tool, and -1 is not allowed as an identifier in the event system.
EVT_TOOL(id, func) | Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool. |
EVT_MENU(id, func) | The same as EVT_TOOL. |
EVT_TOOL_RANGE(id1, id2, func) | Process a wxEVT_COMMAND_TOOL_CLICKED event for a range id identifiers. Pass the ids of the tools. |
EVT_MENU_RANGE(id1, id2, func) | The same as EVT_TOOL_RANGE. |
EVT_TOOL_RCLICKED(id, func) | Process a wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. |
EVT_TOOL_RCLICKED_RANGE(id1, id2, func) | Process a wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. |
EVT_TOOL_ENTER(id, func) | Process a wxEVT_COMMAND_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. |
See also
Toolbar overview, wxScrolledWindow
Members
wxToolBar::wxToolBar
wxToolBar::~wxToolBar
wxToolBar::AddSeparator
wxToolBar::AddTool
wxToolBar::CreateTools
wxToolBar::DrawTool
wxToolBar::EnableTool
wxToolBar::FindToolForPosition
wxToolBar::GetToolSize
wxToolBar::GetToolBitmapSize
wxToolBar::GetMargins
wxToolBar::GetMaxSize
wxToolBar::GetToolClientData
wxToolBar::GetToolEnabled
wxToolBar::GetToolLongHelp
wxToolBar::GetToolPacking
wxToolBar::GetToolSeparation
wxToolBar::GetToolShortHelp
wxToolBar::GetToolState
wxToolBar::Layout
wxToolBar::OnLeftClick
wxToolBar::OnMouseEnter
wxToolBar::OnRightClick
wxToolBar::Realize
wxToolBar::SetToolBitmapSize
wxToolBar::SetMargins
wxToolBar::SetToolLongHelp
wxToolBar::SetToolPacking
wxToolBar::SetToolShortHelp
wxToolBar::SetToolSeparation
wxToolBar::ToggleTool
wxToolBar()
Default constructor.
wxToolBar(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxTB_HORIZONTAL | wxNO_BORDER, const wxString& name = wxPanelNameStr)
Constructs a toolbar.
Parameters
parent
id
pos
size
style
name
Remarks
After a toolbar is created, you use wxToolBar::AddTool and perhaps wxToolBar::AddSeparator, and then you must call wxToolBar::Realize to construct and display the toolbar tools.
You may also create a toolbar that is managed by the frame, by calling wxFrame::CreateToolBar.
void ~wxToolBar()
Toolbar destructor.
void AddSeparator()
Adds a separator for spacing groups of tools.
See also
wxToolBar::AddTool, wxToolBar::SetToolSeparation
wxToolBarTool* AddTool(int toolIndex, const wxBitmap& bitmap1, const wxBitmap& bitmap2 = wxNullBitmap, bool isToggle = FALSE, long xPos = -1, long yPos = -1, wxObject* clientData = NULL, const wxString& shortHelpString = "", const wxString& longHelpString = "")
Adds a tool to the toolbar.
Parameters
toolIndex
isToggle
bitmap1
bitmap2
xPos
yPos
clientData
shortHelpString
longHelpString
Remarks
After you have added tools to a toolbar, you must call wxToolBar::Realize in order to have the tools appear.
See also
wxToolBar::AddSeparator, wxToolBar::Realize,
bool CreateTools()
This function is implemented for some toolbar classes to create the tools and display them. The portable way of calling it is to call wxToolBar::Realize after you have added tools and separators.
See also
wxToolBar::AddTool, wxToolBar::Realize
void DrawTool(wxMemoryDC& memDC, wxToolBarTool* tool)
Draws the specified tool onto the window using the given memory device context.
Parameters
memDC
tool
Remarks
For internal use only.
void EnableTool(int toolIndex, const bool enable)
Enables or disables the tool.
Parameters
toolIndex
enable
Remarks
For wxToolBarSimple, does nothing. Some other implementations will change the visible state of the tool to indicate that it is disabled.
See also
wxToolBar::GetToolEnabled, wxToolBar::ToggleTool
wxToolBarTool* FindToolForPosition(const float x, const float y) const
Finds a tool for the given mouse position.
Parameters
x
y
Return value
A pointer to a tool if a tool is found, or NULL otherwise.
Remarks
Used internally, and should not need to be used by the programmer.
wxSize GetToolSize()
Returns the size of a whole button, which is usually larger than a tool bitmap because of added 3D effects.
See also
wxToolBar::SetToolBitmapSize, wxToolBar::GetToolBitmapSize
wxSize GetToolBitmapSize()
Returns the size of bitmap that the toolbar expects to have. The default bitmap size is 16 by 15 pixels.
Remarks
Note that this is the size of the bitmap you pass to wxToolBar::AddTool, and not the eventual size of the tool button.
See also
wxToolBar::SetToolBitmapSize, wxToolBar::GetToolSize
wxSize GetMargins() const
Returns the left/right and top/bottom margins, which are also used for inter-toolspacing.
See also
void GetMaxSize(float* w, float* h) const
Gets the maximum size taken up by the tools after layout, including margins. This can be used to size a frame around the toolbar window.
Parameters
w
h
wxObject* GetToolClientData(int toolIndex) const
Get any client data associated with the tool.
Parameters
toolIndex
Return value
Client data, or NULL if there is none.
bool GetToolEnabled(int toolIndex) const
Called to determine whether a tool is enabled (responds to user input).
Parameters
toolIndex
Return value
TRUE if the tool is enabled, FALSE otherwise.
wxString GetToolLongHelp(int toolIndex) const
Returns the long help for the given tool.
Parameters
toolIndex
See also
wxToolBar::SetToolLongHelp, wxToolBar::SetToolShortHelp
int GetToolPacking() const
Returns the value used for packing tools.
See also
int GetToolSeparation() const
Returns the default separator size.
See also
wxString GetToolShortHelp(int toolIndex) const
Returns the short help for the given tool.
Returns the long help for the given tool.
Parameters
toolIndex
See also
wxToolBar::GetToolLongHelp, wxToolBar::SetToolShortHelp
bool GetToolState(int toolIndex) const
Gets the on/off state of a toggle tool.
Parameters
toolIndex
Return value
TRUE if the tool is toggled on, FALSE otherwise.
void Layout()
Called by the application after the tools have been added to automatically lay the tools out on the window. If you have given absolute positions when adding the tools, do not call this.
This function is only implemented for some toolbar classes. The portable way of calling it is to call wxToolBar::Realize after you have added tools and separators.
See also
wxToolBar::AddTool, wxToolBar::Realize
bool OnLeftClick(int toolIndex, bool toggleDown)
Called when the user clicks on a tool with the left mouse button.
This is the old way of detecting tool clicks; although it will still work, you should use the EVT_MENU or EVT_TOOL macro instead.
Parameters
toolIndex
toggleDown
Return value
If the tool is a toggle and this function returns FALSE, the toggle toggle state (internal and visual) will not be changed. This provides a way of specifying that toggle operations are not permitted in some circumstances.
See also
wxToolBar::OnMouseEnter, wxToolBar::OnRightClick
void OnMouseEnter(int toolIndex)
This is called when the mouse cursor moves into a tool or out of the toolbar.
This is the old way of detecting mouse enter events; although it will still work, you should use the EVT_TOOL_ENTER macro instead.
Parameters
toolIndex
Remarks
With some derived toolbar classes, if the mouse moves quickly out of the toolbar, wxWindows may not be able to detect it. Therefore this function may not always be called when expected.
void OnRightClick(int toolIndex, float x, float y)
Called when the user clicks on a tool with the right mouse button. The programmer should override this function to detect right tool clicks.
This is the old way of detecting tool right clicks; although it will still work, you should use the EVT_TOOL_RCLICKED macro instead.
Parameters
toolIndex
x
y
Remarks
A typical use of this member might be to pop up a menu.
See also
wxToolBar::OnMouseEnter, wxToolBar::OnLeftClick
bool Realize()
This function should be called after you have added tools. It calls, according to the implementation, either wxToolBar::CreateTools or wxToolBar::Layout.
If you are using absolute positions for your tools when using a wxToolBarSimple object, do not call this function. You must call it at all other times.
void SetToolBitmapSize(const wxSize& size)
Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 pixels.
Parameters
size
Remarks
This should be called to tell the toolbar what the tool bitmap size is. Call it before you add tools.
Note that this is the size of the bitmap you pass to wxToolBar::AddTool, and not the eventual size of the tool button.
See also
wxToolBar::GetToolBitmapSize, wxToolBar::GetToolSize
void SetMargins(const wxSize& size)
void SetMargins(int x, int y)
Set the values to be used as margins for the toolbar.
Parameters
size
x
y
Remarks
This must be called before the tools are added if absolute positioning is to be used, and the default (zero-size) margins are to be overridden.
See also
void SetToolLongHelp(int toolIndex, const wxString& helpString)
Sets the long help for the given tool.
Parameters
toolIndex
helpString
Remarks
You might use the long help for displaying the tool purpose on the status line.
See also
wxToolBar::GetToolLongHelp, wxToolBar::SetToolShortHelp,
void SetToolPacking(int packing)
Sets the value used for spacing tools. The default value is 1.
Parameters
packing
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.
See also
void SetToolShortHelp(int toolIndex, const wxString& helpString)
Sets the short help for the given tool.
Parameters
toolIndex
helpString
Remarks
An application might use short help for identifying the tool purpose in a tooltip.
See also
wxToolBar::GetToolShortHelp, wxToolBar::SetToolLongHelp
void SetToolSeparation(int separation)
Sets the default separator size. The default value is 5.
Parameters
separation
See also
void ToggleTool(int toolIndex, const bool toggle)
Toggles a tool on or off.
Parameters
toolIndex
toggle
Remarks
Only applies to a tool that has been specified as a toggle tool.
See also