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