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