]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/toolbar.h
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(), AddStretchableSpace()
233 virtual wxToolBarToolBase
* AddSeparator();
236 Adds a stretchable space to the toolbar.
238 Any space not taken up by the fixed items (all items except for
239 stretchable spaces) is distributed in equal measure between the
240 stretchable spaces in the toolbar. The most common use for this method
241 is to add a single stretchable space before the items which should be
242 right-aligned in the toolbar, but more exotic possibilities are
243 possible, e.g. a stretchable space may be added in the beginning and
244 the end of the toolbar to centre all toolbar items.
246 @see AddTool(), AddSeparator(), InsertStretchableSpace()
250 wxToolBarToolBase
*AddStretchableSpace();
254 Adds a tool to the toolbar.
257 The tool to be added.
259 @remarks After you have added tools to a toolbar, you must call
260 Realize() in order to have the tools appear.
262 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
263 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
265 virtual wxToolBarToolBase
* AddTool(wxToolBarToolBase
* tool
);
268 Adds a tool to the toolbar. This most commonly used version has fewer
269 parameters than the full version below which specifies the more rarely
270 used button features.
273 An integer by which the tool may be identified in subsequent
276 The string to be displayed with the tool.
278 The primary tool bitmap.
280 This string is used for the tools tooltip.
282 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
283 for a checkable tool (such tool stays pressed after it had been
284 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
285 a radio group of tools each of which is automatically unchecked
286 whenever another button in the group is checked. ::wxITEM_DROPDOWN
287 specifies that a drop-down menu button will appear next to the
288 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
290 @remarks After you have added tools to a toolbar, you must call
291 Realize() in order to have the tools appear.
293 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
294 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
296 wxToolBarToolBase
* AddTool(int toolId
, const wxString
& label
,
297 const wxBitmap
& bitmap
,
298 const wxString
& shortHelp
= wxEmptyString
,
299 wxItemKind kind
= wxITEM_NORMAL
);
302 Adds a tool to the toolbar.
305 An integer by which the tool may be identified in subsequent
308 The string to be displayed with the tool.
310 The primary tool bitmap.
312 The bitmap used when the tool is disabled. If it is equal to
313 ::wxNullBitmap (default), the disabled bitmap is automatically
314 generated by greying the normal one.
315 @param shortHelpString
316 This string is used for the tools tooltip.
317 @param longHelpString
318 This string is shown in the statusbar (if any) of the parent frame
319 when the mouse pointer is inside the tool.
321 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
322 for a checkable tool (such tool stays pressed after it had been
323 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
324 a radio group of tools each of which is automatically unchecked
325 whenever another button in the group is checked. ::wxITEM_DROPDOWN
326 specifies that a drop-down menu button will appear next to the
327 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
329 An optional pointer to client data which can be retrieved later
330 using GetToolClientData().
332 @remarks After you have added tools to a toolbar, you must call
333 Realize() in order to have the tools appear.
335 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
336 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
338 wxToolBarToolBase
* AddTool(int toolId
, const wxString
& label
,
339 const wxBitmap
& bitmap
,
340 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
341 wxItemKind kind
= wxITEM_NORMAL
,
342 const wxString
& shortHelpString
= wxEmptyString
,
343 const wxString
& longHelpString
= wxEmptyString
,
344 wxObject
* clientData
= NULL
);
348 Deletes all the tools in the toolbar.
350 virtual void ClearTools();
353 Removes the specified tool from the toolbar and deletes it. If you don't
354 want to delete the tool, but just to remove it from the toolbar (to
355 possibly add it back later), you may use RemoveTool() instead.
357 @note It is unnecessary to call Realize() for the change to take
358 place, it will happen immediately.
360 @returns @true if the tool was deleted, @false otherwise.
362 @see DeleteToolByPos()
364 virtual bool DeleteTool(int toolId
);
367 This function behaves like DeleteTool() but it deletes the tool at the
368 specified position and not the one with the given id.
370 virtual bool DeleteToolByPos(size_t pos
);
373 Enables or disables the tool.
376 Tool to enable or disable.
378 If @true, enables the tool, otherwise disables it.
380 @remarks Some implementations will change the visible state of the tool
381 to indicate that it is disabled.
384 @see GetToolEnabled(), ToggleTool()
386 virtual void EnableTool(int toolId
, bool enable
);
389 Returns a pointer to the tool identified by @a id or @NULL if no
390 corresponding tool is found.
392 wxToolBarToolBase
* FindById(int id
) const;
395 Returns a pointer to the control identified by @a id or @NULL if no
396 corresponding control is found.
398 virtual wxControl
* FindControl(int id
);
401 Finds a tool for the given mouse position.
408 @return A pointer to a tool if a tool is found, or @NULL otherwise.
410 @remarks Currently not implemented in wxGTK (always returns @NULL
413 virtual wxToolBarToolBase
* FindToolForPosition(wxCoord x
, wxCoord y
) const;
416 Returns the left/right and top/bottom margins, which are also used for
421 wxSize
GetMargins() const;
424 Returns the size of bitmap that the toolbar expects to have.
426 The default bitmap size is platform-dependent: for example, it is 16*15
427 for MSW and 24*24 for GTK. This size does @em not necessarily indicate
428 the best size to use for the toolbars on the given platform, for this
429 you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
430 in any case, as the bitmap size is deduced automatically from the size
431 of the bitmaps associated with the tools added to the toolbar, it is
432 usually unnecessary to call SetToolBitmapSize() explicitly.
434 @remarks Note that this is the size of the bitmap you pass to AddTool(),
435 and not the eventual size of the tool button.
437 @see SetToolBitmapSize(), GetToolSize()
439 virtual wxSize
GetToolBitmapSize() const;
442 Returns a pointer to the tool at ordinal position @a pos.
444 Don't confuse this with FindToolForPosition().
450 const wxToolBarToolBase
*GetToolByPos(int pos
) const;
453 Get any client data associated with the tool.
456 Id of the tool, as passed to AddTool().
458 @return Client data, or @NULL if there is none.
460 virtual wxObject
* GetToolClientData(int toolId
) const;
463 Called to determine whether a tool is enabled (responds to user input).
466 Id of the tool in question.
468 @return @true if the tool is enabled, @false otherwise.
472 virtual bool GetToolEnabled(int toolId
) const;
475 Returns the long help for the given tool.
478 The tool in question.
480 @see SetToolLongHelp(), SetToolShortHelp()
482 virtual wxString
GetToolLongHelp(int toolId
) const;
485 Returns the value used for packing tools.
487 @see SetToolPacking()
489 virtual int GetToolPacking() const;
492 Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
495 virtual int GetToolPos(int toolId
) const;
498 Returns the default separator size.
500 @see SetToolSeparation()
502 virtual int GetToolSeparation() const;
505 Returns the short help for the given tool.
508 The tool in question.
510 @see GetToolLongHelp(), SetToolShortHelp()
512 virtual wxString
GetToolShortHelp(int toolId
) const;
515 Returns the size of a whole button, which is usually larger than a tool
516 bitmap because of added 3D effects.
518 @see SetToolBitmapSize(), GetToolBitmapSize()
520 virtual wxSize
GetToolSize() const;
523 Gets the on/off state of a toggle tool.
526 The tool in question.
528 @return @true if the tool is toggled on, @false otherwise.
532 virtual bool GetToolState(int toolId
) const;
535 Returns the number of tools in the toolbar.
537 size_t GetToolsCount() const;
540 Inserts the control into the toolbar at the given position. You must
541 call Realize() for the change to take place.
543 @see AddControl(), InsertTool()
545 virtual wxToolBarToolBase
* InsertControl(size_t pos
, wxControl
* control
,
546 const wxString
& label
= wxEmptyString
);
549 Inserts the separator into the toolbar at the given position. You must
550 call Realize() for the change to take place.
552 @see AddSeparator(), InsertTool()
554 virtual wxToolBarToolBase
* InsertSeparator(size_t pos
);
557 Inserts a stretchable space at the given position.
559 See AddStretchableSpace() for details about stretchable spaces.
561 @see InsertTool(), InsertSeparator()
565 wxToolBarToolBase
*InsertStretchableSpace(size_t pos
);
569 Inserts the tool with the specified attributes into the toolbar at the
572 You must call Realize() for the change to take place.
574 @see AddTool(), InsertControl(), InsertSeparator()
576 @return The newly inserted tool or @NULL on failure. Notice that with
577 the overload taking @a tool parameter the caller is responsible for
578 deleting the tool in the latter case.
580 wxToolBarToolBase
* InsertTool(size_t pos
, int toolId
,
581 const wxBitmap
& bitmap1
,
582 const wxBitmap
& bitmap2
= wxNullBitmap
,
583 bool isToggle
= false,
584 wxObject
* clientData
= NULL
,
585 const wxString
& shortHelpString
= wxEmptyString
,
586 const wxString
& longHelpString
= wxEmptyString
);
587 wxToolBarToolBase
* InsertTool(size_t pos
,
588 wxToolBarToolBase
* tool
);
592 Called when the user clicks on a tool with the left mouse button. This
593 is the old way of detecting tool clicks; although it will still work,
594 you should use the EVT_MENU() or EVT_TOOL() macro instead.
597 The identifier passed to AddTool().
599 @true if the tool is a toggle and the toggle is down, otherwise is
602 @return If the tool is a toggle and this function returns @false, the
603 toggle state (internal and visual) will not be changed. This
604 provides a way of specifying that toggle operations are not
605 permitted in some circumstances.
607 @see OnMouseEnter(), OnRightClick()
609 virtual bool OnLeftClick(int toolId
, bool toggleDown
);
612 This is called when the mouse cursor moves into a tool or out of the
613 toolbar. This is the old way of detecting mouse enter events;
614 although it will still work, you should use the EVT_TOOL_ENTER()
618 Greater than -1 if the mouse cursor has moved into the tool, or -1
619 if the mouse cursor has moved. The programmer can override this to
620 provide extra information about the tool, such as a short
621 description on the status line.
623 @remarks With some derived toolbar classes, if the mouse moves quickly
624 out of the toolbar, wxWidgets may not be able to detect it.
625 Therefore this function may not always be called when expected.
627 virtual void OnMouseEnter(int toolId
);
630 @deprecated This is the old way of detecting tool right clicks;
631 although it will still work, you should use the
632 EVT_TOOL_RCLICKED() macro instead.
634 Called when the user clicks on a tool with the right mouse button. The
635 programmer should override this function to detect right tool clicks.
638 The identifier passed to AddTool().
640 The x position of the mouse cursor.
642 The y position of the mouse cursor.
644 @remarks A typical use of this member might be to pop up a menu.
646 @see OnMouseEnter(), OnLeftClick()
648 virtual void OnRightClick(int toolId
, long x
, long y
);
651 This function should be called after you have added tools.
653 virtual bool Realize();
656 Removes the given tool from the toolbar but doesn't delete it. This
657 allows to insert/add this tool back to this (or another) toolbar later.
659 @note It is unnecessary to call Realize() for the change to take place,
660 it will happen immediately.
665 virtual wxToolBarToolBase
* RemoveTool(int id
);
668 Sets the bitmap resource identifier for specifying tool bitmaps as
669 indices into a custom bitmap. Windows CE only.
671 void SetBitmapResource(int resourceId
);
674 Sets the dropdown menu for the tool given by its @e id. The tool itself
675 will delete the menu when it's no longer needed. Only supported under
678 If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
679 call wxEvent::Skip() from it or the menu won't be displayed.
681 bool SetDropdownMenu(int id
, wxMenu
* menu
);
685 Set the values to be used as margins for the toolbar.
688 Left margin, right margin and inter-tool separation value.
690 Top margin, bottom margin and inter-tool separation value.
692 @remarks This must be called before the tools are added if absolute
693 positioning is to be used, and the default (zero-size) margins are
698 virtual void SetMargins(int x
, int y
);
701 Set the margins for the toolbar.
706 @remarks This must be called before the tools are added if absolute
707 positioning is to be used, and the default (zero-size) margins are
710 @see GetMargins(), wxSize
712 void SetMargins(const wxSize
& size
);
716 Sets the default size of each tool bitmap. The default bitmap size is 16
720 The size of the bitmaps in the toolbar.
722 @remarks This should be called to tell the toolbar what the tool bitmap
723 size is. Call it before you add tools.
725 @see GetToolBitmapSize(), GetToolSize()
727 virtual void SetToolBitmapSize(const wxSize
& size
);
730 Sets the client data associated with the tool.
732 virtual void SetToolClientData(int id
, wxObject
* clientData
);
735 Sets the bitmap to be used by the tool with the given ID when the tool
736 is in a disabled state. This can only be used on Button tools, not
739 @note The native toolbar classes on the main platforms all synthesize
740 the disabled bitmap from the normal bitmap, so this function will
741 have no effect on those platforms.
744 virtual void SetToolDisabledBitmap(int id
, const wxBitmap
& bitmap
);
747 Sets the long help for the given tool.
750 The tool in question.
752 A string for the long help.
754 @remarks You might use the long help for displaying the tool purpose on
757 @see GetToolLongHelp(), SetToolShortHelp(),
759 virtual void SetToolLongHelp(int toolId
, const wxString
& helpString
);
762 Sets the bitmap to be used by the tool with the given ID. This can only
763 be used on Button tools, not controls.
765 virtual void SetToolNormalBitmap(int id
, const wxBitmap
& bitmap
);
768 Sets the value used for spacing tools. The default value is 1.
771 The value for packing.
773 @remarks The packing is used for spacing in the vertical direction if
774 the toolbar is horizontal, and for spacing in the horizontal
775 direction if the toolbar is vertical.
777 @see GetToolPacking()
779 virtual void SetToolPacking(int packing
);
782 Sets the default separator size. The default value is 5.
789 virtual void SetToolSeparation(int separation
);
792 Sets the short help for the given tool.
795 The tool in question.
797 The string for the short help.
799 @remarks An application might use short help for identifying the tool
800 purpose in a tooltip.
803 @see GetToolShortHelp(), SetToolLongHelp()
805 virtual void SetToolShortHelp(int toolId
, const wxString
& helpString
);
808 Toggles a tool on or off. This does not cause any event to get emitted.
813 If @true, toggles the tool on, otherwise toggles it off.
815 @remarks Only applies to a tool that has been specified as a toggle
818 virtual void ToggleTool(int toolId
, bool toggle
);