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