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