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     The default theme that is used is wxAuiDefaultTabArt, which provides a modern,
  23     glossy look and feel.
  24     The theme can be changed by calling wxAuiNotebook::SetArtProvider.
  25
  26     @beginStyleTable
  27     @style{wxAUI_NB_DEFAULT_STYLE}
  28            Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE |
  29            wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB.
  30     @style{wxAUI_NB_TAB_SPLIT}
  31            Allows the tab control to be split by dragging a tab.
  32     @style{wxAUI_NB_TAB_MOVE}
  33            Allows a tab to be moved horizontally by dragging.
  34     @style{wxAUI_NB_TAB_EXTERNAL_MOVE}
  35            Allows a tab to be moved to another tab control.
  36     @style{wxAUI_NB_TAB_FIXED_WIDTH}
  37            With this style, all tabs have the same width.
  38     @style{wxAUI_NB_SCROLL_BUTTONS}
  39            With this style, left and right scroll buttons are displayed.
  40     @style{wxAUI_NB_WINDOWLIST_BUTTON}
  41            With this style, a drop-down list of windows is available.
  42     @style{wxAUI_NB_CLOSE_BUTTON}
  43            With this style, a close button is available on the tab bar.
  44     @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB}
  45            With this style, the close button is visible on the active tab.
  46     @style{wxAUI_NB_CLOSE_ON_ALL_TABS}
  47            With this style, the close button is visible on all tabs.
  48     @style{wxAUI_NB_TOP}
  49            With this style, tabs are drawn along the top of the notebook.
  50     @style{wxAUI_NB_BOTTOM}
  51            With this style, tabs are drawn along the bottom of the notebook.
  52     @endStyleTable
  53
  54     @beginEventEmissionTable{wxAuiNotebookEvent}
  55     @event{EVT_AUINOTEBOOK_PAGE_CLOSE(id, func)}
  56         A page is about to be closed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CLOSE event.
  57     @event{EVT_AUINOTEBOOK_PAGE_CHANGED(id, func)}
  58         The page selection was changed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CHANGED event.
  59     @event{EVT_AUINOTEBOOK_PAGE_CHANGING(id, func)}
  60         The page selection is about to be changed. Processes a  @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CHANGING event. This event can be vetoed.
  61     @event{EVT_AUINOTEBOOK_BUTTON(id, func)}
  62         The window list button has been pressed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BUTTON event.
  63     @event{EVT_AUINOTEBOOK_BEGIN_DRAG(id, func)}
  64         Dragging is about to begin. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BEGIN_DRAG event.
  65     @event{EVT_AUINOTEBOOK_END_DRAG(id, func)}
  66         Dragging has ended. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_END_DRAG event.
  67     @event{EVT_AUINOTEBOOK_DRAG_MOTION(id, func)}
  68         Emitted during a drag and drop operation. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_DRAG_MOTION event.
  69     @event{EVT_AUINOTEBOOK_ALLOW_DND(id, func)}
  70         Whether to allow a tab to be dropped. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_ALLOW_DND event. This event must be specially allowed.
  71     @endEventTable
  72
  73     @library{wxaui}
  74     @category{aui}
  75 */
  76 class wxAuiNotebook : public wxBookCtrlBase
  77 {
  78 public:
  79     /**
  80         Default ctor.
  81     */
  82     wxAuiNotebook();
  83
  84     /**
  85         Constructor. Creates a wxAuiNotebok control.
  86     */
  87     wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY,
  88                   const wxPoint& pos = wxDefaultPosition,
  89                   const wxSize& size = wxDefaultSize,
  90                   long style = wxAUI_NB_DEFAULT_STYLE);
  91
  92     /**
  93         Adds a page.
  94         If the @a select parameter is @true, calling this will generate a page change event.
  95     */
  96     bool AddPage(wxWindow* page, const wxString& caption,
  97                  bool select = false,
  98                  const wxBitmap& bitmap = wxNullBitmap);
  99
 100     /**
 101         Adds a new page.
 102
 103         The page must have the book control itself as the parent and must not
 104         have been added to this control previously.
 105
 106         The call to this function may generate the page changing events.
 107
 108         @param page
 109             Specifies the new page.
 110         @param text
 111             Specifies the text for the new page.
 112         @param select
 113             Specifies whether the page should be selected.
 114         @param imageId
 115             Specifies the optional image index for the new page.
 116
 117         @return @true if successful, @false otherwise.
 118
 119         @remarks Do not delete the page, it will be deleted by the book control.
 120
 121         @see InsertPage()
 122         @since 2.9.3
 123     */
 124     virtual bool AddPage(wxWindow *page, const wxString &text, bool select, int imageId);
 125
 126     /**
 127         Sets the selection to the next or previous page.
 128     */
 129     void AdvanceSelection(bool forward = true);
 130
 131     /**
 132         Changes the selection for the given page, returning the previous selection.
 133
 134         This function behaves as SetSelection() but does @em not generate the
 135         page changing events.
 136
 137         See @ref overview_events_prog for more information.
 138         @since 2.9.3
 139     */
 140     virtual int ChangeSelection(size_t n);
 141
 142     /**
 143         Creates the notebook window.
 144     */
 145     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 146                 const wxPoint& pos = wxDefaultPosition,
 147                 const wxSize& size = wxDefaultSize,
 148                 long style = 0);
 149
 150     /**
 151         Deletes all pages.
 152         @since 2.9.3
 153     */
 154     virtual bool DeleteAllPages();
 155
 156     /**
 157         Deletes a page at the given index.
 158         Calling this method will generate a page change event.
 159     */
 160     bool DeletePage(size_t page);
 161
 162     /**
 163         Returns the associated art provider.
 164     */
 165     wxAuiTabArt* GetArtProvider() const;
 166
 167     /**
 168         Returns the currently selected page or @NULL.
 169         @since 2.9.3
 170     */
 171     wxWindow* GetCurrentPage () const;
 172
 173     /**
 174         Returns the desired height of the notebook for the given page height.
 175         Use this to fit the notebook to a given page size.
 176     */
 177     int GetHeightForPageHeight(int pageHeight);
 178
 179     /**
 180         Returns the page specified by the given index.
 181     */
 182     wxWindow* GetPage(size_t page_idx) const;
 183
 184     /**
 185         Returns the tab bitmap for the page.
 186     */
 187     wxBitmap GetPageBitmap(size_t page) const;
 188
 189     /**
 190         Returns the number of pages in the notebook.
 191     */
 192     size_t GetPageCount() const;
 193
 194     /**
 195         Returns the page index for the specified window.
 196         If the window is not found in the notebook, wxNOT_FOUND is returned.
 197     */
 198     int GetPageIndex(wxWindow* page_wnd) const;
 199
 200     /**
 201         Returns the tab label for the page.
 202     */
 203     wxString GetPageText(size_t page) const;
 204
 205     /**
 206         Returns the currently selected page.
 207     */
 208     int GetSelection() const;
 209
 210     /**
 211         Returns the height of the tab control.
 212     */
 213     int GetTabCtrlHeight() const;
 214
 215     /**
 216         InsertPage() is similar to AddPage, but allows the ability to specify the
 217         insert location.
 218         If the @a select parameter is @true, calling this will generate a page change
 219         event.
 220     */
 221     bool InsertPage(size_t page_idx, wxWindow* page,
 222                     const wxString& caption,
 223                     bool select = false,
 224                     const wxBitmap& bitmap = wxNullBitmap);
 225
 226     /**
 227         Inserts a new page at the specified position.
 228
 229         @param index
 230             Specifies the position for the new page.
 231         @param page
 232             Specifies the new page.
 233         @param text
 234             Specifies the text for the new page.
 235         @param select
 236             Specifies whether the page should be selected.
 237         @param imageId
 238             Specifies the optional image index for the new page.
 239
 240         @return @true if successful, @false otherwise.
 241
 242         @remarks Do not delete the page, it will be deleted by the book control.
 243
 244         @see AddPage()
 245         @since 2.9.3
 246     */
 247     virtual bool InsertPage(size_t index, wxWindow *page, const wxString &text,
 248                             bool select=false, int imageId=NO_IMAGE);
 249
 250     /**
 251         Removes a page, without deleting the window pointer.
 252     */
 253     bool RemovePage(size_t page);
 254
 255     /**
 256         Sets the art provider to be used by the notebook.
 257     */
 258     void SetArtProvider(wxAuiTabArt* art);
 259
 260     /**
 261         Sets the font for drawing the tab labels, using a bold version of the font for
 262         selected tab labels.
 263     */
 264     virtual bool SetFont(const wxFont& font);
 265
 266     /**
 267         Sets the font for measuring tab labels.
 268     */
 269     void SetMeasuringFont(const wxFont& font);
 270
 271     /**
 272         Sets the font for drawing unselected tab labels.
 273     */
 274     void SetNormalFont(const wxFont& font);
 275
 276     /**
 277         Sets the bitmap for the page.  To remove a bitmap from the tab caption, pass
 278         wxNullBitmap.
 279     */
 280     bool SetPageBitmap(size_t page, const wxBitmap& bitmap);
 281
 282     /**
 283         Sets the image index for the given page. @a image is an index into
 284         the image list which was set with SetImageList().
 285         @since 2.9.3
 286     */
 287     virtual bool SetPageImage(size_t n, int imageId);
 288
 289     /**
 290         Sets the tab label for the page.
 291     */
 292     bool SetPageText(size_t page, const wxString& text);
 293
 294     /**
 295         Sets the font for drawing selected tab labels.
 296     */
 297     void SetSelectedFont(const wxFont& font);
 298
 299     /**
 300         Sets the page selection.  Calling this method will generate a page change event.
 301     */
 302     size_t SetSelection(size_t new_page);
 303
 304     /**
 305         Sets the tab height. By default, the tab control height is calculated
 306         by measuring the text height and bitmap sizes on the tab captions. Calling this
 307         method will override that calculation and set the tab control to the specified
 308         height parameter. A call to this method will override any call to
 309         SetUniformBitmapSize().
 310
 311         Specifying -1 as the height will return the control to its default auto-sizing
 312         behaviour.
 313     */
 314     virtual void SetTabCtrlHeight(int height);
 315
 316     //@{
 317     /**
 318         Split performs a split operation programmatically. The argument @a page
 319         indicates the page that will be split off.  This page will also become the
 320         active page after the split.
 321
 322         The @a direction argument specifies where the pane should go, it should be one
 323         of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT.
 324     */
 325     virtual void SetUniformBitmapSize(const wxSize& size);
 326     virtual void Split(size_t page, int direction);
 327     //@}
 328
 329     /**
 330         Shows the window menu for the active tab control associated with this notebook,
 331         and returns @true if a selection was made.
 332     */
 333     bool ShowWindowMenu();
 334 };
 335
 336
 337
 338 /**
 339     @class wxAuiTabArt
 340
 341     Tab art class.
 342
 343     @todo BETTER DESCRIPTION NEEDED
 344
 345     @library{wxaui}
 346     @category{aui}
 347 */
 348 class wxAuiTabArt
 349 {
 350 public:
 351     /**
 352         Constructor.
 353     */
 354     wxAuiTabArt();
 355
 356     /**
 357         Clones the art object.
 358     */
 359     virtual wxAuiTabArt* Clone() = 0;
 360
 361     /**
 362         Draws a background on the given area.
 363     */
 364     virtual void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect) = 0;
 365
 366     /**
 367         Draws a button.
 368     */
 369     virtual void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
 370                             int bitmap_id, int button_state, int orientation,
 371                             wxRect* out_rect) = 0;
 372
 373     /**
 374         Draws a tab.
 375     */
 376     virtual void DrawTab(wxDC& dc, wxWindow* wnd, const wxAuiNotebookPage& page,
 377                          const wxRect& rect, int close_button_state,
 378                          wxRect* out_tab_rect, wxRect* out_button_rect, int* x_extent) = 0;
 379
 380     /**
 381         Returns the tab control size.
 382     */
 383     virtual int GetBestTabCtrlSize(wxWindow*, const wxAuiNotebookPageArray&, const wxSize&) = 0;
 384
 385     /**
 386         Returns the indent size.
 387     */
 388     virtual int GetIndentSize() = 0;
 389
 390     /**
 391         Returns the tab size for the given caption, bitmap and state.
 392     */
 393     virtual wxSize GetTabSize(wxDC& dc, wxWindow* wnd, const wxString& caption,
 394                               const wxBitmap& bitmap, bool active,
 395                               int close_button_state, int* x_extent) = 0;
 396
 397     /**
 398         Sets flags.
 399     */
 400     virtual void SetFlags(unsigned int flags) = 0;
 401
 402     /**
 403         Sets the font used for calculating measurements.
 404     */
 405     virtual void SetMeasuringFont(const wxFont& font) = 0;
 406
 407     /**
 408         Sets the normal font for drawing labels.
 409     */
 410     virtual void SetNormalFont(const wxFont& font) = 0;
 411
 412     /**
 413         Sets the font for drawing text for selected UI elements.
 414     */
 415     virtual void SetSelectedFont(const wxFont& font) = 0;
 416
 417     /**
 418         Sets the colour of the inactive tabs.
 419
 420         @since 2.9.2
 421     */
 422     virtual void SetColour(const wxColour& colour) = 0;
 423
 424     /**
 425         Sets the colour of the selected tab.
 426
 427         @since 2.9.2
 428     */
 429     virtual void SetActiveColour(const wxColour& colour) = 0;
 430
 431     /**
 432         Sets sizing information.
 433     */
 434     virtual void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count) = 0;
 435 };
 436
 437 /**
 438     @class wxAuiNotebookEvent
 439
 440     This class is used by the events generated by wxAuiNotebook.
 441
 442     @beginEventEmissionTable{wxAuiNotebookEvent}
 443     @event{EVT_AUINOTEBOOK_PAGE_CLOSE(id, func)}
 444         A page is about to be closed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CLOSE event.
 445     @event{EVT_AUINOTEBOOK_PAGE_CHANGED(id, func)}
 446         The page selection was changed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CHANGED event.
 447     @event{EVT_AUINOTEBOOK_PAGE_CHANGING(id, func)}
 448         The page selection is about to be changed. Processes a  @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CHANGING event. This event can be vetoed.
 449     @event{EVT_AUINOTEBOOK_BUTTON(id, func)}
 450         The window list button has been pressed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BUTTON event.
 451     @event{EVT_AUINOTEBOOK_BEGIN_DRAG(id, func)}
 452         Dragging is about to begin. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BEGIN_DRAG event.
 453     @event{EVT_AUINOTEBOOK_END_DRAG(id, func)}
 454         Dragging has ended. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_END_DRAG event.
 455     @event{EVT_AUINOTEBOOK_DRAG_MOTION(id, func)}
 456         Emitted during a drag and drop operation. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_DRAG_MOTION event.
 457     @event{EVT_AUINOTEBOOK_ALLOW_DND(id, func)}
 458         Whether to allow a tab to be dropped. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_ALLOW_DND event. This event must be specially allowed.
 459     @endEventTable
 460
 461     @library{wxaui}
 462     @category{events,bookctrl}
 463
 464     @see wxAuiNotebook, wxBookCtrlEvent
 465 */
 466 class wxAuiNotebookEvent : public wxBookCtrlEvent
 467 {
 468 public:
 469     /**
 470         Constructor.
 471     */
 472     wxAuiNotebookEvent(wxEventType command_type = wxEVT_NULL, int win_id = 0);
 473
 474     wxEvent *Clone();
 475 };
 476