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