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
 345     */
 346     void SetHasDropDown(bool b);
 347     /**
 348
 349     */
 350     bool HasDropDown() const;
 351
 352     /**
 353
 354     */
 355     void SetSticky(bool b);
 356     /**
 357
 358     */
 359     bool IsSticky() const;
 360
 361     /**
 362
 363     */
 364     void SetUserData(long l);
 365     /**
 366
 367     */
 368     long GetUserData() const;
 369
 370     /**
 371
 372     */
 373     void SetAlignment(int l);
 374     /**
 375
 376     */
 377     int GetAlignment() const;
 378 };
 379
 380 /**
 381     @class wxAuiToolBarArt
 382
 383     wxAuiToolBarArt is part of the wxAUI class framework.
 384     See also @ref wxAuiToolBar and @ref overview_aui.
 385
 386     @library{wxaui}
 387     @category{aui}
 388 */
 389 class wxAuiToolBarArt
 390 {
 391 public:
 392     wxAuiToolBarArt();
 393
 394     virtual wxAuiToolBarArt* Clone() = 0;
 395     virtual void SetFlags(unsigned int flags) = 0;
 396     virtual unsigned int GetFlags() = 0;
 397     virtual void SetFont(const wxFont& font) = 0;
 398     virtual wxFont GetFont() = 0;
 399     virtual void SetTextOrientation(int orientation) = 0;
 400     virtual int GetTextOrientation() = 0;
 401
 402     virtual void DrawBackground(
 403                          wxDC& dc,
 404                          wxWindow* wnd,
 405                          const wxRect& rect) = 0;
 406
 407     virtual void DrawLabel(
 408                          wxDC& dc,
 409                          wxWindow* wnd,
 410                          const wxAuiToolBarItem& item,
 411                          const wxRect& rect) = 0;
 412
 413     virtual void DrawButton(
 414                          wxDC& dc,
 415                          wxWindow* wnd,
 416                          const wxAuiToolBarItem& item,
 417                          const wxRect& rect) = 0;
 418
 419     virtual void DrawDropDownButton(
 420                          wxDC& dc,
 421                          wxWindow* wnd,
 422                          const wxAuiToolBarItem& item,
 423                          const wxRect& rect) = 0;
 424
 425     virtual void DrawControlLabel(
 426                          wxDC& dc,
 427                          wxWindow* wnd,
 428                          const wxAuiToolBarItem& item,
 429                          const wxRect& rect) = 0;
 430
 431     virtual void DrawSeparator(
 432                          wxDC& dc,
 433                          wxWindow* wnd,
 434                          const wxRect& rect) = 0;
 435
 436     virtual void DrawGripper(
 437                          wxDC& dc,
 438                          wxWindow* wnd,
 439                          const wxRect& rect) = 0;
 440
 441     virtual void DrawOverflowButton(
 442                          wxDC& dc,
 443                          wxWindow* wnd,
 444                          const wxRect& rect,
 445                          int state) = 0;
 446
 447     virtual wxSize GetLabelSize(
 448                          wxDC& dc,
 449                          wxWindow* wnd,
 450                          const wxAuiToolBarItem& item) = 0;
 451
 452     virtual wxSize GetToolSize(
 453                          wxDC& dc,
 454                          wxWindow* wnd,
 455                          const wxAuiToolBarItem& item) = 0;
 456
 457     virtual int GetElementSize(int element_id) = 0;
 458     virtual void SetElementSize(int element_id, int size) = 0;
 459
 460     virtual int ShowDropDown(
 461                          wxWindow* wnd,
 462                          const wxAuiToolBarItemArray& items) = 0;
 463 };
 464
 465
 466 /**
 467     @class wxAuiDefaultToolBarArt
 468
 469     wxAuiDefaultToolBarArt is part of the wxAUI class framework.
 470     See also @ref wxAuiToolBarArt , @ref wxAuiToolBar and @ref overview_aui.
 471
 472     @library{wxaui}
 473     @category{aui}
 474 */
 475 class wxAuiDefaultToolBarArt : public wxAuiToolBarArt
 476 {
 477 public:
 478     wxAuiDefaultToolBarArt();
 479     virtual ~wxAuiDefaultToolBarArt();
 480
 481     virtual wxAuiToolBarArt* Clone();
 482     virtual void SetFlags(unsigned int flags);
 483     virtual unsigned int GetFlags();
 484     virtual void SetFont(const wxFont& font);
 485     virtual wxFont GetFont();
 486     virtual void SetTextOrientation(int orientation);
 487     virtual int GetTextOrientation();
 488
 489     virtual void DrawBackground(
 490                 wxDC& dc,
 491                 wxWindow* wnd,
 492                 const wxRect& rect);
 493
 494     virtual void DrawLabel(
 495                 wxDC& dc,
 496                 wxWindow* wnd,
 497                 const wxAuiToolBarItem& item,
 498                 const wxRect& rect);
 499
 500     virtual void DrawButton(
 501                 wxDC& dc,
 502                 wxWindow* wnd,
 503                 const wxAuiToolBarItem& item,
 504                 const wxRect& rect);
 505
 506     virtual void DrawDropDownButton(
 507                 wxDC& dc,
 508                 wxWindow* wnd,
 509                 const wxAuiToolBarItem& item,
 510                 const wxRect& rect);
 511
 512     virtual void DrawControlLabel(
 513                 wxDC& dc,
 514                 wxWindow* wnd,
 515                 const wxAuiToolBarItem& item,
 516                 const wxRect& rect);
 517
 518     virtual void DrawSeparator(
 519                 wxDC& dc,
 520                 wxWindow* wnd,
 521                 const wxRect& rect);
 522
 523     virtual void DrawGripper(
 524                 wxDC& dc,
 525                 wxWindow* wnd,
 526                 const wxRect& rect);
 527
 528     virtual void DrawOverflowButton(
 529                 wxDC& dc,
 530                 wxWindow* wnd,
 531                 const wxRect& rect,
 532                 int state);
 533
 534     virtual wxSize GetLabelSize(
 535                 wxDC& dc,
 536                 wxWindow* wnd,
 537                 const wxAuiToolBarItem& item);
 538
 539     virtual wxSize GetToolSize(
 540                 wxDC& dc,
 541                 wxWindow* wnd,
 542                 const wxAuiToolBarItem& item);
 543
 544     virtual int GetElementSize(int element);
 545     virtual void SetElementSize(int element_id, int size);
 546
 547     virtual int ShowDropDown(wxWindow* wnd,
 548                              const wxAuiToolBarItemArray& items);
 549 };
 550
 551
 552
 553 /**
 554     @class wxAuiToolBar
 555
 556     wxAuiToolBar is a dockable toolbar, part of the wxAUI class framework.
 557     See also @ref overview_aui.
 558
 559     @beginStyleTable
 560     @style{wxAUI_TB_TEXT}
 561     @style{wxAUI_TB_NO_TOOLTIPS}
 562     @style{wxAUI_TB_NO_AUTORESIZE}
 563     @style{wxAUI_TB_GRIPPER}
 564     @style{wxAUI_TB_OVERFLOW}
 565     @style{wxAUI_TB_VERTICAL}
 566         using this style forces the toolbar to be vertical and
 567         be only dockable to the left or right sides of the window
 568         whereas by default it can be horizontal or vertical and
 569         be docked anywhere
 570     @style{wxAUI_TB_HORZ_LAYOUT}
 571     @style{wxAUI_TB_HORIZONTAL}
 572         analogous to wxAUI_TB_VERTICAL, but forces the toolbar
 573         to be horizontal
 574     @style{wxAUI_TB_HORZ_TEXT}
 575         Equivalent to wxAUI_TB_HORZ_LAYOUT | wxAUI_TB_TEXT
 576     @style{wxAUI_TB_DEFAULT_STYLE}
 577         The default is to have no styles
 578     @endStyleTable
 579
 580     @beginEventEmissionTable{wxAuiToolBarEvent}
 581     @event{EVT_AUITOOLBAR_TOOL_DROPDOWN(id, func)}
 582         Process a wxEVT_COMMAND_AUITOOLBAR_TOOL_DROPDOWN event
 583     @event{EVT_AUITOOLBAR_OVERFLOW_CLICK(id, func)}
 584         Process a wxEVT_COMMAND_AUITOOLBAR_OVERFLOW_CLICK event
 585     @event{EVT_AUITOOLBAR_RIGHT_CLICK(id, func)}
 586         Process a wxEVT_COMMAND_AUITOOLBAR_RIGHT_CLICK event
 587     @event{EVT_AUITOOLBAR_MIDDLE_CLICK(id, func)}
 588         Process a wxEVT_COMMAND_AUITOOLBAR_MIDDLE_CLICK event
 589     @event{EVT_AUITOOLBAR_BEGIN_DRAG(id, func)}
 590         Process a wxEVT_COMMAND_AUITOOLBAR_BEGIN_DRAG event
 591     @endEventTable
 592
 593     @library{wxaui}
 594     @category{aui}
 595 */
 596 class wxAuiToolBar : public wxControl
 597 {
 598 public:
 599     /**
 600         Default constructor, use Create() later.
 601
 602         @since 2.9.5
 603      */
 604     wxAuiToolBar();
 605
 606     /**
 607         Constructor creating and initializing the object.
 608      */
 609     wxAuiToolBar(wxWindow* parent,
 610                  wxWindowID id = wxID_ANY,
 611                  const wxPoint& position = wxDefaultPosition,
 612                  const wxSize& size = wxDefaultSize,
 613                  long style = wxAUI_TB_DEFAULT_STYLE);
 614
 615     /**
 616         Really create wxAuiToolBar created using default constructor.
 617
 618         @since 2.9.5
 619      */
 620     bool Create(wxWindow* parent,
 621                 wxWindowID id = wxID_ANY,
 622                 const wxPoint& pos = wxDefaultPosition,
 623                 const wxSize& size = wxDefaultSize,
 624                 long style = wxAUI_TB_DEFAULT_STYLE);
 625     virtual ~wxAuiToolBar();
 626
 627     void SetWindowStyleFlag(long style);
 628     long GetWindowStyleFlag() const;
 629
 630     void SetArtProvider(wxAuiToolBarArt* art);
 631     wxAuiToolBarArt* GetArtProvider() const;
 632
 633     bool SetFont(const wxFont& font);
 634
 635
 636     wxAuiToolBarItem* AddTool(int tool_id,
 637                  const wxString& label,
 638                  const wxBitmap& bitmap,
 639                  const wxString& short_help_string = wxEmptyString,
 640                  wxItemKind kind = wxITEM_NORMAL);
 641
 642     wxAuiToolBarItem* AddTool(int tool_id,
 643                  const wxString& label,
 644                  const wxBitmap& bitmap,
 645                  const wxBitmap& disabled_bitmap,
 646                  wxItemKind kind,
 647                  const wxString& short_help_string,
 648                  const wxString& long_help_string,
 649                  wxObject* client_data);
 650
 651     wxAuiToolBarItem* AddTool(int tool_id,
 652                  const wxBitmap& bitmap,
 653                  const wxBitmap& disabled_bitmap,
 654                  bool toggle = false,
 655                  wxObject* client_data = NULL,
 656                  const wxString& short_help_string = wxEmptyString,
 657                  const wxString& long_help_string = wxEmptyString);
 658
 659     wxAuiToolBarItem* AddLabel(int tool_id,
 660                   const wxString& label = wxEmptyString,
 661                   const int width = -1);
 662     wxAuiToolBarItem* AddControl(wxControl* control,
 663                     const wxString& label = wxEmptyString);
 664     wxAuiToolBarItem* AddSeparator();
 665     wxAuiToolBarItem* AddSpacer(int pixels);
 666     wxAuiToolBarItem* AddStretchSpacer(int proportion = 1);
 667
 668     bool Realize();
 669
 670     wxControl* FindControl(int window_id);
 671     wxAuiToolBarItem* FindToolByPosition(wxCoord x, wxCoord y) const;
 672     wxAuiToolBarItem* FindToolByIndex(int idx) const;
 673     wxAuiToolBarItem* FindTool(int tool_id) const;
 674
 675     void ClearTools();
 676     void Clear();
 677     bool DeleteTool(int tool_id);
 678     bool DeleteByIndex(int tool_id);
 679
 680     size_t GetToolCount() const;
 681     int GetToolPos(int tool_id) const;
 682     int GetToolIndex(int tool_id) const;
 683     bool GetToolFits(int tool_id) const;
 684     wxRect GetToolRect(int tool_id) const;
 685     bool GetToolFitsByIndex(int tool_id) const;
 686     bool GetToolBarFits() const;
 687
 688     void SetMargins(const wxSize& size);
 689     void SetMargins(int x, int y);
 690     void SetMargins(int left, int right, int top, int bottom);
 691
 692     void SetToolBitmapSize(const wxSize& size);
 693     wxSize GetToolBitmapSize() const;
 694
 695     bool GetOverflowVisible() const;
 696     void SetOverflowVisible(bool visible);
 697
 698     bool GetGripperVisible() const;
 699     void SetGripperVisible(bool visible);
 700
 701     void ToggleTool(int tool_id, bool state);
 702     bool GetToolToggled(int tool_id) const;
 703
 704     void EnableTool(int tool_id, bool state);
 705     bool GetToolEnabled(int tool_id) const;
 706
 707     void SetToolDropDown(int tool_id, bool dropdown);
 708     bool GetToolDropDown(int tool_id) const;
 709
 710     void SetToolBorderPadding(int padding);
 711     int  GetToolBorderPadding() const;
 712
 713     void SetToolTextOrientation(int orientation);
 714     int  GetToolTextOrientation() const;
 715
 716     void SetToolPacking(int packing);
 717     int  GetToolPacking() const;
 718
 719     void SetToolProportion(int tool_id, int proportion);
 720     int  GetToolProportion(int tool_id) const;
 721
 722     void SetToolSeparation(int separation);
 723     int GetToolSeparation() const;
 724
 725     void SetToolSticky(int tool_id, bool sticky);
 726     bool GetToolSticky(int tool_id) const;
 727
 728     wxString GetToolLabel(int tool_id) const;
 729     void SetToolLabel(int tool_id, const wxString& label);
 730
 731     wxBitmap GetToolBitmap(int tool_id) const;
 732     void SetToolBitmap(int tool_id, const wxBitmap& bitmap);
 733
 734     wxString GetToolShortHelp(int tool_id) const;
 735     void SetToolShortHelp(int tool_id, const wxString& help_string);
 736
 737     wxString GetToolLongHelp(int tool_id) const;
 738     void SetToolLongHelp(int tool_id, const wxString& help_string);
 739
 740     void SetCustomOverflowItems(const wxAuiToolBarItemArray& prepend,
 741                                 const wxAuiToolBarItemArray& append);
 742
 743     /** get size of hint rectangle for a particular dock location */
 744     wxSize GetHintSize(int dock_direction) const;
 745     bool IsPaneValid(const wxAuiPaneInfo& pane) const;
 746 };
 747