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 tooltip for the tab label of the page.
 224
 225         @since 2.9.4
 226     */
 227     wxString GetPageToolTip(size_t pageIdx) const;
 228
 229     /**
 230         Returns the currently selected page.
 231     */
 232     int GetSelection() const;
 233
 234     /**
 235         Returns the height of the tab control.
 236     */
 237     int GetTabCtrlHeight() const;
 238
 239     /**
 240         InsertPage() is similar to AddPage, but allows the ability to specify the
 241         insert location.
 242         If the @a select parameter is @true, calling this will generate a page change
 243         event.
 244     */
 245     bool InsertPage(size_t page_idx, wxWindow* page,
 246                     const wxString& caption,
 247                     bool select = false,
 248                     const wxBitmap& bitmap = wxNullBitmap);
 249
 250     /**
 251         Inserts a new page at the specified position.
 252
 253         @param index
 254             Specifies the position for the new page.
 255         @param page
 256             Specifies the new page.
 257         @param text
 258             Specifies the text for the new page.
 259         @param select
 260             Specifies whether the page should be selected.
 261         @param imageId
 262             Specifies the optional image index for the new page.
 263
 264         @return @true if successful, @false otherwise.
 265
 266         @remarks Do not delete the page, it will be deleted by the book control.
 267
 268         @see AddPage()
 269         @since 2.9.3
 270     */
 271     virtual bool InsertPage(size_t index, wxWindow *page, const wxString &text,
 272                             bool select=false, int imageId=NO_IMAGE);
 273
 274     /**
 275         Removes a page, without deleting the window pointer.
 276     */
 277     bool RemovePage(size_t page);
 278
 279     /**
 280         Sets the art provider to be used by the notebook.
 281     */
 282     void SetArtProvider(wxAuiTabArt* art);
 283
 284     /**
 285         Sets the font for drawing the tab labels, using a bold version of the font for
 286         selected tab labels.
 287     */
 288     virtual bool SetFont(const wxFont& font);
 289
 290     /**
 291         Sets the font for measuring tab labels.
 292     */
 293     void SetMeasuringFont(const wxFont& font);
 294
 295     /**
 296         Sets the font for drawing unselected tab labels.
 297     */
 298     void SetNormalFont(const wxFont& font);
 299
 300     /**
 301         Sets the bitmap for the page.  To remove a bitmap from the tab caption, pass
 302         wxNullBitmap.
 303     */
 304     bool SetPageBitmap(size_t page, const wxBitmap& bitmap);
 305
 306     /**
 307         Sets the image index for the given page. @a image is an index into
 308         the image list which was set with SetImageList().
 309         @since 2.9.3
 310     */
 311     virtual bool SetPageImage(size_t n, int imageId);
 312
 313     /**
 314         Sets the tab label for the page.
 315     */
 316     bool SetPageText(size_t page, const wxString& text);
 317
 318     /**
 319         Sets the tooltip displayed when hovering over the tab label of the page.
 320
 321         @return
 322             @true if tooltip was updated, @false if it failed, e.g. because the
 323             page index is invalid.
 324
 325         @since 2.9.4
 326     */
 327     bool SetPageToolTip(size_t page, const wxString& text);
 328
 329     /**
 330         Sets the font for drawing selected tab labels.
 331     */
 332     void SetSelectedFont(const wxFont& font);
 333
 334     /**
 335         Sets the page selection.  Calling this method will generate a page change event.
 336     */
 337     size_t SetSelection(size_t new_page);
 338
 339     /**
 340         Sets the tab height. By default, the tab control height is calculated
 341         by measuring the text height and bitmap sizes on the tab captions. Calling this
 342         method will override that calculation and set the tab control to the specified
 343         height parameter. A call to this method will override any call to
 344         SetUniformBitmapSize().
 345
 346         Specifying -1 as the height will return the control to its default auto-sizing
 347         behaviour.
 348     */
 349     virtual void SetTabCtrlHeight(int height);
 350
 351     //@{
 352     /**
 353         Split performs a split operation programmatically. The argument @a page
 354         indicates the page that will be split off.  This page will also become the
 355         active page after the split.
 356
 357         The @a direction argument specifies where the pane should go, it should be one
 358         of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT.
 359     */
 360     virtual void SetUniformBitmapSize(const wxSize& size);
 361     virtual void Split(size_t page, int direction);
 362     //@}
 363
 364     /**
 365         Shows the window menu for the active tab control associated with this notebook,
 366         and returns @true if a selection was made.
 367     */
 368     bool ShowWindowMenu();
 369 };
 370
 371
 372
 373 /**
 374     @class wxAuiTabArt
 375
 376     Tab art class.
 377
 378     @todo BETTER DESCRIPTION NEEDED
 379
 380     @library{wxaui}
 381     @category{aui}
 382 */
 383 class wxAuiTabArt
 384 {
 385 public:
 386     /**
 387         Constructor.
 388     */
 389     wxAuiTabArt();
 390
 391     /**
 392         Clones the art object.
 393     */
 394     virtual wxAuiTabArt* Clone() = 0;
 395
 396     /**
 397         Draws a background on the given area.
 398     */
 399     virtual void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect) = 0;
 400
 401     /**
 402         Draws a button.
 403     */
 404     virtual void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
 405                             int bitmap_id, int button_state, int orientation,
 406                             wxRect* out_rect) = 0;
 407
 408     /**
 409         Draws a tab.
 410     */
 411     virtual void DrawTab(wxDC& dc, wxWindow* wnd, const wxAuiNotebookPage& page,
 412                          const wxRect& rect, int close_button_state,
 413                          wxRect* out_tab_rect, wxRect* out_button_rect, int* x_extent) = 0;
 414
 415     /**
 416         Returns the tab control size.
 417     */
 418     virtual int GetBestTabCtrlSize(wxWindow*, const wxAuiNotebookPageArray&, const wxSize&) = 0;
 419
 420     /**
 421         Returns the indent size.
 422     */
 423     virtual int GetIndentSize() = 0;
 424
 425     /**
 426         Returns the tab size for the given caption, bitmap and state.
 427     */
 428     virtual wxSize GetTabSize(wxDC& dc, wxWindow* wnd, const wxString& caption,
 429                               const wxBitmap& bitmap, bool active,
 430                               int close_button_state, int* x_extent) = 0;
 431
 432     /**
 433         Sets flags.
 434     */
 435     virtual void SetFlags(unsigned int flags) = 0;
 436
 437     /**
 438         Sets the font used for calculating measurements.
 439     */
 440     virtual void SetMeasuringFont(const wxFont& font) = 0;
 441
 442     /**
 443         Sets the normal font for drawing labels.
 444     */
 445     virtual void SetNormalFont(const wxFont& font) = 0;
 446
 447     /**
 448         Sets the font for drawing text for selected UI elements.
 449     */
 450     virtual void SetSelectedFont(const wxFont& font) = 0;
 451
 452     /**
 453         Sets the colour of the inactive tabs.
 454
 455         @since 2.9.2
 456     */
 457     virtual void SetColour(const wxColour& colour) = 0;
 458
 459     /**
 460         Sets the colour of the selected tab.
 461
 462         @since 2.9.2
 463     */
 464     virtual void SetActiveColour(const wxColour& colour) = 0;
 465
 466     /**
 467         Sets sizing information.
 468     */
 469     virtual void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count) = 0;
 470 };
 471
 472 /**
 473     @class wxAuiNotebookEvent
 474
 475     This class is used by the events generated by wxAuiNotebook.
 476
 477     @beginEventEmissionTable{wxAuiNotebookEvent}
 478     @event{EVT_AUINOTEBOOK_PAGE_CLOSE(id, func)}
 479         A page is about to be closed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CLOSE event.
 480     @event{EVT_AUINOTEBOOK_PAGE_CLOSED(winid, fn)}
 481         A page has been closed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CLOSED event.
 482     @event{EVT_AUINOTEBOOK_PAGE_CHANGED(id, func)}
 483         The page selection was changed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CHANGED event.
 484     @event{EVT_AUINOTEBOOK_PAGE_CHANGING(id, func)}
 485         The page selection is about to be changed. Processes a  @c wxEVT_COMMAND_AUINOTEBOOK_PAGE_CHANGING event. This event can be vetoed.
 486     @event{EVT_AUINOTEBOOK_BUTTON(id, func)}
 487         The window list button has been pressed. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BUTTON event.
 488     @event{EVT_AUINOTEBOOK_BEGIN_DRAG(id, func)}
 489         Dragging is about to begin. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BEGIN_DRAG event.
 490     @event{EVT_AUINOTEBOOK_END_DRAG(id, func)}
 491         Dragging has ended. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_END_DRAG event.
 492     @event{EVT_AUINOTEBOOK_DRAG_MOTION(id, func)}
 493         Emitted during a drag and drop operation. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_DRAG_MOTION event.
 494     @event{EVT_AUINOTEBOOK_ALLOW_DND(id, func)}
 495         Whether to allow a tab to be dropped. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_ALLOW_DND event. This event must be specially allowed.
 496     @event{EVT_AUINOTEBOOK_DRAG_DONE(winid, fn)}
 497         Notify that the tab has been dragged. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_DRAG_DONE event.
 498     @event{EVT_AUINOTEBOOK_TAB_MIDDLE_DOWN(winid, fn)}
 499         The middle mouse button is pressed on a tab. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_TAB_MIDDLE_DOWN event.
 500     @event{EVT_AUINOTEBOOK_TAB_MIDDLE_UP(winid, fn)}
 501         The middle mouse button is released on a tab. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_TAB_MIDDLE_UP event.
 502     @event{EVT_AUINOTEBOOK_TAB_RIGHT_DOWN(winid, fn)}
 503         The right mouse button is pressed on a tab. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_TAB_RIGHT_DOWN event.
 504     @event{EVT_AUINOTEBOOK_TAB_RIGHT_UP(winid, fn)}
 505         The right mouse button is released on a tab. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_TAB_RIGHT_UP event.
 506     @event{EVT_AUINOTEBOOK_BG_DCLICK(winid, fn)}
 507         Double clicked on the tabs background area. Processes a @c wxEVT_COMMAND_AUINOTEBOOK_BG_DCLICK event.
 508     @endEventTable
 509
 510     @library{wxaui}
 511     @category{events,bookctrl}
 512
 513     @see wxAuiNotebook, wxBookCtrlEvent
 514 */
 515 class wxAuiNotebookEvent : public wxBookCtrlEvent
 516 {
 517 public:
 518     /**
 519         Constructor.
 520     */
 521     wxAuiNotebookEvent(wxEventType command_type = wxEVT_NULL, int win_id = 0);
 522
 523     wxEvent *Clone();
 524 };
 525