docs/latex/wx/toolbar.tex

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