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