1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxToolBar
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 A toolbar is a bar of buttons and/or other controls usually placed below
13 the menu bar in a wxFrame.
15 You may create a toolbar that is managed by a frame calling
16 wxFrame::CreateToolBar(). Under Pocket PC, you should always use this
17 function for creating the toolbar to be managed by the frame, so that
18 wxWidgets can use a combined menubar and toolbar. Where you manage your
19 own toolbars, create wxToolBar as usual.
21 There are several different types of tools you can add to a toolbar.
22 These types are controlled by the ::wxItemKind enumeration.
24 Note that many methods in wxToolBar such as wxToolBar::AddTool return a
25 @c wxToolBarToolBase* object.
26 This should be regarded as an opaque handle representing the newly added
27 toolbar item, providing access to its id and position within the toolbar.
28 Changes to the item's state should be made through calls to wxToolBar methods,
29 for example wxToolBar::EnableTool.
30 Calls to @c wxToolBarToolBase methods (undocumented by purpose) will not change
31 the visible state of the item within the the tool bar.
33 <b>wxMSW note</b>: Note that under wxMSW toolbar paints tools to reflect
34 system-wide colours. If you use more than 16 colours in your tool bitmaps,
35 you may wish to suppress this behaviour, otherwise system colours in your
36 bitmaps will inadvertently be mapped to system colours.
37 To do this, set the msw.remap system option before creating the toolbar:
39 wxSystemOptions::SetOption("msw.remap", 0);
41 If you wish to use 32-bit images (which include an alpha channel for
44 wxSystemOptions::SetOption("msw.remap", 2);
46 Then colour remapping is switched off, and a transparent background
47 used. But only use this option under Windows XP with true colour:
49 if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
54 Gives the toolbar a flat look (Windows and GTK only).
56 Makes the toolbar floatable and dockable (GTK only).
57 @style{wxTB_HORIZONTAL}
58 Specifies horizontal layout (default).
60 Specifies vertical layout.
62 Shows the text in the toolbar buttons; by default only icons are shown.
64 Specifies no icons in the toolbar buttons; by default they are shown.
65 @style{wxTB_NODIVIDER}
66 Specifies no divider (border) above the toolbar (Windows only)
68 Specifies no alignment with the parent window (Windows only, not very
70 @style{wxTB_HORZ_LAYOUT}
71 Shows the text and the icons alongside, not vertically stacked (Windows
72 and GTK 2 only). This style must be used with @c wxTB_TEXT.
73 @style{wxTB_HORZ_TEXT}
74 Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT.
75 @style{wxTB_NO_TOOLTIPS}
76 Don't show the short help tooltips for the tools when the mouse hovers
79 Align the toolbar at the bottom of parent window.
81 Align the toolbar at the right side of parent window.
84 See also @ref overview_windowstyles. Note that the wxMSW native toolbar
85 ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only
86 if the style was initially on.
88 @beginEventEmissionTable{wxCommandEvent}
89 @event{EVT_TOOL(id, func)}
90 Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c
91 wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool.
92 @event{EVT_MENU(id, func)}
93 The same as EVT_TOOL().
94 @event{EVT_TOOL_RANGE(id1, id2, func)}
95 Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of
96 identifiers. Pass the ids of the tools.
97 @event{EVT_MENU_RANGE(id1, id2, func)}
98 The same as EVT_TOOL_RANGE().
99 @event{EVT_TOOL_RCLICKED(id, func)}
100 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the
101 tool. (Not available on wxOSX.)
102 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
103 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass
104 the ids of the tools. (Not available on wxOSX.)
105 @event{EVT_TOOL_ENTER(id, func)}
106 Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar
107 itself. The value of wxCommandEvent::GetSelection() is the tool id, or
108 -1 if the mouse cursor has moved off a tool. (Not available on wxOSX.)
109 @event{EVT_TOOL_DROPDOWN(id, func)}
110 Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled,
111 displays the default dropdown menu set using
112 wxToolBar::SetDropdownMenu().
115 The toolbar class emits menu commands in the same way that a frame menubar
116 does, so you can use one EVT_MENU() macro for both a menu item and a toolbar
117 button. The event handler functions take a wxCommandEvent argument. For most
118 event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER()
119 the toolbar window identifier is passed and the tool identifier is retrieved
120 from the wxCommandEvent. This is because the identifier may be @c wxID_ANY when the
121 mouse moves off a tool, and @c wxID_ANY is not allowed as an identifier in the event
127 @see @ref overview_toolbar
129 class wxToolBar
: public wxControl
138 Constructs a toolbar.
141 Pointer to a parent window.
143 Window identifier. If -1, will automatically create an identifier.
145 Window position. ::wxDefaultPosition indicates that wxWidgets should
146 generate a default position for the window.
147 If using the wxWindow class directly, supply an actual position.
149 Window size. ::wxDefaultSize indicates that wxWidgets should generate
150 a default size for the window.
152 Window style. See wxToolBar initial description for details.
156 @remarks After a toolbar is created, you use AddTool() and perhaps
157 AddSeparator(), and then you must call Realize() to construct
158 and display the toolbar tools.
160 wxToolBar(wxWindow
* parent
, wxWindowID id
,
161 const wxPoint
& pos
= wxDefaultPosition
,
162 const wxSize
& size
= wxDefaultSize
,
163 long style
= wxTB_HORIZONTAL
,
164 const wxString
& name
= wxToolBarNameStr
);
169 virtual ~wxToolBar();
172 Adds a new check (or toggle) tool to the toolbar. The parameters are the
173 same as in AddTool().
177 wxToolBarToolBase
* AddCheckTool(int toolId
, const wxString
& label
,
178 const wxBitmap
& bitmap1
,
179 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
180 const wxString
& shortHelp
= wxEmptyString
,
181 const wxString
& longHelp
= wxEmptyString
,
182 wxObject
* clientData
= NULL
);
185 Adds any control to the toolbar, typically e.g. a wxComboBox.
188 The control to be added.
190 Text to be displayed near the control.
193 wxMSW: the label is only displayed if there is enough space
194 available below the embedded control.
197 wxMac: labels are only displayed if wxWidgets is built with @c
198 wxMAC_USE_NATIVE_TOOLBAR set to 1
200 virtual wxToolBarToolBase
* AddControl(wxControl
* control
,
201 const wxString
& label
= wxEmptyString
);
204 Adds a new radio tool to the toolbar. Consecutive radio tools form a
205 radio group such that exactly one button in the group is pressed at any
206 moment, in other words whenever a button in the group is pressed the
207 previously pressed button is automatically released. You should avoid
208 having the radio groups of only one element as it would be impossible
209 for the user to use such button.
211 By default, the first button in the radio group is initially pressed,
217 wxToolBarToolBase
* AddRadioTool(int toolId
, const wxString
& label
,
218 const wxBitmap
& bitmap1
,
219 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
220 const wxString
& shortHelp
= wxEmptyString
,
221 const wxString
& longHelp
= wxEmptyString
,
222 wxObject
* clientData
= NULL
);
225 Adds a separator for spacing groups of tools.
227 Notice that the separator uses the look appropriate for the current
228 platform so it can be a vertical line (MSW, some versions of GTK) or
229 just an empty space or something else.
231 @see AddTool(), SetToolSeparation()
233 virtual wxToolBarToolBase
* AddSeparator();
237 Adds a tool to the toolbar.
240 The tool to be added.
242 @remarks After you have added tools to a toolbar, you must call
243 Realize() in order to have the tools appear.
245 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
246 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
248 virtual wxToolBarToolBase
* AddTool(wxToolBarToolBase
* tool
);
251 Adds a tool to the toolbar. This most commonly used version has fewer
252 parameters than the full version below which specifies the more rarely
253 used button features.
256 An integer by which the tool may be identified in subsequent
259 The string to be displayed with the tool.
261 The primary tool bitmap.
263 This string is used for the tools tooltip.
265 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
266 for a checkable tool (such tool stays pressed after it had been
267 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
268 a radio group of tools each of which is automatically unchecked
269 whenever another button in the group is checked. ::wxITEM_DROPDOWN
270 specifies that a drop-down menu button will appear next to the
271 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
273 @remarks After you have added tools to a toolbar, you must call
274 Realize() in order to have the tools appear.
276 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
277 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
279 wxToolBarToolBase
* AddTool(int toolId
, const wxString
& label
,
280 const wxBitmap
& bitmap
,
281 const wxString
& shortHelp
= wxEmptyString
,
282 wxItemKind kind
= wxITEM_NORMAL
);
285 Adds a tool to the toolbar.
288 An integer by which the tool may be identified in subsequent
291 The string to be displayed with the tool.
293 The primary tool bitmap.
295 The bitmap used when the tool is disabled. If it is equal to
296 ::wxNullBitmap (default), the disabled bitmap is automatically
297 generated by greying the normal one.
298 @param shortHelpString
299 This string is used for the tools tooltip.
300 @param longHelpString
301 This string is shown in the statusbar (if any) of the parent frame
302 when the mouse pointer is inside the tool.
304 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
305 for a checkable tool (such tool stays pressed after it had been
306 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
307 a radio group of tools each of which is automatically unchecked
308 whenever another button in the group is checked. ::wxITEM_DROPDOWN
309 specifies that a drop-down menu button will appear next to the
310 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
312 An optional pointer to client data which can be retrieved later
313 using GetToolClientData().
315 @remarks After you have added tools to a toolbar, you must call
316 Realize() in order to have the tools appear.
318 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
319 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
321 wxToolBarToolBase
* AddTool(int toolId
, const wxString
& label
,
322 const wxBitmap
& bitmap
,
323 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
324 wxItemKind kind
= wxITEM_NORMAL
,
325 const wxString
& shortHelpString
= wxEmptyString
,
326 const wxString
& longHelpString
= wxEmptyString
,
327 wxObject
* clientData
= NULL
);
331 Deletes all the tools in the toolbar.
333 virtual void ClearTools();
336 Removes the specified tool from the toolbar and deletes it. If you don't
337 want to delete the tool, but just to remove it from the toolbar (to
338 possibly add it back later), you may use RemoveTool() instead.
340 @note It is unnecessary to call Realize() for the change to take
341 place, it will happen immediately.
343 @returns @true if the tool was deleted, @false otherwise.
345 @see DeleteToolByPos()
347 virtual bool DeleteTool(int toolId
);
350 This function behaves like DeleteTool() but it deletes the tool at the
351 specified position and not the one with the given id.
353 virtual bool DeleteToolByPos(size_t pos
);
356 Enables or disables the tool.
359 Tool to enable or disable.
361 If @true, enables the tool, otherwise disables it.
363 @remarks Some implementations will change the visible state of the tool
364 to indicate that it is disabled.
367 @see GetToolEnabled(), ToggleTool()
369 virtual void EnableTool(int toolId
, bool enable
);
372 Returns a pointer to the tool identified by @a id or @NULL if no
373 corresponding tool is found.
375 wxToolBarToolBase
* FindById(int id
) const;
378 Returns a pointer to the control identified by @a id or @NULL if no
379 corresponding control is found.
381 virtual wxControl
* FindControl(int id
);
384 Finds a tool for the given mouse position.
391 @return A pointer to a tool if a tool is found, or @NULL otherwise.
393 @remarks Currently not implemented in wxGTK (always returns @NULL
396 virtual wxToolBarToolBase
* FindToolForPosition(wxCoord x
, wxCoord y
) const;
399 Returns the left/right and top/bottom margins, which are also used for
404 wxSize
GetMargins() const;
407 Returns the size of bitmap that the toolbar expects to have.
409 The default bitmap size is platform-dependent: for example, it is 16*15
410 for MSW and 24*24 for GTK. This size does @em not necessarily indicate
411 the best size to use for the toolbars on the given platform, for this
412 you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
413 in any case, as the bitmap size is deduced automatically from the size
414 of the bitmaps associated with the tools added to the toolbar, it is
415 usually unnecessary to call SetToolBitmapSize() explicitly.
417 @remarks Note that this is the size of the bitmap you pass to AddTool(),
418 and not the eventual size of the tool button.
420 @see SetToolBitmapSize(), GetToolSize()
422 virtual wxSize
GetToolBitmapSize() const;
425 Get any client data associated with the tool.
428 Id of the tool, as passed to AddTool().
430 @return Client data, or @NULL if there is none.
432 virtual wxObject
* GetToolClientData(int toolId
) const;
435 Called to determine whether a tool is enabled (responds to user input).
438 Id of the tool in question.
440 @return @true if the tool is enabled, @false otherwise.
444 virtual bool GetToolEnabled(int toolId
) const;
447 Returns the long help for the given tool.
450 The tool in question.
452 @see SetToolLongHelp(), SetToolShortHelp()
454 virtual wxString
GetToolLongHelp(int toolId
) const;
457 Returns the value used for packing tools.
459 @see SetToolPacking()
461 virtual int GetToolPacking() const;
464 Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
467 virtual int GetToolPos(int toolId
) const;
470 Returns the default separator size.
472 @see SetToolSeparation()
474 virtual int GetToolSeparation() const;
477 Returns the short help for the given tool.
480 The tool in question.
482 @see GetToolLongHelp(), SetToolShortHelp()
484 virtual wxString
GetToolShortHelp(int toolId
) const;
487 Returns the size of a whole button, which is usually larger than a tool
488 bitmap because of added 3D effects.
490 @see SetToolBitmapSize(), GetToolBitmapSize()
492 virtual wxSize
GetToolSize() const;
495 Gets the on/off state of a toggle tool.
498 The tool in question.
500 @return @true if the tool is toggled on, @false otherwise.
504 virtual bool GetToolState(int toolId
) const;
507 Returns the number of tools in the toolbar.
509 size_t GetToolsCount() const;
512 Inserts the control into the toolbar at the given position. You must
513 call Realize() for the change to take place.
515 @see AddControl(), InsertTool()
517 virtual wxToolBarToolBase
* InsertControl(size_t pos
, wxControl
* control
,
518 const wxString
& label
= wxEmptyString
);
521 Inserts the separator into the toolbar at the given position. You must
522 call Realize() for the change to take place.
524 @see AddSeparator(), InsertTool()
526 virtual wxToolBarToolBase
* InsertSeparator(size_t pos
);
530 Inserts the tool with the specified attributes into the toolbar at the
533 You must call Realize() for the change to take place.
535 @see AddTool(), InsertControl(), InsertSeparator()
537 @return The newly inserted tool or @NULL on failure. Notice that with
538 the overload taking @a tool parameter the caller is responsible for
539 deleting the tool in the latter case.
541 wxToolBarToolBase
* InsertTool(size_t pos
, int toolId
,
542 const wxBitmap
& bitmap1
,
543 const wxBitmap
& bitmap2
= wxNullBitmap
,
544 bool isToggle
= false,
545 wxObject
* clientData
= NULL
,
546 const wxString
& shortHelpString
= wxEmptyString
,
547 const wxString
& longHelpString
= wxEmptyString
);
548 wxToolBarToolBase
* InsertTool(size_t pos
,
549 wxToolBarToolBase
* tool
);
553 Called when the user clicks on a tool with the left mouse button. This
554 is the old way of detecting tool clicks; although it will still work,
555 you should use the EVT_MENU() or EVT_TOOL() macro instead.
558 The identifier passed to AddTool().
560 @true if the tool is a toggle and the toggle is down, otherwise is
563 @return If the tool is a toggle and this function returns @false, the
564 toggle state (internal and visual) will not be changed. This
565 provides a way of specifying that toggle operations are not
566 permitted in some circumstances.
568 @see OnMouseEnter(), OnRightClick()
570 virtual bool OnLeftClick(int toolId
, bool toggleDown
);
573 This is called when the mouse cursor moves into a tool or out of the
574 toolbar. This is the old way of detecting mouse enter events;
575 although it will still work, you should use the EVT_TOOL_ENTER()
579 Greater than -1 if the mouse cursor has moved into the tool, or -1
580 if the mouse cursor has moved. The programmer can override this to
581 provide extra information about the tool, such as a short
582 description on the status line.
584 @remarks With some derived toolbar classes, if the mouse moves quickly
585 out of the toolbar, wxWidgets may not be able to detect it.
586 Therefore this function may not always be called when expected.
588 virtual void OnMouseEnter(int toolId
);
591 @deprecated This is the old way of detecting tool right clicks;
592 although it will still work, you should use the
593 EVT_TOOL_RCLICKED() macro instead.
595 Called when the user clicks on a tool with the right mouse button. The
596 programmer should override this function to detect right tool clicks.
599 The identifier passed to AddTool().
601 The x position of the mouse cursor.
603 The y position of the mouse cursor.
605 @remarks A typical use of this member might be to pop up a menu.
607 @see OnMouseEnter(), OnLeftClick()
609 virtual void OnRightClick(int toolId
, long x
, long y
);
612 This function should be called after you have added tools.
614 virtual bool Realize();
617 Removes the given tool from the toolbar but doesn't delete it. This
618 allows to insert/add this tool back to this (or another) toolbar later.
620 @note It is unnecessary to call Realize() for the change to take place,
621 it will happen immediately.
626 virtual wxToolBarToolBase
* RemoveTool(int id
);
629 Sets the bitmap resource identifier for specifying tool bitmaps as
630 indices into a custom bitmap. Windows CE only.
632 void SetBitmapResource(int resourceId
);
635 Sets the dropdown menu for the tool given by its @e id. The tool itself
636 will delete the menu when it's no longer needed. Only supported under
639 If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
640 call wxEvent::Skip() from it or the menu won't be displayed.
642 bool SetDropdownMenu(int id
, wxMenu
* menu
);
646 Set the values to be used as margins for the toolbar.
649 Left margin, right margin and inter-tool separation value.
651 Top margin, bottom margin and inter-tool separation value.
653 @remarks This must be called before the tools are added if absolute
654 positioning is to be used, and the default (zero-size) margins are
659 virtual void SetMargins(int x
, int y
);
662 Set the margins for the toolbar.
667 @remarks This must be called before the tools are added if absolute
668 positioning is to be used, and the default (zero-size) margins are
671 @see GetMargins(), wxSize
673 void SetMargins(const wxSize
& size
);
677 Sets the default size of each tool bitmap. The default bitmap size is 16
681 The size of the bitmaps in the toolbar.
683 @remarks This should be called to tell the toolbar what the tool bitmap
684 size is. Call it before you add tools.
686 @see GetToolBitmapSize(), GetToolSize()
688 virtual void SetToolBitmapSize(const wxSize
& size
);
691 Sets the client data associated with the tool.
693 virtual void SetToolClientData(int id
, wxObject
* clientData
);
696 Sets the bitmap to be used by the tool with the given ID when the tool
697 is in a disabled state. This can only be used on Button tools, not
700 @note The native toolbar classes on the main platforms all synthesize
701 the disabled bitmap from the normal bitmap, so this function will
702 have no effect on those platforms.
705 virtual void SetToolDisabledBitmap(int id
, const wxBitmap
& bitmap
);
708 Sets the long help for the given tool.
711 The tool in question.
713 A string for the long help.
715 @remarks You might use the long help for displaying the tool purpose on
718 @see GetToolLongHelp(), SetToolShortHelp(),
720 virtual void SetToolLongHelp(int toolId
, const wxString
& helpString
);
723 Sets the bitmap to be used by the tool with the given ID. This can only
724 be used on Button tools, not controls.
726 virtual void SetToolNormalBitmap(int id
, const wxBitmap
& bitmap
);
729 Sets the value used for spacing tools. The default value is 1.
732 The value for packing.
734 @remarks The packing is used for spacing in the vertical direction if
735 the toolbar is horizontal, and for spacing in the horizontal
736 direction if the toolbar is vertical.
738 @see GetToolPacking()
740 virtual void SetToolPacking(int packing
);
743 Sets the default separator size. The default value is 5.
750 virtual void SetToolSeparation(int separation
);
753 Sets the short help for the given tool.
756 The tool in question.
758 The string for the short help.
760 @remarks An application might use short help for identifying the tool
761 purpose in a tooltip.
764 @see GetToolShortHelp(), SetToolLongHelp()
766 virtual void SetToolShortHelp(int toolId
, const wxString
& helpString
);
769 Toggles a tool on or off. This does not cause any event to get emitted.
774 If @true, toggles the tool on, otherwise toggles it off.
776 @remarks Only applies to a tool that has been specified as a toggle
779 virtual void ToggleTool(int toolId
, bool toggle
);