]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/toolbar.tex
don't use _T() inside wxGetTranslation() and related macros (wxTRANSLATE, _, ......
[wxWidgets.git] / docs / latex / wx / toolbar.tex
1 \section{\class{wxToolBar}}\label{wxtoolbar}
2
3 The name wxToolBar is defined to be a synonym for one of the following classes:
4
5 \begin{itemize}\itemsep=0pt
6 \item {\bf wxToolBar95} The native Windows 95 toolbar. Used on Windows 95, NT 4 and above.
7 \item {\bf wxToolBarMSW} A Windows implementation. Used on 16-bit Windows.
8 \item {\bf wxToolBarGTK} The GTK toolbar.
9 \end{itemize}
10
11 \wxheading{Derived from}
12
13 wxToolBarBase\\
14 \helpref{wxControl}{wxcontrol}\\
15 \helpref{wxWindow}{wxwindow}\\
16 \helpref{wxEvtHandler}{wxevthandler}\\
17 \helpref{wxObject}{wxobject}
18
19 \wxheading{Include files}
20
21 <wx/toolbar.h> (to allow wxWidgets to select an appropriate toolbar class)\\
22 <wx/tbarbase.h> (the base class)
23
24 \wxheading{Remarks}
25
26 You may also create a toolbar that is managed by the frame, by
27 calling \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}. Under Pocket PC,
28 you should \arg{always} use this function for creating the toolbar
29 to be managed by the frame, so that wxWidgets can use a combined
30 menubar and toolbar. Where you manage your own toolbars, create a wxToolBar
31 as usual.
32
33 The meaning of a "separator" is a vertical line under Windows and simple space under GTK+.
34
35 {\bf wxToolBar95:} Note that this toolbar paints tools to reflect system-wide colours.
36 If you use more than 16 colours in your tool bitmaps, you may wish to suppress
37 this behaviour, otherwise system colours in your bitmaps will inadvertently be
38 mapped to system colours. To do this, set the {\tt msw.remap} system option
39 before creating the toolbar:
40
41 \begin{verbatim}
42 wxSystemOptions::SetOption(wxT("msw.remap"), 0);
43 \end{verbatim}
44
45 If you wish to use 32-bit images (which include an alpha channel for transparency)
46 use:
47
48 \begin{verbatim}
49 wxSystemOptions::SetOption(wxT("msw.remap"), 2);
50 \end{verbatim}
51
52 then colour remapping is switched off, and a transparent background used. But only
53 use this option under Windows XP with true colour:
54
55 \begin{verbatim}
56 (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
57 \end{verbatim}
58
59 \wxheading{Window styles}
60
61 \twocolwidtha{5cm}
62 \begin{twocollist}\itemsep=0pt
63 \twocolitem{\windowstyle{wxTB\_FLAT}}{Gives the toolbar a flat look (Windows and GTK only).}
64 \twocolitem{\windowstyle{wxTB\_DOCKABLE}}{Makes the toolbar floatable and dockable (GTK only).}
65 \twocolitem{\windowstyle{wxTB\_HORIZONTAL}}{Specifies horizontal layout (default).}
66 \twocolitem{\windowstyle{wxTB\_VERTICAL}}{Specifies vertical layout.}
67 \twocolitem{\windowstyle{wxTB\_TEXT}}{Shows the text in the toolbar buttons; by default only icons are shown.}
68 \twocolitem{\windowstyle{wxTB\_NOICONS}}{Specifies no icons in the toolbar buttons; by default they are shown.}
69 \twocolitem{\windowstyle{wxTB\_NODIVIDER}}{Specifies no divider (border) above the toolbar (Windows only).}
70 \twocolitem{\windowstyle{wxTB\_NOALIGN}}{Specifies no alignment with the parent window (Windows only, not very useful).}
71 \twocolitem{\windowstyle{wxTB\_HORZ\_LAYOUT}}{Shows the text and the icons alongside, not vertically stacked (Windows and GTK
72 2 only). This style must be used with wxTB\_TEXT.}
73 \twocolitem{\windowstyle{wxTB\_HORZ\_TEXT}}{Combination of wxTB\_HORZ\_LAYOUT and wxTB\_TEXT.}
74 \twocolitem{\windowstyle{wxTB\_NO\_TOOLTIPS}}{Don't show the short help tooltips for the tools when the mouse hovers over them.}
75 \twocolitem{\windowstyle{wxTB\_BOTTOM}}{Align the toolbar at the bottom of parent window.}
76 \twocolitem{\windowstyle{wxTB\_RIGHT}}{Align the toolbar at the right side of parent window.}
77 \end{twocollist}
78
79 See also \helpref{window styles overview}{windowstyles}. Note that the Win32
80 native toolbar ignores {\tt wxTB\_NOICONS} style. Also, toggling the
81 {\tt wxTB\_TEXT} works only if the style was initially on.
82
83 \wxheading{Event handling}
84
85 The toolbar class emits menu commands in the same way that a frame menubar does,
86 so you can use one EVT\_MENU macro for both a menu item and a toolbar button.
87 The event handler functions take a wxCommandEvent argument. For most event macros,
88 the identifier of the tool is passed, but for EVT\_TOOL\_ENTER the toolbar
89 window identifier is passed and the tool identifier is retrieved from the wxCommandEvent.
90 This is because the identifier may be -1 when the mouse moves off a tool, and -1 is not
91 allowed as an identifier in the event system.
92
93 \twocolwidtha{7cm}
94 \begin{twocollist}\itemsep=0pt
95 \twocolitem{{\bf EVT\_TOOL(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
96 (a synonym for wxEVT\_COMMAND\_MENU\_SELECTED). Pass the id of the tool.}
97 \twocolitem{{\bf EVT\_MENU(id, func)}}{The same as EVT\_TOOL.}
98 \twocolitem{{\bf EVT\_TOOL\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
99 for a range of identifiers. Pass the ids of the tools.}
100 \twocolitem{{\bf EVT\_MENU\_RANGE(id1, id2, func)}}{The same as EVT\_TOOL\_RANGE.}
101 \twocolitem{{\bf EVT\_TOOL\_RCLICKED(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event.
102 Pass the id of the tool.}
103 \twocolitem{{\bf EVT\_TOOL\_RCLICKED\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event
104 for a range of ids. Pass the ids of the tools.}
105 \twocolitem{{\bf EVT\_TOOL\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_ENTER event.
106 Pass the id of the toolbar itself. The value of wxCommandEvent::GetSelection is the tool id, or -1 if the mouse cursor has moved off a tool.}
107 \twocolitem{{\bf EVT\_TOOL\_DROPDOWN(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_DROPDOWN\_CLICKED event. If unhandled, displays the default dropdown menu set using \helpref{wxToolBar::SetDropdownMenu}{wxtoolbarsetdropdownmenu}.}
108 \end{twocollist}
109
110 \wxheading{wxItemKind}
111
112 There are several different types of tools you can add to a toolbar. These
113 types are controlled by the wxItemKind enumeration which has the following
114 values:
115 \twocolwidtha{5cm}
116 \begin{twocollist}\itemsep=0pt
117 \twocolitem{{\bf wxITEM\_NORMAL}}{Normal tool button}
118 \twocolitem{{\bf wxITEM\_CHECK}}{Check (or toggle) tool button.}
119 \twocolitem{{\bf wxITEM\_NORMAL}}{Radio tool button. See \helpref{wxToolBar::AddRadioTool}{wxtoolbaraddradiotool} for details}
120 \twocolitem{{\bf wxITEM\_DROPDOWN}}{Normal tool button with a dropdown arrow
121 next to it. Clicking the dropdown arrow sends a wxEVT\_COMMAND\_TOOL\_DROPDOWN\_CLICKED
122 event and may also display the menu previously associated with the item with
123 \helpref{wxToolBar::SetDropdownMenu}{wxtoolbarsetdropdownmenu}. Currently this
124 type of tools is supported under MSW and GTK.}
125 \end{twocollist}
126
127 \wxheading{See also}
128
129 \overview{Toolbar overview}{wxtoolbaroverview},\rtfsp
130 \helpref{wxScrolledWindow}{wxscrolledwindow}
131
132 \latexignore{\rtfignore{\wxheading{Members}}}
133
134
135 \membersection{wxToolBar::wxToolBar}\label{wxtoolbarconstr}
136
137 \func{}{wxToolBar}{\void}
138
139 Default constructor.
140
141 \func{}{wxToolBar}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},
142 \param{const wxPoint\& }{pos = wxDefaultPosition},
143 \param{const wxSize\& }{size = wxDefaultSize},
144 \param{long }{style = wxTB\_HORIZONTAL \pipe wxBORDER\_NONE},
145 \param{const wxString\& }{name = wxPanelNameStr}}
146
147 Constructs a toolbar.
148
149 \wxheading{Parameters}
150
151 \docparam{parent}{Pointer to a parent window.}
152
153 \docparam{id}{Window identifier. If -1, will automatically create an identifier.}
154
155 \docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
156 should generate a default position for the window. If using the wxWindow class directly, supply
157 an actual position.}
158
159 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets
160 should generate a default size for the window.}
161
162 \docparam{style}{Window style. See \helpref{wxToolBar}{wxtoolbar} for details.}
163
164 \docparam{name}{Window name.}
165
166 \wxheading{Remarks}
167
168 After a toolbar is created, you use \helpref{wxToolBar::AddTool}{wxtoolbaraddtool} and
169 perhaps \helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator}, and then you
170 must call \helpref{wxToolBar::Realize}{wxtoolbarrealize} to construct and display the toolbar
171 tools.
172
173 You may also create a toolbar that is managed by the frame, by
174 calling \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}.
175
176
177 \membersection{wxToolBar::\destruct{wxToolBar}}\label{wxtoolbardtor}
178
179 \func{void}{\destruct{wxToolBar}}{\void}
180
181 Toolbar destructor.
182
183
184 \membersection{wxToolBar::AddControl}\label{wxtoolbaraddcontrol}
185
186 \func{bool}{AddControl}{\param{wxControl*}{ control}, \param{const wxString&}{ label = ""}}
187
188 Adds any control to the toolbar, typically e.g. a combobox.
189
190 \docparam{control}{The control to be added.}
191
192 \docparam{label}{Text to be displayed near the control.}
193
194 \wxheading{Remarks}
195
196 wxMSW: the label is only displayed if there is enough space available below the embedded control.
197
198 wxMac: labels are only displayed if wxWidgets is built with wxMAC\_USE\_NATIVE\_TOOLBAR set to 1
199
200
201 \membersection{wxToolBar::AddSeparator}\label{wxtoolbaraddseparator}
202
203 \func{void}{AddSeparator}{\void}
204
205 Adds a separator for spacing groups of tools.
206
207 \wxheading{See also}
208
209 \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}, \helpref{wxToolBar::SetToolSeparation}{wxtoolbarsettoolseparation}
210
211
212 \membersection{wxToolBar::AddTool}\label{wxtoolbaraddtool}
213
214 \func{wxToolBarToolBase*}{AddTool}{\param{int}{ toolId},\rtfsp
215 \param{const wxString\&}{ label},\rtfsp
216 \param{const wxBitmap\&}{ bitmap1},\rtfsp
217 \param{const wxString\& }{shortHelpString = ""},\rtfsp
218 \param{wxItemKind}{ kind = wxITEM\_NORMAL}}
219
220 \func{wxToolBarToolBase*}{AddTool}{\param{int}{ toolId},\rtfsp
221 \param{const wxString\&}{ label},\rtfsp
222 \param{const wxBitmap\&}{ bitmap1},\rtfsp
223 \param{const wxBitmap\&}{ bitmap2 = wxNullBitmap},\rtfsp
224 \param{wxItemKind}{ kind = wxITEM\_NORMAL},\rtfsp
225 \param{const wxString\& }{shortHelpString = ""},
226 \param{const wxString\& }{longHelpString = ""},\rtfsp
227 \param{wxObject* }{clientData = \NULL}}
228
229 \func{wxToolBarToolBase*}{AddTool}{\param{wxToolBarToolBase* }{tool}}
230
231 Adds a tool to the toolbar. The first (short and most commonly used) version
232 has fewer parameters than the full version at the price of not being able to
233 specify some of the more rarely used button features. The last version allows
234 you to add an existing tool.
235
236 \wxheading{Parameters}
237
238 \docparam{toolId}{An integer by which
239 the tool may be identified in subsequent operations.}
240
241 \docparam{kind}{May be wxITEM\_NORMAL for a normal button (default),
242 wxITEM\_CHECK for a checkable tool (such tool stays pressed after it had been
243 toggled) or wxITEM\_RADIO for a checkable tool which makes part of a radio
244 group of tools each of which is automatically unchecked whenever another button
245 in the group is checked}
246
247 \docparam{bitmap1}{The primary tool bitmap.}
248
249 \docparam{bitmap2}{The bitmap used when the tool is disabled. If it is equal to
250 wxNullBitmap, the disabled bitmap is automatically generated by greing the
251 normal one.}
252
253 \docparam{shortHelpString}{This string is used for the tools tooltip}
254
255 \docparam{longHelpString}{This string is shown in the statusbar (if any) of the
256 parent frame when the mouse pointer is inside the tool}
257
258 \docparam{clientData}{An optional pointer to client data which can be
259 retrieved later using \helpref{wxToolBar::GetToolClientData}{wxtoolbargettoolclientdata}.}
260
261 \docparam{tool}{The tool to be added.}
262
263 \wxheading{Remarks}
264
265 After you have added tools to a toolbar, you must call \helpref{wxToolBar::Realize}{wxtoolbarrealize} in
266 order to have the tools appear.
267
268 \wxheading{See also}
269
270 \helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator},\rtfsp
271 \helpref{wxToolBar::AddCheckTool}{wxtoolbaraddchecktool},\rtfsp
272 \helpref{wxToolBar::AddRadioTool}{wxtoolbaraddradiotool},\rtfsp
273 \helpref{wxToolBar::InsertTool}{wxtoolbarinserttool},\rtfsp
274 \helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool},\rtfsp
275 \helpref{wxToolBar::Realize}{wxtoolbarrealize}
276
277
278 \membersection{wxToolBar::AddCheckTool}\label{wxtoolbaraddchecktool}
279
280 \func{wxToolBarToolBase*}{AddCheckTool}{\param{int}{ toolId},\rtfsp
281 \param{const wxString\&}{ label},\rtfsp
282 \param{const wxBitmap\&}{ bitmap1},\rtfsp
283 \param{const wxBitmap\&}{ bitmap2},\rtfsp
284 \param{const wxString\& }{shortHelpString = ""},\rtfsp
285 \param{const wxString\& }{longHelpString = ""},\rtfsp
286 \param{wxObject* }{clientData = \NULL}}
287
288 Adds a new check (or toggle) tool to the toolbar. The parameters are the same
289 as in \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.
290
291 \wxheading{See also}
292
293 \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
294
295
296 \membersection{wxToolBar::AddRadioTool}\label{wxtoolbaraddradiotool}
297
298 \func{wxToolBarToolBase*}{AddRadioTool}{\param{int}{ toolId},\rtfsp
299 \param{const wxString\&}{ label},\rtfsp
300 \param{const wxBitmap\&}{ bitmap1},\rtfsp
301 \param{const wxBitmap\&}{ bitmap2},\rtfsp
302 \param{const wxString\& }{shortHelpString = ""},\rtfsp
303 \param{const wxString\& }{longHelpString = ""},\rtfsp
304 \param{wxObject* }{clientData = \NULL}}
305
306 Adds a new radio tool to the toolbar. Consecutive radio tools form a radio
307 group such that exactly one button in the group is pressed at any moment, in
308 other words whenever a button in the group is pressed the previously pressed
309 button is automatically released. You should avoid having the radio groups of
310 only one element as it would be impossible for the user to use such button.
311
312 By default, the first button in the radio group is initially pressed, the
313 others are not.
314
315 \wxheading{See also}
316
317 \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
318
319 \membersection{wxToolBar::ClearTools}\label{wxtoolbarcleartools}
320
321 \func{void}{ClearTools}{\void}
322
323 Deletes all the tools in the toolbar.
324
325 \membersection{wxToolBar::DeleteTool}\label{wxtoolbardeletetool}
326
327 \func{bool}{DeleteTool}{\param{int }{toolId}}
328
329 Removes the specified tool from the toolbar and deletes it. If you don't want
330 to delete the tool, but just to remove it from the toolbar (to possibly add it
331 back later), you may use \helpref{RemoveTool}{wxtoolbarremovetool} instead.
332
333 Note that it is unnecessary to call \helpref{Realize}{wxtoolbarrealize} for the
334 change to take place, it will happen immediately.
335
336 Returns true if the tool was deleted, false otherwise.
337
338 \wxheading{See also}
339
340 \helpref{DeleteToolByPos}{wxtoolbardeletetoolbypos}
341
342
343 \membersection{wxToolBar::DeleteToolByPos}\label{wxtoolbardeletetoolbypos}
344
345 \func{bool}{DeleteToolByPos}{\param{size\_t }{pos}}
346
347 This function behaves like \helpref{DeleteTool}{wxtoolbardeletetool} but it
348 deletes the tool at the specified position and not the one with the given id.
349
350
351 \membersection{wxToolBar::EnableTool}\label{wxtoolbarenabletool}
352
353 \func{void}{EnableTool}{\param{int }{toolId}, \param{bool}{ enable}}
354
355 Enables or disables the tool.
356
357 \wxheading{Parameters}
358
359 \docparam{toolId}{Tool to enable or disable.}
360
361 \docparam{enable}{If true, enables the tool, otherwise disables it.}
362
363 {\bf NB:} This function should only be called after
364 \helpref{Realize}{wxtoolbarrealize}.
365
366 \wxheading{Remarks}
367
368 Some implementations will change the visible state of the tool to indicate that it is disabled.
369
370 \wxheading{See also}
371
372 \helpref{wxToolBar::GetToolEnabled}{wxtoolbargettoolenabled},\rtfsp
373 \helpref{wxToolBar::ToggleTool}{wxtoolbartoggletool}
374
375
376 \membersection{wxToolBar::FindById}\label{wxtoolbarfindbyid}
377
378 \func{wxToolBarToolBase*}{FindById}{\param{int }{id}}
379
380 Returns a pointer to the tool identified by \arg{id} or
381 \NULL if no corresponding tool is found.
382
383
384 \membersection{wxToolBar::FindControl}\label{wxtoolbarfindcontrol}
385
386 \func{wxControl*}{FindControl}{\param{int }{id}}
387
388 Returns a pointer to the control identified by \arg{id} or
389 \NULL if no corresponding control is found.
390
391
392 \membersection{wxToolBar::FindToolForPosition}\label{wxtoolbarfindtoolforposition}
393
394 \constfunc{wxToolBarToolBase*}{FindToolForPosition}{\param{wxCoord }{x}, \param{wxCoord }{y}}
395
396 Finds a tool for the given mouse position.
397
398 \wxheading{Parameters}
399
400 \docparam{x}{X position.}
401
402 \docparam{y}{Y position.}
403
404 \wxheading{Return value}
405
406 A pointer to a tool if a tool is found, or \NULL otherwise.
407
408 \wxheading{Remarks}
409
410 Currently not implemented in wxGTK (always returns \NULL there).
411
412
413 \membersection{wxToolBar::GetToolsCount}\label{wxtoolbargettoolscount}
414
415 \constfunc{int}{GetToolsCount}{\void}
416
417 Returns the number of tools in the toolbar.
418
419
420 \membersection{wxToolBar::GetToolSize}\label{wxtoolbargettoolsize}
421
422 \func{wxSize}{GetToolSize}{\void}
423
424 Returns the size of a whole button, which is usually larger than a tool bitmap because
425 of added 3D effects.
426
427 \wxheading{See also}
428
429 \helpref{wxToolBar::SetToolBitmapSize}{wxtoolbarsettoolbitmapsize},\rtfsp
430 \helpref{wxToolBar::GetToolBitmapSize}{wxtoolbargettoolbitmapsize}
431
432
433 \membersection{wxToolBar::GetToolBitmapSize}\label{wxtoolbargettoolbitmapsize}
434
435 \func{wxSize}{GetToolBitmapSize}{\void}
436
437 Returns the size of bitmap that the toolbar expects to have. The default bitmap size is 16 by 15 pixels.
438
439 \wxheading{Remarks}
440
441 Note that this is the size of the bitmap you pass to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool},
442 and not the eventual size of the tool button.
443
444 \wxheading{See also}
445
446 \helpref{wxToolBar::SetToolBitmapSize}{wxtoolbarsettoolbitmapsize},\rtfsp
447 \helpref{wxToolBar::GetToolSize}{wxtoolbargettoolsize}
448
449
450 \membersection{wxToolBar::GetMargins}\label{wxtoolbargetmargins}
451
452 \constfunc{wxSize}{GetMargins}{\void}
453
454 Returns the left/right and top/bottom margins, which are also used for inter-toolspacing.
455
456 \wxheading{See also}
457
458 \helpref{wxToolBar::SetMargins}{wxtoolbarsetmargins}
459
460
461 \membersection{wxToolBar::GetToolClientData}\label{wxtoolbargettoolclientdata}
462
463 \constfunc{wxObject*}{GetToolClientData}{\param{int }{toolId}}
464
465 Get any client data associated with the tool.
466
467 \wxheading{Parameters}
468
469 \docparam{toolId}{Id of the tool, as passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
470
471 \wxheading{Return value}
472
473 Client data, or \NULL if there is none.
474
475
476 \membersection{wxToolBar::GetToolEnabled}\label{wxtoolbargettoolenabled}
477
478 \constfunc{bool}{GetToolEnabled}{\param{int }{toolId}}
479
480 Called to determine whether a tool is enabled (responds to user input).
481
482 \wxheading{Parameters}
483
484 \docparam{toolId}{Id of the tool in question.}
485
486 \wxheading{Return value}
487
488 true if the tool is enabled, false otherwise.
489
490 \wxheading{See also}
491
492 \helpref{wxToolBar::EnableTool}{wxtoolbarenabletool}
493
494
495 \membersection{wxToolBar::GetToolLongHelp}\label{wxtoolbargettoollonghelp}
496
497 \constfunc{wxString}{GetToolLongHelp}{\param{int }{toolId}}
498
499 Returns the long help for the given tool.
500
501 \wxheading{Parameters}
502
503 \docparam{toolId}{The tool in question.}
504
505 \wxheading{See also}
506
507 \helpref{wxToolBar::SetToolLongHelp}{wxtoolbarsettoollonghelp},\rtfsp
508 \helpref{wxToolBar::SetToolShortHelp}{wxtoolbarsettoolshorthelp}\rtfsp
509
510
511 \membersection{wxToolBar::GetToolPacking}\label{wxtoolbargettoolpacking}
512
513 \constfunc{int}{GetToolPacking}{\void}
514
515 Returns the value used for packing tools.
516
517 \wxheading{See also}
518
519 \helpref{wxToolBar::SetToolPacking}{wxtoolbarsettoolpacking}
520
521
522 \membersection{wxToolBar::GetToolPos}\label{wxtoolbargettoolpos}
523
524 \constfunc{int}{GetToolPos}{\param{int }{toolId}}
525
526 Returns the tool position in the toolbar, or {\tt wxNOT\_FOUND} if the tool is not found.
527
528
529 \membersection{wxToolBar::GetToolSeparation}\label{wxtoolbargettoolseparation}
530
531 \constfunc{int}{GetToolSeparation}{\void}
532
533 Returns the default separator size.
534
535 \wxheading{See also}
536
537 \helpref{wxToolBar::SetToolSeparation}{wxtoolbarsettoolseparation}
538
539
540 \membersection{wxToolBar::GetToolShortHelp}\label{wxtoolbargettoolshorthelp}
541
542 \constfunc{wxString}{GetToolShortHelp}{\param{int }{toolId}}
543
544 Returns the short help for the given tool.
545
546 \wxheading{Parameters}
547
548 \docparam{toolId}{The tool in question.}
549
550 \wxheading{See also}
551
552 \helpref{wxToolBar::GetToolLongHelp}{wxtoolbargettoollonghelp},\rtfsp
553 \helpref{wxToolBar::SetToolShortHelp}{wxtoolbarsettoolshorthelp}\rtfsp
554
555
556 \membersection{wxToolBar::GetToolState}\label{wxtoolbargettoolstate}
557
558 \constfunc{bool}{GetToolState}{\param{int }{toolId}}
559
560 Gets the on/off state of a toggle tool.
561
562 \wxheading{Parameters}
563
564 \docparam{toolId}{The tool in question.}
565
566 \wxheading{Return value}
567
568 true if the tool is toggled on, false otherwise.
569
570 \wxheading{See also}
571
572 \helpref{wxToolBar::ToggleTool}{wxtoolbartoggletool}
573
574
575 \membersection{wxToolBar::InsertControl}\label{wxtoolbarinsertcontrol}
576
577 \func{wxToolBarToolBase *}{InsertControl}{\param{size\_t }{pos}, \param{wxControl *}{control}}
578
579 Inserts the control into the toolbar at the given position.
580
581 You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
582
583 \wxheading{See also}
584
585 \helpref{AddControl}{wxtoolbaraddcontrol},\\
586 \helpref{InsertTool}{wxtoolbarinserttool}
587
588
589 \membersection{wxToolBar::InsertSeparator}\label{wxtoolbarinsertseparator}
590
591 \func{wxToolBarToolBase *}{InsertSeparator}{\param{size\_t }{pos}}
592
593 Inserts the separator into the toolbar at the given position.
594
595 You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
596
597 \wxheading{See also}
598
599 \helpref{AddSeparator}{wxtoolbaraddseparator},\\
600 \helpref{InsertTool}{wxtoolbarinserttool}
601
602
603 \membersection{wxToolBar::InsertTool}\label{wxtoolbarinserttool}
604
605 \func{wxToolBarToolBase *}{InsertTool}{\param{size\_t }{pos},\rtfsp
606 \param{int}{ toolId}, \param{const wxBitmap\&}{ bitmap1},\rtfsp
607 \param{const wxBitmap\&}{ bitmap2 = wxNullBitmap}, \param{bool}{ isToggle = false},\rtfsp
608 \param{wxObject* }{clientData = \NULL}, \param{const wxString\& }{shortHelpString = ""}, \param{const wxString\& }{longHelpString = ""}}
609
610 \func{wxToolBarToolBase *}{InsertTool}{\param{size\_t }{pos},\rtfsp
611 \param{wxToolBarToolBase* }{tool}}
612
613 Inserts the tool with the specified attributes into the toolbar at the given
614 position.
615
616 You must call \helpref{Realize}{wxtoolbarrealize} for the change to take place.
617
618 \wxheading{See also}
619
620 \helpref{AddTool}{wxtoolbaraddtool},\\
621 \helpref{InsertControl}{wxtoolbarinsertcontrol},\\
622 \helpref{InsertSeparator}{wxtoolbarinsertseparator}
623
624
625 \membersection{wxToolBar::OnLeftClick}\label{wxtoolbaronleftclick}
626
627 \func{bool}{OnLeftClick}{\param{int}{ toolId}, \param{bool}{ toggleDown}}
628
629 Called when the user clicks on a tool with the left mouse button.
630
631 This is the old way of detecting tool clicks; although it will still work,
632 you should use the EVT\_MENU or EVT\_TOOL macro instead.
633
634 \wxheading{Parameters}
635
636 \docparam{toolId}{The identifier passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
637
638 \docparam{toggleDown}{true if the tool is a toggle and the toggle is down, otherwise is false.}
639
640 \wxheading{Return value}
641
642 If the tool is a toggle and this function returns false, the toggle
643 toggle state (internal and visual) will not be changed. This provides a way of
644 specifying that toggle operations are not permitted in some circumstances.
645
646 \wxheading{See also}
647
648 \helpref{wxToolBar::OnMouseEnter}{wxtoolbaronmouseenter},\rtfsp
649 \helpref{wxToolBar::OnRightClick}{wxtoolbaronrightclick}
650
651
652 \membersection{wxToolBar::OnMouseEnter}\label{wxtoolbaronmouseenter}
653
654 \func{void}{OnMouseEnter}{\param{int}{ toolId}}
655
656 This is called when the mouse cursor moves into a tool or out of
657 the toolbar.
658
659 This is the old way of detecting mouse enter events; although it will still work,
660 you should use the EVT\_TOOL\_ENTER macro instead.
661
662 \wxheading{Parameters}
663
664 \docparam{toolId}{Greater than -1 if the mouse cursor has moved into the tool,
665 or -1 if the mouse cursor has moved. The
666 programmer can override this to provide extra information about the tool,
667 such as a short description on the status line.}
668
669 \wxheading{Remarks}
670
671 With some derived toolbar classes, if the mouse moves quickly out of the toolbar, wxWidgets may not be able to
672 detect it. Therefore this function may not always be called when expected.
673
674
675 \membersection{wxToolBar::OnRightClick}\label{wxtoolbaronrightclick}
676
677 \func{void}{OnRightClick}{\param{int}{ toolId}, \param{float}{ x}, \param{float}{ y}}
678
679 Called when the user clicks on a tool with the right mouse button. The
680 programmer should override this function to detect right tool clicks.
681
682 This is the old way of detecting tool right clicks; although it will still work,
683 you should use the EVT\_TOOL\_RCLICKED macro instead.
684
685 \wxheading{Parameters}
686
687 \docparam{toolId}{The identifier passed to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.}
688
689 \docparam{x}{The x position of the mouse cursor.}
690
691 \docparam{y}{The y position of the mouse cursor.}
692
693 \wxheading{Remarks}
694
695 A typical use of this member might be to pop up a menu.
696
697 \wxheading{See also}
698
699 \helpref{wxToolBar::OnMouseEnter}{wxtoolbaronmouseenter},\rtfsp
700 \helpref{wxToolBar::OnLeftClick}{wxtoolbaronleftclick}
701
702
703 \membersection{wxToolBar::Realize}\label{wxtoolbarrealize}
704
705 \func{bool}{Realize}{\void}
706
707 This function should be called after you have added tools.
708
709
710 \membersection{wxToolBar::RemoveTool}\label{wxtoolbarremovetool}
711
712 \func{wxToolBarToolBase *}{RemoveTool}{\param{int }{id}}
713
714 Removes the given tool from the toolbar but doesn't delete it. This allows to
715 insert/add this tool back to this (or another) toolbar later.
716
717 Note that it is unnecessary to call \helpref{Realize}{wxtoolbarrealize} for the
718 change to take place, it will happen immediately.
719
720 \wxheading{See also}
721
722 \helpref{DeleteTool}{wxtoolbardeletetool}
723
724
725 \membersection{wxToolBar::SetBitmapResource}\label{wxtoolbarsetbitmapresource}
726
727 \func{void}{SetBitmapResource}{\param{int }{resourceId}}
728
729 Sets the bitmap resource identifier for specifying tool bitmaps as indices
730 into a custom bitmap. Windows CE only.
731
732
733 \membersection{wxToolBar::SetMargins}\label{wxtoolbarsetmargins}
734
735 \func{void}{SetMargins}{\param{const wxSize\&}{ size}}
736
737 \func{void}{SetMargins}{\param{int}{ x}, \param{int}{ y}}
738
739 Set the values to be used as margins for the toolbar.
740
741 \wxheading{Parameters}
742
743 \docparam{size}{Margin size.}
744
745 \docparam{x}{Left margin, right margin and inter-tool separation value.}
746
747 \docparam{y}{Top margin, bottom margin and inter-tool separation value.}
748
749 \wxheading{Remarks}
750
751 This must be called before the tools are added if absolute positioning is to be used, and the
752 default (zero-size) margins are to be overridden.
753
754 \wxheading{See also}
755
756 \helpref{wxToolBar::GetMargins}{wxtoolbargetmargins}, \helpref{wxSize}{wxsize}
757
758
759 \membersection{wxToolBar::SetDropdownMenu}\label{wxtoolbarsetdropdownmenu}
760
761 \func{bool}{SetDropdownMenu}{\param{int }{id}, \param{wxMenu* }{menu}}
762
763 Sets the dropdown menu for the tool given by its \arg{id}. The tool itself will
764 delete the menu when it's no longer needed.
765
766 If you define a EVT\_TOOL\_DROPDOWN handler in your program, you must call
767 \helpref{wxEvent::Skip()}{wxeventskip} from it or the menu won't be displayed.
768
769
770 \membersection{wxToolBar::SetToolBitmapSize}\label{wxtoolbarsettoolbitmapsize}
771
772 \func{void}{SetToolBitmapSize}{\param{const wxSize\&}{ size}}
773
774 Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 pixels.
775
776 \wxheading{Parameters}
777
778 \docparam{size}{The size of the bitmaps in the toolbar.}
779
780 \wxheading{Remarks}
781
782 This should be called to tell the toolbar what the tool bitmap size is. Call
783 it before you add tools.
784
785 Note that this is the size of the bitmap you pass to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool},
786 and not the eventual size of the tool button.
787
788 \wxheading{See also}
789
790 \helpref{wxToolBar::GetToolBitmapSize}{wxtoolbargettoolbitmapsize},\rtfsp
791 \helpref{wxToolBar::GetToolSize}{wxtoolbargettoolsize}
792
793
794 \membersection{wxToolBar::SetToolClientData}\label{wxtoolbarsettoolclientdata}
795
796 \func{void}{SetToolClientData}{\param{int }{id}, \param{wxObject* }{clientData}}
797
798 Sets the client data associated with the tool.
799
800
801 \membersection{wxToolBar::SetToolDisabledBitmap}\label{wxtoolbarsettooldisabledbitmap}
802
803 \func{void}{SetToolDisabledBitmap}{\param{int }{id}, \param{const wxBitmap\& }{bitmap}}
804
805 Sets the bitmap to be used by the tool with the given ID when the tool
806 is in a disabled state. This can only be used on Button tools, not
807 controls. NOTE: The native toolbar classes on the main platforms all
808 synthesize the disabled bitmap from the normal bitmap, so this
809 function will have no effect on those platforms.
810
811
812 \membersection{wxToolBar::SetToolLongHelp}\label{wxtoolbarsettoollonghelp}
813
814 \func{void}{SetToolLongHelp}{\param{int }{toolId}, \param{const wxString\& }{helpString}}
815
816 Sets the long help for the given tool.
817
818 \wxheading{Parameters}
819
820 \docparam{toolId}{The tool in question.}
821
822 \docparam{helpString}{A string for the long help.}
823
824 \wxheading{Remarks}
825
826 You might use the long help for displaying the tool purpose on the status line.
827
828 \wxheading{See also}
829
830 \helpref{wxToolBar::GetToolLongHelp}{wxtoolbargettoollonghelp},\rtfsp
831 \helpref{wxToolBar::SetToolShortHelp}{wxtoolbarsettoolshorthelp},\rtfsp
832
833
834 \membersection{wxToolBar::SetToolPacking}\label{wxtoolbarsettoolpacking}
835
836 \func{void}{SetToolPacking}{\param{int}{ packing}}
837
838 Sets the value used for spacing tools. The default value is 1.
839
840 \wxheading{Parameters}
841
842 \docparam{packing}{The value for packing.}
843
844 \wxheading{Remarks}
845
846 The packing is used for spacing in the vertical direction if the toolbar is horizontal,
847 and for spacing in the horizontal direction if the toolbar is vertical.
848
849 \wxheading{See also}
850
851 \helpref{wxToolBar::GetToolPacking}{wxtoolbargettoolpacking}
852
853
854 \membersection{wxToolBar::SetToolShortHelp}\label{wxtoolbarsettoolshorthelp}
855
856 \func{void}{SetToolShortHelp}{\param{int }{toolId}, \param{const wxString\& }{helpString}}
857
858 Sets the short help for the given tool.
859
860 \wxheading{Parameters}
861
862 \docparam{toolId}{The tool in question.}
863
864 \docparam{helpString}{The string for the short help.}
865
866 \wxheading{Remarks}
867
868 An application might use short help for identifying the tool purpose in a tooltip.
869
870 \wxheading{See also}
871
872 \helpref{wxToolBar::GetToolShortHelp}{wxtoolbargettoolshorthelp}, \helpref{wxToolBar::SetToolLongHelp}{wxtoolbarsettoollonghelp}
873
874
875 \membersection{wxToolBar::SetToolNormalBitmap}\label{wxtoolbarsettoolnormalbitmap}
876
877 \func{void}{SetToolNormalBitmap}{\param{int }{id}, \param{const wxBitmap\& }{bitmap}}
878
879 Sets the bitmap to be used by the tool with the given ID. This can
880 only be used on Button tools, not controls.
881
882
883
884 \membersection{wxToolBar::SetToolSeparation}\label{wxtoolbarsettoolseparation}
885
886 \func{void}{SetToolSeparation}{\param{int}{ separation}}
887
888 Sets the default separator size. The default value is 5.
889
890 \wxheading{Parameters}
891
892 \docparam{separation}{The separator size.}
893
894 \wxheading{See also}
895
896 \helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator}
897
898
899 \membersection{wxToolBar::ToggleTool}\label{wxtoolbartoggletool}
900
901 \func{void}{ToggleTool}{\param{int }{toolId}, \param{bool}{ toggle}}
902
903 Toggles a tool on or off. This does not cause any event to get emitted.
904
905 \wxheading{Parameters}
906
907 \docparam{toolId}{Tool in question.}
908
909 \docparam{toggle}{If true, toggles the tool on, otherwise toggles it off.}
910
911 \wxheading{Remarks}
912
913 Only applies to a tool that has been specified as a toggle tool.
914
915 \wxheading{See also}
916
917 \helpref{wxToolBar::GetToolState}{wxtoolbargettoolstate}
918