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