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