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