Contents Up Previous Next

wxToolBar

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::wxToolBar

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.


wxToolBar::~wxToolBar

void ~wxToolBar()

Toolbar destructor.


wxToolBar::AddSeparator

void AddSeparator()

Adds a separator for spacing groups of tools.

See also

wxToolBar::AddTool, wxToolBar::SetToolSeparation


wxToolBar::AddTool

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,


wxToolBar::CreateTools

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


wxToolBar::DrawTool

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.


wxToolBar::EnableTool

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


wxToolBar::FindToolForPosition

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.


wxToolBar::GetToolSize

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


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


wxToolBar::GetMargins

wxSize GetMargins() const

Returns the left/right and top/bottom margins, which are also used for inter-toolspacing.

See also

wxToolBar::SetMargins


wxToolBar::GetMaxSize

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


wxToolBar::GetToolClientData

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.


wxToolBar::GetToolEnabled

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.


wxToolBar::GetToolLongHelp

wxString GetToolLongHelp(int toolIndex) const

Returns the long help for the given tool.

Parameters

toolIndex

See also

wxToolBar::SetToolLongHelp, wxToolBar::SetToolShortHelp


wxToolBar::GetToolPacking

int GetToolPacking() const

Returns the value used for packing tools.

See also

wxToolBar::SetToolPacking


wxToolBar::GetToolSeparation

int GetToolSeparation() const

Returns the default separator size.

See also

wxToolBar::SetToolSeparation


wxToolBar::GetToolShortHelp

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


wxToolBar::GetToolState

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.


wxToolBar::Layout

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


wxToolBar::OnLeftClick

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


wxToolBar::OnMouseEnter

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.


wxToolBar::OnRightClick

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


wxToolBar::Realize

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.


wxToolBar::SetToolBitmapSize

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


wxToolBar::SetMargins

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

wxToolBar::GetMargins, wxSize


wxToolBar::SetToolLongHelp

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,


wxToolBar::SetToolPacking

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

wxToolBar::GetToolPacking


wxToolBar::SetToolShortHelp

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


wxToolBar::SetToolSeparation

void SetToolSeparation(int separation)

Sets the default separator size. The default value is 5.

Parameters

separation

See also

wxToolBar::AddSeparator


wxToolBar::ToggleTool

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

wxToolBar::GetToolState