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