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 licence
   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 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(), AddStretchableSpace()
 232     */
 233     virtual wxToolBarToolBase* AddSeparator();
 234
 235     /**
 236         Adds a stretchable space to the toolbar.
 237
 238         Any space not taken up by the fixed items (all items except for
 239         stretchable spaces) is distributed in equal measure between the
 240         stretchable spaces in the toolbar. The most common use for this method
 241         is to add a single stretchable space before the items which should be
 242         right-aligned in the toolbar, but more exotic possibilities are
 243         possible, e.g. a stretchable space may be added in the beginning and
 244         the end of the toolbar to centre all toolbar items.
 245
 246         @see AddTool(), AddSeparator(), InsertStretchableSpace()
 247
 248         @since 2.9.1
 249      */
 250     wxToolBarToolBase *AddStretchableSpace();
 251
 252     //@{
 253     /**
 254         Adds a tool to the toolbar.
 255
 256         @param tool
 257             The tool to be added.
 258
 259         @remarks After you have added tools to a toolbar, you must call
 260                  Realize() in order to have the tools appear.
 261
 262         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 263              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 264     */
 265     virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
 266
 267     /**
 268         Adds a tool to the toolbar. This most commonly used version has fewer
 269         parameters than the full version below which specifies the more rarely
 270         used button features.
 271
 272         @param toolId
 273             An integer by which the tool may be identified in subsequent
 274             operations.
 275         @param label
 276             The string to be displayed with the tool.
 277         @param bitmap
 278             The primary tool bitmap.
 279         @param shortHelp
 280             This string is used for the tools tooltip.
 281         @param kind
 282             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 283             for a checkable tool (such tool stays pressed after it had been
 284             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 285             a radio group of tools each of which is automatically unchecked
 286             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 287             specifies that a drop-down menu button will appear next to the
 288             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 289
 290         @remarks After you have added tools to a toolbar, you must call
 291             Realize() in order to have the tools appear.
 292
 293         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 294              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 295     */
 296     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 297                                const wxBitmap& bitmap,
 298                                const wxString& shortHelp = wxEmptyString,
 299                                wxItemKind kind = wxITEM_NORMAL);
 300
 301     /**
 302         Adds a tool to the toolbar.
 303
 304         @param toolId
 305             An integer by which the tool may be identified in subsequent
 306             operations.
 307         @param label
 308             The string to be displayed with the tool.
 309         @param bitmap
 310             The primary tool bitmap.
 311         @param bmpDisabled
 312             The bitmap used when the tool is disabled. If it is equal to
 313             ::wxNullBitmap (default), the disabled bitmap is automatically
 314             generated by greying the normal one.
 315         @param kind
 316             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 317             for a checkable tool (such tool stays pressed after it had been
 318             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 319             a radio group of tools each of which is automatically unchecked
 320             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 321             specifies that a drop-down menu button will appear next to the
 322             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 323         @param shortHelpString
 324             This string is used for the tools tooltip.
 325         @param longHelpString
 326             This string is shown in the statusbar (if any) of the parent frame
 327             when the mouse pointer is inside the tool.
 328         @param clientData
 329             An optional pointer to client data which can be retrieved later
 330             using GetToolClientData().
 331
 332         @remarks After you have added tools to a toolbar, you must call
 333             Realize() in order to have the tools appear.
 334
 335         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 336              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 337     */
 338     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 339                                const wxBitmap& bitmap,
 340                                const wxBitmap& bmpDisabled = wxNullBitmap,
 341                                wxItemKind kind = wxITEM_NORMAL,
 342                                const wxString& shortHelpString = wxEmptyString,
 343                                const wxString& longHelpString = wxEmptyString,
 344                                wxObject* clientData = NULL);
 345     //@}
 346
 347     /**
 348         Deletes all the tools in the toolbar.
 349     */
 350     virtual void ClearTools();
 351
 352     /**
 353         Removes the specified tool from the toolbar and deletes it. If you don't
 354         want to delete the tool, but just to remove it from the toolbar (to
 355         possibly add it back later), you may use RemoveTool() instead.
 356
 357         @note It is unnecessary to call Realize() for the change to take
 358             place, it will happen immediately.
 359
 360         @returns @true if the tool was deleted, @false otherwise.
 361
 362         @see DeleteToolByPos()
 363     */
 364     virtual bool DeleteTool(int toolId);
 365
 366     /**
 367         This function behaves like DeleteTool() but it deletes the tool at the
 368         specified position and not the one with the given id.
 369     */
 370     virtual bool DeleteToolByPos(size_t pos);
 371
 372     /**
 373         Enables or disables the tool.
 374
 375         @param toolId
 376             ID of the tool to enable or disable, as passed to AddTool().
 377         @param enable
 378             If @true, enables the tool, otherwise disables it.
 379
 380         @remarks Some implementations will change the visible state of the tool
 381             to indicate that it is disabled.
 382
 383
 384         @see GetToolEnabled(), ToggleTool()
 385     */
 386     virtual void EnableTool(int toolId, bool enable);
 387
 388     /**
 389         Returns a pointer to the tool identified by @a id or @NULL if no
 390         corresponding tool is found.
 391     */
 392     wxToolBarToolBase* FindById(int id) const;
 393
 394     /**
 395         Returns a pointer to the control identified by @a id or @NULL if no
 396         corresponding control is found.
 397     */
 398     virtual wxControl* FindControl(int id);
 399
 400     /**
 401         Finds a tool for the given mouse position.
 402
 403         @param x
 404             X position.
 405         @param y
 406             Y position.
 407
 408         @return A pointer to a tool if a tool is found, or @NULL otherwise.
 409
 410         @remarks Currently not implemented in wxGTK (always returns @NULL
 411         there).
 412     */
 413     virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;
 414
 415     /**
 416         Returns the left/right and top/bottom margins, which are also used for
 417         inter-toolspacing.
 418
 419         @see SetMargins()
 420     */
 421     wxSize GetMargins() const;
 422
 423     /**
 424         Returns the size of bitmap that the toolbar expects to have.
 425
 426         The default bitmap size is platform-dependent: for example, it is 16*15
 427         for MSW and 24*24 for GTK. This size does @em not necessarily indicate
 428         the best size to use for the toolbars on the given platform, for this
 429         you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
 430         in any case, as the bitmap size is deduced automatically from the size
 431         of the bitmaps associated with the tools added to the toolbar, it is
 432         usually unnecessary to call SetToolBitmapSize() explicitly.
 433
 434         @remarks Note that this is the size of the bitmap you pass to AddTool(),
 435             and not the eventual size of the tool button.
 436
 437         @see SetToolBitmapSize(), GetToolSize()
 438     */
 439     virtual wxSize GetToolBitmapSize() const;
 440
 441     /**
 442         Returns a pointer to the tool at ordinal position @a pos.
 443
 444         Don't confuse this with FindToolForPosition().
 445
 446         @since 2.9.1
 447
 448         @see GetToolsCount()
 449     */
 450     const wxToolBarToolBase *GetToolByPos(int pos) const;
 451
 452     /**
 453         Get any client data associated with the tool.
 454
 455         @param toolId
 456             ID of the tool in question, as passed to AddTool().
 457
 458         @return Client data, or @NULL if there is none.
 459     */
 460     virtual wxObject* GetToolClientData(int toolId) const;
 461
 462     /**
 463         Called to determine whether a tool is enabled (responds to user input).
 464
 465         @param toolId
 466             ID of the tool in question, as passed to AddTool().
 467
 468         @return @true if the tool is enabled, @false otherwise.
 469
 470         @see EnableTool()
 471     */
 472     virtual bool GetToolEnabled(int toolId) const;
 473
 474     /**
 475         Returns the long help for the given tool.
 476
 477         @param toolId
 478             ID of the tool in question, as passed to AddTool().
 479
 480         @see SetToolLongHelp(), SetToolShortHelp()
 481     */
 482     virtual wxString GetToolLongHelp(int toolId) const;
 483
 484     /**
 485         Returns the value used for packing tools.
 486
 487         @see SetToolPacking()
 488     */
 489     virtual int GetToolPacking() const;
 490
 491     /**
 492         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
 493         is not found.
 494
 495         @param toolId
 496             ID of the tool in question, as passed to AddTool().
 497     */
 498     virtual int GetToolPos(int toolId) const;
 499
 500     /**
 501         Returns the default separator size.
 502
 503         @see SetToolSeparation()
 504     */
 505     virtual int GetToolSeparation() const;
 506
 507     /**
 508         Returns the short help for the given tool.
 509
 510         @param toolId
 511             ID of the tool in question, as passed to AddTool().
 512
 513         @see GetToolLongHelp(), SetToolShortHelp()
 514     */
 515     virtual wxString GetToolShortHelp(int toolId) const;
 516
 517     /**
 518         Returns the size of a whole button, which is usually larger than a tool
 519         bitmap because of added 3D effects.
 520
 521         @see SetToolBitmapSize(), GetToolBitmapSize()
 522     */
 523     virtual wxSize GetToolSize() const;
 524
 525     /**
 526         Gets the on/off state of a toggle tool.
 527
 528         @param toolId
 529             ID of the tool in question, as passed to AddTool().
 530
 531         @return @true if the tool is toggled on, @false otherwise.
 532
 533         @see ToggleTool()
 534     */
 535     virtual bool GetToolState(int toolId) const;
 536
 537     /**
 538         Returns the number of tools in the toolbar.
 539     */
 540     size_t GetToolsCount() const;
 541
 542     /**
 543         Inserts the control into the toolbar at the given position. You must
 544         call Realize() for the change to take place.
 545
 546         @see AddControl(), InsertTool()
 547     */
 548     virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control,
 549                                              const wxString& label = wxEmptyString);
 550
 551     /**
 552         Inserts the separator into the toolbar at the given position. You must
 553         call Realize() for the change to take place.
 554
 555         @see AddSeparator(), InsertTool()
 556     */
 557     virtual wxToolBarToolBase* InsertSeparator(size_t pos);
 558
 559     /**
 560         Inserts a stretchable space at the given position.
 561
 562         See AddStretchableSpace() for details about stretchable spaces.
 563
 564         @see InsertTool(), InsertSeparator()
 565
 566         @since 2.9.1
 567      */
 568     wxToolBarToolBase *InsertStretchableSpace(size_t pos);
 569
 570     //@{
 571     /**
 572         Inserts the tool with the specified attributes into the toolbar at the
 573         given position.
 574
 575         You must call Realize() for the change to take place.
 576
 577         @see AddTool(), InsertControl(), InsertSeparator()
 578
 579         @return The newly inserted tool or @NULL on failure. Notice that with
 580             the overload taking @a tool parameter the caller is responsible for
 581             deleting the tool in the latter case.
 582     */
 583     wxToolBarToolBase* InsertTool(size_t pos, int toolId,
 584                                   const wxBitmap& bitmap1,
 585                                   const wxBitmap& bitmap2 = wxNullBitmap,
 586                                   bool isToggle = false,
 587                                   wxObject* clientData = NULL,
 588                                   const wxString& shortHelpString = wxEmptyString,
 589                                   const wxString& longHelpString = wxEmptyString);
 590     wxToolBarToolBase* InsertTool(size_t pos,
 591                                   wxToolBarToolBase* tool);
 592     //@}
 593
 594     /**
 595         Called when the user clicks on a tool with the left mouse button. This
 596         is the old way of detecting tool clicks; although it will still work,
 597         you should use the EVT_MENU() or EVT_TOOL() macro instead.
 598
 599         @param toolId
 600             The identifier passed to AddTool().
 601         @param toggleDown
 602             @true if the tool is a toggle and the toggle is down, otherwise is
 603             @false.
 604
 605         @return If the tool is a toggle and this function returns @false, the
 606                 toggle state (internal and visual) will not be changed. This
 607                 provides a way of specifying that toggle operations are not
 608                 permitted in some circumstances.
 609
 610         @see OnMouseEnter(), OnRightClick()
 611     */
 612     virtual bool OnLeftClick(int toolId, bool toggleDown);
 613
 614     /**
 615         This is called when the mouse cursor moves into a tool or out of the
 616         toolbar. This is the old way of detecting mouse enter events;
 617         although it will still work, you should use the EVT_TOOL_ENTER()
 618         macro instead.
 619
 620         @param toolId
 621             Greater than -1 if the mouse cursor has moved into the tool, or -1
 622             if the mouse cursor has moved. The programmer can override this to
 623             provide extra information about the tool, such as a short
 624             description on the status line.
 625
 626         @remarks With some derived toolbar classes, if the mouse moves quickly
 627                  out of the toolbar, wxWidgets may not be able to detect it.
 628                  Therefore this function may not always be called when expected.
 629     */
 630     virtual void OnMouseEnter(int toolId);
 631
 632     /**
 633         @deprecated This is the old way of detecting tool right clicks;
 634                     although it will still work, you should use the
 635                     EVT_TOOL_RCLICKED() macro instead.
 636
 637         Called when the user clicks on a tool with the right mouse button. The
 638         programmer should override this function to detect right tool clicks.
 639
 640         @param toolId
 641             The identifier passed to AddTool().
 642         @param x
 643             The x position of the mouse cursor.
 644         @param y
 645             The y position of the mouse cursor.
 646
 647         @remarks A typical use of this member might be to pop up a menu.
 648
 649         @see OnMouseEnter(), OnLeftClick()
 650     */
 651     virtual void OnRightClick(int toolId, long x, long y);
 652
 653     /**
 654         This function should be called after you have added tools.
 655     */
 656     virtual bool Realize();
 657
 658     /**
 659         Removes the given tool from the toolbar but doesn't delete it. This
 660         allows to insert/add this tool back to this (or another) toolbar later.
 661
 662         @note It is unnecessary to call Realize() for the change to take place,
 663             it will happen immediately.
 664
 665
 666         @see DeleteTool()
 667     */
 668     virtual wxToolBarToolBase* RemoveTool(int id);
 669
 670     /**
 671         Sets the bitmap resource identifier for specifying tool bitmaps as
 672         indices into a custom bitmap. Windows CE only.
 673     */
 674     void SetBitmapResource(int resourceId);
 675
 676     /**
 677         Sets the dropdown menu for the tool given by its @e id. The tool itself
 678         will delete the menu when it's no longer needed. Only supported under
 679         GTK+ und MSW.
 680
 681         If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
 682         call wxEvent::Skip() from it or the menu won't be displayed.
 683     */
 684     bool SetDropdownMenu(int id, wxMenu* menu);
 685
 686     //@{
 687     /**
 688         Set the values to be used as margins for the toolbar.
 689
 690         @param x
 691             Left margin, right margin and inter-tool separation value.
 692         @param y
 693             Top margin, bottom margin and inter-tool separation value.
 694
 695         @remarks This must be called before the tools are added if absolute
 696             positioning is to be used, and the default (zero-size) margins are
 697             to be overridden.
 698
 699         @see GetMargins()
 700     */
 701     virtual void SetMargins(int x, int y);
 702
 703     /**
 704         Set the margins for the toolbar.
 705
 706         @param size
 707             Margin size.
 708
 709         @remarks This must be called before the tools are added if absolute
 710             positioning is to be used, and the default (zero-size) margins are
 711             to be overridden.
 712
 713         @see GetMargins(), wxSize
 714     */
 715     void SetMargins(const wxSize& size);
 716     //@}
 717
 718     /**
 719         Sets the default size of each tool bitmap. The default bitmap size is 16
 720         by 15 pixels.
 721
 722         @param size
 723             The size of the bitmaps in the toolbar.
 724
 725         @remarks This should be called to tell the toolbar what the tool bitmap
 726             size is. Call it before you add tools.
 727
 728         @see GetToolBitmapSize(), GetToolSize()
 729     */
 730     virtual void SetToolBitmapSize(const wxSize& size);
 731
 732     /**
 733         Sets the client data associated with the tool.
 734
 735         @param id
 736             ID of the tool in question, as passed to AddTool().
 737     */
 738     virtual void SetToolClientData(int id, wxObject* clientData);
 739
 740     /**
 741         Sets the bitmap to be used by the tool with the given ID when the tool
 742         is in a disabled state. This can only be used on Button tools, not
 743         controls.
 744
 745         @param id
 746             ID of the tool in question, as passed to AddTool().
 747
 748         @note The native toolbar classes on the main platforms all synthesize
 749             the disabled bitmap from the normal bitmap, so this function will
 750             have no effect on those platforms.
 751
 752     */
 753     virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
 754
 755     /**
 756         Sets the long help for the given tool.
 757
 758         @param toolId
 759             ID of the tool in question, as passed to AddTool().
 760         @param helpString
 761             A string for the long help.
 762
 763         @remarks You might use the long help for displaying the tool purpose on
 764             the status line.
 765
 766         @see GetToolLongHelp(), SetToolShortHelp(),
 767     */
 768     virtual void SetToolLongHelp(int toolId, const wxString& helpString);
 769
 770     /**
 771         Sets the bitmap to be used by the tool with the given ID. This can only
 772         be used on Button tools, not controls.
 773
 774         @param id
 775             ID of the tool in question, as passed to AddTool().
 776     */
 777     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 778
 779     /**
 780         Sets the value used for spacing tools. The default value is 1.
 781
 782         @param packing
 783             The value for packing.
 784
 785         @remarks The packing is used for spacing in the vertical direction if
 786             the toolbar is horizontal, and for spacing in the horizontal
 787             direction if the toolbar is vertical.
 788
 789         @see GetToolPacking()
 790     */
 791     virtual void SetToolPacking(int packing);
 792
 793     /**
 794         Sets the default separator size. The default value is 5.
 795
 796         @param separation
 797             The separator size.
 798
 799         @see AddSeparator()
 800     */
 801     virtual void SetToolSeparation(int separation);
 802
 803     /**
 804         Sets the short help for the given tool.
 805
 806         @param toolId
 807             ID of the tool in question, as passed to AddTool().
 808         @param helpString
 809             The string for the short help.
 810
 811         @remarks An application might use short help for identifying the tool
 812             purpose in a tooltip.
 813
 814
 815         @see GetToolShortHelp(), SetToolLongHelp()
 816     */
 817     virtual void SetToolShortHelp(int toolId, const wxString& helpString);
 818
 819     /**
 820         Toggles a tool on or off. This does not cause any event to get emitted.
 821
 822         @param toolId
 823             ID of the tool in question, as passed to AddTool().
 824         @param toggle
 825             If @true, toggles the tool on, otherwise toggles it off.
 826
 827         @remarks Only applies to a tool that has been specified as a toggle
 828             tool.
 829     */
 830     virtual void ToggleTool(int toolId, bool toggle);
 831 };
 832