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