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