interface/wx/toolbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        toolbar.h
   3 // Purpose:     interface of wxToolBar
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 enum wxToolBarToolStyle
   9 {
  10     wxTOOL_STYLE_BUTTON    = 1,
  11     wxTOOL_STYLE_SEPARATOR = 2,
  12     wxTOOL_STYLE_CONTROL
  13 };
  14
  15
  16 /** wxToolBar style flags */
  17 enum
  18 {
  19     /** lay out the toolbar horizontally */
  20     wxTB_HORIZONTAL  = wxHORIZONTAL,
  21     wxTB_TOP         = wxTB_HORIZONTAL,
  22
  23     /** lay out the toolbar vertically */
  24     wxTB_VERTICAL    = wxVERTICAL,
  25     wxTB_LEFT        = wxTB_VERTICAL,
  26
  27     /** show 3D buttons (wxToolBarSimple only) */
  28     wxTB_3DBUTTONS,
  29
  30     /** "flat" buttons (Win32/GTK only) */
  31     wxTB_FLAT,
  32
  33     /** dockable toolbar (GTK only) */
  34     wxTB_DOCKABLE,
  35
  36     /** don't show the icons (they're shown by default) */
  37     wxTB_NOICONS,
  38
  39     /** show the text (not shown by default) */
  40     wxTB_TEXT,
  41
  42     /** don't show the divider between toolbar and the window (Win32 only) */
  43     wxTB_NODIVIDER,
  44
  45     /** no automatic alignment (Win32 only, useless) */
  46     wxTB_NOALIGN,
  47
  48     /** show the text and the icons alongside, not vertically stacked (Win32/GTK) */
  49     wxTB_HORZ_LAYOUT,
  50     wxTB_HORZ_TEXT   = wxTB_HORZ_LAYOUT | wxTB_TEXT,
  51
  52     /** don't show the toolbar short help tooltips */
  53     wxTB_NO_TOOLTIPS,
  54
  55     /** lay out toolbar at the bottom of the window */
  56     wxTB_BOTTOM,
  57
  58     /** lay out toolbar at the right edge of the window */
  59     wxTB_RIGHT,
  60
  61     /** flags that are closest to the native look*/
  62     wxTB_DEFAULT_STYLE = wxTB_HORIZONTAL | wxTB_FLAT
  63 };
  64
  65
  66
  67 /**
  68     @class wxToolBarToolBase
  69
  70     A toolbar tool represents one item on the toolbar.
  71
  72     It has a unique id (except for the separators), the style (telling whether
  73     it is a normal button, separator or a control), the state (toggled or not,
  74     enabled or not) and short and long help strings. The default
  75     implementations use the short help string for the tooltip text which is
  76     popped up when the mouse pointer enters the tool and the long help string
  77     for the applications status bar.
  78 */
  79 class wxToolBarToolBase : public wxObject
  80 {
  81 public:
  82     wxToolBarToolBase(wxToolBarBase *tbar = NULL,
  83                       int toolid = wxID_SEPARATOR,
  84                       const wxString& label = wxEmptyString,
  85                       const wxBitmap& bmpNormal = wxNullBitmap,
  86                       const wxBitmap& bmpDisabled = wxNullBitmap,
  87                       wxItemKind kind = wxITEM_NORMAL,
  88                       wxObject *clientData = NULL,
  89                       const wxString& shortHelpString = wxEmptyString,
  90                       const wxString& longHelpString = wxEmptyString);
  91
  92     wxToolBarToolBase(wxToolBarBase *tbar,
  93                       wxControl *control,
  94                       const wxString& label);
  95
  96     virtual ~wxToolBarToolBase();
  97
  98     int GetId() const;
  99
 100     wxControl *GetControl() const;
 101     wxToolBarBase *GetToolBar() const;
 102
 103     bool IsStretchable() const;
 104     bool IsButton() const;
 105     bool IsControl() const;
 106     bool IsSeparator() const;
 107     bool IsStretchableSpace() const;
 108     int GetStyle() const;
 109     wxItemKind GetKind() const;
 110     void MakeStretchable();
 111
 112     bool IsEnabled() const;
 113     bool IsToggled() const;
 114     bool CanBeToggled() const;
 115
 116     const wxBitmap& GetNormalBitmap() const;
 117     const wxBitmap& GetDisabledBitmap() const;
 118
 119     const wxBitmap& GetBitmap() const;
 120     const wxString& GetLabel() const;
 121
 122     const wxString& GetShortHelp() const;
 123     const wxString& GetLongHelp() const;
 124
 125     wxObject *GetClientData() const;
 126
 127     virtual bool Enable(bool enable);
 128     virtual bool Toggle(bool toggle);
 129     virtual bool SetToggle(bool toggle);
 130     virtual bool SetShortHelp(const wxString& help);
 131     virtual bool SetLongHelp(const wxString& help);
 132     void Toggle();
 133     virtual void SetNormalBitmap(const wxBitmap& bmp);
 134     virtual void SetDisabledBitmap(const wxBitmap& bmp);
 135     virtual void SetLabel(const wxString& label);
 136     void SetClientData(wxObject *clientData);
 137
 138     virtual void Detach();
 139     virtual void Attach(wxToolBarBase *tbar);
 140
 141     virtual void SetDropdownMenu(wxMenu *menu);
 142     wxMenu *GetDropdownMenu() const;
 143 };
 144
 145
 146
 147
 148 /**
 149     @class wxToolBar
 150
 151     A toolbar is a bar of buttons and/or other controls usually placed below
 152     the menu bar in a wxFrame.
 153
 154     You may create a toolbar that is managed by a frame calling
 155     wxFrame::CreateToolBar(). Under Pocket PC, you should always use this
 156     function for creating the toolbar to be managed by the frame, so that
 157     wxWidgets can use a combined menubar and toolbar. Where you manage your
 158     own toolbars, create wxToolBar as usual.
 159
 160     There are several different types of tools you can add to a toolbar.
 161     These types are controlled by the ::wxItemKind enumeration.
 162
 163     Note that many methods in wxToolBar such as wxToolBar::AddTool return a
 164     @c wxToolBarToolBase* object.
 165     This should be regarded as an opaque handle representing the newly added
 166     toolbar item, providing access to its id and position within the toolbar.
 167     Changes to the item's state should be made through calls to wxToolBar methods,
 168     for example wxToolBar::EnableTool.
 169     Calls to @c wxToolBarToolBase methods (undocumented by purpose) will not change
 170     the visible state of the item within the tool bar.
 171
 172     <b>wxMSW note</b>: Note that under wxMSW toolbar paints tools to reflect
 173     system-wide colours. If you use more than 16 colours in your tool bitmaps,
 174     you may wish to suppress this behaviour, otherwise system colours in your
 175     bitmaps will inadvertently be mapped to system colours.
 176     To do this, set the msw.remap system option before creating the toolbar:
 177     @code
 178     wxSystemOptions::SetOption("msw.remap", 0);
 179     @endcode
 180     If you wish to use 32-bit images (which include an alpha channel for
 181     transparency) use:
 182     @code
 183     wxSystemOptions::SetOption("msw.remap", 2);
 184     @endcode
 185     Then colour remapping is switched off, and a transparent background
 186     used. But only use this option under Windows XP with true colour:
 187     @code
 188     if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32)
 189     @endcode
 190
 191     @beginStyleTable
 192     @style{wxTB_FLAT}
 193         Gives the toolbar a flat look (Windows and GTK only).
 194     @style{wxTB_DOCKABLE}
 195         Makes the toolbar floatable and dockable (GTK only).
 196     @style{wxTB_HORIZONTAL}
 197         Specifies horizontal layout (default).
 198     @style{wxTB_VERTICAL}
 199         Specifies vertical layout.
 200     @style{wxTB_TEXT}
 201         Shows the text in the toolbar buttons; by default only icons are shown.
 202     @style{wxTB_NOICONS}
 203         Specifies no icons in the toolbar buttons; by default they are shown.
 204     @style{wxTB_NODIVIDER}
 205         Specifies no divider (border) above the toolbar (Windows only)
 206     @style{wxTB_NOALIGN}
 207         Specifies no alignment with the parent window (Windows only, not very
 208         useful).
 209     @style{wxTB_HORZ_LAYOUT}
 210         Shows the text and the icons alongside, not vertically stacked (Windows
 211         and GTK 2 only). This style must be used with @c wxTB_TEXT.
 212     @style{wxTB_HORZ_TEXT}
 213         Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT.
 214     @style{wxTB_NO_TOOLTIPS}
 215         Don't show the short help tooltips for the tools when the mouse hovers
 216         over them.
 217     @style{wxTB_BOTTOM}
 218         Align the toolbar at the bottom of parent window.
 219     @style{wxTB_RIGHT}
 220         Align the toolbar at the right side of parent window.
 221     @style{wxTB_DEFAULT_STYLE}
 222         Combination of @c wxTB_HORIZONTAL and @c wxTB_FLAT. This style is new
 223         since wxWidgets 2.9.5.
 224     @endStyleTable
 225
 226     See also @ref overview_windowstyles. Note that the wxMSW native toolbar
 227     ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only
 228     if the style was initially on.
 229
 230     @beginEventEmissionTable{wxCommandEvent}
 231     @event{EVT_TOOL(id, func)}
 232         Process a @c wxEVT_TOOL event (a synonym for @c
 233         wxEVT_MENU). Pass the id of the tool.
 234     @event{EVT_MENU(id, func)}
 235         The same as EVT_TOOL().
 236     @event{EVT_TOOL_RANGE(id1, id2, func)}
 237         Process a @c wxEVT_TOOL event for a range of
 238         identifiers. Pass the ids of the tools.
 239     @event{EVT_MENU_RANGE(id1, id2, func)}
 240         The same as EVT_TOOL_RANGE().
 241     @event{EVT_TOOL_RCLICKED(id, func)}
 242         Process a @c wxEVT_TOOL_RCLICKED event. Pass the id of the
 243         tool.  (Not available on wxOSX.)
 244     @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
 245         Process a @c wxEVT_TOOL_RCLICKED event for a range of ids. Pass
 246         the ids of the tools.  (Not available on wxOSX.)
 247     @event{EVT_TOOL_ENTER(id, func)}
 248         Process a @c wxEVT_TOOL_ENTER event. Pass the id of the toolbar
 249         itself. The value of wxCommandEvent::GetSelection() is the tool id, or
 250         -1 if the mouse cursor has moved off a tool.  (Not available on wxOSX.)
 251     @event{EVT_TOOL_DROPDOWN(id, func)}
 252         Process a @c wxEVT_TOOL_DROPDOWN event. If unhandled,
 253         displays the default dropdown menu set using
 254         wxToolBar::SetDropdownMenu().
 255     @endEventTable
 256
 257     The toolbar class emits menu commands in the same way that a frame menubar
 258     does, so you can use one EVT_MENU() macro for both a menu item and a toolbar
 259     button. The event handler functions take a wxCommandEvent argument. For most
 260     event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER()
 261     the toolbar window identifier is passed and the tool identifier is retrieved
 262     from the wxCommandEvent. This is because the identifier may be @c wxID_ANY when the
 263     mouse moves off a tool, and @c wxID_ANY is not allowed as an identifier in the event
 264     system.
 265
 266     @library{wxcore}
 267     @category{miscwnd}
 268
 269     @see @ref overview_toolbar
 270 */
 271 class wxToolBar : public wxControl
 272 {
 273 public:
 274     /**
 275         Default constructor.
 276     */
 277     wxToolBar();
 278
 279     /**
 280         Constructs a toolbar.
 281
 282         @param parent
 283             Pointer to a parent window.
 284         @param id
 285             Window identifier. If -1, will automatically create an identifier.
 286         @param pos
 287             Window position. ::wxDefaultPosition indicates that wxWidgets should
 288             generate a default position for the window.
 289             If using the wxWindow class directly, supply an actual position.
 290         @param size
 291             Window size. ::wxDefaultSize indicates that wxWidgets should generate
 292             a default size for the window.
 293         @param style
 294             Window style. See wxToolBar initial description for details.
 295         @param name
 296             Window name.
 297
 298         @remarks After a toolbar is created, you use AddTool() and perhaps
 299                  AddSeparator(), and then you must call Realize() to construct
 300                  and display the toolbar tools.
 301     */
 302     wxToolBar(wxWindow* parent, wxWindowID id,
 303               const wxPoint& pos = wxDefaultPosition,
 304               const wxSize& size = wxDefaultSize,
 305               long style = wxTB_HORIZONTAL,
 306               const wxString& name = wxToolBarNameStr);
 307
 308     /**
 309         Toolbar destructor.
 310     */
 311     virtual ~wxToolBar();
 312
 313     /**
 314         Adds a new check (or toggle) tool to the toolbar. The parameters are the
 315         same as in AddTool().
 316
 317         @see AddTool()
 318     */
 319     wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label,
 320                                     const wxBitmap& bitmap1,
 321                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 322                                     const wxString& shortHelp = wxEmptyString,
 323                                     const wxString& longHelp = wxEmptyString,
 324                                     wxObject* clientData = NULL);
 325
 326     /**
 327         Adds any control to the toolbar, typically e.g.\ a wxComboBox.
 328
 329         @param control
 330             The control to be added.
 331         @param label
 332             Text to be displayed near the control.
 333
 334         @remarks
 335             wxMSW: the label is only displayed if there is enough space
 336             available below the embedded control.
 337
 338         @remarks
 339             wxMac: labels are only displayed if wxWidgets is built with @c
 340             wxMAC_USE_NATIVE_TOOLBAR set to 1
 341     */
 342     virtual wxToolBarToolBase* AddControl(wxControl* control,
 343                                           const wxString& label = wxEmptyString);
 344
 345     /**
 346         Adds a new radio tool to the toolbar. Consecutive radio tools form a
 347         radio group such that exactly one button in the group is pressed at any
 348         moment, in other words whenever a button in the group is pressed the
 349         previously pressed button is automatically released. You should avoid
 350         having the radio groups of only one element as it would be impossible
 351         for the user to use such button.
 352
 353         By default, the first button in the radio group is initially pressed,
 354         the others are not.
 355
 356
 357         @see AddTool()
 358     */
 359     wxToolBarToolBase* AddRadioTool(int toolId, const wxString& label,
 360                                     const wxBitmap& bitmap1,
 361                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 362                                     const wxString& shortHelp = wxEmptyString,
 363                                     const wxString& longHelp = wxEmptyString,
 364                                     wxObject* clientData = NULL);
 365
 366     /**
 367         Adds a separator for spacing groups of tools.
 368
 369         Notice that the separator uses the look appropriate for the current
 370         platform so it can be a vertical line (MSW, some versions of GTK) or
 371         just an empty space or something else.
 372
 373         @see AddTool(), SetToolSeparation(), AddStretchableSpace()
 374     */
 375     virtual wxToolBarToolBase* AddSeparator();
 376
 377     /**
 378         Adds a stretchable space to the toolbar.
 379
 380         Any space not taken up by the fixed items (all items except for
 381         stretchable spaces) is distributed in equal measure between the
 382         stretchable spaces in the toolbar. The most common use for this method
 383         is to add a single stretchable space before the items which should be
 384         right-aligned in the toolbar, but more exotic possibilities are
 385         possible, e.g. a stretchable space may be added in the beginning and
 386         the end of the toolbar to centre all toolbar items.
 387
 388         @see AddTool(), AddSeparator(), InsertStretchableSpace()
 389
 390         @since 2.9.1
 391      */
 392     wxToolBarToolBase *AddStretchableSpace();
 393
 394     //@{
 395     /**
 396         Adds a tool to the toolbar.
 397
 398         @param tool
 399             The tool to be added.
 400
 401         @remarks After you have added tools to a toolbar, you must call
 402                  Realize() in order to have the tools appear.
 403
 404         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 405              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 406     */
 407     virtual wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
 408
 409     /**
 410         Adds a tool to the toolbar. This most commonly used version has fewer
 411         parameters than the full version below which specifies the more rarely
 412         used button features.
 413
 414         @param toolId
 415             An integer by which the tool may be identified in subsequent
 416             operations.
 417         @param label
 418             The string to be displayed with the tool.
 419         @param bitmap
 420             The primary tool bitmap.
 421         @param shortHelp
 422             This string is used for the tools tooltip.
 423         @param kind
 424             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 425             for a checkable tool (such tool stays pressed after it had been
 426             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 427             a radio group of tools each of which is automatically unchecked
 428             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 429             specifies that a drop-down menu button will appear next to the
 430             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 431
 432         @remarks After you have added tools to a toolbar, you must call
 433             Realize() in order to have the tools appear.
 434
 435         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 436              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 437     */
 438     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 439                                const wxBitmap& bitmap,
 440                                const wxString& shortHelp = wxEmptyString,
 441                                wxItemKind kind = wxITEM_NORMAL);
 442
 443     /**
 444         Adds a tool to the toolbar.
 445
 446         @param toolId
 447             An integer by which the tool may be identified in subsequent
 448             operations.
 449         @param label
 450             The string to be displayed with the tool.
 451         @param bitmap
 452             The primary tool bitmap.
 453         @param bmpDisabled
 454             The bitmap used when the tool is disabled. If it is equal to
 455             ::wxNullBitmap (default), the disabled bitmap is automatically
 456             generated by greying the normal one.
 457         @param kind
 458             May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK
 459             for a checkable tool (such tool stays pressed after it had been
 460             toggled) or ::wxITEM_RADIO for a checkable tool which makes part of
 461             a radio group of tools each of which is automatically unchecked
 462             whenever another button in the group is checked. ::wxITEM_DROPDOWN
 463             specifies that a drop-down menu button will appear next to the
 464             tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards.
 465         @param shortHelpString
 466             This string is used for the tools tooltip.
 467         @param longHelpString
 468             This string is shown in the statusbar (if any) of the parent frame
 469             when the mouse pointer is inside the tool.
 470         @param clientData
 471             An optional pointer to client data which can be retrieved later
 472             using GetToolClientData().
 473
 474         @remarks After you have added tools to a toolbar, you must call
 475             Realize() in order to have the tools appear.
 476
 477         @see AddSeparator(), AddCheckTool(), AddRadioTool(),
 478              InsertTool(), DeleteTool(), Realize(), SetDropdownMenu()
 479     */
 480     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 481                                const wxBitmap& bitmap,
 482                                const wxBitmap& bmpDisabled,
 483                                wxItemKind kind = wxITEM_NORMAL,
 484                                const wxString& shortHelpString = wxEmptyString,
 485                                const wxString& longHelpString = wxEmptyString,
 486                                wxObject* clientData = NULL);
 487     //@}
 488
 489     /**
 490         Deletes all the tools in the toolbar.
 491     */
 492     virtual void ClearTools();
 493
 494     /**
 495         Removes the specified tool from the toolbar and deletes it. If you don't
 496         want to delete the tool, but just to remove it from the toolbar (to
 497         possibly add it back later), you may use RemoveTool() instead.
 498
 499         @note It is unnecessary to call Realize() for the change to take
 500             place, it will happen immediately.
 501
 502         @returns @true if the tool was deleted, @false otherwise.
 503
 504         @see DeleteToolByPos()
 505     */
 506     virtual bool DeleteTool(int toolId);
 507
 508     /**
 509         This function behaves like DeleteTool() but it deletes the tool at the
 510         specified position and not the one with the given id.
 511     */
 512     virtual bool DeleteToolByPos(size_t pos);
 513
 514     /**
 515         Enables or disables the tool.
 516
 517         @param toolId
 518             ID of the tool to enable or disable, as passed to AddTool().
 519         @param enable
 520             If @true, enables the tool, otherwise disables it.
 521
 522         @remarks Some implementations will change the visible state of the tool
 523             to indicate that it is disabled.
 524
 525
 526         @see GetToolEnabled(), ToggleTool()
 527     */
 528     virtual void EnableTool(int toolId, bool enable);
 529
 530     /**
 531         Returns a pointer to the tool identified by @a id or @NULL if no
 532         corresponding tool is found.
 533     */
 534     wxToolBarToolBase* FindById(int id) const;
 535
 536     /**
 537         Returns a pointer to the control identified by @a id or @NULL if no
 538         corresponding control is found.
 539     */
 540     virtual wxControl* FindControl(int id);
 541
 542     /**
 543         Finds a tool for the given mouse position.
 544
 545         @param x
 546             X position.
 547         @param y
 548             Y position.
 549
 550         @return A pointer to a tool if a tool is found, or @NULL otherwise.
 551
 552         @remarks Currently not implemented in wxGTK (always returns @NULL
 553         there).
 554     */
 555     virtual wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const;
 556
 557     /**
 558         Returns the left/right and top/bottom margins, which are also used for
 559         inter-toolspacing.
 560
 561         @see SetMargins()
 562     */
 563     wxSize GetMargins() const;
 564
 565     /**
 566         Returns the size of bitmap that the toolbar expects to have.
 567
 568         The default bitmap size is platform-dependent: for example, it is 16*15
 569         for MSW and 24*24 for GTK. This size does @em not necessarily indicate
 570         the best size to use for the toolbars on the given platform, for this
 571         you should use @c wxArtProvider::GetNativeSizeHint(wxART_TOOLBAR) but
 572         in any case, as the bitmap size is deduced automatically from the size
 573         of the bitmaps associated with the tools added to the toolbar, it is
 574         usually unnecessary to call SetToolBitmapSize() explicitly.
 575
 576         @remarks Note that this is the size of the bitmap you pass to AddTool(),
 577             and not the eventual size of the tool button.
 578
 579         @see SetToolBitmapSize(), GetToolSize()
 580     */
 581     virtual wxSize GetToolBitmapSize() const;
 582
 583     /**
 584         Returns a pointer to the tool at ordinal position @a pos.
 585
 586         Don't confuse this with FindToolForPosition().
 587
 588         @since 2.9.1
 589
 590         @see GetToolsCount()
 591     */
 592     const wxToolBarToolBase *GetToolByPos(int pos) const;
 593
 594     /**
 595         Get any client data associated with the tool.
 596
 597         @param toolId
 598             ID of the tool in question, as passed to AddTool().
 599
 600         @return Client data, or @NULL if there is none.
 601     */
 602     virtual wxObject* GetToolClientData(int toolId) const;
 603
 604     /**
 605         Called to determine whether a tool is enabled (responds to user input).
 606
 607         @param toolId
 608             ID of the tool in question, as passed to AddTool().
 609
 610         @return @true if the tool is enabled, @false otherwise.
 611
 612         @see EnableTool()
 613     */
 614     virtual bool GetToolEnabled(int toolId) const;
 615
 616     /**
 617         Returns the long help for the given tool.
 618
 619         @param toolId
 620             ID of the tool in question, as passed to AddTool().
 621
 622         @see SetToolLongHelp(), SetToolShortHelp()
 623     */
 624     virtual wxString GetToolLongHelp(int toolId) const;
 625
 626     /**
 627         Returns the value used for packing tools.
 628
 629         @see SetToolPacking()
 630     */
 631     virtual int GetToolPacking() const;
 632
 633     /**
 634         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
 635         is not found.
 636
 637         @param toolId
 638             ID of the tool in question, as passed to AddTool().
 639     */
 640     virtual int GetToolPos(int toolId) const;
 641
 642     /**
 643         Returns the default separator size.
 644
 645         @see SetToolSeparation()
 646     */
 647     virtual int GetToolSeparation() const;
 648
 649     /**
 650         Returns the short help for the given tool.
 651
 652         @param toolId
 653             ID of the tool in question, as passed to AddTool().
 654
 655         @see GetToolLongHelp(), SetToolShortHelp()
 656     */
 657     virtual wxString GetToolShortHelp(int toolId) const;
 658
 659     /**
 660         Returns the size of a whole button, which is usually larger than a tool
 661         bitmap because of added 3D effects.
 662
 663         @see SetToolBitmapSize(), GetToolBitmapSize()
 664     */
 665     virtual wxSize GetToolSize() const;
 666
 667     /**
 668         Gets the on/off state of a toggle tool.
 669
 670         @param toolId
 671             ID of the tool in question, as passed to AddTool().
 672
 673         @return @true if the tool is toggled on, @false otherwise.
 674
 675         @see ToggleTool()
 676     */
 677     virtual bool GetToolState(int toolId) const;
 678
 679     /**
 680         Returns the number of tools in the toolbar.
 681     */
 682     size_t GetToolsCount() const;
 683
 684     /**
 685         Inserts the control into the toolbar at the given position. You must
 686         call Realize() for the change to take place.
 687
 688         @see AddControl(), InsertTool()
 689     */
 690     virtual wxToolBarToolBase* InsertControl(size_t pos, wxControl* control,
 691                                              const wxString& label = wxEmptyString);
 692
 693     /**
 694         Inserts the separator into the toolbar at the given position. You must
 695         call Realize() for the change to take place.
 696
 697         @see AddSeparator(), InsertTool()
 698     */
 699     virtual wxToolBarToolBase* InsertSeparator(size_t pos);
 700
 701     /**
 702         Inserts a stretchable space at the given position.
 703
 704         See AddStretchableSpace() for details about stretchable spaces.
 705
 706         @see InsertTool(), InsertSeparator()
 707
 708         @since 2.9.1
 709      */
 710     wxToolBarToolBase *InsertStretchableSpace(size_t pos);
 711
 712     //@{
 713     /**
 714         Inserts the tool with the specified attributes into the toolbar at the
 715         given position.
 716
 717         You must call Realize() for the change to take place.
 718
 719         @see AddTool(), InsertControl(), InsertSeparator()
 720
 721         @return The newly inserted tool or @NULL on failure. Notice that with
 722             the overload taking @a tool parameter the caller is responsible for
 723             deleting the tool in the latter case.
 724     */
 725     wxToolBarToolBase* InsertTool(  size_t pos,
 726                                     int toolId,
 727                                     const wxString& label,
 728                                     const wxBitmap& bitmap,
 729                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 730                                     wxItemKind kind = wxITEM_NORMAL,
 731                                     const wxString& shortHelp = wxEmptyString,
 732                                     const wxString& longHelp = wxEmptyString,
 733                                     wxObject *clientData = NULL);
 734
 735     wxToolBarToolBase* InsertTool(size_t pos,
 736                                   wxToolBarToolBase* tool);
 737     //@}
 738
 739     /**
 740         Called when the user clicks on a tool with the left mouse button. This
 741         is the old way of detecting tool clicks; although it will still work,
 742         you should use the EVT_MENU() or EVT_TOOL() macro instead.
 743
 744         @param toolId
 745             The identifier passed to AddTool().
 746         @param toggleDown
 747             @true if the tool is a toggle and the toggle is down, otherwise is
 748             @false.
 749
 750         @return If the tool is a toggle and this function returns @false, the
 751                 toggle state (internal and visual) will not be changed. This
 752                 provides a way of specifying that toggle operations are not
 753                 permitted in some circumstances.
 754
 755         @see OnMouseEnter(), OnRightClick()
 756     */
 757     virtual bool OnLeftClick(int toolId, bool toggleDown);
 758
 759     /**
 760         This is called when the mouse cursor moves into a tool or out of the
 761         toolbar. This is the old way of detecting mouse enter events;
 762         although it will still work, you should use the EVT_TOOL_ENTER()
 763         macro instead.
 764
 765         @param toolId
 766             Greater than -1 if the mouse cursor has moved into the tool, or -1
 767             if the mouse cursor has moved. The programmer can override this to
 768             provide extra information about the tool, such as a short
 769             description on the status line.
 770
 771         @remarks With some derived toolbar classes, if the mouse moves quickly
 772                  out of the toolbar, wxWidgets may not be able to detect it.
 773                  Therefore this function may not always be called when expected.
 774     */
 775     virtual void OnMouseEnter(int toolId);
 776
 777     /**
 778         @deprecated This is the old way of detecting tool right clicks;
 779                     although it will still work, you should use the
 780                     EVT_TOOL_RCLICKED() macro instead.
 781
 782         Called when the user clicks on a tool with the right mouse button. The
 783         programmer should override this function to detect right tool clicks.
 784
 785         @param toolId
 786             The identifier passed to AddTool().
 787         @param x
 788             The x position of the mouse cursor.
 789         @param y
 790             The y position of the mouse cursor.
 791
 792         @remarks A typical use of this member might be to pop up a menu.
 793
 794         @see OnMouseEnter(), OnLeftClick()
 795     */
 796     virtual void OnRightClick(int toolId, long x, long y);
 797
 798     /**
 799         This function should be called after you have added tools.
 800     */
 801     virtual bool Realize();
 802
 803     /**
 804         Removes the given tool from the toolbar but doesn't delete it. This
 805         allows to insert/add this tool back to this (or another) toolbar later.
 806
 807         @note It is unnecessary to call Realize() for the change to take place,
 808             it will happen immediately.
 809
 810
 811         @see DeleteTool()
 812     */
 813     virtual wxToolBarToolBase* RemoveTool(int id);
 814
 815     /**
 816         Sets the bitmap resource identifier for specifying tool bitmaps as
 817         indices into a custom bitmap.
 818
 819         This is a Windows CE-specific method not available in the other ports.
 820
 821         @onlyfor{wxmsw_wince}
 822     */
 823     void SetBitmapResource(int resourceId);
 824
 825     /**
 826         Sets the dropdown menu for the tool given by its @e id. The tool itself
 827         will delete the menu when it's no longer needed. Only supported under
 828         GTK+ und MSW.
 829
 830         If you define a EVT_TOOL_DROPDOWN() handler in your program, you must
 831         call wxEvent::Skip() from it or the menu won't be displayed.
 832     */
 833     bool SetDropdownMenu(int id, wxMenu* menu);
 834
 835     //@{
 836     /**
 837         Set the values to be used as margins for the toolbar.
 838
 839         @param x
 840             Left margin, right margin and inter-tool separation value.
 841         @param y
 842             Top margin, bottom margin and inter-tool separation value.
 843
 844         @remarks This must be called before the tools are added if absolute
 845             positioning is to be used, and the default (zero-size) margins are
 846             to be overridden.
 847
 848         @see GetMargins()
 849     */
 850     virtual void SetMargins(int x, int y);
 851
 852     /**
 853         Set the margins for the toolbar.
 854
 855         @param size
 856             Margin size.
 857
 858         @remarks This must be called before the tools are added if absolute
 859             positioning is to be used, and the default (zero-size) margins are
 860             to be overridden.
 861
 862         @see GetMargins(), wxSize
 863     */
 864     void SetMargins(const wxSize& size);
 865     //@}
 866
 867     /**
 868         Sets the default size of each tool bitmap. The default bitmap size is 16
 869         by 15 pixels.
 870
 871         @param size
 872             The size of the bitmaps in the toolbar.
 873
 874         @remarks This should be called to tell the toolbar what the tool bitmap
 875             size is. Call it before you add tools.
 876
 877         @see GetToolBitmapSize(), GetToolSize()
 878     */
 879     virtual void SetToolBitmapSize(const wxSize& size);
 880
 881     /**
 882         Sets the client data associated with the tool.
 883
 884         @param id
 885             ID of the tool in question, as passed to AddTool().
 886     */
 887     virtual void SetToolClientData(int id, wxObject* clientData);
 888
 889     /**
 890         Sets the bitmap to be used by the tool with the given ID when the tool
 891         is in a disabled state. This can only be used on Button tools, not
 892         controls.
 893
 894         @param id
 895             ID of the tool in question, as passed to AddTool().
 896
 897         @note The native toolbar classes on the main platforms all synthesize
 898             the disabled bitmap from the normal bitmap, so this function will
 899             have no effect on those platforms.
 900
 901     */
 902     virtual void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
 903
 904     /**
 905         Sets the long help for the given tool.
 906
 907         @param toolId
 908             ID of the tool in question, as passed to AddTool().
 909         @param helpString
 910             A string for the long help.
 911
 912         @remarks You might use the long help for displaying the tool purpose on
 913             the status line.
 914
 915         @see GetToolLongHelp(), SetToolShortHelp(),
 916     */
 917     virtual void SetToolLongHelp(int toolId, const wxString& helpString);
 918
 919     /**
 920         Sets the bitmap to be used by the tool with the given ID. This can only
 921         be used on Button tools, not controls.
 922
 923         @param id
 924             ID of the tool in question, as passed to AddTool().
 925     */
 926     virtual void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 927
 928     /**
 929         Sets the value used for spacing tools. The default value is 1.
 930
 931         @param packing
 932             The value for packing.
 933
 934         @remarks The packing is used for spacing in the vertical direction if
 935             the toolbar is horizontal, and for spacing in the horizontal
 936             direction if the toolbar is vertical.
 937
 938         @see GetToolPacking()
 939     */
 940     virtual void SetToolPacking(int packing);
 941
 942     /**
 943         Sets the default separator size. The default value is 5.
 944
 945         @param separation
 946             The separator size.
 947
 948         @see AddSeparator()
 949     */
 950     virtual void SetToolSeparation(int separation);
 951
 952     /**
 953         Sets the short help for the given tool.
 954
 955         @param toolId
 956             ID of the tool in question, as passed to AddTool().
 957         @param helpString
 958             The string for the short help.
 959
 960         @remarks An application might use short help for identifying the tool
 961             purpose in a tooltip.
 962
 963
 964         @see GetToolShortHelp(), SetToolLongHelp()
 965     */
 966     virtual void SetToolShortHelp(int toolId, const wxString& helpString);
 967
 968     /**
 969         Toggles a tool on or off. This does not cause any event to get emitted.
 970
 971         @param toolId
 972             ID of the tool in question, as passed to AddTool().
 973         @param toggle
 974             If @true, toggles the tool on, otherwise toggles it off.
 975
 976         @remarks Only applies to a tool that has been specified as a toggle
 977             tool.
 978     */
 979     virtual void ToggleTool(int toolId, bool toggle);
 980
 981
 982     /**
 983        Factory function to create a new toolbar tool.
 984     */
 985     virtual wxToolBarToolBase *CreateTool(int toolId,
 986                                           const wxString& label,
 987                                           const wxBitmap& bmpNormal,
 988                                           const wxBitmap& bmpDisabled = wxNullBitmap,
 989                                           wxItemKind kind = wxITEM_NORMAL,
 990                                           wxObject *clientData = NULL,
 991                                           const wxString& shortHelp = wxEmptyString,
 992                                           const wxString& longHelp = wxEmptyString);
 993     /**
 994        Factory function to create a new control toolbar tool.
 995     */
 996     virtual wxToolBarToolBase *CreateTool(wxControl *control,
 997                                           const wxString& label);
 998
 999     /**
1000        Factory function to create a new separator toolbar tool.
1001     */
1002     wxToolBarToolBase *CreateSeparator()
1003 };
1004