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     @library{wxaui}
  12     @category{aui}
  13   */
  14 enum wxAuiToolBarStyle
  15 {
  16     wxAUI_TB_TEXT          = 1 << 0,
  17     wxAUI_TB_NO_TOOLTIPS   = 1 << 1,
  18     wxAUI_TB_NO_AUTORESIZE = 1 << 2,
  19     wxAUI_TB_GRIPPER       = 1 << 3,
  20     wxAUI_TB_OVERFLOW      = 1 << 4,
  21     /**
  22       Using this style forces the toolbar to be vertical and be only dockable
  23       to the left or right sides of the window whereas by default it can be
  24       horizontal or vertical and be docked anywhere.
  25       */
  26     wxAUI_TB_VERTICAL      = 1 << 5,
  27     wxAUI_TB_HORZ_LAYOUT   = 1 << 6,
  28     /**
  29       Analogous to wxAUI_TB_VERTICAL, but forces the toolbar
  30       to be horizontal
  31       */
  32     wxAUI_TB_HORIZONTAL    = 1 << 7,
  33     wxAUI_TB_HORZ_TEXT     = (wxAUI_TB_HORZ_LAYOUT | wxAUI_TB_TEXT),
  34     wxAUI_ORIENTATION_MASK = (wxAUI_TB_VERTICAL | wxAUI_TB_HORIZONTAL),
  35     wxAUI_TB_DEFAULT_STYLE = 0
  36 };
  37
  38 /**
  39   @library{wxaui}
  40   @category{aui}
  41   */
  42 enum wxAuiToolBarArtSetting
  43 {
  44     wxAUI_TBART_SEPARATOR_SIZE = 0,
  45     wxAUI_TBART_GRIPPER_SIZE = 1,
  46     wxAUI_TBART_OVERFLOW_SIZE = 2
  47 };
  48
  49 /**
  50   @library{wxaui}
  51   @category{aui}
  52   */
  53 enum wxAuiToolBarToolTextOrientation
  54 {
  55     wxAUI_TBTOOL_TEXT_LEFT = 0,     //!< unused/unimplemented
  56     wxAUI_TBTOOL_TEXT_RIGHT = 1,
  57     wxAUI_TBTOOL_TEXT_TOP = 2,      //!< unused/unimplemented
  58     wxAUI_TBTOOL_TEXT_BOTTOM = 3
  59 };
  60
  61
  62 /**
  63     @class wxAuiToolBarEvent
  64
  65     wxAuiToolBarEvent is used for the events generated by @ref wxAuiToolBar.
  66
  67     @library{wxaui}
  68     @category{aui}
  69 */
  70 class wxAuiToolBarEvent : public wxNotifyEvent
  71 {
  72 public:
  73     bool IsDropDownClicked() const;
  74
  75     wxPoint GetClickPoint() const;
  76
  77     wxRect GetItemRect() const;
  78
  79     int GetToolId() const;
  80 };
  81
  82
  83 /**
  84     @class wxAuiToolBarItem
  85
  86     wxAuiToolBarItem is part of the wxAUI class framework.
  87     See also @ref wxAuiToolBar and @ref overview_aui.
  88
  89     @library{wxaui}
  90     @category{aui}
  91 */
  92 class wxAuiToolBarItem
  93 {
  94 public:
  95
  96     wxAuiToolBarItem();
  97
  98     wxAuiToolBarItem(const wxAuiToolBarItem& c);
  99
 100     wxAuiToolBarItem& operator=(const wxAuiToolBarItem& c);
 101
 102     void Assign(const wxAuiToolBarItem& c);
 103
 104     void SetWindow(wxWindow* w);
 105     wxWindow* GetWindow();
 106
 107     void SetId(int new_id);
 108     int GetId() const;
 109
 110     void SetKind(int new_kind);
 111     int GetKind() const;
 112
 113     void SetState(int new_state);
 114     int GetState() const;
 115
 116     void SetSizerItem(wxSizerItem* s);
 117     wxSizerItem* GetSizerItem() const;
 118
 119     void SetLabel(const wxString& s);
 120     const wxString& GetLabel() const;
 121
 122     void SetBitmap(const wxBitmap& bmp);
 123     const wxBitmap& GetBitmap() const;
 124
 125     void SetDisabledBitmap(const wxBitmap& bmp);
 126     const wxBitmap& GetDisabledBitmap() const;
 127
 128     void SetHoverBitmap(const wxBitmap& bmp);
 129     const wxBitmap& GetHoverBitmap() const;
 130
 131     void SetShortHelp(const wxString& s);
 132     const wxString& GetShortHelp() const;
 133
 134     void SetLongHelp(const wxString& s);
 135     const wxString& GetLongHelp() const;
 136
 137     void SetMinSize(const wxSize& s);
 138     const wxSize& GetMinSize() const;
 139
 140     void SetSpacerPixels(int s);
 141     int GetSpacerPixels() const;
 142
 143     void SetProportion(int p);
 144     int GetProportion() const;
 145
 146     void SetActive(bool b);
 147     bool IsActive() const;
 148
 149     void SetHasDropDown(bool b);
 150     bool HasDropDown() const;
 151
 152     void SetSticky(bool b);
 153     bool IsSticky() const;
 154
 155     void SetUserData(long l);
 156     long GetUserData() const;
 157
 158     void SetAlignment(int l);
 159     int GetAlignment() const;
 160 };
 161
 162 /**
 163     @class wxAuiToolBarArt
 164
 165     wxAuiToolBarArt is part of the wxAUI class framework.
 166     See also @ref wxAuiToolBar and @ref overview_aui.
 167
 168     @library{wxaui}
 169     @category{aui}
 170 */
 171 class wxAuiToolBarArt
 172 {
 173 public:
 174     wxAuiToolBarArt();
 175
 176     virtual wxAuiToolBarArt* Clone() = 0;
 177     virtual void SetFlags(unsigned int flags) = 0;
 178     virtual unsigned int GetFlags() = 0;
 179     virtual void SetFont(const wxFont& font) = 0;
 180     virtual wxFont GetFont() = 0;
 181     virtual void SetTextOrientation(int orientation) = 0;
 182     virtual int GetTextOrientation() = 0;
 183
 184     virtual void DrawBackground(
 185                          wxDC& dc,
 186                          wxWindow* wnd,
 187                          const wxRect& rect) = 0;
 188
 189     virtual void DrawLabel(
 190                          wxDC& dc,
 191                          wxWindow* wnd,
 192                          const wxAuiToolBarItem& item,
 193                          const wxRect& rect) = 0;
 194
 195     virtual void DrawButton(
 196                          wxDC& dc,
 197                          wxWindow* wnd,
 198                          const wxAuiToolBarItem& item,
 199                          const wxRect& rect) = 0;
 200
 201     virtual void DrawDropDownButton(
 202                          wxDC& dc,
 203                          wxWindow* wnd,
 204                          const wxAuiToolBarItem& item,
 205                          const wxRect& rect) = 0;
 206
 207     virtual void DrawControlLabel(
 208                          wxDC& dc,
 209                          wxWindow* wnd,
 210                          const wxAuiToolBarItem& item,
 211                          const wxRect& rect) = 0;
 212
 213     virtual void DrawSeparator(
 214                          wxDC& dc,
 215                          wxWindow* wnd,
 216                          const wxRect& rect) = 0;
 217
 218     virtual void DrawGripper(
 219                          wxDC& dc,
 220                          wxWindow* wnd,
 221                          const wxRect& rect) = 0;
 222
 223     virtual void DrawOverflowButton(
 224                          wxDC& dc,
 225                          wxWindow* wnd,
 226                          const wxRect& rect,
 227                          int state) = 0;
 228
 229     virtual wxSize GetLabelSize(
 230                          wxDC& dc,
 231                          wxWindow* wnd,
 232                          const wxAuiToolBarItem& item) = 0;
 233
 234     virtual wxSize GetToolSize(
 235                          wxDC& dc,
 236                          wxWindow* wnd,
 237                          const wxAuiToolBarItem& item) = 0;
 238
 239     virtual int GetElementSize(int element_id) = 0;
 240     virtual void SetElementSize(int element_id, int size) = 0;
 241
 242     virtual int ShowDropDown(
 243                          wxWindow* wnd,
 244                          const wxAuiToolBarItemArray& items) = 0;
 245 };
 246
 247
 248 /**
 249     @class wxAuiDefaultToolBarArt
 250
 251     wxAuiDefaultToolBarArt is part of the wxAUI class framework.
 252     See also @ref wxAuiToolBarArt , @ref wxAuiToolBar and @ref overview_aui.
 253
 254     @library{wxaui}
 255     @category{aui}
 256 */
 257 class wxAuiDefaultToolBarArt : public wxAuiToolBarArt
 258 {
 259 public:
 260     wxAuiDefaultToolBarArt();
 261     virtual ~wxAuiDefaultToolBarArt();
 262
 263     virtual wxAuiToolBarArt* Clone();
 264     virtual void SetFlags(unsigned int flags);
 265     virtual unsigned int GetFlags();
 266     virtual void SetFont(const wxFont& font);
 267     virtual wxFont GetFont();
 268     virtual void SetTextOrientation(int orientation);
 269     virtual int GetTextOrientation();
 270
 271     virtual void DrawBackground(
 272                 wxDC& dc,
 273                 wxWindow* wnd,
 274                 const wxRect& rect);
 275
 276     virtual void DrawLabel(
 277                 wxDC& dc,
 278                 wxWindow* wnd,
 279                 const wxAuiToolBarItem& item,
 280                 const wxRect& rect);
 281
 282     virtual void DrawButton(
 283                 wxDC& dc,
 284                 wxWindow* wnd,
 285                 const wxAuiToolBarItem& item,
 286                 const wxRect& rect);
 287
 288     virtual void DrawDropDownButton(
 289                 wxDC& dc,
 290                 wxWindow* wnd,
 291                 const wxAuiToolBarItem& item,
 292                 const wxRect& rect);
 293
 294     virtual void DrawControlLabel(
 295                 wxDC& dc,
 296                 wxWindow* wnd,
 297                 const wxAuiToolBarItem& item,
 298                 const wxRect& rect);
 299
 300     virtual void DrawSeparator(
 301                 wxDC& dc,
 302                 wxWindow* wnd,
 303                 const wxRect& rect);
 304
 305     virtual void DrawGripper(
 306                 wxDC& dc,
 307                 wxWindow* wnd,
 308                 const wxRect& rect);
 309
 310     virtual void DrawOverflowButton(
 311                 wxDC& dc,
 312                 wxWindow* wnd,
 313                 const wxRect& rect,
 314                 int state);
 315
 316     virtual wxSize GetLabelSize(
 317                 wxDC& dc,
 318                 wxWindow* wnd,
 319                 const wxAuiToolBarItem& item);
 320
 321     virtual wxSize GetToolSize(
 322                 wxDC& dc,
 323                 wxWindow* wnd,
 324                 const wxAuiToolBarItem& item);
 325
 326     virtual int GetElementSize(int element);
 327     virtual void SetElementSize(int element_id, int size);
 328
 329     virtual int ShowDropDown(wxWindow* wnd,
 330                              const wxAuiToolBarItemArray& items);
 331 };
 332
 333
 334
 335 /**
 336     @class wxAuiToolBar
 337
 338     wxAuiToolBar is a dockable toolbar, part of the wxAUI class framework.
 339     See also @ref overview_aui.
 340
 341     @beginStyleTable
 342     @style{wxAUI_TB_TEXT}
 343     @style{wxAUI_TB_NO_TOOLTIPS}
 344     @style{wxAUI_TB_NO_AUTORESIZE}
 345     @style{wxAUI_TB_GRIPPER}
 346     @style{wxAUI_TB_OVERFLOW}
 347     @style{wxAUI_TB_VERTICAL}
 348         using this style forces the toolbar to be vertical and
 349         be only dockable to the left or right sides of the window
 350         whereas by default it can be horizontal or vertical and
 351         be docked anywhere
 352     @style{wxAUI_TB_HORZ_LAYOUT}
 353     @style{wxAUI_TB_HORIZONTAL}
 354         analogous to wxAUI_TB_VERTICAL, but forces the toolbar
 355         to be horizontal
 356     @style{wxAUI_TB_HORZ_TEXT}
 357         Equivalent to wxAUI_TB_HORZ_LAYOUT | wxAUI_TB_TEXT
 358     @style{wxAUI_TB_DEFAULT_STYLE}
 359         The default is to have no styles
 360     @endStyleTable
 361
 362     @beginEventEmissionTable{wxAuiToolBarEvent}
 363     @event{EVT_AUITOOLBAR_TOOL_DROPDOWN(id, func)}
 364         Process a wxEVT_COMMAND_AUITOOLBAR_TOOL_DROPDOWN event
 365     @event{EVT_AUITOOLBAR_OVERFLOW_CLICK(id, func)}
 366         Process a wxEVT_COMMAND_AUITOOLBAR_OVERFLOW_CLICK event
 367     @event{EVT_AUITOOLBAR_RIGHT_CLICK(id, func)}
 368         Process a wxEVT_COMMAND_AUITOOLBAR_RIGHT_CLICK event
 369     @event{EVT_AUITOOLBAR_MIDDLE_CLICK(id, func)}
 370         Process a wxEVT_COMMAND_AUITOOLBAR_MIDDLE_CLICK event
 371     @event{EVT_AUITOOLBAR_BEGIN_DRAG(id, func)}
 372         Process a wxEVT_COMMAND_AUITOOLBAR_BEGIN_DRAG event
 373     @endEventTable
 374
 375     @library{wxaui}
 376     @category{aui}
 377 */
 378 class wxAuiToolBar : public wxControl
 379 {
 380 public:
 381     wxAuiToolBar(wxWindow* parent,
 382                  wxWindowID id = -1,
 383                  const wxPoint& position = wxDefaultPosition,
 384                  const wxSize& size = wxDefaultSize,
 385                  long style = wxAUI_TB_DEFAULT_STYLE);
 386     virtual ~wxAuiToolBar();
 387
 388     void SetWindowStyleFlag(long style);
 389     long GetWindowStyleFlag() const;
 390
 391     void SetArtProvider(wxAuiToolBarArt* art);
 392     wxAuiToolBarArt* GetArtProvider() const;
 393
 394     bool SetFont(const wxFont& font);
 395
 396
 397     wxAuiToolBarItem* AddTool(int tool_id,
 398                  const wxString& label,
 399                  const wxBitmap& bitmap,
 400                  const wxString& short_help_string = wxEmptyString,
 401                  wxItemKind kind = wxITEM_NORMAL);
 402
 403     wxAuiToolBarItem* AddTool(int tool_id,
 404                  const wxString& label,
 405                  const wxBitmap& bitmap,
 406                  const wxBitmap& disabled_bitmap,
 407                  wxItemKind kind,
 408                  const wxString& short_help_string,
 409                  const wxString& long_help_string,
 410                  wxObject* client_data);
 411
 412     wxAuiToolBarItem* AddTool(int tool_id,
 413                  const wxBitmap& bitmap,
 414                  const wxBitmap& disabled_bitmap,
 415                  bool toggle = false,
 416                  wxObject* client_data = NULL,
 417                  const wxString& short_help_string = wxEmptyString,
 418                  const wxString& long_help_string = wxEmptyString);
 419
 420     wxAuiToolBarItem* AddLabel(int tool_id,
 421                   const wxString& label = wxEmptyString,
 422                   const int width = -1);
 423     wxAuiToolBarItem* AddControl(wxControl* control,
 424                     const wxString& label = wxEmptyString);
 425     wxAuiToolBarItem* AddSeparator();
 426     wxAuiToolBarItem* AddSpacer(int pixels);
 427     wxAuiToolBarItem* AddStretchSpacer(int proportion = 1);
 428
 429     bool Realize();
 430
 431     wxControl* FindControl(int window_id);
 432     wxAuiToolBarItem* FindToolByPosition(wxCoord x, wxCoord y) const;
 433     wxAuiToolBarItem* FindToolByIndex(int idx) const;
 434     wxAuiToolBarItem* FindTool(int tool_id) const;
 435
 436     void ClearTools();
 437     void Clear();
 438     bool DeleteTool(int tool_id);
 439     bool DeleteByIndex(int tool_id);
 440
 441     size_t GetToolCount() const;
 442     int GetToolPos(int tool_id) const;
 443     int GetToolIndex(int tool_id) const;
 444     bool GetToolFits(int tool_id) const;
 445     wxRect GetToolRect(int tool_id) const;
 446     bool GetToolFitsByIndex(int tool_id) const;
 447     bool GetToolBarFits() const;
 448
 449     void SetMargins(const wxSize& size);
 450     void SetMargins(int x, int y);
 451     void SetMargins(int left, int right, int top, int bottom);
 452
 453     void SetToolBitmapSize(const wxSize& size);
 454     wxSize GetToolBitmapSize() const;
 455
 456     bool GetOverflowVisible() const;
 457     void SetOverflowVisible(bool visible);
 458
 459     bool GetGripperVisible() const;
 460     void SetGripperVisible(bool visible);
 461
 462     void ToggleTool(int tool_id, bool state);
 463     bool GetToolToggled(int tool_id) const;
 464
 465     void EnableTool(int tool_id, bool state);
 466     bool GetToolEnabled(int tool_id) const;
 467
 468     void SetToolDropDown(int tool_id, bool dropdown);
 469     bool GetToolDropDown(int tool_id) const;
 470
 471     void SetToolBorderPadding(int padding);
 472     int  GetToolBorderPadding() const;
 473
 474     void SetToolTextOrientation(int orientation);
 475     int  GetToolTextOrientation() const;
 476
 477     void SetToolPacking(int packing);
 478     int  GetToolPacking() const;
 479
 480     void SetToolProportion(int tool_id, int proportion);
 481     int  GetToolProportion(int tool_id) const;
 482
 483     void SetToolSeparation(int separation);
 484     int GetToolSeparation() const;
 485
 486     void SetToolSticky(int tool_id, bool sticky);
 487     bool GetToolSticky(int tool_id) const;
 488
 489     wxString GetToolLabel(int tool_id) const;
 490     void SetToolLabel(int tool_id, const wxString& label);
 491
 492     wxBitmap GetToolBitmap(int tool_id) const;
 493     void SetToolBitmap(int tool_id, const wxBitmap& bitmap);
 494
 495     wxString GetToolShortHelp(int tool_id) const;
 496     void SetToolShortHelp(int tool_id, const wxString& help_string);
 497
 498     wxString GetToolLongHelp(int tool_id) const;
 499     void SetToolLongHelp(int tool_id, const wxString& help_string);
 500
 501     void SetCustomOverflowItems(const wxAuiToolBarItemArray& prepend,
 502                                 const wxAuiToolBarItemArray& append);
 503
 504     /** get size of hint rectangle for a particular dock location */
 505     wxSize GetHintSize(int dock_direction) const;
 506     bool IsPaneValid(const wxAuiPaneInfo& pane) const;
 507 };
 508