interface/aui/auibook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        aui/auibook.h
   3 // Purpose:     documentation for wxAuiNotebook class
   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_wxauioverview "wxAUI overview".
  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,
  20     split the tab window into many different splitter configurations, and toggle
  21     through different themes to customize
  22     the control's look and feel.
  23
  24     An effort has been made to try to maintain an API as similar to that of
  25     wxNotebook.
  26
  27     The default theme that is used is wxAuiDefaultTabArt, which provides a modern,
  28     glossy look and feel.
  29     The theme can be changed by calling wxAuiNotebook::SetArtProvider.
  30
  31     @beginStyleTable
  32     @style{wxAUI_NB_DEFAULT_STYLE}:
  33            Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE |
  34            wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB.
  35     @style{wxAUI_NB_TAB_SPLIT}:
  36            Allows the tab control to be split by dragging a tab.
  37     @style{wxAUI_NB_TAB_MOVE}:
  38            Allows a tab to be moved horizontally by dragging.
  39     @style{wxAUI_NB_TAB_EXTERNAL_MOVE}:
  40            Allows a tab to be moved to another tab control.
  41     @style{wxAUI_NB_TAB_FIXED_WIDTH}:
  42            With this style, all tabs have the same width.
  43     @style{wxAUI_NB_SCROLL_BUTTONS}:
  44            With this style, left and right scroll buttons are displayed.
  45     @style{wxAUI_NB_WINDOWLIST_BUTTON}:
  46            With this style, a drop-down list of windows is available.
  47     @style{wxAUI_NB_CLOSE_BUTTON}:
  48            With this style, a close button is available on the tab bar.
  49     @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB}:
  50            With this style, the close button is visible on the active tab.
  51     @style{wxAUI_NB_CLOSE_ON_ALL_TABS}:
  52            With this style, the close button is visible on all tabs.
  53     @style{wxAUI_NB_TOP}:
  54            With this style, tabs are drawn along the top of the notebook.
  55     @style{wxAUI_NB_BOTTOM}:
  56            With this style, tabs are drawn along the bottom of the notebook.
  57     @endStyleTable
  58
  59     @library{wxaui}
  60     @category{aui}
  61 */
  62 class wxAuiNotebook : public wxControl
  63 {
  64 public:
  65     //@{
  66     /**
  67         Constructor. Creates a wxAuiNotebok control.
  68     */
  69     wxAuiNotebook();
  70     wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY,
  71                   const wxPoint& pos = wxDefaultPosition,
  72                   const wxSize& size = wxDefaultSize,
  73                   long style = wxAUI_NB_DEFAULT_STYLE);
  74     //@}
  75
  76     /**
  77         Adds a page.  If the @e select parameter is @true, calling this will generate a
  78         page change event.
  79     */
  80     bool AddPage(wxWindow* page, const wxString& caption,
  81                  bool select = @false,
  82                  const wxBitmap& bitmap = wxNullBitmap);
  83
  84     /**
  85         Sets the selection to the next or previous page.
  86     */
  87     void AdvanceSelection(bool forward = @true);
  88
  89     /**
  90         Creates the notebook window.
  91     */
  92     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  93                 const wxPoint& pos = wxDefaultPosition,
  94                 const wxSize& size = wxDefaultSize,
  95                 long style = 0);
  96
  97     /**
  98         Deletes a page at the given index.  Calling this method will generate a page
  99         change event.
 100     */
 101     bool DeletePage(size_t page);
 102
 103     /**
 104         Returns the associated art provider.
 105     */
 106     wxAuiTabArt* GetArtProvider();
 107
 108     /**
 109         Returns the desired height of the notebook for the given page height. Use this
 110         to fit the notebook to
 111         a given page size.
 112     */
 113     int GetHeightForPageHeight(int pageHeight);
 114
 115     /**
 116         Returns the page specified by the given index.
 117     */
 118     wxWindow* GetPage(size_t page_idx);
 119
 120     /**
 121         Returns the tab bitmap for the page.
 122     */
 123     wxBitmap GetPageBitmap(size_t page);
 124
 125     /**
 126         Returns the number of pages in the notebook.
 127     */
 128     size_t GetPageCount();
 129
 130     /**
 131         Returns the page index for the specified window.  If the window is not found in
 132         the notebook, wxNOT_FOUND is returned.
 133     */
 134     int GetPageIndex(wxWindow* page_wnd);
 135
 136     /**
 137         Returns the tab label for the page.
 138     */
 139     wxString GetPageText(size_t page);
 140
 141     /**
 142         Returns the currently selected page.
 143     */
 144     int GetSelection();
 145
 146     /**
 147         Returns the height of the tab control.
 148     */
 149     int GetTabCtrlHeight();
 150
 151     /**
 152         InsertPage() is similar to AddPage, but allows the ability to specify the
 153         insert location.
 154         If the @e select parameter is @true, calling this will generate a page change
 155         event.
 156     */
 157     bool InsertPage(size_t page_idx, wxWindow* page,
 158                     const wxString& caption,
 159                     bool select = @false,
 160                     const wxBitmap& bitmap = wxNullBitmap);
 161
 162     /**
 163         Removes a page, without deleting the window pointer.
 164     */
 165     bool RemovePage(size_t page);
 166
 167     /**
 168         Sets the art provider to be used by the notebook.
 169     */
 170     void SetArtProvider(wxAuiTabArt* art);
 171
 172     /**
 173         Sets the font for drawing the tab labels, using a bold version of the font for
 174         selected tab labels.
 175     */
 176     bool SetFont(const wxFont& font);
 177
 178     /**
 179         Sets the font for measuring tab labels.
 180     */
 181     void SetMeasuringFont(const wxFont& font);
 182
 183     /**
 184         Sets the font for drawing unselected tab labels.
 185     */
 186     void SetNormalFont(const wxFont& font);
 187
 188     /**
 189         Sets the bitmap for the page.  To remove a bitmap from the tab caption, pass
 190         wxNullBitmap.
 191     */
 192     bool SetPageBitmap(size_t page, const wxBitmap& bitmap);
 193
 194     /**
 195         Sets the tab label for the page.
 196     */
 197     bool SetPageText(size_t page, const wxString& text);
 198
 199     /**
 200         Sets the font for drawing selected tab labels.
 201     */
 202     void SetSelectedFont(const wxFont& font);
 203
 204     /**
 205         Sets the page selection.  Calling this method will generate a page change event.
 206     */
 207     size_t SetSelection(size_t new_page);
 208
 209     /**
 210         Sets the tab height.  By default, the tab control height is calculated
 211         by measuring the text height and bitmap sizes on the tab captions.  Calling this
 212         method will override that calculation and set the tab control to the specified
 213         height parameter.  A call to this method will override any call to
 214         SetUniformBitmapSize().
 215         Specifying -1 as the height will return the control to its default auto-sizing
 216         behaviour.
 217     */
 218     void SetTabCtrlHeight(int height);
 219
 220     //@{
 221     /**
 222         Split performs a split operation programmatically. The argument @e page
 223         indicates
 224         the page that will be split off.  This page will also become the active page
 225         after the
 226         split.  The @e direction argument specifies where the pane should go, it should
 227         be one
 228         of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT.
 229     */
 230     void SetUniformBitmapSize(const wxSize& size);
 231     void Split(size_t page, int direction);
 232     //@}
 233
 234     /**
 235         Shows the window menu for the active tab control associated with this notebook,
 236         and returns @true if a selection was made.
 237     */
 238     bool ShowWindowMenu();
 239 };
 240
 241
 242 /**
 243     @class wxAuiTabArt
 244     @headerfile auibook.h wx/aui/auibook.h
 245
 246     Tab art class.
 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 };