interface/toolbar.h

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