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