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