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