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