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 wxWindows 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 \wxheading{Window styles}
  55
  56 \twocolwidtha{5cm}
  57 \begin{twocollist}\itemsep=0pt
  58 \twocolitem{\windowstyle{wxTB\_FLAT}}{Gives the toolbar a flat look (Windows and GTK only).}
  59 \twocolitem{\windowstyle{wxTB\_DOCKABLE}}{Makes the toolbar floatable and dockable (GTK only).}
  60 \twocolitem{\windowstyle{wxTB\_HORIZONTAL}}{Specifies horizontal layout (default).}
  61 \twocolitem{\windowstyle{wxTB\_VERTICAL}}{Specifies vertical layout.}
  62 \twocolitem{\windowstyle{wxTB\_3DBUTTONS}}{Only for wxToolBarSimple: gives a mild 3D look to its buttons.}
  63 \twocolitem{\windowstyle{wxTB\_TEXT}}{Show the text in the toolbar buttons; by default only icons are shown.}
  64 \twocolitem{\windowstyle{wxTB\_NOICONS}}{Specifies no icons in the toolbar buttons; by default they are shown.}
  65 \twocolitem{\windowstyle{wxTB\_NODIVIDER}}{Specifies no divider (border) above the toolbar (Windows only).}
  66 \twocolitem{\windowstyle{wxTB\_NOALIGN}}{Specifies no alignment with the parent window (Windows only, not very useful).}
  67 \twocolitem{\windowstyle{wxTB\_HORZ\_LAYOUT}}{Show the text and the icons alongside, not vertically stacked (Windows and GTK
  68 2 only). This style must be used with wxTB\_TEXT.}
  69 \twocolitem{\windowstyle{wxTB\_HORZ\_TEXT}}{Combination of wxTB\_HORZ\_LAYOUT and wxTB\_TEXT.}
  70 \end{twocollist}
  71
  72 See also \helpref{window styles overview}{windowstyles}. Note that the Win32
  73 native toolbar ignores {\tt wxTB\_NOICONS} style. Also, toggling the
  74 {\tt wxTB\_TEXT} works only if the style was initially on.
  75
  76 \wxheading{Event handling}
  77
  78 The toolbar class emits menu commands in the same was that a frame menubar does,
  79 so you can use one EVT\_MENU macro for both a menu item and a toolbar button.
  80 The event handler functions take a wxCommandEvent argument. For most event macros,
  81 the identifier of the tool is passed, but for EVT\_TOOL\_ENTER the toolbar
  82 window is passed and the tool id is retrieved from the wxCommandEvent.
  83 This is because the id may be -1 when the mouse moves off a tool, and -1 is not
  84 allowed as an identifier in the event system.
  85
  86 Note that tool commands (and UI update events for tools) are first sent to
  87 the focus window within the frame that contains the toolbar. If no window within the frame has the focus,
  88 then the events are sent directly to the toolbar (and up the hierarchy to the
  89 frame, depending on where the application has put its event handlers). This allows command and UI update
  90 handling to be processed by specific windows and controls, and not necessarily
  91 by the application frame.
  92
  93 \twocolwidtha{7cm}
  94 \begin{twocollist}\itemsep=0pt
  95 \twocolitem{{\bf EVT\_TOOL(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
  96 (a synonym for wxEVT\_COMMAND\_MENU\_SELECTED). Pass the id of the tool.}
  97 \twocolitem{{\bf EVT\_MENU(id, func)}}{The same as EVT\_TOOL.}
  98 \twocolitem{{\bf EVT\_TOOL\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
  99 for a range id identifiers. Pass the ids of the tools.}
 100 \twocolitem{{\bf EVT\_MENU\_RANGE(id1, id2, func)}}{The same as EVT\_TOOL\_RANGE.}
 101 \twocolitem{{\bf EVT\_TOOL\_RCLICKED(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event.
 102 Pass the id of the tool.}
 103 \twocolitem{{\bf EVT\_TOOL\_RCLICKED\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event
 104 for a range of ids. Pass the ids of the tools.}
 105 \twocolitem{{\bf EVT\_TOOL\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_ENTER event.
 106 Pass the id of the toolbar itself. The value of wxCommandEvent::GetSelection is the tool id, or -1 if the mouse cursor has moved off a tool.}
 107 \end{twocollist}
 108
 109 \wxheading{See also}
 110
 111 \overview{Toolbar overview}{wxtoolbaroverview},\rtfsp
 112 \helpref{wxScrolledWindow}{wxscrolledwindow}
 113
 114 \latexignore{\rtfignore{\wxheading{Members}}}
 115
 116 \membersection{wxToolBar::wxToolBar}\label{wxtoolbarconstr}
 117
 118 \func{}{wxToolBar}{\void}
 119
 120 Default constructor.
 121
 122 \func{}{wxToolBar}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},
 123  \param{const wxPoint\& }{pos = wxDefaultPosition},
 124  \param{const wxSize\& }{size = wxDefaultSize},
 125  \param{long }{style = wxTB\_HORIZONTAL \pipe wxNO\_BORDER},
 126  \param{const wxString\& }{name = wxPanelNameStr}}
 127
 128 Constructs a toolbar.
 129
 130 \wxheading{Parameters}
 131
 132 \docparam{parent}{Pointer to a parent window.}
 133
 134 \docparam{id}{Window identifier. If -1, will automatically create an identifier.}
 135
 136 \docparam{pos}{Window position. wxDefaultPosition is (-1, -1) which indicates that wxWindows
 137 should generate a default position for the window. If using the wxWindow class directly, supply
 138 an actual position.}
 139
 140 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWindows
 141 should generate a default size for the window.}
 142
 143 \docparam{style}{Window style. See \helpref{wxToolBar}{wxtoolbar} for details.}
 144
 145 \docparam{name}{Window name.}
 146
 147 \wxheading{Remarks}
 148
 149 After a toolbar is created, you use \helpref{wxToolBar::AddTool}{wxtoolbaraddtool} and
 150 perhaps \helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator}, and then you
 151 must call \helpref{wxToolBar::Realize}{wxtoolbarrealize} to construct and display the toolbar
 152 tools.
 153
 154 You may also create a toolbar that is managed by the frame, by
 155 calling \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}.
 156
 157 \membersection{wxToolBar::\destruct{wxToolBar}}
 158
 159 \func{void}{\destruct{wxToolBar}}{\void}
 160
 161 Toolbar destructor.
 162
 163 \membersection{wxToolBar::AddControl}\label{wxtoolbaraddcontrol}
 164
 165 \func{bool}{AddControl}{\param{wxControl*}{ control}}
 166
 167 Adds any control to the toolbar, typically e.g. a combobox.
 168
 169 \docparam{control}{The control to be added.}
 170
 171 \membersection{wxToolBar::AddSeparator}\label{wxtoolbaraddseparator}
 172
 173 \func{void}{AddSeparator}{\void}
 174
 175 Adds a separator for spacing groups of tools.
 176
 177 \wxheading{See also}
 178
 179 \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}, \helpref{wxToolBar::SetToolSeparation}{wxtoolbarsettoolseparation}
 180
 181 \membersection{wxToolBar::AddTool}\label{wxtoolbaraddtool}
 182
 183 \func{wxToolBarTool*}{AddTool}{\param{int}{ toolId},\rtfsp
 184 \param{const wxString\&}{ label},\rtfsp
 185 \param{const wxBitmap\&}{ bitmap1},\rtfsp
 186 \param{const wxString\& }{shortHelpString = ""},\rtfsp
 187 \param{wxItemKind}{ kind = wxITEM\_NORMAL}}
 188
 189 \func{wxToolBarTool*}{AddTool}{\param{int}{ toolId},\rtfsp
 190 \param{const wxString\&}{ label},\rtfsp
 191 \param{const wxBitmap\&}{ bitmap1},\rtfsp
 192 \param{const wxBitmap\&}{ bitmap2 = wxNullBitmap},\rtfsp
 193 \param{wxItemKind}{ kind = wxITEM\_NORMAL},\rtfsp
 194 \param{const wxString\& }{shortHelpString = ""},
 195 \param{const wxString\& }{longHelpString = ""},\rtfsp
 196 \param{wxObject* }{clientData = NULL}}
 197
 198 \func{wxToolBarTool*}{AddTool}{\param{wxToolBarTool* }{tool}}
 199
 200 Adds a tool to the toolbar. The first (short and most commonly used) version
 201 has fewer parameters than the full version at the price of not being able to
 202 specify some of the more rarely used button features. The last version allows
 203 to add an existing tool.
 204
 205 \wxheading{Parameters}
 206
 207 \docparam{toolId}{An integer by which
 208 the tool may be identified in subsequent operations.}
 209
 210 \docparam{kind}{May be wxITEM\_NORMAL for a normal button (default),
 211 wxITEM\_CHECK for a checkable tool (such tool stays pressed after it had been
 212 toggled) or wxITEM\_RADIO for a checkable tool which makes part of a radio
 213 group of tools each of which is automatically unchecked whenever another button
 214 in the group is checked}
 215
 216 \docparam{bitmap1}{The primary tool bitmap for toggle and button tools.}
 217
 218 \docparam{bitmap2}{The second bitmap specifies the on-state bitmap for a toggle
 219 tool. If this is wxNullBitmap, either an inverted version of the primary bitmap is
 220 used for the on-state of a toggle tool (monochrome displays) or a black
 221 border is drawn around the tool (colour displays) or the pixmap is shown
 222 as a pressed button (GTK). }
 223
 224 \docparam{shortHelpString}{This string is used for the tools tooltip}
 225
 226 \docparam{longHelpString}{This string is shown in the statusbar (if any) of the
 227 parent frame when the mouse pointer is inside the tool}
 228
 229 \docparam{clientData}{An optional pointer to client data which can be
 230 retrieved later using \helpref{wxToolBar::GetToolClientData}{wxtoolbargettoolclientdata}.}
 231
 232 \docparam{tool}{The tool to be added.}
 233
 234 \wxheading{Remarks}
 235
 236 After you have added tools to a toolbar, you must call \helpref{wxToolBar::Realize}{wxtoolbarrealize} in
 237 order to have the tools appear.
 238
 239 \wxheading{See also}
 240
 241 \helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator},\rtfsp
 242 \helpref{wxToolBar::AddCheckTool}{wxtoolbaraddchecktool},\rtfsp
 243 \helpref{wxToolBar::AddRadioTool}{wxtoolbaraddradiotool},\rtfsp
 244 \helpref{wxToolBar::InsertTool}{wxtoolbarinserttool},\rtfsp
 245 \helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool},\rtfsp
 246 \helpref{wxToolBar::Realize}{wxtoolbarrealize}
 247
 248 \membersection{wxToolBar::AddCheckTool}\label{wxtoolbaraddchecktool}
 249
 250 \func{wxToolBarTool*}{AddCheckTool}{\param{int}{ toolId},\rtfsp
 251 \param{const wxString\&}{ label},\rtfsp
 252 \param{const wxBitmap\&}{ bitmap1},\rtfsp
 253 \param{const wxBitmap\&}{ bitmap2},\rtfsp
 254 \param{const wxString\& }{shortHelpString = ""},\rtfsp
 255 \param{const wxString\& }{longHelpString = ""},\rtfsp
 256 \param{wxObject* }{clientData = NULL}}
 257
 258 Adds a new check (or toggle) tool to the toolbar. The parameters are the same
 259 as in \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}.
 260
 261 \wxheading{See also}
 262
 263 \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
 264
 265 \membersection{wxToolBar::AddRadioTool}\label{wxtoolbaraddradiotool}
 266
 267 \func{wxToolBarTool*}{AddRadioTool}{\param{int}{ toolId},\rtfsp
 268 \param{const wxString\&}{ label},\rtfsp
 269 \param{const wxBitmap\&}{ bitmap1},\rtfsp
 270 \param{const wxBitmap\&}{ bitmap2},\rtfsp
 271 \param{const wxString\& }{shortHelpString = ""},\rtfsp
 272 \param{const wxString\& }{longHelpString = ""},\rtfsp
 273 \param{wxObject* }{clientData = NULL}}
 274
 275 Adds a new radio tool to the toolbar. Consecutive radio tools form a radio
 276 group such that exactly one button in the group is pressed at any moment, in
 277 other words whenever a button in the group is pressed the previously pressed
 278 button is automatically released. You should avoid having the radio groups of
 279 only one element as it would be impossible for the user to use such button.
 280
 281 By default, the first button in the radio group is initially pressed, the
 282 others are not.
 283
 284 \wxheading{See also}
 285
 286 \helpref{wxToolBar::AddTool}{wxtoolbaraddtool}
 287
 288 \membersection{wxToolBar::DeleteTool}\label{wxtoolbardeletetool}
 289
 290 \func{bool}{DeleteTool}{\param{int }{toolId}}
 291
 292 Removes the specified tool from the toolbar and deletes it. If you don't want
 293 to delete the tool, but just to remove it from the toolbar (to possibly add it
 294 back later), you may use \helpref{RemoveTool}{wxtoolbarremovetool} instead.
 295
 296 Note that it is unnecessary to call \helpref{Realize}{wxtoolbarrealize} for the
 297 change to take place, it will happen immediately.
 298
 299 Returns true if the tool was deleted, false otherwise.
 300
 301 \wxheading{See also}
 302
 303 \helpref{DeleteToolByPos}{wxtoolbardeletetoolbypos}
 304
 305 \membersection{wxToolBar::DeleteToolByPos}\label{wxtoolbardeletetoolbypos}
 306
 307 \func{bool}{DeleteToolByPos}{\param{size\_t }{pos}}
 308
 309 This function behaves like \helpref{DeleteTool}{wxtoolbardeletetool} but it
 310 deletes the tool at the specified position and not the one with the given id.
 311
 312 \membersection{wxToolBar::EnableTool}\label{wxtoolbarenabletool}
 313
 314 \func{void}{EnableTool}{\param{int }{toolId}, \param{const bool}{ enable}}
 315
 316 Enables or disables the tool.
 317
 318 \wxheading{Parameters}
 319
 320 \docparam{toolId}{Tool to enable or disable.}
 321
 322 \docparam{enable}{If true, enables the tool, otherwise disables it.}
 323
 324 {\bf NB:} This function should only be called after
 325 \helpref{Realize}{wxtoolbarrealize}.
 326
 327 \wxheading{Remarks}
 328
 329 For wxToolBarSimple, does nothing. Some other implementations
 330 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{wxToolBarTool*}{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{wxToolBarTool*}{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 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{wxToolBarTool *}{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{wxToolBarTool *}{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{wxToolBarTool *}{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{wxToolBarTool *}{InsertTool}{\param{size\_t }{pos},\rtfsp
 549 \param{wxToolBarTool* }{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, wxWindows 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 If you are using absolute positions for your tools when using a wxToolBarSimple object,
 644 do not call this function. You must call it at all other times.
 645
 646 \membersection{wxToolBar::RemoveTool}\label{wxtoolbarremovetool}
 647
 648 \func{wxToolBarTool *}{RemoveTool}{\param{int }{id}}
 649
 650 Removes the given tool from the toolbar but doesn't delete it. This allows to
 651 insert/add this tool back to this (or another) toolbar later.
 652
 653 Note that it is unnecessary to call \helpref{Realize}{wxtoolbarrealize} for the
 654 change to take place, it will happen immediately.
 655
 656 \wxheading{See also}
 657
 658 \helpref{DeleteTool}{wxtoolbardeletetool}
 659
 660 \membersection{wxToolBar::SetMargins}\label{wxtoolbarsetmargins}
 661
 662 \func{void}{SetMargins}{\param{const wxSize\&}{ size}}
 663
 664 \func{void}{SetMargins}{\param{int}{ x}, \param{int}{ y}}
 665
 666 Set the values to be used as margins for the toolbar.
 667
 668 \wxheading{Parameters}
 669
 670 \docparam{size}{Margin size.}
 671
 672 \docparam{x}{Left margin, right margin and inter-tool separation value.}
 673
 674 \docparam{y}{Top margin, bottom margin and inter-tool separation value.}
 675
 676 \wxheading{Remarks}
 677
 678 This must be called before the tools are added if absolute positioning is to be used, and the
 679 default (zero-size) margins are to be overridden.
 680
 681 \wxheading{See also}
 682
 683 \helpref{wxToolBar::GetMargins}{wxtoolbargetmargins}, \helpref{wxSize}{wxsize}
 684
 685 \membersection{wxToolBar::SetToolBitmapSize}\label{wxtoolbarsettoolbitmapsize}
 686
 687 \func{void}{SetToolBitmapSize}{\param{const wxSize\&}{ size}}
 688
 689 Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 pixels.
 690
 691 \wxheading{Parameters}
 692
 693 \docparam{size}{The size of the bitmaps in the toolbar.}
 694
 695 \wxheading{Remarks}
 696
 697 This should be called to tell the toolbar what the tool bitmap size is. Call
 698 it before you add tools.
 699
 700 Note that this is the size of the bitmap you pass to \helpref{wxToolBar::AddTool}{wxtoolbaraddtool},
 701 and not the eventual size of the tool button.
 702
 703 \wxheading{See also}
 704
 705 \helpref{wxToolBar::GetToolBitmapSize}{wxtoolbargettoolbitmapsize},\rtfsp
 706 \helpref{wxToolBar::GetToolSize}{wxtoolbargettoolsize}
 707
 708 \membersection{wxToolBar::SetToolClientData}\label{wxtoolbarsettoolclientdata}
 709
 710 \func{void}{SetToolClientData}{\param{int }{id}, \param{wxObject* }{clientData}}
 711
 712 Sets the client data associated with the tool.
 713
 714 \membersection{wxToolBar::SetToolLongHelp}\label{wxtoolbarsettoollonghelp}
 715
 716 \func{void}{SetToolLongHelp}{\param{int }{toolId}, \param{const wxString\& }{helpString}}
 717
 718 Sets the long help for the given tool.
 719
 720 \wxheading{Parameters}
 721
 722 \docparam{toolId}{The tool in question.}
 723
 724 \docparam{helpString}{A string for the long help.}
 725
 726 \wxheading{Remarks}
 727
 728 You might use the long help for displaying the tool purpose on the status line.
 729
 730 \wxheading{See also}
 731
 732 \helpref{wxToolBar::GetToolLongHelp}{wxtoolbargettoollonghelp},\rtfsp
 733 \helpref{wxToolBar::SetToolShortHelp}{wxtoolbarsettoolshorthelp},\rtfsp
 734
 735 \membersection{wxToolBar::SetToolPacking}\label{wxtoolbarsettoolpacking}
 736
 737 \func{void}{SetToolPacking}{\param{int}{ packing}}
 738
 739 Sets the value used for spacing tools. The default value is 1.
 740
 741 \wxheading{Parameters}
 742
 743 \docparam{packing}{The value for packing.}
 744
 745 \wxheading{Remarks}
 746
 747 The packing is used for spacing in the vertical direction if the toolbar is horizontal,
 748 and for spacing in the horizontal direction if the toolbar is vertical.
 749
 750 \wxheading{See also}
 751
 752 \helpref{wxToolBar::GetToolPacking}{wxtoolbargettoolpacking}
 753
 754 \membersection{wxToolBar::SetToolShortHelp}\label{wxtoolbarsettoolshorthelp}
 755
 756 \func{void}{SetToolShortHelp}{\param{int }{toolId}, \param{const wxString\& }{helpString}}
 757
 758 Sets the short help for the given tool.
 759
 760 \wxheading{Parameters}
 761
 762 \docparam{toolId}{The tool in question.}
 763
 764 \docparam{helpString}{The string for the short help.}
 765
 766 \wxheading{Remarks}
 767
 768 An application might use short help for identifying the tool purpose in a tooltip.
 769
 770 \wxheading{See also}
 771
 772 \helpref{wxToolBar::GetToolShortHelp}{wxtoolbargettoolshorthelp}, \helpref{wxToolBar::SetToolLongHelp}{wxtoolbarsettoollonghelp}
 773
 774 \membersection{wxToolBar::SetToolSeparation}\label{wxtoolbarsettoolseparation}
 775
 776 \func{void}{SetToolSeparation}{\param{int}{ separation}}
 777
 778 Sets the default separator size. The default value is 5.
 779
 780 \wxheading{Parameters}
 781
 782 \docparam{separation}{The separator size.}
 783
 784 \wxheading{See also}
 785
 786 \helpref{wxToolBar::AddSeparator}{wxtoolbaraddseparator}
 787
 788 \membersection{wxToolBar::ToggleTool}\label{wxtoolbartoggletool}
 789
 790 \func{void}{ToggleTool}{\param{int }{toolId}, \param{const bool}{ toggle}}
 791
 792 Toggles a tool on or off. This does not cause any event to get emitted.
 793
 794 \wxheading{Parameters}
 795
 796 \docparam{toolId}{Tool in question.}
 797
 798 \docparam{toggle}{If true, toggles the tool on, otherwise toggles it off.}
 799
 800 \wxheading{Remarks}
 801
 802 Only applies to a tool that has been specified as a toggle tool.
 803
 804 \wxheading{See also}
 805
 806 \helpref{wxToolBar::GetToolState}{wxtoolbargettoolstate}
 807