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