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