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