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