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