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