]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/toolbar.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxToolBar
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
9 enum wxToolBarToolStyle
11 wxTOOL_STYLE_BUTTON
= 1,
12 wxTOOL_STYLE_SEPARATOR
= 2,
17 /** wxToolBar style flags */
20 /** lay out the toolbar horizontally */
21 wxTB_HORIZONTAL
= wxHORIZONTAL
,
22 wxTB_TOP
= wxTB_HORIZONTAL
,
24 /** lay out the toolbar vertically */
25 wxTB_VERTICAL
= wxVERTICAL
,
26 wxTB_LEFT
= wxTB_VERTICAL
,
28 /** show 3D buttons (wxToolBarSimple only) */
31 /** "flat" buttons (Win32/GTK only) */
34 /** dockable toolbar (GTK only) */
37 /** don't show the icons (they're shown by default) */
40 /** show the text (not shown by default) */
43 /** don't show the divider between toolbar and the window (Win32 only) */
46 /** no automatic alignment (Win32 only, useless) */
49 /** show the text and the icons alongside, not vertically stacked (Win32/GTK) */
51 wxTB_HORZ_TEXT
= wxTB_HORZ_LAYOUT
| wxTB_TEXT
,
53 /** don't show the toolbar short help tooltips */
56 /** lay out toolbar at the bottom of the window */
59 /** lay out toolbar at the right edge of the window */
62 /** flags that are closest to the native look*/
63 wxTB_DEFAULT_STYLE
= wxTB_HORIZONTAL
| wxTB_FLAT
69 @class wxToolBarToolBase
71 A toolbar tool represents one item on the toolbar.
73 It has a unique id (except for the separators), the style (telling whether
74 it is a normal button, separator or a control), the state (toggled or not,
75 enabled or not) and short and long help strings. The default
76 implementations use the short help string for the tooltip text which is
77 popped up when the mouse pointer enters the tool and the long help string
78 for the applications status bar.
80 class wxToolBarToolBase
: public wxObject
83 wxToolBarToolBase(wxToolBarBase
*tbar
= NULL
,
84 int toolid
= wxID_SEPARATOR
,
85 const wxString
& label
= wxEmptyString
,
86 const wxBitmap
& bmpNormal
= wxNullBitmap
,
87 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
88 wxItemKind kind
= wxITEM_NORMAL
,
89 wxObject
*clientData
= NULL
,
90 const wxString
& shortHelpString
= wxEmptyString
,
91 const wxString
& longHelpString
= wxEmptyString
);
93 wxToolBarToolBase(wxToolBarBase
*tbar
,
95 const wxString
& label
);
97 virtual ~wxToolBarToolBase();
101 wxControl
*GetControl() const;
102 wxToolBarBase
*GetToolBar() const;
104 bool IsStretchable() const;
105 bool IsButton() const;
106 bool IsControl() const;
107 bool IsSeparator() const;
108 bool IsStretchableSpace() const;
109 int GetStyle() const;
110 wxItemKind
GetKind() const;
111 void MakeStretchable();
113 bool IsEnabled() const;
114 bool IsToggled() const;
115 bool CanBeToggled() const;
117 const wxBitmap
& GetNormalBitmap() const;
118 const wxBitmap
& GetDisabledBitmap() const;
120 const wxBitmap
& GetBitmap() const;
121 const wxString
& GetLabel() const;
123 const wxString
& GetShortHelp() const;
124 const wxString
& GetLongHelp() const;
126 wxObject
*GetClientData() const;
128 virtual bool Enable(bool enable
);
129 virtual bool Toggle(bool toggle
);
130 virtual bool SetToggle(bool toggle
);
131 virtual bool SetShortHelp(const wxString
& help
);
132 virtual bool SetLongHelp(const wxString
& help
);
134 virtual void SetNormalBitmap(const wxBitmap
& bmp
);
135 virtual void SetDisabledBitmap(const wxBitmap
& bmp
);
136 virtual void SetLabel(const wxString
& label
);
137 void SetClientData(wxObject
*clientData
);
139 virtual void Detach();
140 virtual void Attach(wxToolBarBase
*tbar
);
142 virtual void SetDropdownMenu(wxMenu
*menu
);
143 wxMenu
*GetDropdownMenu() const;
152 A toolbar is a bar of buttons and/or other controls usually placed below
153 the menu bar in a wxFrame.
155 You may create a toolbar that is managed by a frame calling
156 wxFrame::CreateToolBar(). Under Pocket PC, you should always use this
157 function for creating the toolbar to be managed by the frame, so that
158 wxWidgets can use a combined menubar and toolbar. Where you manage your
159 own toolbars, create wxToolBar as usual.
161 There are several different types of tools you can add to a toolbar.
162 These types are controlled by the ::wxItemKind enumeration.
164 Note that many methods in wxToolBar such as wxToolBar::AddTool return a
165 @c wxToolBarToolBase* object.
166 This should be regarded as an opaque handle representing the newly added
167 toolbar item, providing access to its id and position within the toolbar.
168 Changes to the item's state should be made through calls to wxToolBar methods,
169 for example wxToolBar::EnableTool.
170 Calls to @c wxToolBarToolBase methods (undocumented by purpose) will not change
171 the visible state of the item within the tool bar.
173 <b>wxMSW note</b>: Note that under wxMSW toolbar paints tools to reflect
174 system-wide colours. If you use more than 16 colours in your tool bitmaps,
175 you may wish to suppress this behaviour, otherwise system colours in your
176 bitmaps will inadvertently be mapped to system colours.
177 To do this, set the msw.remap system option before creating the toolbar:
179 wxSystemOptions::SetOption("msw.remap", 0);
181 If you wish to use 32-bit images (which include an alpha channel for
184 wxSystemOptions::SetOption("msw.remap", 2);
186 Then colour remapping is switched off, and a transparent background
187 used. But only use this option under Windows XP with true colour:
189 if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
194 Gives the toolbar a flat look (Windows and GTK only).
195 @style{wxTB_DOCKABLE}
196 Makes the toolbar floatable and dockable (GTK only).
197 @style{wxTB_HORIZONTAL}
198 Specifies horizontal layout (default).
199 @style{wxTB_VERTICAL}
200 Specifies vertical layout.
202 Shows the text in the toolbar buttons; by default only icons are shown.
204 Specifies no icons in the toolbar buttons; by default they are shown.
205 @style{wxTB_NODIVIDER}
206 Specifies no divider (border) above the toolbar (Windows only)
208 Specifies no alignment with the parent window (Windows only, not very
210 @style{wxTB_HORZ_LAYOUT}
211 Shows the text and the icons alongside, not vertically stacked (Windows
212 and GTK 2 only). This style must be used with @c wxTB_TEXT.
213 @style{wxTB_HORZ_TEXT}
214 Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT.
215 @style{wxTB_NO_TOOLTIPS}
216 Don't show the short help tooltips for the tools when the mouse hovers
219 Align the toolbar at the bottom of parent window.
221 Align the toolbar at the right side of parent window.
222 @style{wxTB_DEFAULT_STYLE}
223 Combination of @c wxTB_HORIZONTAL and @c wxTB_FLAT. This style is new
224 since wxWidgets 2.9.5.
227 See also @ref overview_windowstyles. Note that the wxMSW native toolbar
228 ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only
229 if the style was initially on.
231 @beginEventEmissionTable{wxCommandEvent}
232 @event{EVT_TOOL(id, func)}
233 Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c
234 wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool.
235 @event{EVT_MENU(id, func)}
236 The same as EVT_TOOL().
237 @event{EVT_TOOL_RANGE(id1, id2, func)}
238 Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of
239 identifiers. Pass the ids of the tools.
240 @event{EVT_MENU_RANGE(id1, id2, func)}
241 The same as EVT_TOOL_RANGE().
242 @event{EVT_TOOL_RCLICKED(id, func)}
243 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the
244 tool. (Not available on wxOSX.)
245 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
246 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass
247 the ids of the tools. (Not available on wxOSX.)
248 @event{EVT_TOOL_ENTER(id, func)}
249 Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar
250 itself. The value of wxCommandEvent::GetSelection() is the tool id, or
251 -1 if the mouse cursor has moved off a tool. (Not available on wxOSX.)
252 @event{EVT_TOOL_DROPDOWN(id, func)}
253 Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled,
254 displays the default dropdown menu set using
255 wxToolBar::SetDropdownMenu().
258 The toolbar class emits menu commands in the same way that a frame menubar
259 does, so you can use one EVT_MENU() macro for both a menu item and a toolbar
260 button. The event handler functions take a wxCommandEvent argument. For most
261 event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER()
262 the toolbar window identifier is passed and the tool identifier is retrieved
263 from the wxCommandEvent. This is because the identifier may be @c wxID_ANY when the
264 mouse moves off a tool, and @c wxID_ANY is not allowed as an identifier in the event
270 @see @ref overview_toolbar
272 class wxToolBar
: public wxControl
281 Constructs a toolbar.
284 Pointer to a parent window.
286 Window identifier. If -1, will automatically create an identifier.
288 Window position. ::wxDefaultPosition indicates that wxWidgets should
289 generate a default position for the window.
290 If using the wxWindow class directly, supply an actual position.
292 Window size. ::wxDefaultSize indicates that wxWidgets should generate
293 a default size for the window.
295 Window style. See wxToolBar initial description for details.
299 @remarks After a toolbar is created, you use AddTool() and perhaps
300 AddSeparator(), and then you must call Realize() to construct
301 and display the toolbar tools.
303 wxToolBar(wxWindow
* parent
, wxWindowID id
,
304 const wxPoint
& pos
= wxDefaultPosition
,
305 const wxSize
& size
= wxDefaultSize
,
306 long style
= wxTB_HORIZONTAL
,
307 const wxString
& name
= wxToolBarNameStr
);
312 virtual ~wxToolBar();
315 Adds a new check (or toggle) tool to the toolbar. The parameters are the
316 same as in AddTool().
320 wxToolBarToolBase
* AddCheckTool(int toolId
, const wxString
& label
,
321 const wxBitmap
& bitmap1
,
322 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
323 const wxString
& shortHelp
= wxEmptyString
,
324 const wxString
& longHelp
= wxEmptyString
,
325 wxObject
* clientData
= NULL
);
328 Adds any control to the toolbar, typically e.g.\ a wxComboBox.
331 The control to be added.
333 Text to be displayed near the control.
336 wxMSW: the label is only displayed if there is enough space
337 available below the embedded control.
340 wxMac: labels are only displayed if wxWidgets is built with @c
341 wxMAC_USE_NATIVE_TOOLBAR set to 1
343 virtual wxToolBarToolBase
* AddControl(wxControl
* control
,
344 const wxString
& label
= wxEmptyString
);
347 Adds a new radio tool to the toolbar. Consecutive radio tools form a
348 radio group such that exactly one button in the group is pressed at any
349 moment, in other words whenever a button in the group is pressed the
350 previously pressed button is automatically released. You should avoid
351 having the radio groups of only one element as it would be impossible
352 for the user to use such button.
354 By default, the first button in the radio group is initially pressed,
360 wxToolBarToolBase
* AddRadioTool(int toolId
, const wxString
& label
,
361 const wxBitmap
& bitmap1
,
362 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
363 const wxString
& shortHelp
= wxEmptyString
,
364 const wxString
& longHelp
= wxEmptyString
,
365 wxObject
* clientData
= NULL
);
368 Adds a separator for spacing groups of tools.
370 Notice that the separator uses the look appropriate for the current
371 platform so it can be a vertical line (MSW, some versions of GTK) or
372 just an empty space or something else.
374 @see AddTool(), SetToolSeparation(), AddStretchableSpace()
376 virtual wxToolBarToolBase
* AddSeparator();
379 Adds a stretchable space to the toolbar.
381 Any space not taken up by the fixed items (all items except for
382 stretchable spaces) is distributed in equal measure between the
383 stretchable spaces in the toolbar. The most common use for this method
384 is to add a single stretchable space before the items which should be
385 right-aligned in the toolbar, but more exotic possibilities are
386 possible, e.g. a stretchable space may be added in the beginning and
387 the end of the toolbar to centre all toolbar items.
389 @see AddTool(), AddSeparator(), InsertStretchableSpace()
393 wxToolBarToolBase
*AddStretchableSpace();
397 Adds a tool to the toolbar.
400 The tool to be added.
402 @remarks After you have added tools to a toolbar, you must call
403 Realize() in order to have the tools appear.
405 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
406 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
408 virtual wxToolBarToolBase
* AddTool(wxToolBarToolBase
* tool
);
411 Adds a tool to the toolbar. This most commonly used version has fewer
412 parameters than the full version below which specifies the more rarely
413 used button features.
416 An integer by which the tool may be identified in subsequent
419 The string to be displayed with the tool.
421 The primary tool bitmap.
423 This string is used for the tools tooltip.
425 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
426 for a checkable tool (such tool stays pressed after it had been
427 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
428 a radio group of tools each of which is automatically unchecked
429 whenever another button in the group is checked. ::wxITEM_DROPDOWN
430 specifies that a drop-down menu button will appear next to the
431 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
433 @remarks After you have added tools to a toolbar, you must call
434 Realize() in order to have the tools appear.
436 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
437 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
439 wxToolBarToolBase
* AddTool(int toolId
, const wxString
& label
,
440 const wxBitmap
& bitmap
,
441 const wxString
& shortHelp
= wxEmptyString
,
442 wxItemKind kind
= wxITEM_NORMAL
);
445 Adds a tool to the toolbar.
448 An integer by which the tool may be identified in subsequent
451 The string to be displayed with the tool.
453 The primary tool bitmap.
455 The bitmap used when the tool is disabled. If it is equal to
456 ::wxNullBitmap (default), the disabled bitmap is automatically
457 generated by greying the normal one.
459 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
460 for a checkable tool (such tool stays pressed after it had been
461 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
462 a radio group of tools each of which is automatically unchecked
463 whenever another button in the group is checked. ::wxITEM_DROPDOWN
464 specifies that a drop-down menu button will appear next to the
465 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
466 @param shortHelpString
467 This string is used for the tools tooltip.
468 @param longHelpString
469 This string is shown in the statusbar (if any) of the parent frame
470 when the mouse pointer is inside the tool.
472 An optional pointer to client data which can be retrieved later
473 using GetToolClientData().
475 @remarks After you have added tools to a toolbar, you must call
476 Realize() in order to have the tools appear.
478 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
479 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
481 wxToolBarToolBase
* AddTool(int toolId
, const wxString
& label
,
482 const wxBitmap
& bitmap
,
483 const wxBitmap
& bmpDisabled
,
484 wxItemKind kind
= wxITEM_NORMAL
,
485 const wxString
& shortHelpString
= wxEmptyString
,
486 const wxString
& longHelpString
= wxEmptyString
,
487 wxObject
* clientData
= NULL
);
491 Deletes all the tools in the toolbar.
493 virtual void ClearTools();
496 Removes the specified tool from the toolbar and deletes it. If you don't
497 want to delete the tool, but just to remove it from the toolbar (to
498 possibly add it back later), you may use RemoveTool() instead.
500 @note It is unnecessary to call Realize() for the change to take
501 place, it will happen immediately.
503 @returns @true if the tool was deleted, @false otherwise.
505 @see DeleteToolByPos()
507 virtual bool DeleteTool(int toolId
);
510 This function behaves like DeleteTool() but it deletes the tool at the
511 specified position and not the one with the given id.
513 virtual bool DeleteToolByPos(size_t pos
);
516 Enables or disables the tool.
519 ID of the tool to enable or disable, as passed to AddTool().
521 If @true, enables the tool, otherwise disables it.
523 @remarks Some implementations will change the visible state of the tool
524 to indicate that it is disabled.
527 @see GetToolEnabled(), ToggleTool()
529 virtual void EnableTool(int toolId
, bool enable
);
532 Returns a pointer to the tool identified by @a id or @NULL if no
533 corresponding tool is found.
535 wxToolBarToolBase
* FindById(int id
) const;
538 Returns a pointer to the control identified by @a id or @NULL if no
539 corresponding control is found.
541 virtual wxControl
* FindControl(int id
);
544 Finds a tool for the given mouse position.
551 @return A pointer to a tool if a tool is found, or @NULL otherwise.
553 @remarks Currently not implemented in wxGTK (always returns @NULL
556 virtual wxToolBarToolBase
* FindToolForPosition(wxCoord x
, wxCoord y
) const;
559 Returns the left/right and top/bottom margins, which are also used for
564 wxSize
GetMargins() const;
567 Returns the size of bitmap that the toolbar expects to have.
569 The default bitmap size is platform-dependent: for example, it is 16*15
570 for MSW and 24*24 for GTK. This size does @em not necessarily indicate
571 the best size to use for the toolbars on the given platform, for this
572 you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
573 in any case, as the bitmap size is deduced automatically from the size
574 of the bitmaps associated with the tools added to the toolbar, it is
575 usually unnecessary to call SetToolBitmapSize() explicitly.
577 @remarks Note that this is the size of the bitmap you pass to AddTool(),
578 and not the eventual size of the tool button.
580 @see SetToolBitmapSize(), GetToolSize()
582 virtual wxSize
GetToolBitmapSize() const;
585 Returns a pointer to the tool at ordinal position @a pos.
587 Don't confuse this with FindToolForPosition().
593 const wxToolBarToolBase
*GetToolByPos(int pos
) const;
596 Get any client data associated with the tool.
599 ID of the tool in question, as passed to AddTool().
601 @return Client data, or @NULL if there is none.
603 virtual wxObject
* GetToolClientData(int toolId
) const;
606 Called to determine whether a tool is enabled (responds to user input).
609 ID of the tool in question, as passed to AddTool().
611 @return @true if the tool is enabled, @false otherwise.
615 virtual bool GetToolEnabled(int toolId
) const;
618 Returns the long help for the given tool.
621 ID of the tool in question, as passed to AddTool().
623 @see SetToolLongHelp(), SetToolShortHelp()
625 virtual wxString
GetToolLongHelp(int toolId
) const;
628 Returns the value used for packing tools.
630 @see SetToolPacking()
632 virtual int GetToolPacking() const;
635 Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
639 ID of the tool in question, as passed to AddTool().
641 virtual int GetToolPos(int toolId
) const;
644 Returns the default separator size.
646 @see SetToolSeparation()
648 virtual int GetToolSeparation() const;
651 Returns the short help for the given tool.
654 ID of the tool in question, as passed to AddTool().
656 @see GetToolLongHelp(), SetToolShortHelp()
658 virtual wxString
GetToolShortHelp(int toolId
) const;
661 Returns the size of a whole button, which is usually larger than a tool
662 bitmap because of added 3D effects.
664 @see SetToolBitmapSize(), GetToolBitmapSize()
666 virtual wxSize
GetToolSize() const;
669 Gets the on/off state of a toggle tool.
672 ID of the tool in question, as passed to AddTool().
674 @return @true if the tool is toggled on, @false otherwise.
678 virtual bool GetToolState(int toolId
) const;
681 Returns the number of tools in the toolbar.
683 size_t GetToolsCount() const;
686 Inserts the control into the toolbar at the given position. You must
687 call Realize() for the change to take place.
689 @see AddControl(), InsertTool()
691 virtual wxToolBarToolBase
* InsertControl(size_t pos
, wxControl
* control
,
692 const wxString
& label
= wxEmptyString
);
695 Inserts the separator into the toolbar at the given position. You must
696 call Realize() for the change to take place.
698 @see AddSeparator(), InsertTool()
700 virtual wxToolBarToolBase
* InsertSeparator(size_t pos
);
703 Inserts a stretchable space at the given position.
705 See AddStretchableSpace() for details about stretchable spaces.
707 @see InsertTool(), InsertSeparator()
711 wxToolBarToolBase
*InsertStretchableSpace(size_t pos
);
715 Inserts the tool with the specified attributes into the toolbar at the
718 You must call Realize() for the change to take place.
720 @see AddTool(), InsertControl(), InsertSeparator()
722 @return The newly inserted tool or @NULL on failure. Notice that with
723 the overload taking @a tool parameter the caller is responsible for
724 deleting the tool in the latter case.
726 wxToolBarToolBase
* InsertTool( size_t pos
,
728 const wxString
& label
,
729 const wxBitmap
& bitmap
,
730 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
731 wxItemKind kind
= wxITEM_NORMAL
,
732 const wxString
& shortHelp
= wxEmptyString
,
733 const wxString
& longHelp
= wxEmptyString
,
734 wxObject
*clientData
= NULL
);
736 wxToolBarToolBase
* InsertTool(size_t pos
,
737 wxToolBarToolBase
* tool
);
741 Called when the user clicks on a tool with the left mouse button. This
742 is the old way of detecting tool clicks; although it will still work,
743 you should use the EVT_MENU() or EVT_TOOL() macro instead.
746 The identifier passed to AddTool().
748 @true if the tool is a toggle and the toggle is down, otherwise is
751 @return If the tool is a toggle and this function returns @false, the
752 toggle state (internal and visual) will not be changed. This
753 provides a way of specifying that toggle operations are not
754 permitted in some circumstances.
756 @see OnMouseEnter(), OnRightClick()
758 virtual bool OnLeftClick(int toolId
, bool toggleDown
);
761 This is called when the mouse cursor moves into a tool or out of the
762 toolbar. This is the old way of detecting mouse enter events;
763 although it will still work, you should use the EVT_TOOL_ENTER()
767 Greater than -1 if the mouse cursor has moved into the tool, or -1
768 if the mouse cursor has moved. The programmer can override this to
769 provide extra information about the tool, such as a short
770 description on the status line.
772 @remarks With some derived toolbar classes, if the mouse moves quickly
773 out of the toolbar, wxWidgets may not be able to detect it.
774 Therefore this function may not always be called when expected.
776 virtual void OnMouseEnter(int toolId
);
779 @deprecated This is the old way of detecting tool right clicks;
780 although it will still work, you should use the
781 EVT_TOOL_RCLICKED() macro instead.
783 Called when the user clicks on a tool with the right mouse button. The
784 programmer should override this function to detect right tool clicks.
787 The identifier passed to AddTool().
789 The x position of the mouse cursor.
791 The y position of the mouse cursor.
793 @remarks A typical use of this member might be to pop up a menu.
795 @see OnMouseEnter(), OnLeftClick()
797 virtual void OnRightClick(int toolId
, long x
, long y
);
800 This function should be called after you have added tools.
802 virtual bool Realize();
805 Removes the given tool from the toolbar but doesn't delete it. This
806 allows to insert/add this tool back to this (or another) toolbar later.
808 @note It is unnecessary to call Realize() for the change to take place,
809 it will happen immediately.
814 virtual wxToolBarToolBase
* RemoveTool(int id
);
817 Sets the bitmap resource identifier for specifying tool bitmaps as
818 indices into a custom bitmap.
820 This is a Windows CE-specific method not available in the other ports.
822 @onlyfor{wxmsw_wince}
824 void SetBitmapResource(int resourceId
);
827 Sets the dropdown menu for the tool given by its @e id. The tool itself
828 will delete the menu when it's no longer needed. Only supported under
831 If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
832 call wxEvent::Skip() from it or the menu won't be displayed.
834 bool SetDropdownMenu(int id
, wxMenu
* menu
);
838 Set the values to be used as margins for the toolbar.
841 Left margin, right margin and inter-tool separation value.
843 Top margin, bottom margin and inter-tool separation value.
845 @remarks This must be called before the tools are added if absolute
846 positioning is to be used, and the default (zero-size) margins are
851 virtual void SetMargins(int x
, int y
);
854 Set the margins for the toolbar.
859 @remarks This must be called before the tools are added if absolute
860 positioning is to be used, and the default (zero-size) margins are
863 @see GetMargins(), wxSize
865 void SetMargins(const wxSize
& size
);
869 Sets the default size of each tool bitmap. The default bitmap size is 16
873 The size of the bitmaps in the toolbar.
875 @remarks This should be called to tell the toolbar what the tool bitmap
876 size is. Call it before you add tools.
878 @see GetToolBitmapSize(), GetToolSize()
880 virtual void SetToolBitmapSize(const wxSize
& size
);
883 Sets the client data associated with the tool.
886 ID of the tool in question, as passed to AddTool().
888 virtual void SetToolClientData(int id
, wxObject
* clientData
);
891 Sets the bitmap to be used by the tool with the given ID when the tool
892 is in a disabled state. This can only be used on Button tools, not
896 ID of the tool in question, as passed to AddTool().
898 @note The native toolbar classes on the main platforms all synthesize
899 the disabled bitmap from the normal bitmap, so this function will
900 have no effect on those platforms.
903 virtual void SetToolDisabledBitmap(int id
, const wxBitmap
& bitmap
);
906 Sets the long help for the given tool.
909 ID of the tool in question, as passed to AddTool().
911 A string for the long help.
913 @remarks You might use the long help for displaying the tool purpose on
916 @see GetToolLongHelp(), SetToolShortHelp(),
918 virtual void SetToolLongHelp(int toolId
, const wxString
& helpString
);
921 Sets the bitmap to be used by the tool with the given ID. This can only
922 be used on Button tools, not controls.
925 ID of the tool in question, as passed to AddTool().
927 virtual void SetToolNormalBitmap(int id
, const wxBitmap
& bitmap
);
930 Sets the value used for spacing tools. The default value is 1.
933 The value for packing.
935 @remarks The packing is used for spacing in the vertical direction if
936 the toolbar is horizontal, and for spacing in the horizontal
937 direction if the toolbar is vertical.
939 @see GetToolPacking()
941 virtual void SetToolPacking(int packing
);
944 Sets the default separator size. The default value is 5.
951 virtual void SetToolSeparation(int separation
);
954 Sets the short help for the given tool.
957 ID of the tool in question, as passed to AddTool().
959 The string for the short help.
961 @remarks An application might use short help for identifying the tool
962 purpose in a tooltip.
965 @see GetToolShortHelp(), SetToolLongHelp()
967 virtual void SetToolShortHelp(int toolId
, const wxString
& helpString
);
970 Toggles a tool on or off. This does not cause any event to get emitted.
973 ID of the tool in question, as passed to AddTool().
975 If @true, toggles the tool on, otherwise toggles it off.
977 @remarks Only applies to a tool that has been specified as a toggle
980 virtual void ToggleTool(int toolId
, bool toggle
);
984 Factory function to create a new toolbar tool.
986 virtual wxToolBarToolBase
*CreateTool(int toolId
,
987 const wxString
& label
,
988 const wxBitmap
& bmpNormal
,
989 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
990 wxItemKind kind
= wxITEM_NORMAL
,
991 wxObject
*clientData
= NULL
,
992 const wxString
& shortHelp
= wxEmptyString
,
993 const wxString
& longHelp
= wxEmptyString
);
995 Factory function to create a new control toolbar tool.
997 virtual wxToolBarToolBase
*CreateTool(wxControl
*control
,
998 const wxString
& label
);
1001 Factory function to create a new separator toolbar tool.
1003 wxToolBarToolBase
*CreateSeparator()