interface/aui/auibook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        aui/auibook.h
   3 // Purpose:     interface of wxAuiNotebook
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxAuiNotebook
  11     @headerfile auibook.h wx/aui/auibook.h
  12
  13     wxAuiNotebook is part of the wxAUI class framework.
  14     See also @ref overview_aui.
  15
  16     wxAuiNotebook is a notebook control which implements many features common in
  17     applications with dockable panes.
  18     Specifically, wxAuiNotebook implements functionality which allows the user to
  19     rearrange tab order via drag-and-drop, split the tab window into many different
  20     splitter configurations, and toggle through different themes to customize
  21     the control's look and feel.
  22
  23     An effort has been made to try to maintain an API as similar to that of
  24     wxNotebook.
  25
  26     The default theme that is used is wxAuiDefaultTabArt, which provides a modern,
  27     glossy look and feel.
  28     The theme can be changed by calling wxAuiNotebook::SetArtProvider.
  29
  30     @beginStyleTable
  31     @style{wxAUI_NB_DEFAULT_STYLE}:
  32            Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE |
  33            wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB.
  34     @style{wxAUI_NB_TAB_SPLIT}:
  35            Allows the tab control to be split by dragging a tab.
  36     @style{wxAUI_NB_TAB_MOVE}:
  37            Allows a tab to be moved horizontally by dragging.
  38     @style{wxAUI_NB_TAB_EXTERNAL_MOVE}:
  39            Allows a tab to be moved to another tab control.
  40     @style{wxAUI_NB_TAB_FIXED_WIDTH}:
  41            With this style, all tabs have the same width.
  42     @style{wxAUI_NB_SCROLL_BUTTONS}:
  43            With this style, left and right scroll buttons are displayed.
  44     @style{wxAUI_NB_WINDOWLIST_BUTTON}:
  45            With this style, a drop-down list of windows is available.
  46     @style{wxAUI_NB_CLOSE_BUTTON}:
  47            With this style, a close button is available on the tab bar.
  48     @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB}:
  49            With this style, the close button is visible on the active tab.
  50     @style{wxAUI_NB_CLOSE_ON_ALL_TABS}:
  51            With this style, the close button is visible on all tabs.
  52     @style{wxAUI_NB_TOP}:
  53            With this style, tabs are drawn along the top of the notebook.
  54     @style{wxAUI_NB_BOTTOM}:
  55            With this style, tabs are drawn along the bottom of the notebook.
  56     @endStyleTable
  57
  58     @library{wxaui}
  59     @category{aui}
  60 */
  61 class wxAuiNotebook : public wxControl
  62 {
  63 public:
  64     wxAuiNotebook();
  65
  66     /**
  67         Constructor. Creates a wxAuiNotebok control.
  68     */
  69     wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY,
  70                   const wxPoint& pos = wxDefaultPosition,
  71                   const wxSize& size = wxDefaultSize,
  72                   long style = wxAUI_NB_DEFAULT_STYLE);
  73
  74     /**
  75         Adds a page.
  76         If the @a select parameter is @true, calling this will generate a page change event.
  77     */
  78     bool AddPage(wxWindow* page, const wxString& caption,
  79                  bool select = false,
  80                  const wxBitmap& bitmap = wxNullBitmap);
  81
  82     /**
  83         Sets the selection to the next or previous page.
  84     */
  85     void AdvanceSelection(bool forward = true);
  86
  87     /**
  88         Creates the notebook window.
  89     */
  90     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  91                 const wxPoint& pos = wxDefaultPosition,
  92                 const wxSize& size = wxDefaultSize,
  93                 long style = 0);
  94
  95     /**
  96         Deletes a page at the given index.
  97         Calling this method will generate a page change event.
  98     */
  99     bool DeletePage(size_t page);
 100
 101     /**
 102         Returns the associated art provider.
 103     */
 104     wxAuiTabArt* GetArtProvider() const;
 105
 106     /**
 107         Returns the desired height of the notebook for the given page height.
 108         Use this to fit the notebook to a given page size.
 109     */
 110     int GetHeightForPageHeight(int pageHeight);
 111
 112     /**
 113         Returns the page specified by the given index.
 114     */
 115     wxWindow* GetPage(size_t page_idx) const;
 116
 117     /**
 118         Returns the tab bitmap for the page.
 119     */
 120     wxBitmap GetPageBitmap(size_t page) const;
 121
 122     /**
 123         Returns the number of pages in the notebook.
 124     */
 125     size_t GetPageCount() const;
 126
 127     /**
 128         Returns the page index for the specified window.
 129         If the window is not found in the notebook, wxNOT_FOUND is returned.
 130     */
 131     int GetPageIndex(wxWindow* page_wnd) const;
 132
 133     /**
 134         Returns the tab label for the page.
 135     */
 136     wxString GetPageText(size_t page) const;
 137
 138     /**
 139         Returns the currently selected page.
 140     */
 141     int GetSelection() const;
 142
 143     /**
 144         Returns the height of the tab control.
 145     */
 146     int GetTabCtrlHeight() const;
 147
 148     /**
 149         InsertPage() is similar to AddPage, but allows the ability to specify the
 150         insert location.
 151         If the @a select parameter is @true, calling this will generate a page change
 152         event.
 153     */
 154     bool InsertPage(size_t page_idx, wxWindow* page,
 155                     const wxString& caption,
 156                     bool select = false,
 157                     const wxBitmap& bitmap = wxNullBitmap);
 158
 159     /**
 160         Removes a page, without deleting the window pointer.
 161     */
 162     bool RemovePage(size_t page);
 163
 164     /**
 165         Sets the art provider to be used by the notebook.
 166     */
 167     void SetArtProvider(wxAuiTabArt* art);
 168
 169     /**
 170         Sets the font for drawing the tab labels, using a bold version of the font for
 171         selected tab labels.
 172     */
 173     bool SetFont(const wxFont& font);
 174
 175     /**
 176         Sets the font for measuring tab labels.
 177     */
 178     void SetMeasuringFont(const wxFont& font);
 179
 180     /**
 181         Sets the font for drawing unselected tab labels.
 182     */
 183     void SetNormalFont(const wxFont& font);
 184
 185     /**
 186         Sets the bitmap for the page.  To remove a bitmap from the tab caption, pass
 187         wxNullBitmap.
 188     */
 189     bool SetPageBitmap(size_t page, const wxBitmap& bitmap);
 190
 191     /**
 192         Sets the tab label for the page.
 193     */
 194     bool SetPageText(size_t page, const wxString& text);
 195
 196     /**
 197         Sets the font for drawing selected tab labels.
 198     */
 199     void SetSelectedFont(const wxFont& font);
 200
 201     /**
 202         Sets the page selection.  Calling this method will generate a page change event.
 203     */
 204     size_t SetSelection(size_t new_page);
 205
 206     /**
 207         Sets the tab height. By default, the tab control height is calculated
 208         by measuring the text height and bitmap sizes on the tab captions. Calling this
 209         method will override that calculation and set the tab control to the specified
 210         height parameter. A call to this method will override any call to
 211         SetUniformBitmapSize().
 212
 213         Specifying -1 as the height will return the control to its default auto-sizing
 214         behaviour.
 215     */
 216     void SetTabCtrlHeight(int height);
 217
 218     //@{
 219     /**
 220         Split performs a split operation programmatically. The argument @a page
 221         indicates the page that will be split off.  This page will also become the
 222         active page after the split.
 223
 224         The @a direction argument specifies where the pane should go, it should be one
 225         of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT.
 226     */
 227     void SetUniformBitmapSize(const wxSize& size);
 228     void Split(size_t page, int direction);
 229     //@}
 230
 231     /**
 232         Shows the window menu for the active tab control associated with this notebook,
 233         and returns @true if a selection was made.
 234     */
 235     bool ShowWindowMenu();
 236 };
 237
 238
 239
 240 /**
 241     @class wxAuiTabArt
 242     @headerfile auibook.h wx/aui/auibook.h
 243
 244     Tab art class.
 245
 246     @todo BETTER DESCRIPTION NEEDED
 247
 248     @library{wxaui}
 249     @category{aui}
 250 */
 251 class wxAuiTabArt
 252 {
 253 public:
 254     /**
 255         Constructor.
 256     */
 257     wxAuiTabArt();
 258
 259     /**
 260         Clones the art object.
 261     */
 262     wxAuiTabArt* Clone();
 263
 264     /**
 265         Draws a background on the given area.
 266     */
 267     void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect);
 268
 269     /**
 270         Draws a button.
 271     */
 272     void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
 273                     int bitmap_id,
 274                     int button_state,
 275                     int orientation,
 276                     const wxBitmap& bitmap_override,
 277                     wxRect* out_rect);
 278
 279     /**
 280         Draws a tab.
 281     */
 282     void DrawTab(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
 283                  const wxString& caption,
 284                  const wxBitmap& bitmap,
 285                  bool active,
 286                  int close_button_state,
 287                  wxRect* out_tab_rect,
 288                  wxRect* out_button_rect,
 289                  int* x_extent);
 290
 291     /**
 292         Returns the tab control size.
 293     */
 294     int GetBestTabCtrlSize(wxWindow* wnd,
 295                            wxAuiNotebookPageArray& pages);
 296
 297     /**
 298         Returns the indent size.
 299     */
 300     int GetIndentSize();
 301
 302     /**
 303         Returns the tab size for the given caption, bitmap and state.
 304     */
 305     wxSize GetTabSize(wxDC& dc, wxWindow* wnd,
 306                       const wxString& caption,
 307                       const wxBitmap& bitmap,
 308                       bool active,
 309                       int close_button_state,
 310                       int* x_extent);
 311
 312     /**
 313         Sets flags.
 314     */
 315     void SetFlags(unsigned int flags);
 316
 317     /**
 318         Sets the font used for calculating measurements.
 319     */
 320     void SetMeasuringFont(const wxFont& font);
 321
 322     /**
 323         Sets the normal font for drawing labels.
 324     */
 325     void SetNormalFont(const wxFont& font);
 326
 327     /**
 328         Sets the font for drawing text for selected UI elements.
 329     */
 330     void SetSelectedFont(const wxFont& font);
 331
 332     /**
 333         Sets sizing information.
 334     */
 335     void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count);
 336
 337     /**
 338         Pops up a menu to show the list of windows managed by wxAui.
 339     */
 340     int ShowWindowList(wxWindow* wnd, const wxArrayString& items,
 341                        int active_idx);
 342 };
 343