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     virtual 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     virtual 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     virtual wxAuiTabArt* Clone() = 0;
 263
 264     /**
 265         Draws a background on the given area.
 266     */
 267     virtual void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect) = 0;
 268
 269     /**
 270         Draws a button.
 271     */
 272     virtual void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
 273                             int bitmap_id, int button_state, int orientation,
 274                             wxRect* out_rect) = 0;
 275
 276     /**
 277         Draws a tab.
 278     */
 279     virtual void DrawTab(wxDC& dc, wxWindow* wnd, const wxAuiNotebookPage& page,
 280                          const wxRect& rect, int close_button_state,
 281                          wxRect* out_tab_rect, wxRect* out_button_rect, int* x_extent) = 0;
 282
 283     /**
 284         Returns the tab control size.
 285     */
 286     virtual int GetBestTabCtrlSize(wxWindow*, const wxAuiNotebookPageArray&, const wxSize&) = 0;
 287
 288     /**
 289         Returns the indent size.
 290     */
 291     virtual int GetIndentSize() = 0;
 292
 293     /**
 294         Returns the tab size for the given caption, bitmap and state.
 295     */
 296     virtual wxSize GetTabSize(wxDC& dc, wxWindow* wnd, const wxString& caption,
 297                               const wxBitmap& bitmap, bool active,
 298                               int close_button_state, int* x_extent) = 0;
 299
 300     /**
 301         Sets flags.
 302     */
 303     virtual void SetFlags(unsigned int flags) = 0;
 304
 305     /**
 306         Sets the font used for calculating measurements.
 307     */
 308     virtual void SetMeasuringFont(const wxFont& font) = 0;
 309
 310     /**
 311         Sets the normal font for drawing labels.
 312     */
 313     virtual void SetNormalFont(const wxFont& font) = 0;
 314
 315     /**
 316         Sets the font for drawing text for selected UI elements.
 317     */
 318     virtual void SetSelectedFont(const wxFont& font) = 0;
 319
 320     /**
 321         Sets sizing information.
 322     */
 323     virtual void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count) = 0;
 324 };
 325