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(wxT("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(wxT("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     @beginEventTable{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.
 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.
 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.
 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 | wxBORDER_NONE,
 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         Note that the meaning of a "separator" is a vertical line under wxMSW and
 228         a simple space under wxGTK.
 229
 230         @see AddTool(), SetToolSeparation()
 231     */
 232     virtual wxToolBarToolBase* AddSeparator();
 233
 234     //@{
 235     /**
 236         Adds a tool to the toolbar.
 237
 238         @param tool
 239             The tool to be added.
 240
 241         @remarks After you have added tools to a toolbar, you must call
 242             Realize() in order to have the tools appear.
 243
 244         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 245              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 246     */
 247     virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
 248
 249     /**
 250         Adds a tool to the toolbar. This most commonly used version has fewer
 251         parameters than the full version below which specifies the more rarely
 252         used button features.
 253
 254         @param toolId
 255             An integer by which the tool may be identified in subsequent
 256             operations.
 257         @param label
 258             The string to be displayed with the tool.
 259         @param bitmap
 260             The primary tool bitmap.
 261         @param shortHelp
 262             This string is used for the tools tooltip.
 263         @param kind
 264             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 265             for a checkable tool (such tool stays pressed after it had been
 266             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 267             a radio group of tools each of which is automatically unchecked
 268             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 269             specifies that a drop-down menu button will appear next to the
 270             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 271
 272         @remarks After you have added tools to a toolbar, you must call
 273             Realize() in order to have the tools appear.
 274
 275         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 276              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 277     */
 278     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 279                                const wxBitmap& bitmap,
 280                                const wxString& shortHelp = wxEmptyString,
 281                                wxItemKind kind = wxITEM_NORMAL);
 282
 283     /**
 284         Adds a tool to the toolbar.
 285
 286         @param toolId
 287             An integer by which the tool may be identified in subsequent
 288             operations.
 289         @param label
 290             The string to be displayed with the tool.
 291         @param bitmap
 292             The primary tool bitmap.
 293         @param bmpDisabled
 294             The bitmap used when the tool is disabled. If it is equal to
 295             ::wxNullBitmap (default), the disabled bitmap is automatically
 296             generated by greying the normal one.
 297         @param shortHelpString
 298             This string is used for the tools tooltip.
 299         @param longHelpString
 300             This string is shown in the statusbar (if any) of the parent frame
 301             when the mouse pointer is inside the tool.
 302         @param kind
 303             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 304             for a checkable tool (such tool stays pressed after it had been
 305             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 306             a radio group of tools each of which is automatically unchecked
 307             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 308             specifies that a drop-down menu button will appear next to the
 309             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 310         @param clientData
 311             An optional pointer to client data which can be retrieved later
 312             using GetToolClientData().
 313
 314         @remarks After you have added tools to a toolbar, you must call
 315             Realize() in order to have the tools appear.
 316
 317         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 318              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 319     */
 320     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 321                                const wxBitmap& bitmap,
 322                                const wxBitmap& bmpDisabled = wxNullBitmap,
 323                                wxItemKind kind = wxITEM_NORMAL,
 324                                const wxString& shortHelpString = wxEmptyString,
 325                                const wxString& longHelpString = wxEmptyString,
 326                                wxObject* clientData = NULL);
 327     //@}
 328
 329     /**
 330         Deletes all the tools in the toolbar.
 331     */
 332     virtual void ClearTools();
 333
 334     /**
 335         Removes the specified tool from the toolbar and deletes it. If you don't
 336         want to delete the tool, but just to remove it from the toolbar (to
 337         possibly add it back later), you may use RemoveTool() instead.
 338
 339         @note It is unnecessary to call Realize() for the change to take
 340             place, it will happen immediately.
 341
 342         @returns @true if the tool was deleted, @false otherwise.
 343
 344         @see DeleteToolByPos()
 345     */
 346     virtual bool DeleteTool(int toolId);
 347
 348     /**
 349         This function behaves like DeleteTool() but it deletes the tool at the
 350         specified position and not the one with the given id.
 351     */
 352     virtual bool DeleteToolByPos(size_t pos);
 353
 354     /**
 355         Enables or disables the tool.
 356
 357         @param toolId
 358             Tool to enable or disable.
 359         @param enable
 360             If @true, enables the tool, otherwise disables it.
 361
 362         @remarks Some implementations will change the visible state of the tool
 363             to indicate that it is disabled.
 364
 365
 366         @see GetToolEnabled(), ToggleTool()
 367     */
 368     virtual void EnableTool(int toolId, bool enable);
 369
 370     /**
 371         Returns a pointer to the tool identified by @a id or @NULL if no
 372         corresponding tool is found.
 373     */
 374     wxToolBarToolBase* FindById(int id) const;
 375
 376     /**
 377         Returns a pointer to the control identified by @a id or @NULL if no
 378         corresponding control is found.
 379     */
 380     virtual wxControl* FindControl(int id);
 381
 382     /**
 383         Finds a tool for the given mouse position.
 384
 385         @param x
 386             X position.
 387         @param y
 388             Y position.
 389
 390         @return A pointer to a tool if a tool is found, or @NULL otherwise.
 391
 392         @remarks Currently not implemented in wxGTK (always returns @NULL
 393         there).
 394     */
 395     virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;
 396
 397     /**
 398         Returns the left/right and top/bottom margins, which are also used for
 399         inter-toolspacing.
 400
 401         @see SetMargins()
 402     */
 403     wxSize GetMargins() const;
 404
 405     /**
 406         Returns the size of bitmap that the toolbar expects to have. The default
 407         bitmap size is 16 by 15 pixels.
 408
 409         @remarks Note that this is the size of the bitmap you pass to AddTool(),
 410             and not the eventual size of the tool button.
 411
 412         @see SetToolBitmapSize(), GetToolSize()
 413     */
 414     virtual wxSize GetToolBitmapSize() const;
 415
 416     /**
 417         Get any client data associated with the tool.
 418
 419         @param toolId
 420             Id of the tool, as passed to AddTool().
 421
 422         @return Client data, or @NULL if there is none.
 423     */
 424     virtual wxObject* GetToolClientData(int toolId) const;
 425
 426     /**
 427         Called to determine whether a tool is enabled (responds to user input).
 428
 429         @param toolId
 430             Id of the tool in question.
 431
 432         @return @true if the tool is enabled, @false otherwise.
 433
 434         @see EnableTool()
 435     */
 436     virtual bool GetToolEnabled(int toolId) const;
 437
 438     /**
 439         Returns the long help for the given tool.
 440
 441         @param toolId
 442             The tool in question.
 443
 444         @see SetToolLongHelp(), SetToolShortHelp()
 445     */
 446     virtual wxString GetToolLongHelp(int toolId) const;
 447
 448     /**
 449         Returns the value used for packing tools.
 450
 451         @see SetToolPacking()
 452     */
 453     virtual int GetToolPacking() const;
 454
 455     /**
 456         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
 457         is not found.
 458     */
 459     virtual int GetToolPos(int toolId) const;
 460
 461     /**
 462         Returns the default separator size.
 463
 464         @see SetToolSeparation()
 465     */
 466     virtual int GetToolSeparation() const;
 467
 468     /**
 469         Returns the short help for the given tool.
 470
 471         @param toolId
 472             The tool in question.
 473
 474         @see GetToolLongHelp(), SetToolShortHelp()
 475     */
 476     virtual wxString GetToolShortHelp(int toolId) const;
 477
 478     /**
 479         Returns the size of a whole button, which is usually larger than a tool
 480         bitmap because of added 3D effects.
 481
 482         @see SetToolBitmapSize(), GetToolBitmapSize()
 483     */
 484     virtual wxSize GetToolSize() const;
 485
 486     /**
 487         Gets the on/off state of a toggle tool.
 488
 489         @param toolId
 490             The tool in question.
 491
 492         @return @true if the tool is toggled on, @false otherwise.
 493
 494         @see ToggleTool()
 495     */
 496     virtual bool GetToolState(int toolId) const;
 497
 498     /**
 499         Returns the number of tools in the toolbar.
 500     */
 501     size_t GetToolsCount() const;
 502
 503     /**
 504         Inserts the control into the toolbar at the given position. You must
 505         call Realize() for the change to take place.
 506
 507         @see AddControl(), InsertTool()
 508     */
 509     virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control,
 510                                              const wxString& label = wxEmptyString);
 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     virtual 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 = wxEmptyString,
 535                                   const wxString& longHelpString = wxEmptyString);
 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     virtual 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     virtual 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     virtual void OnRightClick(int toolId, long x, long y);
 598
 599     /**
 600         This function should be called after you have added tools.
 601     */
 602     virtual 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     virtual 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     /**
 634         Set the values to be used as margins for the toolbar.
 635
 636         @param x
 637             Left margin, right margin and inter-tool separation value.
 638         @param y
 639             Top margin, bottom margin and inter-tool separation value.
 640
 641         @remarks This must be called before the tools are added if absolute
 642             positioning is to be used, and the default (zero-size) margins are
 643             to be overridden.
 644
 645         @see GetMargins()
 646     */
 647     virtual void SetMargins(int x, int y);
 648
 649     /**
 650         Set the margins for the toolbar.
 651
 652         @param size
 653             Margin size.
 654
 655         @remarks This must be called before the tools are added if absolute
 656             positioning is to be used, and the default (zero-size) margins are
 657             to be overridden.
 658
 659         @see GetMargins(), wxSize
 660     */
 661     void SetMargins(const wxSize& size);
 662     //@}
 663
 664     /**
 665         Sets the default size of each tool bitmap. The default bitmap size is 16
 666         by 15 pixels.
 667
 668         @param size
 669             The size of the bitmaps in the toolbar.
 670
 671         @remarks This should be called to tell the toolbar what the tool bitmap
 672             size is. Call it before you add tools.
 673
 674         @see GetToolBitmapSize(), GetToolSize()
 675     */
 676     virtual void SetToolBitmapSize(const wxSize& size);
 677
 678     /**
 679         Sets the client data associated with the tool.
 680     */
 681     virtual void SetToolClientData(int id, wxObject* clientData);
 682
 683     /**
 684         Sets the bitmap to be used by the tool with the given ID when the tool
 685         is in a disabled state. This can only be used on Button tools, not
 686         controls.
 687
 688         @note The native toolbar classes on the main platforms all synthesize
 689             the disabled bitmap from the normal bitmap, so this function will
 690             have no effect on those platforms.
 691
 692     */
 693     virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
 694
 695     /**
 696         Sets the long help for the given tool.
 697
 698         @param toolId
 699             The tool in question.
 700         @param helpString
 701             A string for the long help.
 702
 703         @remarks You might use the long help for displaying the tool purpose on
 704             the status line.
 705
 706         @see GetToolLongHelp(), SetToolShortHelp(),
 707     */
 708     virtual void SetToolLongHelp(int toolId, const wxString& helpString);
 709
 710     /**
 711         Sets the bitmap to be used by the tool with the given ID. This can only
 712         be used on Button tools, not controls.
 713     */
 714     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 715
 716     /**
 717         Sets the value used for spacing tools. The default value is 1.
 718
 719         @param packing
 720             The value for packing.
 721
 722         @remarks The packing is used for spacing in the vertical direction if
 723             the toolbar is horizontal, and for spacing in the horizontal
 724             direction if the toolbar is vertical.
 725
 726         @see GetToolPacking()
 727     */
 728     virtual void SetToolPacking(int packing);
 729
 730     /**
 731         Sets the default separator size. The default value is 5.
 732
 733         @param separation
 734             The separator size.
 735
 736         @see AddSeparator()
 737     */
 738     virtual void SetToolSeparation(int separation);
 739
 740     /**
 741         Sets the short help for the given tool.
 742
 743         @param toolId
 744             The tool in question.
 745         @param helpString
 746             The string for the short help.
 747
 748         @remarks An application might use short help for identifying the tool
 749             purpose in a tooltip.
 750
 751
 752         @see GetToolShortHelp(), SetToolLongHelp()
 753     */
 754     virtual void SetToolShortHelp(int toolId, const wxString& helpString);
 755
 756     /**
 757         Toggles a tool on or off. This does not cause any event to get emitted.
 758
 759         @param toolId
 760             Tool in question.
 761         @param toggle
 762             If @true, toggles the tool on, otherwise toggles it off.
 763
 764         @remarks Only applies to a tool that has been specified as a toggle
 765             tool.
 766     */
 767     virtual void ToggleTool(int toolId, bool toggle);
 768 };
 769