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