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