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