interface/wx/aui/toolbar.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     wxAuiToolBar(wxWindow* parent,
 600                  wxWindowID id = -1,
 601                  const wxPoint& position = wxDefaultPosition,
 602                  const wxSize& size = wxDefaultSize,
 603                  long style = wxAUI_TB_DEFAULT_STYLE);
 604     virtual ~wxAuiToolBar();
 605
 606     void SetWindowStyleFlag(long style);
 607     long GetWindowStyleFlag() const;
 608
 609     void SetArtProvider(wxAuiToolBarArt* art);
 610     wxAuiToolBarArt* GetArtProvider() const;
 611
 612     bool SetFont(const wxFont& font);
 613
 614
 615     wxAuiToolBarItem* AddTool(int tool_id,
 616                  const wxString& label,
 617                  const wxBitmap& bitmap,
 618                  const wxString& short_help_string = wxEmptyString,
 619                  wxItemKind kind = wxITEM_NORMAL);
 620
 621     wxAuiToolBarItem* AddTool(int tool_id,
 622                  const wxString& label,
 623                  const wxBitmap& bitmap,
 624                  const wxBitmap& disabled_bitmap,
 625                  wxItemKind kind,
 626                  const wxString& short_help_string,
 627                  const wxString& long_help_string,
 628                  wxObject* client_data);
 629
 630     wxAuiToolBarItem* AddTool(int tool_id,
 631                  const wxBitmap& bitmap,
 632                  const wxBitmap& disabled_bitmap,
 633                  bool toggle = false,
 634                  wxObject* client_data = NULL,
 635                  const wxString& short_help_string = wxEmptyString,
 636                  const wxString& long_help_string = wxEmptyString);
 637
 638     wxAuiToolBarItem* AddLabel(int tool_id,
 639                   const wxString& label = wxEmptyString,
 640                   const int width = -1);
 641     wxAuiToolBarItem* AddControl(wxControl* control,
 642                     const wxString& label = wxEmptyString);
 643     wxAuiToolBarItem* AddSeparator();
 644     wxAuiToolBarItem* AddSpacer(int pixels);
 645     wxAuiToolBarItem* AddStretchSpacer(int proportion = 1);
 646
 647     bool Realize();
 648
 649     wxControl* FindControl(int window_id);
 650     wxAuiToolBarItem* FindToolByPosition(wxCoord x, wxCoord y) const;
 651     wxAuiToolBarItem* FindToolByIndex(int idx) const;
 652     wxAuiToolBarItem* FindTool(int tool_id) const;
 653
 654     void ClearTools();
 655     void Clear();
 656     bool DeleteTool(int tool_id);
 657     bool DeleteByIndex(int tool_id);
 658
 659     size_t GetToolCount() const;
 660     int GetToolPos(int tool_id) const;
 661     int GetToolIndex(int tool_id) const;
 662     bool GetToolFits(int tool_id) const;
 663     wxRect GetToolRect(int tool_id) const;
 664     bool GetToolFitsByIndex(int tool_id) const;
 665     bool GetToolBarFits() const;
 666
 667     void SetMargins(const wxSize& size);
 668     void SetMargins(int x, int y);
 669     void SetMargins(int left, int right, int top, int bottom);
 670
 671     void SetToolBitmapSize(const wxSize& size);
 672     wxSize GetToolBitmapSize() const;
 673
 674     bool GetOverflowVisible() const;
 675     void SetOverflowVisible(bool visible);
 676
 677     bool GetGripperVisible() const;
 678     void SetGripperVisible(bool visible);
 679
 680     void ToggleTool(int tool_id, bool state);
 681     bool GetToolToggled(int tool_id) const;
 682
 683     void EnableTool(int tool_id, bool state);
 684     bool GetToolEnabled(int tool_id) const;
 685
 686     void SetToolDropDown(int tool_id, bool dropdown);
 687     bool GetToolDropDown(int tool_id) const;
 688
 689     void SetToolBorderPadding(int padding);
 690     int  GetToolBorderPadding() const;
 691
 692     void SetToolTextOrientation(int orientation);
 693     int  GetToolTextOrientation() const;
 694
 695     void SetToolPacking(int packing);
 696     int  GetToolPacking() const;
 697
 698     void SetToolProportion(int tool_id, int proportion);
 699     int  GetToolProportion(int tool_id) const;
 700
 701     void SetToolSeparation(int separation);
 702     int GetToolSeparation() const;
 703
 704     void SetToolSticky(int tool_id, bool sticky);
 705     bool GetToolSticky(int tool_id) const;
 706
 707     wxString GetToolLabel(int tool_id) const;
 708     void SetToolLabel(int tool_id, const wxString& label);
 709
 710     wxBitmap GetToolBitmap(int tool_id) const;
 711     void SetToolBitmap(int tool_id, const wxBitmap& bitmap);
 712
 713     wxString GetToolShortHelp(int tool_id) const;
 714     void SetToolShortHelp(int tool_id, const wxString& help_string);
 715
 716     wxString GetToolLongHelp(int tool_id) const;
 717     void SetToolLongHelp(int tool_id, const wxString& help_string);
 718
 719     void SetCustomOverflowItems(const wxAuiToolBarItemArray& prepend,
 720                                 const wxAuiToolBarItemArray& append);
 721
 722     /** get size of hint rectangle for a particular dock location */
 723     wxSize GetHintSize(int dock_direction) const;
 724     bool IsPaneValid(const wxAuiPaneInfo& pane) const;
 725 };
 726