interface/wx/toolbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        toolbar.h
   3 // Purpose:     interface of wxToolBar
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxToolBar
  11
  12     A toolbar is a bar of buttons and/or other controls usually placed below
  13     the menu bar in a wxFrame.
  14
  15     You may create a toolbar that is managed by the frame, by calling
  16     wxFrame::CreateToolBar(). Under Pocket PC, you should always use this
  17     function for creating the toolbar to be managed by the frame, so that
  18     wxWidgets can use a combined menubar and toolbar. Where you manage your
  19     own toolbars, create a wxToolBar as usual.
  20
  21     The meaning of a "separator" is a vertical line under Windows and simple
  22     space under GTK+.
  23
  24     <b>wxMSW note</b>: Note that under wxMSW toolbar paints tools to reflect
  25     system-wide colours. If you use more than 16 colours in your tool bitmaps,
  26     you may wish to suppress this behaviour, otherwise system colours in your
  27     bitmaps will inadvertently be mapped to system colours.
  28     To do this, set the msw.remap system option before creating the toolbar:
  29     @code
  30     wxSystemOptions::SetOption(wxT("msw.remap"), 0);
  31     @endcode
  32     If you wish to use 32-bit images (which include an alpha channel for
  33     transparency) use:
  34     @code
  35     wxSystemOptions::SetOption(wxT("msw.remap"), 2);
  36     @endcode
  37     Then colour remapping is switched off, and a transparent background
  38     used. But only use this option under Windows XP with true colour:
  39     @code
  40     if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
  41     @endcode
  42
  43     There are several different types of tools you can add to a toolbar. These
  44     types are controlled by the ::wxItemKind enumeration.
  45
  46     @beginStyleTable
  47     @style{wxTB_FLAT}
  48         Gives the toolbar a flat look (Windows and GTK only).
  49     @style{wxTB_DOCKABLE}
  50         Makes the toolbar floatable and dockable (GTK only).
  51     @style{wxTB_HORIZONTAL}
  52         Specifies horizontal layout (default).
  53     @style{wxTB_VERTICAL}
  54         Specifies vertical layout.
  55     @style{wxTB_TEXT}
  56         Shows the text in the toolbar buttons; by default only icons are shown.
  57     @style{wxTB_NOICONS}
  58         Specifies no icons in the toolbar buttons; by default they are shown.
  59     @style{wxTB_NODIVIDER}
  60         Specifies no divider (border) above the toolbar (Windows only)
  61     @style{wxTB_NOALIGN}
  62         Specifies no alignment with the parent window (Windows only, not very
  63         useful).
  64     @style{wxTB_HORZ_LAYOUT}
  65         Shows the text and the icons alongside, not vertically stacked (Windows
  66         and GTK 2 only). This style must be used with @c wxTB_TEXT.
  67     @style{wxTB_HORZ_TEXT}
  68         Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT.
  69     @style{wxTB_NO_TOOLTIPS}
  70         Don't show the short help tooltips for the tools when the mouse hovers
  71         over them.
  72     @style{wxTB_BOTTOM}
  73         Align the toolbar at the bottom of parent window.
  74     @style{wxTB_RIGHT}
  75         Align the toolbar at the right side of parent window.
  76     @endStyleTable
  77
  78     See also @ref overview_windowstyles. Note that the Win32 native toolbar
  79     ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only
  80     if the style was initially on.
  81
  82     @beginEventTable{wxCommandEvent}
  83     @event{EVT_TOOL(id, func)}
  84         Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c
  85         wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool.
  86     @event{EVT_MENU(id, func)}
  87         The same as EVT_TOOL().
  88     @event{EVT_TOOL_RANGE(id1, id2, func)}
  89         Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of
  90         identifiers. Pass the ids of the tools.
  91     @event{EVT_MENU_RANGE(id1, id2, func)}
  92         The same as EVT_TOOL_RANGE().
  93     @event{EVT_TOOL_RCLICKED(id, func)}
  94         Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the
  95         tool.
  96     @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
  97         Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass
  98         the ids of the tools.
  99     @event{EVT_TOOL_ENTER(id, func)}
 100         Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar
 101         itself. The value of wxCommandEvent::GetSelection() is the tool id, or
 102         -1 if the mouse cursor has moved off a tool.
 103     @event{EVT_TOOL_DROPDOWN(id, func)}
 104         Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled,
 105         displays the default dropdown menu set using
 106         wxToolBar::SetDropdownMenu().
 107     @endEventTable
 108
 109     The toolbar class emits menu commands in the same way that a frame menubar
 110     does, so you can use one EVT_MENU() macro for both a menu item and a toolbar
 111     button. The event handler functions take a wxCommandEvent argument. For most
 112     event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER()
 113     the toolbar window identifier is passed and the tool identifier is retrieved
 114     from the wxCommandEvent. This is because the identifier may be -1 when the
 115     mouse moves off a tool, and -1 is not allowed as an identifier in the event
 116     system.
 117
 118     @library{wxcore}
 119     @category{miscwnd}
 120
 121     @see @ref overview_toolbar
 122 */
 123 class wxToolBar : public wxControl
 124 {
 125 public:
 126     /**
 127         Default constructor.
 128     */
 129     wxToolBar();
 130
 131     /**
 132         Constructs a toolbar.
 133
 134         @param parent
 135             Pointer to a parent window.
 136         @param id
 137             Window identifier. If -1, will automatically create an identifier.
 138         @param pos
 139             Window position. ::wxDefaultPosition is (-1, -1) which indicates that
 140             wxWidgets should generate a default position for the window. If
 141             using the wxWindow class directly, supply an actual position.
 142         @param size
 143             Window size. ::wxDefaultSize is (-1, -1) which indicates that
 144             wxWidgets should generate a default size for the window.
 145         @param style
 146             Window style. See wxToolBar for details.
 147         @param name
 148             Window name.
 149
 150         @remarks After a toolbar is created, you use AddTool() and perhaps
 151             AddSeparator(), and then you must call Realize() to construct and
 152             display the toolbar tools.
 153     */
 154     wxToolBar(wxWindow* parent, wxWindowID id,
 155               const wxPoint& pos = wxDefaultPosition,
 156               const wxSize& size = wxDefaultSize,
 157               long style = wxTB_HORIZONTAL | wxBORDER_NONE,
 158               const wxString& name = wxToolBarNameStr);
 159
 160     /**
 161         Toolbar destructor.
 162     */
 163     virtual ~wxToolBar();
 164
 165     /**
 166         Adds a new check (or toggle) tool to the toolbar. The parameters are the
 167         same as in AddTool().
 168
 169         @see AddTool()
 170     */
 171     wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label,
 172                                     const wxBitmap& bitmap1,
 173                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 174                                     const wxString& shortHelp = wxEmptyString,
 175                                     const wxString& longHelp = wxEmptyString,
 176                                     wxObject* clientData = NULL);
 177
 178     /**
 179         Adds any control to the toolbar, typically e.g. a wxComboBox.
 180
 181         @param control
 182             The control to be added.
 183         @param label
 184             Text to be displayed near the control.
 185
 186         @remarks
 187             wxMSW: the label is only displayed if there is enough space
 188             available below the embedded control.
 189
 190         @remarks
 191             wxMac: labels are only displayed if wxWidgets is built with @c
 192             wxMAC_USE_NATIVE_TOOLBAR set to 1
 193     */
 194     virtual wxToolBarToolBase* AddControl(wxControl* control,
 195                                           const wxString& label = wxEmptyString);
 196
 197     /**
 198         Adds a new radio tool to the toolbar. Consecutive radio tools form a
 199         radio group such that exactly one button in the group is pressed at any
 200         moment, in other words whenever a button in the group is pressed the
 201         previously pressed button is automatically released. You should avoid
 202         having the radio groups of only one element as it would be impossible
 203         for the user to use such button.
 204
 205         By default, the first button in the radio group is initially pressed,
 206         the others are not.
 207
 208
 209         @see AddTool()
 210     */
 211     wxToolBarToolBase* AddRadioTool(int toolId, const wxString& label,
 212                                     const wxBitmap& bitmap1,
 213                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 214                                     const wxString& shortHelp = wxEmptyString,
 215                                     const wxString& longHelp = wxEmptyString,
 216                                     wxObject* clientData = NULL);
 217
 218     /**
 219         Adds a separator for spacing groups of tools.
 220
 221         @see AddTool(), SetToolSeparation()
 222     */
 223     virtual wxToolBarToolBase* AddSeparator();
 224
 225     /**
 226         Adds a tool to the toolbar.
 227
 228         @param tool
 229             The tool to be added.
 230
 231         @remarks After you have added tools to a toolbar, you must call
 232             Realize() in order to have the tools appear.
 233
 234         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 235              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 236     */
 237     virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
 238
 239     /**
 240         Adds a tool to the toolbar. This most commonly used version has fewer
 241         parameters than the full version below which specifies the more rarely
 242         used button features.
 243
 244         @param toolId
 245             An integer by which the tool may be identified in subsequent
 246             operations.
 247         @param label
 248             The string to be displayed with the tool.
 249         @param bitmap
 250             The primary tool bitmap.
 251         @param shortHelp
 252             This string is used for the tools tooltip.
 253         @param kind
 254             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 255             for a checkable tool (such tool stays pressed after it had been
 256             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 257             a radio group of tools each of which is automatically unchecked
 258             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 259             specifies that a drop-down menu button will appear next to the
 260             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 261
 262         @remarks After you have added tools to a toolbar, you must call
 263             Realize() in order to have the tools appear.
 264
 265         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 266              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 267     */
 268     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 269                                const wxBitmap& bitmap,
 270                                const wxString& shortHelp = wxEmptyString,
 271                                wxItemKind kind = wxITEM_NORMAL);
 272
 273     /**
 274         Adds a tool to the toolbar.
 275
 276         @param toolId
 277             An integer by which the tool may be identified in subsequent
 278             operations.
 279         @param label
 280             The string to be displayed with the tool.
 281         @param bitmap
 282             The primary tool bitmap.
 283         @param bmpDisabled
 284             The bitmap used when the tool is disabled. If it is equal to
 285             ::wxNullBitmap (default), the disabled bitmap is automatically
 286             generated by greying the normal one.
 287         @param shortHelpString
 288             This string is used for the tools tooltip.
 289         @param longHelpString
 290             This string is shown in the statusbar (if any) of the parent frame
 291             when the mouse pointer is inside the tool.
 292         @param kind
 293             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 294             for a checkable tool (such tool stays pressed after it had been
 295             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 296             a radio group of tools each of which is automatically unchecked
 297             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 298             specifies that a drop-down menu button will appear next to the
 299             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 300         @param clientData
 301             An optional pointer to client data which can be retrieved later
 302             using GetToolClientData().
 303
 304         @remarks After you have added tools to a toolbar, you must call
 305             Realize() in order to have the tools appear.
 306
 307         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 308              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 309     */
 310     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 311                                const wxBitmap& bitmap,
 312                                const wxBitmap& bmpDisabled = wxNullBitmap,
 313                                wxItemKind kind = wxITEM_NORMAL,
 314                                const wxString& shortHelpString = wxEmptyString,
 315                                const wxString& longHelpString = wxEmptyString,
 316                                wxObject* clientData = NULL);
 317
 318     /**
 319         Deletes all the tools in the toolbar.
 320     */
 321     virtual void ClearTools();
 322
 323     /**
 324         Removes the specified tool from the toolbar and deletes it. If you don't
 325         want to delete the tool, but just to remove it from the toolbar (to
 326         possibly add it back later), you may use RemoveTool() instead.
 327
 328         @note It is unnecessary to call Realize() for the change to take
 329             place, it will happen immediately.
 330
 331         @returns @true if the tool was deleted, @false otherwise.
 332
 333         @see DeleteToolByPos()
 334     */
 335     virtual bool DeleteTool(int toolId);
 336
 337     /**
 338         This function behaves like DeleteTool() but it deletes the tool at the
 339         specified position and not the one with the given id.
 340     */
 341     virtual bool DeleteToolByPos(size_t pos);
 342
 343     /**
 344         Enables or disables the tool.
 345
 346         @param toolId
 347             Tool to enable or disable.
 348         @param enable
 349             If @true, enables the tool, otherwise disables it.
 350
 351         @remarks Some implementations will change the visible state of the tool
 352             to indicate that it is disabled.
 353
 354
 355         @see GetToolEnabled(), ToggleTool()
 356     */
 357     virtual void EnableTool(int toolId, bool enable);
 358
 359     /**
 360         Returns a pointer to the tool identified by @a id or @NULL if no
 361         corresponding tool is found.
 362     */
 363     wxToolBarToolBase* FindById(int id) const;
 364
 365     /**
 366         Returns a pointer to the control identified by @a id or @NULL if no
 367         corresponding control is found.
 368     */
 369     virtual wxControl* FindControl(int id);
 370
 371     /**
 372         Finds a tool for the given mouse position.
 373
 374         @param x
 375             X position.
 376         @param y
 377             Y position.
 378
 379         @return A pointer to a tool if a tool is found, or @NULL otherwise.
 380
 381         @remarks Currently not implemented in wxGTK (always returns @NULL
 382         there).
 383     */
 384     virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;
 385
 386     /**
 387         Returns the left/right and top/bottom margins, which are also used for
 388         inter-toolspacing.
 389
 390         @see SetMargins()
 391     */
 392     wxSize GetMargins() const;
 393
 394     /**
 395         Returns the size of bitmap that the toolbar expects to have. The default
 396         bitmap size is 16 by 15 pixels.
 397
 398         @remarks Note that this is the size of the bitmap you pass to AddTool(),
 399             and not the eventual size of the tool button.
 400
 401         @see SetToolBitmapSize(), GetToolSize()
 402     */
 403     virtual wxSize GetToolBitmapSize() const;
 404
 405     /**
 406         Get any client data associated with the tool.
 407
 408         @param toolId
 409             Id of the tool, as passed to AddTool().
 410
 411         @return Client data, or @NULL if there is none.
 412     */
 413     virtual wxObject* GetToolClientData(int toolId) const;
 414
 415     /**
 416         Called to determine whether a tool is enabled (responds to user input).
 417
 418         @param toolId
 419             Id of the tool in question.
 420
 421         @return @true if the tool is enabled, @false otherwise.
 422
 423         @see EnableTool()
 424     */
 425     virtual bool GetToolEnabled(int toolId) const;
 426
 427     /**
 428         Returns the long help for the given tool.
 429
 430         @param toolId
 431             The tool in question.
 432
 433         @see SetToolLongHelp(), SetToolShortHelp()
 434     */
 435     virtual wxString GetToolLongHelp(int toolId) const;
 436
 437     /**
 438         Returns the value used for packing tools.
 439
 440         @see SetToolPacking()
 441     */
 442     virtual int GetToolPacking() const;
 443
 444     /**
 445         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
 446         is not found.
 447     */
 448     virtual int GetToolPos(int toolId) const;
 449
 450     /**
 451         Returns the default separator size.
 452
 453         @see SetToolSeparation()
 454     */
 455     virtual int GetToolSeparation() const;
 456
 457     /**
 458         Returns the short help for the given tool.
 459
 460         @param toolId
 461             The tool in question.
 462
 463         @see GetToolLongHelp(), SetToolShortHelp()
 464     */
 465     virtual wxString GetToolShortHelp(int toolId) const;
 466
 467     /**
 468         Returns the size of a whole button, which is usually larger than a tool
 469         bitmap because of added 3D effects.
 470
 471         @see SetToolBitmapSize(), GetToolBitmapSize()
 472     */
 473     virtual wxSize GetToolSize() const;
 474
 475     /**
 476         Gets the on/off state of a toggle tool.
 477
 478         @param toolId
 479             The tool in question.
 480
 481         @return @true if the tool is toggled on, @false otherwise.
 482
 483         @see ToggleTool()
 484     */
 485     virtual bool GetToolState(int toolId) const;
 486
 487     /**
 488         Returns the number of tools in the toolbar.
 489     */
 490     size_t GetToolsCount() const;
 491
 492     /**
 493         Inserts the control into the toolbar at the given position. You must
 494         call Realize() for the change to take place.
 495
 496         @see AddControl(), InsertTool()
 497     */
 498     virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control,
 499                                              const wxString& label = wxEmptyString);
 500
 501     /**
 502         Inserts the separator into the toolbar at the given position. You must
 503         call Realize() for the change to take place.
 504
 505         @see AddSeparator(), InsertTool()
 506     */
 507     virtual wxToolBarToolBase* InsertSeparator(size_t pos);
 508
 509     //@{
 510     /**
 511         Inserts the tool with the specified attributes into the toolbar at the
 512         given position.
 513
 514         You must call Realize() for the change to take place.
 515
 516         @see AddTool(), InsertControl(), InsertSeparator()
 517     */
 518     wxToolBarToolBase* InsertTool(size_t pos, int toolId,
 519                                   const wxBitmap& bitmap1,
 520                                   const wxBitmap& bitmap2 = wxNullBitmap,
 521                                   bool isToggle = false,
 522                                   wxObject* clientData = NULL,
 523                                   const wxString& shortHelpString = "",
 524                                   const wxString& longHelpString = "");
 525     wxToolBarToolBase* InsertTool(size_t pos,
 526                                   wxToolBarToolBase* tool);
 527     //@}
 528
 529     /**
 530         Called when the user clicks on a tool with the left mouse button. This
 531         is the old way of detecting tool clicks; although it will still work,
 532         you should use the EVT_MENU() or EVT_TOOL() macro instead.
 533
 534         @param toolId
 535             The identifier passed to AddTool().
 536         @param toggleDown
 537             @true if the tool is a toggle and the toggle is down, otherwise is
 538             @false.
 539
 540         @return If the tool is a toggle and this function returns @false, the
 541                 toggle state (internal and visual) will not be changed. This
 542                 provides a way of specifying that toggle operations are not
 543                 permitted in some circumstances.
 544
 545         @see OnMouseEnter(), OnRightClick()
 546     */
 547     virtual bool OnLeftClick(int toolId, bool toggleDown);
 548
 549     /**
 550         This is called when the mouse cursor moves into a tool or out of the
 551         toolbar. This is the old way of detecting mouse enter events;
 552         although it will still work, you should use the EVT_TOOL_ENTER()
 553         macro instead.
 554
 555         @param toolId
 556             Greater than -1 if the mouse cursor has moved into the tool, or -1
 557             if the mouse cursor has moved. The programmer can override this to
 558             provide extra information about the tool, such as a short
 559             description on the status line.
 560
 561         @remarks With some derived toolbar classes, if the mouse moves quickly
 562                  out of the toolbar, wxWidgets may not be able to detect it.
 563                  Therefore this function may not always be called when expected.
 564     */
 565     virtual void OnMouseEnter(int toolId);
 566
 567     /**
 568         @deprecated This is the old way of detecting tool right clicks;
 569                     although it will still work, you should use the
 570                     EVT_TOOL_RCLICKED() macro instead.
 571
 572         Called when the user clicks on a tool with the right mouse button. The
 573         programmer should override this function to detect right tool clicks.
 574
 575         @param toolId
 576             The identifier passed to AddTool().
 577         @param x
 578             The x position of the mouse cursor.
 579         @param y
 580             The y position of the mouse cursor.
 581
 582         @remarks A typical use of this member might be to pop up a menu.
 583
 584         @see OnMouseEnter(), OnLeftClick()
 585     */
 586     virtual void OnRightClick(int toolId, long x, long y);
 587
 588     /**
 589         This function should be called after you have added tools.
 590     */
 591     virtual bool Realize();
 592
 593     /**
 594         Removes the given tool from the toolbar but doesn't delete it. This
 595         allows to insert/add this tool back to this (or another) toolbar later.
 596
 597         @note It is unnecessary to call Realize() for the change to take place,
 598             it will happen immediately.
 599
 600
 601         @see DeleteTool()
 602     */
 603     virtual wxToolBarToolBase* RemoveTool(int id);
 604
 605     /**
 606         Sets the bitmap resource identifier for specifying tool bitmaps as
 607         indices into a custom bitmap. Windows CE only.
 608     */
 609     void SetBitmapResource(int resourceId);
 610
 611     /**
 612         Sets the dropdown menu for the tool given by its @e id. The tool itself
 613         will delete the menu when it's no longer needed. Only supported under
 614         GTK+ und MSW.
 615
 616         If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
 617         call wxEvent::Skip() from it or the menu won't be displayed.
 618     */
 619     bool SetDropdownMenu(int id, wxMenu* menu);
 620
 621     /**
 622         Set the values to be used as margins for the toolbar.
 623
 624         @param x
 625             Left margin, right margin and inter-tool separation value.
 626         @param y
 627             Top margin, bottom margin and inter-tool separation value.
 628
 629         @remarks This must be called before the tools are added if absolute
 630             positioning is to be used, and the default (zero-size) margins are
 631             to be overridden.
 632
 633         @see GetMargins()
 634     */
 635     virtual void SetMargins(int x, int y);
 636
 637     /**
 638         Set the margins for the toolbar.
 639
 640         @param size
 641             Margin size.
 642
 643         @remarks This must be called before the tools are added if absolute
 644             positioning is to be used, and the default (zero-size) margins are
 645             to be overridden.
 646
 647         @see GetMargins(), wxSize
 648     */
 649     void SetMargins(const wxSize& size);
 650
 651     /**
 652         Sets the default size of each tool bitmap. The default bitmap size is 16
 653         by 15 pixels.
 654
 655         @param size
 656             The size of the bitmaps in the toolbar.
 657
 658         @remarks This should be called to tell the toolbar what the tool bitmap
 659             size is. Call it before you add tools.
 660
 661         @see GetToolBitmapSize(), GetToolSize()
 662     */
 663     virtual void SetToolBitmapSize(const wxSize& size);
 664
 665     /**
 666         Sets the client data associated with the tool.
 667     */
 668     virtual void SetToolClientData(int id, wxObject* clientData);
 669
 670     /**
 671         Sets the bitmap to be used by the tool with the given ID when the tool
 672         is in a disabled state. This can only be used on Button tools, not
 673         controls.
 674
 675         @note The native toolbar classes on the main platforms all synthesize
 676             the disabled bitmap from the normal bitmap, so this function will
 677             have no effect on those platforms.
 678
 679     */
 680     virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
 681
 682     /**
 683         Sets the long help for the given tool.
 684
 685         @param toolId
 686             The tool in question.
 687         @param helpString
 688             A string for the long help.
 689
 690         @remarks You might use the long help for displaying the tool purpose on
 691             the status line.
 692
 693         @see GetToolLongHelp(), SetToolShortHelp(),
 694     */
 695     virtual void SetToolLongHelp(int toolId, const wxString& helpString);
 696
 697     /**
 698         Sets the bitmap to be used by the tool with the given ID. This can only
 699         be used on Button tools, not controls.
 700     */
 701     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 702
 703     /**
 704         Sets the value used for spacing tools. The default value is 1.
 705
 706         @param packing
 707             The value for packing.
 708
 709         @remarks The packing is used for spacing in the vertical direction if
 710             the toolbar is horizontal, and for spacing in the horizontal
 711             direction if the toolbar is vertical.
 712
 713         @see GetToolPacking()
 714     */
 715     virtual void SetToolPacking(int packing);
 716
 717     /**
 718         Sets the default separator size. The default value is 5.
 719
 720         @param separation
 721             The separator size.
 722
 723         @see AddSeparator()
 724     */
 725     virtual void SetToolSeparation(int separation);
 726
 727     /**
 728         Sets the short help for the given tool.
 729
 730         @param toolId
 731             The tool in question.
 732         @param helpString
 733             The string for the short help.
 734
 735         @remarks An application might use short help for identifying the tool
 736             purpose in a tooltip.
 737
 738
 739         @see GetToolShortHelp(), SetToolLongHelp()
 740     */
 741     virtual void SetToolShortHelp(int toolId, const wxString& helpString);
 742
 743     /**
 744         Toggles a tool on or off. This does not cause any event to get emitted.
 745
 746         @param toolId
 747             Tool in question.
 748         @param toggle
 749             If @true, toggles the tool on, otherwise toggles it off.
 750
 751         @remarks Only applies to a tool that has been specified as a toggle
 752             tool.
 753     */
 754     virtual void ToggleTool(int toolId, bool toggle);
 755 };
 756