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 (note that wxAuiNotebook does not derive from 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
  58     @beginEventTable{wxAuiNotebookEvent}
  59     @event{EVT_AUINOTEBOOK_PAGE_CLOSE(id, func)}
  60         Provide description.
  61     @event{EVT_AUINOTEBOOK_PAGE_CHANGED(id, func)}
  62         Provide description.
  63     @event{EVT_AUINOTEBOOK_PAGE_CHANGING(id, func)}
  64         Provide description.
  65     @event{EVT_AUINOTEBOOK_BUTTON(id, func)}
  66         Provide description.
  67     @event{EVT_AUINOTEBOOK_BEGIN_DRAG(id, func)}
  68         Provide description.
  69     @event{EVT_AUINOTEBOOK_END_DRAG(id, func)}
  70         Provide description.
  71     @event{EVT_AUINOTEBOOK_DRAG_MOTION(id, func)}
  72         Provide description.
  73     @event{EVT_AUINOTEBOOK_ALLOW_DND(id, func)}
  74         Provide description.
  75     @endEventTable
  76
  77     @todo provide description for the events above.
  78
  79     @library{wxaui}
  80     @category{aui}
  81 */
  82 class wxAuiNotebook : public wxControl
  83 {
  84 public:
  85     /**
  86         Default ctor.
  87     */
  88     wxAuiNotebook();
  89
  90     /**
  91         Constructor. Creates a wxAuiNotebok control.
  92     */
  93     wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY,
  94                   const wxPoint& pos = wxDefaultPosition,
  95                   const wxSize& size = wxDefaultSize,
  96                   long style = wxAUI_NB_DEFAULT_STYLE);
  97
  98     /**
  99         Adds a page.
 100         If the @a select parameter is @true, calling this will generate a page change event.
 101     */
 102     bool AddPage(wxWindow* page, const wxString& caption,
 103                  bool select = false,
 104                  const wxBitmap& bitmap = wxNullBitmap);
 105
 106     /**
 107         Sets the selection to the next or previous page.
 108     */
 109     void AdvanceSelection(bool forward = true);
 110
 111     /**
 112         Creates the notebook window.
 113     */
 114     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 115                 const wxPoint& pos = wxDefaultPosition,
 116                 const wxSize& size = wxDefaultSize,
 117                 long style = 0);
 118
 119     /**
 120         Deletes a page at the given index.
 121         Calling this method will generate a page change event.
 122     */
 123     bool DeletePage(size_t page);
 124
 125     /**
 126         Returns the associated art provider.
 127     */
 128     wxAuiTabArt* GetArtProvider() const;
 129
 130     /**
 131         Returns the desired height of the notebook for the given page height.
 132         Use this to fit the notebook to a given page size.
 133     */
 134     int GetHeightForPageHeight(int pageHeight);
 135
 136     /**
 137         Returns the page specified by the given index.
 138     */
 139     wxWindow* GetPage(size_t page_idx) const;
 140
 141     /**
 142         Returns the tab bitmap for the page.
 143     */
 144     wxBitmap GetPageBitmap(size_t page) const;
 145
 146     /**
 147         Returns the number of pages in the notebook.
 148     */
 149     size_t GetPageCount() const;
 150
 151     /**
 152         Returns the page index for the specified window.
 153         If the window is not found in the notebook, wxNOT_FOUND is returned.
 154     */
 155     int GetPageIndex(wxWindow* page_wnd) const;
 156
 157     /**
 158         Returns the tab label for the page.
 159     */
 160     wxString GetPageText(size_t page) const;
 161
 162     /**
 163         Returns the currently selected page.
 164     */
 165     int GetSelection() const;
 166
 167     /**
 168         Returns the height of the tab control.
 169     */
 170     int GetTabCtrlHeight() const;
 171
 172     /**
 173         InsertPage() is similar to AddPage, but allows the ability to specify the
 174         insert location.
 175         If the @a select parameter is @true, calling this will generate a page change
 176         event.
 177     */
 178     bool InsertPage(size_t page_idx, wxWindow* page,
 179                     const wxString& caption,
 180                     bool select = false,
 181                     const wxBitmap& bitmap = wxNullBitmap);
 182
 183     /**
 184         Removes a page, without deleting the window pointer.
 185     */
 186     bool RemovePage(size_t page);
 187
 188     /**
 189         Sets the art provider to be used by the notebook.
 190     */
 191     void SetArtProvider(wxAuiTabArt* art);
 192
 193     /**
 194         Sets the font for drawing the tab labels, using a bold version of the font for
 195         selected tab labels.
 196     */
 197     virtual bool SetFont(const wxFont& font);
 198
 199     /**
 200         Sets the font for measuring tab labels.
 201     */
 202     void SetMeasuringFont(const wxFont& font);
 203
 204     /**
 205         Sets the font for drawing unselected tab labels.
 206     */
 207     void SetNormalFont(const wxFont& font);
 208
 209     /**
 210         Sets the bitmap for the page.  To remove a bitmap from the tab caption, pass
 211         wxNullBitmap.
 212     */
 213     bool SetPageBitmap(size_t page, const wxBitmap& bitmap);
 214
 215     /**
 216         Sets the tab label for the page.
 217     */
 218     bool SetPageText(size_t page, const wxString& text);
 219
 220     /**
 221         Sets the font for drawing selected tab labels.
 222     */
 223     void SetSelectedFont(const wxFont& font);
 224
 225     /**
 226         Sets the page selection.  Calling this method will generate a page change event.
 227     */
 228     size_t SetSelection(size_t new_page);
 229
 230     /**
 231         Sets the tab height. By default, the tab control height is calculated
 232         by measuring the text height and bitmap sizes on the tab captions. Calling this
 233         method will override that calculation and set the tab control to the specified
 234         height parameter. A call to this method will override any call to
 235         SetUniformBitmapSize().
 236
 237         Specifying -1 as the height will return the control to its default auto-sizing
 238         behaviour.
 239     */
 240     virtual void SetTabCtrlHeight(int height);
 241
 242     //@{
 243     /**
 244         Split performs a split operation programmatically. The argument @a page
 245         indicates the page that will be split off.  This page will also become the
 246         active page after the split.
 247
 248         The @a direction argument specifies where the pane should go, it should be one
 249         of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT.
 250     */
 251     void SetUniformBitmapSize(const wxSize& size);
 252     void Split(size_t page, int direction);
 253     //@}
 254
 255     /**
 256         Shows the window menu for the active tab control associated with this notebook,
 257         and returns @true if a selection was made.
 258     */
 259     bool ShowWindowMenu();
 260 };
 261
 262
 263
 264 /**
 265     @class wxAuiTabArt
 266
 267     Tab art class.
 268
 269     @todo BETTER DESCRIPTION NEEDED
 270
 271     @library{wxaui}
 272     @category{aui}
 273 */
 274 class wxAuiTabArt
 275 {
 276 public:
 277     /**
 278         Constructor.
 279     */
 280     wxAuiTabArt();
 281
 282     /**
 283         Clones the art object.
 284     */
 285     virtual wxAuiTabArt* Clone() = 0;
 286
 287     /**
 288         Draws a background on the given area.
 289     */
 290     virtual void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect) = 0;
 291
 292     /**
 293         Draws a button.
 294     */
 295     virtual void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
 296                             int bitmap_id, int button_state, int orientation,
 297                             wxRect* out_rect) = 0;
 298
 299     /**
 300         Draws a tab.
 301     */
 302     virtual void DrawTab(wxDC& dc, wxWindow* wnd, const wxAuiNotebookPage& page,
 303                          const wxRect& rect, int close_button_state,
 304                          wxRect* out_tab_rect, wxRect* out_button_rect, int* x_extent) = 0;
 305
 306     /**
 307         Returns the tab control size.
 308     */
 309     virtual int GetBestTabCtrlSize(wxWindow*, const wxAuiNotebookPageArray&, const wxSize&) = 0;
 310
 311     /**
 312         Returns the indent size.
 313     */
 314     virtual int GetIndentSize() = 0;
 315
 316     /**
 317         Returns the tab size for the given caption, bitmap and state.
 318     */
 319     virtual wxSize GetTabSize(wxDC& dc, wxWindow* wnd, const wxString& caption,
 320                               const wxBitmap& bitmap, bool active,
 321                               int close_button_state, int* x_extent) = 0;
 322
 323     /**
 324         Sets flags.
 325     */
 326     virtual void SetFlags(unsigned int flags) = 0;
 327
 328     /**
 329         Sets the font used for calculating measurements.
 330     */
 331     virtual void SetMeasuringFont(const wxFont& font) = 0;
 332
 333     /**
 334         Sets the normal font for drawing labels.
 335     */
 336     virtual void SetNormalFont(const wxFont& font) = 0;
 337
 338     /**
 339         Sets the font for drawing text for selected UI elements.
 340     */
 341     virtual void SetSelectedFont(const wxFont& font) = 0;
 342
 343     /**
 344         Sets sizing information.
 345     */
 346     virtual void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count) = 0;
 347 };
 348