interface/wx/aui/auibar.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/aui/toolbar.h
   3 // Purpose:     Documentation of wxAuiToolBar and related classes.
   4 // Created:     2011-01-17
   5 // RCS-ID:      $Id$
   6 // Copyright:   (c) 2011 wxWidgets development team
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     wxAuiToolBarStyle is part of the wxAUI class framework, used to define the appearance of a wxAuiToolBar.
  12
  13     See also @ref overview_aui.
  14
  15     @library{wxaui}
  16     @category{aui}
  17   */
  18 enum wxAuiToolBarStyle
  19 {
  20     /**
  21       Shows the text in the toolbar buttons; by default only icons are shown.
  22     */
  23     wxAUI_TB_TEXT          = 1 << 0,
  24
  25     /**
  26       Don't show tooltips on wxAuiToolBar items.
  27     */
  28     wxAUI_TB_NO_TOOLTIPS   = 1 << 1,
  29
  30     /**
  31       Do not auto-resize the wxAuiToolBar.
  32     */
  33     wxAUI_TB_NO_AUTORESIZE = 1 << 2,
  34
  35     /**
  36       Shows a gripper on the wxAuiToolBar.
  37     */
  38     wxAUI_TB_GRIPPER       = 1 << 3,
  39
  40     /**
  41       The wxAuiToolBar can contain overflow items.
  42     */
  43     wxAUI_TB_OVERFLOW      = 1 << 4,
  44
  45     /**
  46       Using this style forces the toolbar to be vertical and be only dockable to the left or right sides of the window whereas by default it can be horizontal or vertical and be docked anywhere.
  47     */
  48     wxAUI_TB_VERTICAL      = 1 << 5,
  49
  50     /**
  51       Shows the text and the icons alongside, not vertically stacked. This style must be used with wxAUI_TB_TEXT
  52     */
  53     wxAUI_TB_HORZ_LAYOUT   = 1 << 6,
  54
  55     /**
  56       Analogous to wxAUI_TB_VERTICAL, but forces the toolbar to be horizontal, docking to the top or bottom of the window.
  57     */
  58     wxAUI_TB_HORIZONTAL    = 1 << 7,
  59
  60     /**
  61        Shows the text alongside the icons, not vertically stacked.
  62     */
  63     wxAUI_TB_HORZ_TEXT     = (wxAUI_TB_HORZ_LAYOUT | wxAUI_TB_TEXT),
  64
  65     /**
  66       Shows the text in the toolbar buttons; by default only icons are shown.
  67     */
  68     wxAUI_ORIENTATION_MASK = (wxAUI_TB_VERTICAL | wxAUI_TB_HORIZONTAL),
  69
  70     /**
  71       By default only icons are shown.
  72     */
  73     wxAUI_TB_DEFAULT_STYLE = 0
  74
  75 };
  76
  77 /**
  78     wxAuiToolBarArtSetting
  79
  80     @library{wxaui}
  81     @category{aui}
  82 */
  83 enum wxAuiToolBarArtSetting
  84 {
  85     /**
  86       wxAuiToolBar seperator size.
  87     */
  88     wxAUI_TBART_SEPARATOR_SIZE = 0,
  89
  90     /**
  91       wxAuiToolBar gripper size.
  92     */
  93     wxAUI_TBART_GRIPPER_SIZE = 1,
  94
  95     /**
  96       Overflow button size in wxAuiToolBar.
  97     */
  98     wxAUI_TBART_OVERFLOW_SIZE = 2
  99
 100 };
 101
 102 /**
 103   wxAuiToolBarToolTextOrientation
 104
 105   @library{wxaui}
 106   @category{aui}
 107   */
 108 enum wxAuiToolBarToolTextOrientation
 109 {
 110     /**
 111       Text in wxAuiToolBar items is left aligned, currently unused/unimplemented.
 112     */
 113     wxAUI_TBTOOL_TEXT_LEFT = 0,
 114
 115     /**
 116       Text in wxAuiToolBar items is right aligned.
 117     */
 118     wxAUI_TBTOOL_TEXT_RIGHT = 1,
 119
 120     /**
 121       Text in wxAuiToolBar items is top aligned, currently unused/unimplemented.
 122     */
 123     wxAUI_TBTOOL_TEXT_TOP = 2,
 124
 125     /**
 126       Text in wxAuiToolBar items is bottom aligned.
 127     */
 128     wxAUI_TBTOOL_TEXT_BOTTOM = 3
 129
 130 };
 131
 132
 133 /**
 134     @class wxAuiToolBarEvent
 135
 136     wxAuiToolBarEvent is used for the events generated by @ref wxAuiToolBar.
 137
 138     @library{wxaui}
 139     @category{aui}
 140 */
 141 class wxAuiToolBarEvent : public wxNotifyEvent
 142 {
 143 public:
 144     /**
 145       Returns whether the drop down menu has been clicked.
 146     */
 147     bool IsDropDownClicked() const;
 148
 149     /**
 150       Returns the point where the user clicked with the mouse.
 151     */
 152     wxPoint GetClickPoint() const;
 153
 154     /**
 155       Returns the wxAuiToolBarItem rectangle bounding the mouse click point.
 156     */
 157     wxRect GetItemRect() const;
 158
 159     /**
 160       Returns the wxAuiToolBarItem identifier.
 161     */
 162     int GetToolId() const;
 163 };
 164
 165
 166 /**
 167     @class wxAuiToolBarItem
 168
 169     wxAuiToolBarItem is part of the wxAUI class framework, representing a toolbar element.
 170
 171     See also @ref wxAuiToolBar and @ref overview_aui.
 172
 173     It has a unique id (except for the separators which always have id = -1), the
 174     style (telling whether it is a normal button, separator or a control), the
 175     state (toggled or not, enabled or not) and short and long help strings. The
 176     default implementations use the short help string for the tooltip text which
 177     is popped up when the mouse pointer enters the tool and the long help string
 178     for the applications status bar (currently not implemented).
 179
 180     @library{wxaui}
 181     @category{aui}
 182 */
 183 class wxAuiToolBarItem
 184 {
 185 public:
 186
 187     /**
 188        Default Constructor
 189     */
 190     wxAuiToolBarItem();
 191
 192     /**
 193       Assigns the properties of the wxAuiToolBarItem "c" to this.
 194     */
 195     wxAuiToolBarItem(const wxAuiToolBarItem& c);
 196
 197     /**
 198        Assigns the properties of the wxAuiToolBarItem "c" to this, returning a pointer to this.
 199     */
 200     wxAuiToolBarItem& operator=(const wxAuiToolBarItem& c);
 201
 202     /**
 203       Assigns the properties of the wxAuiToolBarItem "c" to this.
 204     */
 205     void Assign(const wxAuiToolBarItem& c);
 206
 207     /**
 208       Assigns a window to the toolbar item.
 209     */
 210     void SetWindow(wxWindow* w);
 211     /**
 212       Returns the wxWindow* associated to the toolbar item.
 213     */
 214     wxWindow* GetWindow();
 215
 216     /**
 217       Sets the toolbar item identifier.
 218     */
 219     void SetId(int new_id);
 220     /**
 221       Returns the toolbar item identifier.
 222     */
 223     int GetId() const;
 224
 225     /**
 226       Sets the wxAuiToolBarItem kind.
 227     */
 228     void SetKind(int new_kind);
 229
 230     /**
 231       Returns the toolbar item kind.
 232     */
 233     int GetKind() const;
 234
 235     /**
 236
 237     */
 238     void SetState(int new_state);
 239     /**
 240
 241     */
 242     int GetState() const;
 243
 244     /**
 245
 246     */
 247     void SetSizerItem(wxSizerItem* s);
 248     /**
 249
 250     */
 251     wxSizerItem* GetSizerItem() const;
 252
 253     /**
 254
 255     */
 256     void SetLabel(const wxString& s);
 257     /**
 258
 259     */
 260     const wxString& GetLabel() const;
 261
 262     /**
 263
 264     */
 265     void SetBitmap(const wxBitmap& bmp);
 266     /**
 267
 268     */
 269     const wxBitmap& GetBitmap() const;
 270
 271     /**
 272
 273     */
 274     void SetDisabledBitmap(const wxBitmap& bmp);
 275     /**
 276
 277     */
 278     const wxBitmap& GetDisabledBitmap() const;
 279
 280     /**
 281
 282     */
 283     void SetHoverBitmap(const wxBitmap& bmp);
 284     /**
 285
 286     */
 287     const wxBitmap& GetHoverBitmap() const;
 288
 289     /**
 290
 291     */
 292     void SetShortHelp(const wxString& s);
 293     /**
 294
 295     */
 296     const wxString& GetShortHelp() const;
 297
 298     /**
 299
 300     */
 301     void SetLongHelp(const wxString& s);
 302     /**
 303
 304     */
 305     const wxString& GetLongHelp() const;
 306
 307     /**
 308
 309     */
 310     void SetMinSize(const wxSize& s);
 311     /**
 312
 313     */
 314     const wxSize& GetMinSize() const;
 315
 316     /**
 317
 318     */
 319     void SetSpacerPixels(int s);
 320     /**
 321
 322     */
 323     int GetSpacerPixels() const;
 324
 325     /**
 326
 327     */
 328     void SetProportion(int p);
 329     /**
 330
 331     */
 332     int GetProportion() const;
 333
 334     /**
 335
 336     */
 337     void SetActive(bool b);
 338     /**
 339
 340     */
 341     bool IsActive() const;
 342
 343     /**
 344         Set whether this tool has a drop down button.
 345
 346         This is only valid for wxITEM_NORMAL tools.
 347     */
 348     void SetHasDropDown(bool b);
 349     /**
 350         Returns whether the toolbar item has an associated drop down button.
 351     */
 352     bool HasDropDown() const;
 353
 354     /**
 355
 356     */
 357     void SetSticky(bool b);
 358     /**
 359
 360     */
 361     bool IsSticky() const;
 362
 363     /**
 364
 365     */
 366     void SetUserData(long l);
 367     /**
 368
 369     */
 370     long GetUserData() const;
 371
 372     /**
 373
 374     */
 375     void SetAlignment(int l);
 376     /**
 377
 378     */
 379     int GetAlignment() const;
 380 };
 381
 382 /**
 383     @class wxAuiToolBarArt
 384
 385     wxAuiToolBarArt is part of the wxAUI class framework.
 386     See also @ref wxAuiToolBar and @ref overview_aui.
 387
 388     @library{wxaui}
 389     @category{aui}
 390 */
 391 class wxAuiToolBarArt
 392 {
 393 public:
 394     wxAuiToolBarArt();
 395
 396     virtual wxAuiToolBarArt* Clone() = 0;
 397     virtual void SetFlags(unsigned int flags) = 0;
 398     virtual unsigned int GetFlags() = 0;
 399     virtual void SetFont(const wxFont& font) = 0;
 400     virtual wxFont GetFont() = 0;
 401     virtual void SetTextOrientation(int orientation) = 0;
 402     virtual int GetTextOrientation() = 0;
 403
 404     virtual void DrawBackground(
 405                          wxDC& dc,
 406                          wxWindow* wnd,
 407                          const wxRect& rect) = 0;
 408
 409     virtual void DrawLabel(
 410                          wxDC& dc,
 411                          wxWindow* wnd,
 412                          const wxAuiToolBarItem& item,
 413                          const wxRect& rect) = 0;
 414
 415     virtual void DrawButton(
 416                          wxDC& dc,
 417                          wxWindow* wnd,
 418                          const wxAuiToolBarItem& item,
 419                          const wxRect& rect) = 0;
 420
 421     virtual void DrawDropDownButton(
 422                          wxDC& dc,
 423                          wxWindow* wnd,
 424                          const wxAuiToolBarItem& item,
 425                          const wxRect& rect) = 0;
 426
 427     virtual void DrawControlLabel(
 428                          wxDC& dc,
 429                          wxWindow* wnd,
 430                          const wxAuiToolBarItem& item,
 431                          const wxRect& rect) = 0;
 432
 433     virtual void DrawSeparator(
 434                          wxDC& dc,
 435                          wxWindow* wnd,
 436                          const wxRect& rect) = 0;
 437
 438     virtual void DrawGripper(
 439                          wxDC& dc,
 440                          wxWindow* wnd,
 441                          const wxRect& rect) = 0;
 442
 443     virtual void DrawOverflowButton(
 444                          wxDC& dc,
 445                          wxWindow* wnd,
 446                          const wxRect& rect,
 447                          int state) = 0;
 448
 449     virtual wxSize GetLabelSize(
 450                          wxDC& dc,
 451                          wxWindow* wnd,
 452                          const wxAuiToolBarItem& item) = 0;
 453
 454     virtual wxSize GetToolSize(
 455                          wxDC& dc,
 456                          wxWindow* wnd,
 457                          const wxAuiToolBarItem& item) = 0;
 458
 459     virtual int GetElementSize(int element_id) = 0;
 460     virtual void SetElementSize(int element_id, int size) = 0;
 461
 462     virtual int ShowDropDown(
 463                          wxWindow* wnd,
 464                          const wxAuiToolBarItemArray& items) = 0;
 465 };
 466
 467
 468 /**
 469     @class wxAuiDefaultToolBarArt
 470
 471     wxAuiDefaultToolBarArt is part of the wxAUI class framework.
 472     See also @ref wxAuiToolBarArt , @ref wxAuiToolBar and @ref overview_aui.
 473
 474     @library{wxaui}
 475     @category{aui}
 476 */
 477 class wxAuiDefaultToolBarArt : public wxAuiToolBarArt
 478 {
 479 public:
 480     wxAuiDefaultToolBarArt();
 481     virtual ~wxAuiDefaultToolBarArt();
 482
 483     virtual wxAuiToolBarArt* Clone();
 484     virtual void SetFlags(unsigned int flags);
 485     virtual unsigned int GetFlags();
 486     virtual void SetFont(const wxFont& font);
 487     virtual wxFont GetFont();
 488     virtual void SetTextOrientation(int orientation);
 489     virtual int GetTextOrientation();
 490
 491     virtual void DrawBackground(
 492                 wxDC& dc,
 493                 wxWindow* wnd,
 494                 const wxRect& rect);
 495
 496     virtual void DrawLabel(
 497                 wxDC& dc,
 498                 wxWindow* wnd,
 499                 const wxAuiToolBarItem& item,
 500                 const wxRect& rect);
 501
 502     virtual void DrawButton(
 503                 wxDC& dc,
 504                 wxWindow* wnd,
 505                 const wxAuiToolBarItem& item,
 506                 const wxRect& rect);
 507
 508     virtual void DrawDropDownButton(
 509                 wxDC& dc,
 510                 wxWindow* wnd,
 511                 const wxAuiToolBarItem& item,
 512                 const wxRect& rect);
 513
 514     virtual void DrawControlLabel(
 515                 wxDC& dc,
 516                 wxWindow* wnd,
 517                 const wxAuiToolBarItem& item,
 518                 const wxRect& rect);
 519
 520     virtual void DrawSeparator(
 521                 wxDC& dc,
 522                 wxWindow* wnd,
 523                 const wxRect& rect);
 524
 525     virtual void DrawGripper(
 526                 wxDC& dc,
 527                 wxWindow* wnd,
 528                 const wxRect& rect);
 529
 530     virtual void DrawOverflowButton(
 531                 wxDC& dc,
 532                 wxWindow* wnd,
 533                 const wxRect& rect,
 534                 int state);
 535
 536     virtual wxSize GetLabelSize(
 537                 wxDC& dc,
 538                 wxWindow* wnd,
 539                 const wxAuiToolBarItem& item);
 540
 541     virtual wxSize GetToolSize(
 542                 wxDC& dc,
 543                 wxWindow* wnd,
 544                 const wxAuiToolBarItem& item);
 545
 546     virtual int GetElementSize(int element);
 547     virtual void SetElementSize(int element_id, int size);
 548
 549     virtual int ShowDropDown(wxWindow* wnd,
 550                              const wxAuiToolBarItemArray& items);
 551 };
 552
 553
 554
 555 /**
 556     @class wxAuiToolBar
 557
 558     wxAuiToolBar is a dockable toolbar, part of the wxAUI class framework.
 559     See also @ref overview_aui.
 560
 561     @beginStyleTable
 562     @style{wxAUI_TB_TEXT}
 563     @style{wxAUI_TB_NO_TOOLTIPS}
 564     @style{wxAUI_TB_NO_AUTORESIZE}
 565     @style{wxAUI_TB_GRIPPER}
 566     @style{wxAUI_TB_OVERFLOW}
 567     @style{wxAUI_TB_VERTICAL}
 568         using this style forces the toolbar to be vertical and
 569         be only dockable to the left or right sides of the window
 570         whereas by default it can be horizontal or vertical and
 571         be docked anywhere
 572     @style{wxAUI_TB_HORZ_LAYOUT}
 573     @style{wxAUI_TB_HORIZONTAL}
 574         analogous to wxAUI_TB_VERTICAL, but forces the toolbar
 575         to be horizontal
 576     @style{wxAUI_TB_HORZ_TEXT}
 577         Equivalent to wxAUI_TB_HORZ_LAYOUT | wxAUI_TB_TEXT
 578     @style{wxAUI_TB_DEFAULT_STYLE}
 579         The default is to have no styles
 580     @endStyleTable
 581
 582     @beginEventEmissionTable{wxAuiToolBarEvent}
 583     @event{EVT_AUITOOLBAR_TOOL_DROPDOWN(id, func)}
 584         Process a wxEVT_COMMAND_AUITOOLBAR_TOOL_DROPDOWN event
 585     @event{EVT_AUITOOLBAR_OVERFLOW_CLICK(id, func)}
 586         Process a wxEVT_COMMAND_AUITOOLBAR_OVERFLOW_CLICK event
 587     @event{EVT_AUITOOLBAR_RIGHT_CLICK(id, func)}
 588         Process a wxEVT_COMMAND_AUITOOLBAR_RIGHT_CLICK event
 589     @event{EVT_AUITOOLBAR_MIDDLE_CLICK(id, func)}
 590         Process a wxEVT_COMMAND_AUITOOLBAR_MIDDLE_CLICK event
 591     @event{EVT_AUITOOLBAR_BEGIN_DRAG(id, func)}
 592         Process a wxEVT_COMMAND_AUITOOLBAR_BEGIN_DRAG event
 593     @endEventTable
 594
 595     @library{wxaui}
 596     @category{aui}
 597 */
 598 class wxAuiToolBar : public wxControl
 599 {
 600 public:
 601     /**
 602         Default constructor, use Create() later.
 603
 604         @since 2.9.5
 605      */
 606     wxAuiToolBar();
 607
 608     /**
 609         Constructor creating and initializing the object.
 610      */
 611     wxAuiToolBar(wxWindow* parent,
 612                  wxWindowID id = wxID_ANY,
 613                  const wxPoint& position = wxDefaultPosition,
 614                  const wxSize& size = wxDefaultSize,
 615                  long style = wxAUI_TB_DEFAULT_STYLE);
 616
 617     /**
 618         Really create wxAuiToolBar created using default constructor.
 619
 620         @since 2.9.5
 621      */
 622     bool Create(wxWindow* parent,
 623                 wxWindowID id = wxID_ANY,
 624                 const wxPoint& pos = wxDefaultPosition,
 625                 const wxSize& size = wxDefaultSize,
 626                 long style = wxAUI_TB_DEFAULT_STYLE);
 627     virtual ~wxAuiToolBar();
 628
 629     void SetWindowStyleFlag(long style);
 630     long GetWindowStyleFlag() const;
 631
 632     void SetArtProvider(wxAuiToolBarArt* art);
 633     wxAuiToolBarArt* GetArtProvider() const;
 634
 635     bool SetFont(const wxFont& font);
 636
 637
 638     wxAuiToolBarItem* AddTool(int tool_id,
 639                  const wxString& label,
 640                  const wxBitmap& bitmap,
 641                  const wxString& short_help_string = wxEmptyString,
 642                  wxItemKind kind = wxITEM_NORMAL);
 643
 644     wxAuiToolBarItem* AddTool(int tool_id,
 645                  const wxString& label,
 646                  const wxBitmap& bitmap,
 647                  const wxBitmap& disabled_bitmap,
 648                  wxItemKind kind,
 649                  const wxString& short_help_string,
 650                  const wxString& long_help_string,
 651                  wxObject* client_data);
 652
 653     wxAuiToolBarItem* AddTool(int tool_id,
 654                  const wxBitmap& bitmap,
 655                  const wxBitmap& disabled_bitmap,
 656                  bool toggle = false,
 657                  wxObject* client_data = NULL,
 658                  const wxString& short_help_string = wxEmptyString,
 659                  const wxString& long_help_string = wxEmptyString);
 660
 661     wxAuiToolBarItem* AddLabel(int tool_id,
 662                   const wxString& label = wxEmptyString,
 663                   const int width = -1);
 664     wxAuiToolBarItem* AddControl(wxControl* control,
 665                     const wxString& label = wxEmptyString);
 666     wxAuiToolBarItem* AddSeparator();
 667     wxAuiToolBarItem* AddSpacer(int pixels);
 668     wxAuiToolBarItem* AddStretchSpacer(int proportion = 1);
 669
 670     bool Realize();
 671
 672     wxControl* FindControl(int window_id);
 673     wxAuiToolBarItem* FindToolByPosition(wxCoord x, wxCoord y) const;
 674     wxAuiToolBarItem* FindToolByIndex(int idx) const;
 675     wxAuiToolBarItem* FindTool(int tool_id) const;
 676
 677     void ClearTools();
 678     void Clear();
 679     bool DeleteTool(int tool_id);
 680     bool DeleteByIndex(int tool_id);
 681
 682     size_t GetToolCount() const;
 683     int GetToolPos(int tool_id) const;
 684     int GetToolIndex(int tool_id) const;
 685     bool GetToolFits(int tool_id) const;
 686     wxRect GetToolRect(int tool_id) const;
 687     bool GetToolFitsByIndex(int tool_id) const;
 688     bool GetToolBarFits() const;
 689
 690     void SetMargins(const wxSize& size);
 691     void SetMargins(int x, int y);
 692     void SetMargins(int left, int right, int top, int bottom);
 693
 694     void SetToolBitmapSize(const wxSize& size);
 695     wxSize GetToolBitmapSize() const;
 696
 697     bool GetOverflowVisible() const;
 698     void SetOverflowVisible(bool visible);
 699
 700     bool GetGripperVisible() const;
 701     void SetGripperVisible(bool visible);
 702
 703     void ToggleTool(int tool_id, bool state);
 704     bool GetToolToggled(int tool_id) const;
 705
 706     void EnableTool(int tool_id, bool state);
 707     bool GetToolEnabled(int tool_id) const;
 708
 709     /**
 710         Set whether the specified toolbar item has a drop down button.
 711
 712         This is only valid for wxITEM_NORMAL tools.
 713
 714         @see wxAuiToolBarItem::SetHasDropDown()
 715     */
 716     void SetToolDropDown(int tool_id, bool dropdown);
 717
 718     /**
 719         Returns whether the specified toolbar item has an associated drop down
 720         button.
 721
 722         @see wxAuiToolBarItem::HasDropDown()
 723     */
 724     bool GetToolDropDown(int tool_id) const;
 725
 726     void SetToolBorderPadding(int padding);
 727     int  GetToolBorderPadding() const;
 728
 729     void SetToolTextOrientation(int orientation);
 730     int  GetToolTextOrientation() const;
 731
 732     void SetToolPacking(int packing);
 733     int  GetToolPacking() const;
 734
 735     void SetToolProportion(int tool_id, int proportion);
 736     int  GetToolProportion(int tool_id) const;
 737
 738     void SetToolSeparation(int separation);
 739     int GetToolSeparation() const;
 740
 741     void SetToolSticky(int tool_id, bool sticky);
 742     bool GetToolSticky(int tool_id) const;
 743
 744     wxString GetToolLabel(int tool_id) const;
 745     void SetToolLabel(int tool_id, const wxString& label);
 746
 747     wxBitmap GetToolBitmap(int tool_id) const;
 748     void SetToolBitmap(int tool_id, const wxBitmap& bitmap);
 749
 750     wxString GetToolShortHelp(int tool_id) const;
 751     void SetToolShortHelp(int tool_id, const wxString& help_string);
 752
 753     wxString GetToolLongHelp(int tool_id) const;
 754     void SetToolLongHelp(int tool_id, const wxString& help_string);
 755
 756     void SetCustomOverflowItems(const wxAuiToolBarItemArray& prepend,
 757                                 const wxAuiToolBarItemArray& append);
 758
 759     /** get size of hint rectangle for a particular dock location */
 760     wxSize GetHintSize(int dock_direction) const;
 761     bool IsPaneValid(const wxAuiPaneInfo& pane) const;
 762 };
 763