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