]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/toolbar.h
Consistently handle DST start time in wxDateTime::Set().
[wxWidgets.git] / interface / wx / toolbar.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: toolbar.h
e54c96f1 3// Purpose: interface of wxToolBar
23324ae1 4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
23324ae1
FM
6/////////////////////////////////////////////////////////////////////////////
7
db51298a
RD
8enum wxToolBarToolStyle
9{
10 wxTOOL_STYLE_BUTTON = 1,
11 wxTOOL_STYLE_SEPARATOR = 2,
12 wxTOOL_STYLE_CONTROL
13};
14
15
16/** wxToolBar style flags */
17enum
18{
19 /** lay out the toolbar horizontally */
f75b1bd3
VZ
20 wxTB_HORIZONTAL = wxHORIZONTAL,
21 wxTB_TOP = wxTB_HORIZONTAL,
db51298a
RD
22
23 /** lay out the toolbar vertically */
f75b1bd3
VZ
24 wxTB_VERTICAL = wxVERTICAL,
25 wxTB_LEFT = wxTB_VERTICAL,
db51298a
RD
26
27 /** show 3D buttons (wxToolBarSimple only) */
28 wxTB_3DBUTTONS,
29
30 /** "flat" buttons (Win32/GTK only) */
31 wxTB_FLAT,
32
33 /** dockable toolbar (GTK only) */
34 wxTB_DOCKABLE,
35
36 /** don't show the icons (they're shown by default) */
37 wxTB_NOICONS,
38
39 /** show the text (not shown by default) */
40 wxTB_TEXT,
41
42 /** don't show the divider between toolbar and the window (Win32 only) */
43 wxTB_NODIVIDER,
44
45 /** no automatic alignment (Win32 only, useless) */
46 wxTB_NOALIGN,
47
48 /** show the text and the icons alongside, not vertically stacked (Win32/GTK) */
49 wxTB_HORZ_LAYOUT,
f75b1bd3 50 wxTB_HORZ_TEXT = wxTB_HORZ_LAYOUT | wxTB_TEXT,
db51298a
RD
51
52 /** don't show the toolbar short help tooltips */
53 wxTB_NO_TOOLTIPS,
54
55 /** lay out toolbar at the bottom of the window */
56 wxTB_BOTTOM,
57
58 /** lay out toolbar at the right edge of the window */
f75b1bd3
VZ
59 wxTB_RIGHT,
60
61 /** flags that are closest to the native look*/
62 wxTB_DEFAULT_STYLE = wxTB_HORIZONTAL | wxTB_FLAT
db51298a
RD
63};
64
65
66
67/**
68 @class wxToolBarToolBase
69
70 A toolbar tool represents one item on the toolbar.
71
72 It has a unique id (except for the separators), the style (telling whether
73 it is a normal button, separator or a control), the state (toggled or not,
74 enabled or not) and short and long help strings. The default
75 implementations use the short help string for the tooltip text which is
76 popped up when the mouse pointer enters the tool and the long help string
77 for the applications status bar.
78*/
79class wxToolBarToolBase : public wxObject
80{
81public:
82 wxToolBarToolBase(wxToolBarBase *tbar = NULL,
83 int toolid = wxID_SEPARATOR,
84 const wxString& label = wxEmptyString,
85 const wxBitmap& bmpNormal = wxNullBitmap,
86 const wxBitmap& bmpDisabled = wxNullBitmap,
87 wxItemKind kind = wxITEM_NORMAL,
88 wxObject *clientData = NULL,
89 const wxString& shortHelpString = wxEmptyString,
90 const wxString& longHelpString = wxEmptyString);
91
92 wxToolBarToolBase(wxToolBarBase *tbar,
93 wxControl *control,
94 const wxString& label);
95
96 virtual ~wxToolBarToolBase();
97
98 int GetId() const;
99
100 wxControl *GetControl() const;
101 wxToolBarBase *GetToolBar() const;
102
db51298a
RD
103 bool IsStretchable() const;
104 bool IsButton() const;
105 bool IsControl() const;
106 bool IsSeparator() const;
107 bool IsStretchableSpace() const;
108 int GetStyle() const;
109 wxItemKind GetKind() const;
110 void MakeStretchable();
111
db51298a
RD
112 bool IsEnabled() const;
113 bool IsToggled() const;
114 bool CanBeToggled() const;
115
db51298a
RD
116 const wxBitmap& GetNormalBitmap() const;
117 const wxBitmap& GetDisabledBitmap() const;
118
119 const wxBitmap& GetBitmap() const;
120 const wxString& GetLabel() const;
121
122 const wxString& GetShortHelp() const;
123 const wxString& GetLongHelp() const;
124
125 wxObject *GetClientData() const;
126
db51298a
RD
127 virtual bool Enable(bool enable);
128 virtual bool Toggle(bool toggle);
129 virtual bool SetToggle(bool toggle);
130 virtual bool SetShortHelp(const wxString& help);
131 virtual bool SetLongHelp(const wxString& help);
132 void Toggle();
133 virtual void SetNormalBitmap(const wxBitmap& bmp);
134 virtual void SetDisabledBitmap(const wxBitmap& bmp);
135 virtual void SetLabel(const wxString& label);
136 void SetClientData(wxObject *clientData);
137
db51298a
RD
138 virtual void Detach();
139 virtual void Attach(wxToolBarBase *tbar);
140
db51298a 141 virtual void SetDropdownMenu(wxMenu *menu);
b23ea178 142 wxMenu *GetDropdownMenu() const;
db51298a
RD
143};
144
145
146
147
23324ae1
FM
148/**
149 @class wxToolBar
7c913512 150
bb69632a
FM
151 A toolbar is a bar of buttons and/or other controls usually placed below
152 the menu bar in a wxFrame.
7977b62a 153
b1557978 154 You may create a toolbar that is managed by a frame calling
7977b62a
BP
155 wxFrame::CreateToolBar(). Under Pocket PC, you should always use this
156 function for creating the toolbar to be managed by the frame, so that
157 wxWidgets can use a combined menubar and toolbar. Where you manage your
b1557978 158 own toolbars, create wxToolBar as usual.
7977b62a 159
b1557978
FM
160 There are several different types of tools you can add to a toolbar.
161 These types are controlled by the ::wxItemKind enumeration.
162
163 Note that many methods in wxToolBar such as wxToolBar::AddTool return a
164 @c wxToolBarToolBase* object.
165 This should be regarded as an opaque handle representing the newly added
166 toolbar item, providing access to its id and position within the toolbar.
167 Changes to the item's state should be made through calls to wxToolBar methods,
168 for example wxToolBar::EnableTool.
169 Calls to @c wxToolBarToolBase methods (undocumented by purpose) will not change
4c51a665 170 the visible state of the item within the tool bar.
7977b62a 171
bb69632a
FM
172 <b>wxMSW note</b>: Note that under wxMSW toolbar paints tools to reflect
173 system-wide colours. If you use more than 16 colours in your tool bitmaps,
174 you may wish to suppress this behaviour, otherwise system colours in your
175 bitmaps will inadvertently be mapped to system colours.
7977b62a 176 To do this, set the msw.remap system option before creating the toolbar:
7977b62a 177 @code
f8ebb70d 178 wxSystemOptions::SetOption("msw.remap", 0);
7977b62a 179 @endcode
7977b62a
BP
180 If you wish to use 32-bit images (which include an alpha channel for
181 transparency) use:
7977b62a 182 @code
f8ebb70d 183 wxSystemOptions::SetOption("msw.remap", 2);
7977b62a 184 @endcode
7977b62a
BP
185 Then colour remapping is switched off, and a transparent background
186 used. But only use this option under Windows XP with true colour:
7977b62a
BP
187 @code
188 if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
189 @endcode
408776d0 190
23324ae1 191 @beginStyleTable
8c6791e4 192 @style{wxTB_FLAT}
7977b62a 193 Gives the toolbar a flat look (Windows and GTK only).
8c6791e4 194 @style{wxTB_DOCKABLE}
7977b62a 195 Makes the toolbar floatable and dockable (GTK only).
8c6791e4 196 @style{wxTB_HORIZONTAL}
7977b62a 197 Specifies horizontal layout (default).
8c6791e4 198 @style{wxTB_VERTICAL}
7977b62a 199 Specifies vertical layout.
8c6791e4 200 @style{wxTB_TEXT}
7977b62a 201 Shows the text in the toolbar buttons; by default only icons are shown.
8c6791e4 202 @style{wxTB_NOICONS}
7977b62a 203 Specifies no icons in the toolbar buttons; by default they are shown.
8c6791e4 204 @style{wxTB_NODIVIDER}
7977b62a 205 Specifies no divider (border) above the toolbar (Windows only)
8c6791e4 206 @style{wxTB_NOALIGN}
7977b62a
BP
207 Specifies no alignment with the parent window (Windows only, not very
208 useful).
8c6791e4 209 @style{wxTB_HORZ_LAYOUT}
7977b62a
BP
210 Shows the text and the icons alongside, not vertically stacked (Windows
211 and GTK 2 only). This style must be used with @c wxTB_TEXT.
8c6791e4 212 @style{wxTB_HORZ_TEXT}
7977b62a 213 Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT.
8c6791e4 214 @style{wxTB_NO_TOOLTIPS}
7977b62a
BP
215 Don't show the short help tooltips for the tools when the mouse hovers
216 over them.
8c6791e4 217 @style{wxTB_BOTTOM}
7977b62a 218 Align the toolbar at the bottom of parent window.
8c6791e4 219 @style{wxTB_RIGHT}
7977b62a 220 Align the toolbar at the right side of parent window.
f75b1bd3
VZ
221 @style{wxTB_DEFAULT_STYLE}
222 Combination of @c wxTB_HORIZONTAL and @c wxTB_FLAT. This style is new
223 since wxWidgets 2.9.5.
23324ae1 224 @endStyleTable
7c913512 225
b1557978 226 See also @ref overview_windowstyles. Note that the wxMSW native toolbar
7977b62a
BP
227 ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only
228 if the style was initially on.
229
3051a44a 230 @beginEventEmissionTable{wxCommandEvent}
7977b62a 231 @event{EVT_TOOL(id, func)}
ce7fe42e
VZ
232 Process a @c wxEVT_TOOL event (a synonym for @c
233 wxEVT_MENU). Pass the id of the tool.
7977b62a
BP
234 @event{EVT_MENU(id, func)}
235 The same as EVT_TOOL().
236 @event{EVT_TOOL_RANGE(id1, id2, func)}
ce7fe42e 237 Process a @c wxEVT_TOOL event for a range of
7977b62a
BP
238 identifiers. Pass the ids of the tools.
239 @event{EVT_MENU_RANGE(id1, id2, func)}
240 The same as EVT_TOOL_RANGE().
241 @event{EVT_TOOL_RCLICKED(id, func)}
ce7fe42e 242 Process a @c wxEVT_TOOL_RCLICKED event. Pass the id of the
e431dd05 243 tool. (Not available on wxOSX.)
7977b62a 244 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
ce7fe42e 245 Process a @c wxEVT_TOOL_RCLICKED event for a range of ids. Pass
e431dd05 246 the ids of the tools. (Not available on wxOSX.)
7977b62a 247 @event{EVT_TOOL_ENTER(id, func)}
ce7fe42e 248 Process a @c wxEVT_TOOL_ENTER event. Pass the id of the toolbar
7977b62a 249 itself. The value of wxCommandEvent::GetSelection() is the tool id, or
e431dd05 250 -1 if the mouse cursor has moved off a tool. (Not available on wxOSX.)
7977b62a 251 @event{EVT_TOOL_DROPDOWN(id, func)}
ce7fe42e 252 Process a @c wxEVT_TOOL_DROPDOWN event. If unhandled,
7977b62a
BP
253 displays the default dropdown menu set using
254 wxToolBar::SetDropdownMenu().
255 @endEventTable
408776d0 256
7977b62a
BP
257 The toolbar class emits menu commands in the same way that a frame menubar
258 does, so you can use one EVT_MENU() macro for both a menu item and a toolbar
259 button. The event handler functions take a wxCommandEvent argument. For most
260 event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER()
261 the toolbar window identifier is passed and the tool identifier is retrieved
b1557978
FM
262 from the wxCommandEvent. This is because the identifier may be @c wxID_ANY when the
263 mouse moves off a tool, and @c wxID_ANY is not allowed as an identifier in the event
7977b62a
BP
264 system.
265
266 @library{wxcore}
23324ae1 267 @category{miscwnd}
7c913512 268
f09b5681 269 @see @ref overview_toolbar
23324ae1
FM
270*/
271class wxToolBar : public wxControl
272{
273public:
7977b62a
BP
274 /**
275 Default constructor.
276 */
277 wxToolBar();
278
23324ae1
FM
279 /**
280 Constructs a toolbar.
3c4f71cc 281
7c913512 282 @param parent
4cc4bfaf 283 Pointer to a parent window.
7c913512 284 @param id
4cc4bfaf 285 Window identifier. If -1, will automatically create an identifier.
7c913512 286 @param pos
b1557978
FM
287 Window position. ::wxDefaultPosition indicates that wxWidgets should
288 generate a default position for the window.
289 If using the wxWindow class directly, supply an actual position.
7c913512 290 @param size
b1557978
FM
291 Window size. ::wxDefaultSize indicates that wxWidgets should generate
292 a default size for the window.
7c913512 293 @param style
b1557978 294 Window style. See wxToolBar initial description for details.
7c913512 295 @param name
4cc4bfaf 296 Window name.
3c4f71cc 297
7977b62a 298 @remarks After a toolbar is created, you use AddTool() and perhaps
b1557978
FM
299 AddSeparator(), and then you must call Realize() to construct
300 and display the toolbar tools.
23324ae1 301 */
7c913512
FM
302 wxToolBar(wxWindow* parent, wxWindowID id,
303 const wxPoint& pos = wxDefaultPosition,
304 const wxSize& size = wxDefaultSize,
ccf39540 305 long style = wxTB_HORIZONTAL,
408776d0 306 const wxString& name = wxToolBarNameStr);
23324ae1
FM
307
308 /**
309 Toolbar destructor.
310 */
adaaa686 311 virtual ~wxToolBar();
23324ae1
FM
312
313 /**
7977b62a
BP
314 Adds a new check (or toggle) tool to the toolbar. The parameters are the
315 same as in AddTool().
3c4f71cc 316
4cc4bfaf 317 @see AddTool()
23324ae1 318 */
43c48e1e 319 wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label,
23324ae1 320 const wxBitmap& bitmap1,
43c48e1e
FM
321 const wxBitmap& bmpDisabled = wxNullBitmap,
322 const wxString& shortHelp = wxEmptyString,
323 const wxString& longHelp = wxEmptyString,
4cc4bfaf 324 wxObject* clientData = NULL);
23324ae1
FM
325
326 /**
0824e369 327 Adds any control to the toolbar, typically e.g.\ a wxComboBox.
3c4f71cc 328
7c913512 329 @param control
4cc4bfaf 330 The control to be added.
7c913512 331 @param label
4cc4bfaf 332 Text to be displayed near the control.
3c4f71cc 333
7977b62a
BP
334 @remarks
335 wxMSW: the label is only displayed if there is enough space
336 available below the embedded control.
337
338 @remarks
339 wxMac: labels are only displayed if wxWidgets is built with @c
340 wxMAC_USE_NATIVE_TOOLBAR set to 1
23324ae1 341 */
43c48e1e
FM
342 virtual wxToolBarToolBase* AddControl(wxControl* control,
343 const wxString& label = wxEmptyString);
23324ae1
FM
344
345 /**
7977b62a
BP
346 Adds a new radio tool to the toolbar. Consecutive radio tools form a
347 radio group such that exactly one button in the group is pressed at any
348 moment, in other words whenever a button in the group is pressed the
349 previously pressed button is automatically released. You should avoid
350 having the radio groups of only one element as it would be impossible
351 for the user to use such button.
408776d0 352
7977b62a
BP
353 By default, the first button in the radio group is initially pressed,
354 the others are not.
355
3c4f71cc 356
4cc4bfaf 357 @see AddTool()
23324ae1 358 */
43c48e1e 359 wxToolBarToolBase* AddRadioTool(int toolId, const wxString& label,
23324ae1 360 const wxBitmap& bitmap1,
43c48e1e
FM
361 const wxBitmap& bmpDisabled = wxNullBitmap,
362 const wxString& shortHelp = wxEmptyString,
363 const wxString& longHelp = wxEmptyString,
4cc4bfaf 364 wxObject* clientData = NULL);
23324ae1
FM
365
366 /**
367 Adds a separator for spacing groups of tools.
3c4f71cc 368
8a9a313d
VZ
369 Notice that the separator uses the look appropriate for the current
370 platform so it can be a vertical line (MSW, some versions of GTK) or
371 just an empty space or something else.
b1557978 372
cc260109 373 @see AddTool(), SetToolSeparation(), AddStretchableSpace()
23324ae1 374 */
43c48e1e 375 virtual wxToolBarToolBase* AddSeparator();
23324ae1 376
cc260109
VZ
377 /**
378 Adds a stretchable space to the toolbar.
379
380 Any space not taken up by the fixed items (all items except for
381 stretchable spaces) is distributed in equal measure between the
382 stretchable spaces in the toolbar. The most common use for this method
383 is to add a single stretchable space before the items which should be
384 right-aligned in the toolbar, but more exotic possibilities are
385 possible, e.g. a stretchable space may be added in the beginning and
386 the end of the toolbar to centre all toolbar items.
387
388 @see AddTool(), AddSeparator(), InsertStretchableSpace()
389
390 @since 2.9.1
391 */
392 wxToolBarToolBase *AddStretchableSpace();
393
8d13e301 394 //@{
23324ae1 395 /**
922da38b
BP
396 Adds a tool to the toolbar.
397
398 @param tool
399 The tool to be added.
400
401 @remarks After you have added tools to a toolbar, you must call
163bd4f7 402 Realize() in order to have the tools appear.
922da38b
BP
403
404 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
405 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
406 */
adaaa686 407 virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
922da38b
BP
408
409 /**
408776d0 410 Adds a tool to the toolbar. This most commonly used version has fewer
922da38b
BP
411 parameters than the full version below which specifies the more rarely
412 used button features.
3c4f71cc 413
7c913512 414 @param toolId
7977b62a
BP
415 An integer by which the tool may be identified in subsequent
416 operations.
408776d0 417 @param label
922da38b
BP
418 The string to be displayed with the tool.
419 @param bitmap
420 The primary tool bitmap.
421 @param shortHelp
422 This string is used for the tools tooltip.
7c913512 423 @param kind
7977b62a
BP
424 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
425 for a checkable tool (such tool stays pressed after it had been
426 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
408776d0 427 a radio group of tools each of which is automatically unchecked
970e987e
RR
428 whenever another button in the group is checked. ::wxITEM_DROPDOWN
429 specifies that a drop-down menu button will appear next to the
430 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
922da38b
BP
431
432 @remarks After you have added tools to a toolbar, you must call
433 Realize() in order to have the tools appear.
434
435 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
436 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
437 */
438 wxToolBarToolBase* AddTool(int toolId, const wxString& label,
439 const wxBitmap& bitmap,
440 const wxString& shortHelp = wxEmptyString,
441 wxItemKind kind = wxITEM_NORMAL);
442
443 /**
444 Adds a tool to the toolbar.
445
446 @param toolId
447 An integer by which the tool may be identified in subsequent
448 operations.
408776d0 449 @param label
922da38b
BP
450 The string to be displayed with the tool.
451 @param bitmap
4cc4bfaf 452 The primary tool bitmap.
922da38b 453 @param bmpDisabled
4cc4bfaf 454 The bitmap used when the tool is disabled. If it is equal to
408776d0 455 ::wxNullBitmap (default), the disabled bitmap is automatically
922da38b 456 generated by greying the normal one.
922da38b
BP
457 @param kind
458 May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
459 for a checkable tool (such tool stays pressed after it had been
460 toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
408776d0 461 a radio group of tools each of which is automatically unchecked
922da38b
BP
462 whenever another button in the group is checked. ::wxITEM_DROPDOWN
463 specifies that a drop-down menu button will appear next to the
464 tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
001f1f56
FM
465 @param shortHelpString
466 This string is used for the tools tooltip.
467 @param longHelpString
468 This string is shown in the statusbar (if any) of the parent frame
469 when the mouse pointer is inside the tool.
7c913512 470 @param clientData
7977b62a
BP
471 An optional pointer to client data which can be retrieved later
472 using GetToolClientData().
3c4f71cc 473
23324ae1 474 @remarks After you have added tools to a toolbar, you must call
7977b62a 475 Realize() in order to have the tools appear.
3c4f71cc 476
4cc4bfaf 477 @see AddSeparator(), AddCheckTool(), AddRadioTool(),
970e987e 478 InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
23324ae1
FM
479 */
480 wxToolBarToolBase* AddTool(int toolId, const wxString& label,
922da38b 481 const wxBitmap& bitmap,
db51298a 482 const wxBitmap& bmpDisabled,
7c913512 483 wxItemKind kind = wxITEM_NORMAL,
922da38b
BP
484 const wxString& shortHelpString = wxEmptyString,
485 const wxString& longHelpString = wxEmptyString,
4cc4bfaf 486 wxObject* clientData = NULL);
8d13e301 487 //@}
23324ae1
FM
488
489 /**
490 Deletes all the tools in the toolbar.
491 */
adaaa686 492 virtual void ClearTools();
23324ae1
FM
493
494 /**
7977b62a
BP
495 Removes the specified tool from the toolbar and deletes it. If you don't
496 want to delete the tool, but just to remove it from the toolbar (to
497 possibly add it back later), you may use RemoveTool() instead.
498
499 @note It is unnecessary to call Realize() for the change to take
500 place, it will happen immediately.
501
502 @returns @true if the tool was deleted, @false otherwise.
3c4f71cc 503
4cc4bfaf 504 @see DeleteToolByPos()
23324ae1 505 */
adaaa686 506 virtual bool DeleteTool(int toolId);
23324ae1
FM
507
508 /**
7977b62a
BP
509 This function behaves like DeleteTool() but it deletes the tool at the
510 specified position and not the one with the given id.
23324ae1 511 */
adaaa686 512 virtual bool DeleteToolByPos(size_t pos);
23324ae1
FM
513
514 /**
515 Enables or disables the tool.
3c4f71cc 516
7c913512 517 @param toolId
51c30bca 518 ID of the tool to enable or disable, as passed to AddTool().
7c913512 519 @param enable
4cc4bfaf 520 If @true, enables the tool, otherwise disables it.
3c4f71cc 521
23324ae1 522 @remarks Some implementations will change the visible state of the tool
7977b62a
BP
523 to indicate that it is disabled.
524
3c4f71cc 525
4cc4bfaf 526 @see GetToolEnabled(), ToggleTool()
23324ae1 527 */
adaaa686 528 virtual void EnableTool(int toolId, bool enable);
23324ae1
FM
529
530 /**
7977b62a
BP
531 Returns a pointer to the tool identified by @a id or @NULL if no
532 corresponding tool is found.
23324ae1 533 */
adaaa686 534 wxToolBarToolBase* FindById(int id) const;
23324ae1
FM
535
536 /**
7977b62a
BP
537 Returns a pointer to the control identified by @a id or @NULL if no
538 corresponding control is found.
23324ae1 539 */
adaaa686 540 virtual wxControl* FindControl(int id);
23324ae1
FM
541
542 /**
543 Finds a tool for the given mouse position.
3c4f71cc 544
7c913512 545 @param x
4cc4bfaf 546 X position.
7c913512 547 @param y
4cc4bfaf 548 Y position.
3c4f71cc 549
d29a9a8a 550 @return A pointer to a tool if a tool is found, or @NULL otherwise.
3c4f71cc 551
7977b62a
BP
552 @remarks Currently not implemented in wxGTK (always returns @NULL
553 there).
23324ae1 554 */
adaaa686 555 virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;
23324ae1
FM
556
557 /**
558 Returns the left/right and top/bottom margins, which are also used for
559 inter-toolspacing.
3c4f71cc 560
4cc4bfaf 561 @see SetMargins()
23324ae1 562 */
328f5751 563 wxSize GetMargins() const;
23324ae1
FM
564
565 /**
040d3c2e
VZ
566 Returns the size of bitmap that the toolbar expects to have.
567
568 The default bitmap size is platform-dependent: for example, it is 16*15
569 for MSW and 24*24 for GTK. This size does @em not necessarily indicate
570 the best size to use for the toolbars on the given platform, for this
571 you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
572 in any case, as the bitmap size is deduced automatically from the size
573 of the bitmaps associated with the tools added to the toolbar, it is
574 usually unnecessary to call SetToolBitmapSize() explicitly.
3c4f71cc 575
7977b62a
BP
576 @remarks Note that this is the size of the bitmap you pass to AddTool(),
577 and not the eventual size of the tool button.
3c4f71cc 578
4cc4bfaf 579 @see SetToolBitmapSize(), GetToolSize()
23324ae1 580 */
adaaa686 581 virtual wxSize GetToolBitmapSize() const;
23324ae1 582
e79f02bd
VZ
583 /**
584 Returns a pointer to the tool at ordinal position @a pos.
585
586 Don't confuse this with FindToolForPosition().
587
588 @since 2.9.1
589
590 @see GetToolsCount()
591 */
592 const wxToolBarToolBase *GetToolByPos(int pos) const;
593
23324ae1
FM
594 /**
595 Get any client data associated with the tool.
3c4f71cc 596
7c913512 597 @param toolId
51c30bca 598 ID of the tool in question, as passed to AddTool().
3c4f71cc 599
d29a9a8a 600 @return Client data, or @NULL if there is none.
23324ae1 601 */
adaaa686 602 virtual wxObject* GetToolClientData(int toolId) const;
23324ae1
FM
603
604 /**
605 Called to determine whether a tool is enabled (responds to user input).
3c4f71cc 606
7c913512 607 @param toolId
51c30bca 608 ID of the tool in question, as passed to AddTool().
3c4f71cc 609
d29a9a8a 610 @return @true if the tool is enabled, @false otherwise.
3c4f71cc 611
4cc4bfaf 612 @see EnableTool()
23324ae1 613 */
adaaa686 614 virtual bool GetToolEnabled(int toolId) const;
23324ae1
FM
615
616 /**
617 Returns the long help for the given tool.
3c4f71cc 618
7c913512 619 @param toolId
51c30bca 620 ID of the tool in question, as passed to AddTool().
3c4f71cc 621
4cc4bfaf 622 @see SetToolLongHelp(), SetToolShortHelp()
23324ae1 623 */
adaaa686 624 virtual wxString GetToolLongHelp(int toolId) const;
23324ae1
FM
625
626 /**
627 Returns the value used for packing tools.
3c4f71cc 628
4cc4bfaf 629 @see SetToolPacking()
23324ae1 630 */
adaaa686 631 virtual int GetToolPacking() const;
23324ae1
FM
632
633 /**
7977b62a
BP
634 Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
635 is not found.
51c30bca
VZ
636
637 @param toolId
638 ID of the tool in question, as passed to AddTool().
23324ae1 639 */
adaaa686 640 virtual int GetToolPos(int toolId) const;
23324ae1
FM
641
642 /**
643 Returns the default separator size.
3c4f71cc 644
4cc4bfaf 645 @see SetToolSeparation()
23324ae1 646 */
adaaa686 647 virtual int GetToolSeparation() const;
23324ae1
FM
648
649 /**
650 Returns the short help for the given tool.
3c4f71cc 651
7c913512 652 @param toolId
51c30bca 653 ID of the tool in question, as passed to AddTool().
3c4f71cc 654
4cc4bfaf 655 @see GetToolLongHelp(), SetToolShortHelp()
23324ae1 656 */
adaaa686 657 virtual wxString GetToolShortHelp(int toolId) const;
23324ae1
FM
658
659 /**
7977b62a
BP
660 Returns the size of a whole button, which is usually larger than a tool
661 bitmap because of added 3D effects.
3c4f71cc 662
4cc4bfaf 663 @see SetToolBitmapSize(), GetToolBitmapSize()
23324ae1 664 */
adaaa686 665 virtual wxSize GetToolSize() const;
23324ae1
FM
666
667 /**
668 Gets the on/off state of a toggle tool.
3c4f71cc 669
7c913512 670 @param toolId
51c30bca 671 ID of the tool in question, as passed to AddTool().
3c4f71cc 672
d29a9a8a 673 @return @true if the tool is toggled on, @false otherwise.
3c4f71cc 674
4cc4bfaf 675 @see ToggleTool()
23324ae1 676 */
adaaa686 677 virtual bool GetToolState(int toolId) const;
23324ae1
FM
678
679 /**
680 Returns the number of tools in the toolbar.
681 */
43c48e1e 682 size_t GetToolsCount() const;
23324ae1
FM
683
684 /**
7977b62a
BP
685 Inserts the control into the toolbar at the given position. You must
686 call Realize() for the change to take place.
3c4f71cc 687
4cc4bfaf 688 @see AddControl(), InsertTool()
23324ae1 689 */
43c48e1e
FM
690 virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control,
691 const wxString& label = wxEmptyString);
23324ae1
FM
692
693 /**
7977b62a
BP
694 Inserts the separator into the toolbar at the given position. You must
695 call Realize() for the change to take place.
3c4f71cc 696
4cc4bfaf 697 @see AddSeparator(), InsertTool()
23324ae1 698 */
adaaa686 699 virtual wxToolBarToolBase* InsertSeparator(size_t pos);
23324ae1 700
cc260109
VZ
701 /**
702 Inserts a stretchable space at the given position.
703
704 See AddStretchableSpace() for details about stretchable spaces.
705
706 @see InsertTool(), InsertSeparator()
707
708 @since 2.9.1
709 */
710 wxToolBarToolBase *InsertStretchableSpace(size_t pos);
711
23324ae1
FM
712 //@{
713 /**
7977b62a
BP
714 Inserts the tool with the specified attributes into the toolbar at the
715 given position.
716
23324ae1 717 You must call Realize() for the change to take place.
3c4f71cc 718
4cc4bfaf 719 @see AddTool(), InsertControl(), InsertSeparator()
26007761
VZ
720
721 @return The newly inserted tool or @NULL on failure. Notice that with
722 the overload taking @a tool parameter the caller is responsible for
723 deleting the tool in the latter case.
4cc4bfaf 724 */
b23ea178
RD
725 wxToolBarToolBase* InsertTool( size_t pos,
726 int toolId,
727 const wxString& label,
728 const wxBitmap& bitmap,
729 const wxBitmap& bmpDisabled = wxNullBitmap,
730 wxItemKind kind = wxITEM_NORMAL,
731 const wxString& shortHelp = wxEmptyString,
732 const wxString& longHelp = wxEmptyString,
733 wxObject *clientData = NULL);
734
4cc4bfaf
FM
735 wxToolBarToolBase* InsertTool(size_t pos,
736 wxToolBarToolBase* tool);
23324ae1
FM
737 //@}
738
739 /**
7977b62a
BP
740 Called when the user clicks on a tool with the left mouse button. This
741 is the old way of detecting tool clicks; although it will still work,
742 you should use the EVT_MENU() or EVT_TOOL() macro instead.
3c4f71cc 743
7c913512 744 @param toolId
4cc4bfaf 745 The identifier passed to AddTool().
7c913512 746 @param toggleDown
7977b62a
BP
747 @true if the tool is a toggle and the toggle is down, otherwise is
748 @false.
3c4f71cc 749
d29a9a8a 750 @return If the tool is a toggle and this function returns @false, the
7977b62a
BP
751 toggle state (internal and visual) will not be changed. This
752 provides a way of specifying that toggle operations are not
753 permitted in some circumstances.
3c4f71cc 754
4cc4bfaf 755 @see OnMouseEnter(), OnRightClick()
23324ae1 756 */
adaaa686 757 virtual bool OnLeftClick(int toolId, bool toggleDown);
23324ae1
FM
758
759 /**
7977b62a
BP
760 This is called when the mouse cursor moves into a tool or out of the
761 toolbar. This is the old way of detecting mouse enter events;
762 although it will still work, you should use the EVT_TOOL_ENTER()
763 macro instead.
3c4f71cc 764
7c913512 765 @param toolId
7977b62a
BP
766 Greater than -1 if the mouse cursor has moved into the tool, or -1
767 if the mouse cursor has moved. The programmer can override this to
768 provide extra information about the tool, such as a short
769 description on the status line.
3c4f71cc 770
23324ae1 771 @remarks With some derived toolbar classes, if the mouse moves quickly
7977b62a
BP
772 out of the toolbar, wxWidgets may not be able to detect it.
773 Therefore this function may not always be called when expected.
23324ae1 774 */
adaaa686 775 virtual void OnMouseEnter(int toolId);
23324ae1
FM
776
777 /**
7977b62a
BP
778 @deprecated This is the old way of detecting tool right clicks;
779 although it will still work, you should use the
780 EVT_TOOL_RCLICKED() macro instead.
781
23324ae1
FM
782 Called when the user clicks on a tool with the right mouse button. The
783 programmer should override this function to detect right tool clicks.
3c4f71cc 784
7c913512 785 @param toolId
4cc4bfaf 786 The identifier passed to AddTool().
7c913512 787 @param x
4cc4bfaf 788 The x position of the mouse cursor.
7c913512 789 @param y
4cc4bfaf 790 The y position of the mouse cursor.
3c4f71cc 791
23324ae1 792 @remarks A typical use of this member might be to pop up a menu.
3c4f71cc 793
4cc4bfaf 794 @see OnMouseEnter(), OnLeftClick()
23324ae1 795 */
43c48e1e 796 virtual void OnRightClick(int toolId, long x, long y);
23324ae1
FM
797
798 /**
799 This function should be called after you have added tools.
800 */
adaaa686 801 virtual bool Realize();
23324ae1
FM
802
803 /**
7977b62a
BP
804 Removes the given tool from the toolbar but doesn't delete it. This
805 allows to insert/add this tool back to this (or another) toolbar later.
806
807 @note It is unnecessary to call Realize() for the change to take place,
808 it will happen immediately.
809
3c4f71cc 810
4cc4bfaf 811 @see DeleteTool()
23324ae1 812 */
adaaa686 813 virtual wxToolBarToolBase* RemoveTool(int id);
23324ae1
FM
814
815 /**
7977b62a 816 Sets the bitmap resource identifier for specifying tool bitmaps as
184abb52
VZ
817 indices into a custom bitmap.
818
819 This is a Windows CE-specific method not available in the other ports.
820
83189c3b 821 @onlyfor{wxmsw_wince}
23324ae1
FM
822 */
823 void SetBitmapResource(int resourceId);
824
825 /**
7977b62a 826 Sets the dropdown menu for the tool given by its @e id. The tool itself
970e987e
RR
827 will delete the menu when it's no longer needed. Only supported under
828 GTK+ und MSW.
7977b62a
BP
829
830 If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
831 call wxEvent::Skip() from it or the menu won't be displayed.
23324ae1
FM
832 */
833 bool SetDropdownMenu(int id, wxMenu* menu);
834
8d13e301 835 //@{
23324ae1
FM
836 /**
837 Set the values to be used as margins for the toolbar.
3c4f71cc 838
7c913512 839 @param x
4cc4bfaf 840 Left margin, right margin and inter-tool separation value.
7c913512 841 @param y
4cc4bfaf 842 Top margin, bottom margin and inter-tool separation value.
3c4f71cc 843
23324ae1 844 @remarks This must be called before the tools are added if absolute
7977b62a
BP
845 positioning is to be used, and the default (zero-size) margins are
846 to be overridden.
3c4f71cc 847
922da38b
BP
848 @see GetMargins()
849 */
adaaa686 850 virtual void SetMargins(int x, int y);
922da38b
BP
851
852 /**
853 Set the margins for the toolbar.
854
855 @param size
856 Margin size.
857
858 @remarks This must be called before the tools are added if absolute
859 positioning is to be used, and the default (zero-size) margins are
860 to be overridden.
861
4cc4bfaf 862 @see GetMargins(), wxSize
23324ae1
FM
863 */
864 void SetMargins(const wxSize& size);
8d13e301 865 //@}
23324ae1
FM
866
867 /**
7977b62a
BP
868 Sets the default size of each tool bitmap. The default bitmap size is 16
869 by 15 pixels.
3c4f71cc 870
7c913512 871 @param size
4cc4bfaf 872 The size of the bitmaps in the toolbar.
3c4f71cc 873
23324ae1 874 @remarks This should be called to tell the toolbar what the tool bitmap
7977b62a 875 size is. Call it before you add tools.
3c4f71cc 876
4cc4bfaf 877 @see GetToolBitmapSize(), GetToolSize()
23324ae1 878 */
adaaa686 879 virtual void SetToolBitmapSize(const wxSize& size);
23324ae1
FM
880
881 /**
882 Sets the client data associated with the tool.
51c30bca
VZ
883
884 @param id
885 ID of the tool in question, as passed to AddTool().
8c6471af
SL
886 @param clientData
887 The client data to use.
23324ae1 888 */
adaaa686 889 virtual void SetToolClientData(int id, wxObject* clientData);
23324ae1
FM
890
891 /**
892 Sets the bitmap to be used by the tool with the given ID when the tool
7977b62a
BP
893 is in a disabled state. This can only be used on Button tools, not
894 controls.
895
51c30bca
VZ
896 @param id
897 ID of the tool in question, as passed to AddTool().
8c6471af
SL
898 @param bitmap
899 Bitmap to use for disabled tools.
51c30bca 900
7977b62a
BP
901 @note The native toolbar classes on the main platforms all synthesize
902 the disabled bitmap from the normal bitmap, so this function will
903 have no effect on those platforms.
904
23324ae1 905 */
adaaa686 906 virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
23324ae1
FM
907
908 /**
909 Sets the long help for the given tool.
3c4f71cc 910
7c913512 911 @param toolId
51c30bca 912 ID of the tool in question, as passed to AddTool().
7c913512 913 @param helpString
4cc4bfaf 914 A string for the long help.
3c4f71cc 915
23324ae1 916 @remarks You might use the long help for displaying the tool purpose on
7977b62a 917 the status line.
3c4f71cc 918
4cc4bfaf 919 @see GetToolLongHelp(), SetToolShortHelp(),
23324ae1 920 */
adaaa686 921 virtual void SetToolLongHelp(int toolId, const wxString& helpString);
23324ae1
FM
922
923 /**
7977b62a
BP
924 Sets the bitmap to be used by the tool with the given ID. This can only
925 be used on Button tools, not controls.
51c30bca
VZ
926
927 @param id
928 ID of the tool in question, as passed to AddTool().
8c6471af
SL
929 @param bitmap
930 Bitmap to use for normals tools.
23324ae1 931 */
adaaa686 932 virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
23324ae1
FM
933
934 /**
935 Sets the value used for spacing tools. The default value is 1.
3c4f71cc 936
7c913512 937 @param packing
4cc4bfaf 938 The value for packing.
3c4f71cc 939
408776d0 940 @remarks The packing is used for spacing in the vertical direction if
7977b62a
BP
941 the toolbar is horizontal, and for spacing in the horizontal
942 direction if the toolbar is vertical.
3c4f71cc 943
4cc4bfaf 944 @see GetToolPacking()
23324ae1 945 */
adaaa686 946 virtual void SetToolPacking(int packing);
23324ae1
FM
947
948 /**
949 Sets the default separator size. The default value is 5.
3c4f71cc 950
7c913512 951 @param separation
4cc4bfaf 952 The separator size.
3c4f71cc 953
4cc4bfaf 954 @see AddSeparator()
23324ae1 955 */
adaaa686 956 virtual void SetToolSeparation(int separation);
23324ae1
FM
957
958 /**
959 Sets the short help for the given tool.
3c4f71cc 960
7c913512 961 @param toolId
51c30bca 962 ID of the tool in question, as passed to AddTool().
7c913512 963 @param helpString
4cc4bfaf 964 The string for the short help.
3c4f71cc 965
23324ae1 966 @remarks An application might use short help for identifying the tool
7977b62a
BP
967 purpose in a tooltip.
968
3c4f71cc 969
4cc4bfaf 970 @see GetToolShortHelp(), SetToolLongHelp()
23324ae1 971 */
adaaa686 972 virtual void SetToolShortHelp(int toolId, const wxString& helpString);
23324ae1
FM
973
974 /**
975 Toggles a tool on or off. This does not cause any event to get emitted.
3c4f71cc 976
7c913512 977 @param toolId
51c30bca 978 ID of the tool in question, as passed to AddTool().
7c913512 979 @param toggle
4cc4bfaf 980 If @true, toggles the tool on, otherwise toggles it off.
3c4f71cc 981
7977b62a
BP
982 @remarks Only applies to a tool that has been specified as a toggle
983 tool.
23324ae1 984 */
adaaa686 985 virtual void ToggleTool(int toolId, bool toggle);
f2b6dd8c
RD
986
987
988 /**
989 Factory function to create a new toolbar tool.
990 */
b23ea178 991 virtual wxToolBarToolBase *CreateTool(int toolId,
f2b6dd8c
RD
992 const wxString& label,
993 const wxBitmap& bmpNormal,
994 const wxBitmap& bmpDisabled = wxNullBitmap,
995 wxItemKind kind = wxITEM_NORMAL,
996 wxObject *clientData = NULL,
997 const wxString& shortHelp = wxEmptyString,
998 const wxString& longHelp = wxEmptyString);
999 /**
1000 Factory function to create a new control toolbar tool.
1001 */
1002 virtual wxToolBarToolBase *CreateTool(wxControl *control,
1003 const wxString& label);
1004
1005 /**
1006 Factory function to create a new separator toolbar tool.
1007 */
1008 wxToolBarToolBase *CreateSeparator()
23324ae1 1009};
e54c96f1 1010