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