interface/toolbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        toolbar.h
   3 // Purpose:     documentation for wxToolBar class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxToolBar
  11     @wxheader{toolbar.h}
  12
  13     The name wxToolBar is defined to be a synonym for one of the following classes:
  14
  15      @b wxToolBar95 The native Windows 95 toolbar. Used on Windows 95, NT 4 and
  16     above.
  17      @b wxToolBarMSW A Windows implementation. Used on 16-bit Windows.
  18      @b wxToolBarGTK The GTK toolbar.
  19
  20
  21     @beginStyleTable
  22     @style{wxTB_FLAT}:
  23            Gives the toolbar a flat look (Windows and GTK only).
  24     @style{wxTB_DOCKABLE}:
  25            Makes the toolbar floatable and dockable (GTK only).
  26     @style{wxTB_HORIZONTAL}:
  27            Specifies horizontal layout (default).
  28     @style{wxTB_VERTICAL}:
  29            Specifies vertical layout.
  30     @style{wxTB_TEXT}:
  31            Shows the text in the toolbar buttons; by default only icons are
  32            shown.
  33     @style{wxTB_NOICONS}:
  34            Specifies no icons in the toolbar buttons; by default they are
  35            shown.
  36     @style{wxTB_NODIVIDER}:
  37            Specifies no divider (border) above the toolbar (Windows only).
  38     @style{wxTB_NOALIGN}:
  39            Specifies no alignment with the parent window (Windows only, not
  40            very useful).
  41     @style{wxTB_HORZ_LAYOUT}:
  42            Shows the text and the icons alongside, not vertically stacked
  43            (Windows and GTK 2 only). This style must be used with wxTB_TEXT.
  44     @style{wxTB_HORZ_TEXT}:
  45            Combination of wxTB_HORZ_LAYOUT and wxTB_TEXT.
  46     @style{wxTB_NO_TOOLTIPS}:
  47            Don't show the short help tooltips for the tools when the mouse
  48            hovers over them.
  49     @style{wxTB_BOTTOM}:
  50            Align the toolbar at the bottom of parent window.
  51     @style{wxTB_RIGHT}:
  52            Align the toolbar at the right side of parent window.
  53     @endStyleTable
  54
  55     @library{wxbase}
  56     @category{miscwnd}
  57
  58     @seealso
  59     @ref overview_wxtoolbaroverview "Toolbar overview", wxScrolledWindow
  60 */
  61 class wxToolBar : public wxControl
  62 {
  63 public:
  64     //@{
  65     /**
  66         Constructs a toolbar.
  67
  68         @param parent
  69         Pointer to a parent window.
  70
  71         @param id
  72         Window identifier. If -1, will automatically create an identifier.
  73
  74         @param pos
  75         Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
  76         should generate a default position for the window. If using the wxWindow class
  77         directly, supply
  78         an actual position.
  79
  80         @param size
  81         Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets
  82         should generate a default size for the window.
  83
  84         @param style
  85         Window style. See wxToolBar for details.
  86
  87         @param name
  88         Window name.
  89
  90         @remarks After a toolbar is created, you use AddTool() and
  91                    perhaps AddSeparator(), and then you must
  92                    call Realize() to construct and display the
  93                    toolbar tools.
  94     */
  95     wxToolBar();
  96     wxToolBar(wxWindow* parent, wxWindowID id,
  97               const wxPoint& pos = wxDefaultPosition,
  98               const wxSize& size = wxDefaultSize,
  99               long style = wxTB_HORIZONTAL |  wxBORDER_NONE,
 100               const wxString& name = wxPanelNameStr);
 101     //@}
 102
 103     /**
 104         Toolbar destructor.
 105     */
 106     ~wxToolBar();
 107
 108     /**
 109         Adds a new check (or toggle) tool to the toolbar. The parameters are the same
 110         as in AddTool().
 111
 112         @sa AddTool()
 113     */
 114     wxToolBarToolBase* AddCheckTool(int toolId,
 115                                     const wxString& label,
 116                                     const wxBitmap& bitmap1,
 117                                     const wxBitmap& bitmap2,
 118                                     const wxString& shortHelpString = "",
 119                                     const wxString& longHelpString = "",
 120                                     wxObject* clientData = @NULL);
 121
 122     /**
 123         Adds any control to the toolbar, typically e.g. a combobox.
 124
 125         @param control
 126         The control to be added.
 127
 128         @param label
 129         Text to be displayed near the control.
 130
 131         @remarks wxMSW: the label is only displayed if there is enough space
 132                    available below the embedded control.
 133     */
 134     bool AddControl(wxControl* control, const wxString label = "");
 135
 136     /**
 137         Adds a new radio tool to the toolbar. Consecutive radio tools form a radio
 138         group such that exactly one button in the group is pressed at any moment, in
 139         other words whenever a button in the group is pressed the previously pressed
 140         button is automatically released. You should avoid having the radio groups of
 141         only one element as it would be impossible for the user to use such button.
 142
 143         By default, the first button in the radio group is initially pressed, the
 144         others are not.
 145
 146         @sa AddTool()
 147     */
 148     wxToolBarToolBase* AddRadioTool(int toolId,
 149                                     const wxString& label,
 150                                     const wxBitmap& bitmap1,
 151                                     const wxBitmap& bitmap2,
 152                                     const wxString& shortHelpString = "",
 153                                     const wxString& longHelpString = "",
 154                                     wxObject* clientData = @NULL);
 155
 156     /**
 157         Adds a separator for spacing groups of tools.
 158
 159         @sa AddTool(), SetToolSeparation()
 160     */
 161     void AddSeparator();
 162
 163     //@{
 164     /**
 165         Adds a tool to the toolbar. The first (short and most commonly used) version
 166         has fewer parameters than the full version at the price of not being able to
 167         specify some of the more rarely used button features. The last version allows
 168         you to add an existing tool.
 169
 170         @param toolId
 171         An integer by which
 172         the tool may be identified in subsequent operations.
 173
 174         @param kind
 175         May be wxITEM_NORMAL for a normal button (default),
 176         wxITEM_CHECK for a checkable tool (such tool stays pressed after it had been
 177         toggled) or wxITEM_RADIO for a checkable tool which makes part of a radio
 178         group of tools each of which is automatically unchecked whenever another button
 179         in the group is checked
 180
 181         @param bitmap1
 182         The primary tool bitmap.
 183
 184         @param bitmap2
 185         The bitmap used when the tool is disabled. If it is equal to
 186         wxNullBitmap, the disabled bitmap is automatically generated by greing the
 187         normal one.
 188
 189         @param shortHelpString
 190         This string is used for the tools tooltip
 191
 192         @param longHelpString
 193         This string is shown in the statusbar (if any) of the
 194         parent frame when the mouse pointer is inside the tool
 195
 196         @param clientData
 197         An optional pointer to client data which can be
 198         retrieved later using GetToolClientData().
 199
 200         @param tool
 201         The tool to be added.
 202
 203         @remarks After you have added tools to a toolbar, you must call
 204                    Realize() in order to have the tools appear.
 205
 206         @sa AddSeparator(), AddCheckTool(), AddRadioTool(),
 207               InsertTool(), DeleteTool(), Realize()
 208     */
 209     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 210                                const wxBitmap& bitmap1,
 211                                const wxString& shortHelpString = "",
 212                                wxItemKind kind = wxITEM_NORMAL);
 213     wxToolBarToolBase* AddTool(int toolId, const wxString& label,
 214                                const wxBitmap& bitmap1,
 215                                const wxBitmap& bitmap2 = wxNullBitmap,
 216                                wxItemKind kind = wxITEM_NORMAL,
 217                                const wxString& shortHelpString = "",
 218                                const wxString& longHelpString = "",
 219                                wxObject* clientData = @NULL);
 220     wxToolBarToolBase* AddTool(wxToolBarToolBase* tool);
 221     //@}
 222
 223     /**
 224         Deletes all the tools in the toolbar.
 225     */
 226     void ClearTools();
 227
 228     /**
 229         Removes the specified tool from the toolbar and deletes it. If you don't want
 230         to delete the tool, but just to remove it from the toolbar (to possibly add it
 231         back later), you may use RemoveTool() instead.
 232
 233         Note that it is unnecessary to call Realize() for the
 234         change to take place, it will happen immediately.
 235
 236         Returns @true if the tool was deleted, @false otherwise.
 237
 238         @sa DeleteToolByPos()
 239     */
 240     bool DeleteTool(int toolId);
 241
 242     /**
 243         This function behaves like DeleteTool() but it
 244         deletes the tool at the specified position and not the one with the given id.
 245     */
 246     bool DeleteToolByPos(size_t pos);
 247
 248     /**
 249         Enables or disables the tool.
 250
 251         @param toolId
 252         Tool to enable or disable.
 253
 254         @param enable
 255         If @true, enables the tool, otherwise disables it.
 256
 257         @remarks Some implementations will change the visible state of the tool
 258                    to indicate that it is disabled.
 259
 260         @sa GetToolEnabled(), ToggleTool()
 261     */
 262     void EnableTool(int toolId, bool enable);
 263
 264     /**
 265         Returns a pointer to the tool identified by @e id or
 266         @NULL if no corresponding tool is found.
 267     */
 268     wxToolBarToolBase* FindById(int id);
 269
 270     /**
 271         Returns a pointer to the control identified by @e id or
 272         @NULL if no corresponding control is found.
 273     */
 274     wxControl* FindControl(int id);
 275
 276     /**
 277         Finds a tool for the given mouse position.
 278
 279         @param x
 280         X position.
 281
 282         @param y
 283         Y position.
 284
 285         @returns A pointer to a tool if a tool is found, or @NULL otherwise.
 286
 287         @remarks Currently not implemented in wxGTK (always returns @NULL there).
 288     */
 289     wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y);
 290
 291     /**
 292         Returns the left/right and top/bottom margins, which are also used for
 293         inter-toolspacing.
 294
 295         @sa SetMargins()
 296     */
 297     wxSize GetMargins();
 298
 299     /**
 300         Returns the size of bitmap that the toolbar expects to have. The default bitmap
 301         size is 16 by 15 pixels.
 302
 303         @remarks Note that this is the size of the bitmap you pass to
 304                    AddTool(), and not the eventual size of the
 305                    tool button.
 306
 307         @sa SetToolBitmapSize(), GetToolSize()
 308     */
 309     wxSize GetToolBitmapSize();
 310
 311     /**
 312         Get any client data associated with the tool.
 313
 314         @param toolId
 315         Id of the tool, as passed to AddTool().
 316
 317         @returns Client data, or @NULL if there is none.
 318     */
 319     wxObject* GetToolClientData(int toolId);
 320
 321     /**
 322         Called to determine whether a tool is enabled (responds to user input).
 323
 324         @param toolId
 325         Id of the tool in question.
 326
 327         @returns @true if the tool is enabled, @false otherwise.
 328
 329         @sa EnableTool()
 330     */
 331     bool GetToolEnabled(int toolId);
 332
 333     /**
 334         Returns the long help for the given tool.
 335
 336         @param toolId
 337         The tool in question.
 338
 339         @sa SetToolLongHelp(), SetToolShortHelp()
 340     */
 341     wxString GetToolLongHelp(int toolId);
 342
 343     /**
 344         Returns the value used for packing tools.
 345
 346         @sa SetToolPacking()
 347     */
 348     int GetToolPacking();
 349
 350     /**
 351         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool is not
 352         found.
 353     */
 354     int GetToolPos(int toolId);
 355
 356     /**
 357         Returns the default separator size.
 358
 359         @sa SetToolSeparation()
 360     */
 361     int GetToolSeparation();
 362
 363     /**
 364         Returns the short help for the given tool.
 365
 366         @param toolId
 367         The tool in question.
 368
 369         @sa GetToolLongHelp(), SetToolShortHelp()
 370     */
 371     wxString GetToolShortHelp(int toolId);
 372
 373     /**
 374         Returns the size of a whole button, which is usually larger than a tool bitmap
 375         because
 376         of added 3D effects.
 377
 378         @sa SetToolBitmapSize(), GetToolBitmapSize()
 379     */
 380     wxSize GetToolSize();
 381
 382     /**
 383         Gets the on/off state of a toggle tool.
 384
 385         @param toolId
 386         The tool in question.
 387
 388         @returns @true if the tool is toggled on, @false otherwise.
 389
 390         @sa ToggleTool()
 391     */
 392     bool GetToolState(int toolId);
 393
 394     /**
 395         Returns the number of tools in the toolbar.
 396     */
 397     int GetToolsCount();
 398
 399     /**
 400         Inserts the control into the toolbar at the given position.
 401
 402         You must call Realize() for the change to take place.
 403
 404         @sa AddControl(), InsertTool()
 405     */
 406     wxToolBarToolBase * InsertControl(size_t pos,
 407                                       wxControl * control);
 408
 409     /**
 410         Inserts the separator into the toolbar at the given position.
 411
 412         You must call Realize() for the change to take place.
 413
 414         @sa AddSeparator(), InsertTool()
 415     */
 416     wxToolBarToolBase * InsertSeparator(size_t pos);
 417
 418     //@{
 419     /**
 420         Inserts the tool with the specified attributes into the toolbar at the given
 421         position.
 422
 423         You must call Realize() for the change to take place.
 424
 425         @sa AddTool(), InsertControl(), InsertSeparator()
 426     */
 427     wxToolBarToolBase * InsertTool(size_t pos, int toolId,
 428                                    const wxBitmap& bitmap1,
 429                                    const wxBitmap& bitmap2 = wxNullBitmap,
 430                                    bool isToggle = @false,
 431                                    wxObject* clientData = @NULL,
 432                                    const wxString& shortHelpString = "",
 433                                    const wxString& longHelpString = "");
 434     wxToolBarToolBase * InsertTool(size_t pos,
 435                                    wxToolBarToolBase* tool);
 436     //@}
 437
 438     /**
 439         Called when the user clicks on a tool with the left mouse button.
 440
 441         This is the old way of detecting tool clicks; although it will still work,
 442         you should use the EVT_MENU or EVT_TOOL macro instead.
 443
 444         @param toolId
 445         The identifier passed to AddTool().
 446
 447         @param toggleDown
 448         @true if the tool is a toggle and the toggle is down, otherwise is @false.
 449
 450         @returns If the tool is a toggle and this function returns @false, the
 451                    toggle toggle state (internal and visual) will not be
 452                    changed. This provides a way of specifying that
 453                    toggle operations are not permitted in some
 454                    circumstances.
 455
 456         @sa OnMouseEnter(), OnRightClick()
 457     */
 458     bool OnLeftClick(int toolId, bool toggleDown);
 459
 460     /**
 461         This is called when the mouse cursor moves into a tool or out of
 462         the toolbar.
 463
 464         This is the old way of detecting mouse enter events; although it will still
 465         work,
 466         you should use the EVT_TOOL_ENTER macro instead.
 467
 468         @param toolId
 469         Greater than -1 if the mouse cursor has moved into the tool,
 470         or -1 if the mouse cursor has moved. The
 471         programmer can override this to provide extra information about the tool,
 472         such as a short description on the status line.
 473
 474         @remarks With some derived toolbar classes, if the mouse moves quickly
 475                    out of the toolbar, wxWidgets may not be able to
 476                    detect it. Therefore this function may not always be
 477                    called when expected.
 478     */
 479     void OnMouseEnter(int toolId);
 480
 481     /**
 482         Called when the user clicks on a tool with the right mouse button. The
 483         programmer should override this function to detect right tool clicks.
 484
 485         This is the old way of detecting tool right clicks; although it will still work,
 486         you should use the EVT_TOOL_RCLICKED macro instead.
 487
 488         @param toolId
 489         The identifier passed to AddTool().
 490
 491         @param x
 492         The x position of the mouse cursor.
 493
 494         @param y
 495         The y position of the mouse cursor.
 496
 497         @remarks A typical use of this member might be to pop up a menu.
 498
 499         @sa OnMouseEnter(), OnLeftClick()
 500     */
 501     void OnRightClick(int toolId, float x, float y);
 502
 503     /**
 504         This function should be called after you have added tools.
 505     */
 506     bool Realize();
 507
 508     /**
 509         Removes the given tool from the toolbar but doesn't delete it. This allows to
 510         insert/add this tool back to this (or another) toolbar later.
 511
 512         Note that it is unnecessary to call Realize() for the
 513         change to take place, it will happen immediately.
 514
 515         @sa DeleteTool()
 516     */
 517     wxToolBarToolBase * RemoveTool(int id);
 518
 519     /**
 520         Sets the bitmap resource identifier for specifying tool bitmaps as indices
 521         into a custom bitmap. Windows CE only.
 522     */
 523     void SetBitmapResource(int resourceId);
 524
 525     /**
 526         Sets the dropdown menu for the tool given by its @e id. The tool itself will
 527         delete the menu when it's no longer needed.
 528
 529         If you define a EVT_TOOL_DROPDOWN handler in your program, you must call
 530         wxEvent::Skip from it or the menu won't be displayed.
 531     */
 532     bool SetDropdownMenu(int id, wxMenu* menu);
 533
 534     //@{
 535     /**
 536         Set the values to be used as margins for the toolbar.
 537
 538         @param size
 539         Margin size.
 540
 541         @param x
 542         Left margin, right margin and inter-tool separation value.
 543
 544         @param y
 545         Top margin, bottom margin and inter-tool separation value.
 546
 547         @remarks This must be called before the tools are added if absolute
 548                    positioning is to be used, and the default
 549                    (zero-size) margins are to be overridden.
 550
 551         @sa GetMargins(), wxSize
 552     */
 553     void SetMargins(const wxSize& size);
 554     void SetMargins(int x, int y);
 555     //@}
 556
 557     /**
 558         Sets the default size of each tool bitmap. The default bitmap size is 16 by 15
 559         pixels.
 560
 561         @param size
 562         The size of the bitmaps in the toolbar.
 563
 564         @remarks This should be called to tell the toolbar what the tool bitmap
 565                    size is. Call it before you add tools.
 566
 567         @sa GetToolBitmapSize(), GetToolSize()
 568     */
 569     void SetToolBitmapSize(const wxSize& size);
 570
 571     /**
 572         Sets the client data associated with the tool.
 573     */
 574     void SetToolClientData(int id, wxObject* clientData);
 575
 576     /**
 577         Sets the bitmap to be used by the tool with the given ID when the tool
 578         is in a disabled state.  This can only be used on Button tools, not
 579         controls.  NOTE: The native toolbar classes on the main platforms all
 580         synthesize the disabled bitmap from the normal bitmap, so this
 581         function will have no effect on those platforms.
 582     */
 583     void SetToolDisabledBitmap(int id, const wxBitmap& bitmap);
 584
 585     /**
 586         Sets the long help for the given tool.
 587
 588         @param toolId
 589         The tool in question.
 590
 591         @param helpString
 592         A string for the long help.
 593
 594         @remarks You might use the long help for displaying the tool purpose on
 595                    the status line.
 596
 597         @sa GetToolLongHelp(), SetToolShortHelp(),
 598     */
 599     void SetToolLongHelp(int toolId, const wxString& helpString);
 600
 601     /**
 602         Sets the bitmap to be used by the tool with the given ID.  This can
 603         only be used on Button tools, not controls.
 604     */
 605     void SetToolNormalBitmap(int id, const wxBitmap& bitmap);
 606
 607     /**
 608         Sets the value used for spacing tools. The default value is 1.
 609
 610         @param packing
 611         The value for packing.
 612
 613         @remarks The packing is used for spacing in the vertical direction if the
 614                    toolbar is horizontal, and for spacing in the
 615                    horizontal direction if the toolbar is vertical.
 616
 617         @sa GetToolPacking()
 618     */
 619     void SetToolPacking(int packing);
 620
 621     /**
 622         Sets the default separator size. The default value is 5.
 623
 624         @param separation
 625         The separator size.
 626
 627         @sa AddSeparator()
 628     */
 629     void SetToolSeparation(int separation);
 630
 631     /**
 632         Sets the short help for the given tool.
 633
 634         @param toolId
 635         The tool in question.
 636
 637         @param helpString
 638         The string for the short help.
 639
 640         @remarks An application might use short help for identifying the tool
 641                    purpose in a tooltip.
 642
 643         @sa GetToolShortHelp(), SetToolLongHelp()
 644     */
 645     void SetToolShortHelp(int toolId, const wxString& helpString);
 646
 647     /**
 648         Toggles a tool on or off. This does not cause any event to get emitted.
 649
 650         @param toolId
 651         Tool in question.
 652
 653         @param toggle
 654         If @true, toggles the tool on, otherwise toggles it off.
 655
 656         @remarks Only applies to a tool that has been specified as a toggle tool.
 657     */
 658     void ToggleTool(int toolId, bool toggle);
 659 };