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