interface/wx/notebook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        notebook.h
   3 // Purpose:     interface of wxNotebook
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxNotebook
  11
  12     This class represents a notebook control, which manages multiple windows with
  13     associated tabs.
  14
  15     To use the class, create a wxNotebook object and call wxNotebook::AddPage
  16     or wxNotebook::InsertPage, passing a window to be used as the page.
  17     Do not explicitly delete the window for a page that is currently managed by
  18     wxNotebook.
  19
  20     @b wxNotebookPage is a typedef for wxWindow.
  21
  22     @beginStyleTable
  23     @style{wxNB_TOP}
  24            Place tabs on the top side.
  25     @style{wxNB_LEFT}
  26            Place tabs on the left side.
  27     @style{wxNB_RIGHT}
  28            Place tabs on the right side.
  29     @style{wxNB_BOTTOM}
  30            Place tabs under instead of above the notebook pages.
  31     @style{wxNB_FIXEDWIDTH}
  32            (Windows only) All tabs will have same width.
  33     @style{wxNB_MULTILINE}
  34            (Windows only) There can be several rows of tabs.
  35     @style{wxNB_NOPAGETHEME}
  36            (Windows only) Display a solid colour on notebook pages, and not a
  37            gradient, which can reduce performance.
  38     @style{wxNB_FLAT}
  39            (Windows CE only) Show tabs in a flat style.
  40     @endStyleTable
  41
  42     The styles wxNB_LEFT, RIGHT and BOTTOM are not supported under
  43     Microsoft Windows XP when using visual themes.
  44
  45     @beginEventTable{wxBookCtrlEvent}
  46     @event{EVT_NOTEBOOK_PAGE_CHANGED(id, func)}
  47         The page selection was changed.
  48         Processes a @c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED event.
  49     @event{EVT_NOTEBOOK_PAGE_CHANGING(id, func)}
  50         The page selection is about to be changed.
  51         Processes a @c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING event.
  52         This event can be vetoed.
  53     @endEventTable
  54
  55
  56     @section notebook_bg Page backgrounds
  57
  58     On Windows XP, the default theme paints a gradient on the notebook's pages.
  59     If you wish to suppress this theme, for aesthetic or performance reasons,
  60     there are three ways of doing it.
  61     You can use @c wxNB_NOPAGETHEME to disable themed drawing for a particular
  62     notebook, you can call wxSystemOptions::SetOption to disable it for the
  63     whole application, or you can disable it for individual pages by using
  64     SetBackgroundColour().
  65
  66     To disable themed pages globally:
  67     @code
  68     wxSystemOptions::SetOption(wxT("msw.notebook.themed-background"), 0);
  69     @endcode
  70
  71     Set the value to 1 to enable it again.
  72     To give a single page a solid background that more or less fits in with the
  73     overall theme, use:
  74     @code
  75     wxColour col = notebook->GetThemeBackgroundColour();
  76     if (col.IsOk())
  77     {
  78         page->SetBackgroundColour(col);
  79     }
  80     @endcode
  81
  82     On platforms other than Windows, or if the application is not using Windows
  83     themes, GetThemeBackgroundColour() will return an uninitialised colour object,
  84     and the above code will therefore work on all platforms.
  85
  86
  87     @library{wxcore}
  88     @category{miscwnd}
  89     @appearance{notebook.png}
  90
  91     @see wxBookCtrl, wxBookCtrlEvent, wxImageList, @ref page_samples_notebook
  92 */
  93 class wxNotebook : public wxBookCtrlBase
  94 {
  95 public:
  96
  97     /**
  98         Constructs a notebook control.
  99     */
 100     wxNotebook();
 101
 102     /**
 103         Constructs a notebook control.
 104         Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN
 105         window style.
 106
 107         @param parent
 108             The parent window. Must be non-@NULL.
 109         @param id
 110             The window identifier.
 111         @param pos
 112             The window position.
 113         @param size
 114             The window size.
 115         @param style
 116             The window style. See wxNotebook.
 117         @param name
 118             The name of the control.
 119     */
 120     wxNotebook(wxWindow* parent, wxWindowID id,
 121                const wxPoint& pos = wxDefaultPosition,
 122                const wxSize& size = wxDefaultSize,
 123                long style = 0,
 124                const wxString& name = wxNotebookNameStr);
 125
 126     /**
 127         Destroys the wxNotebook object.
 128     */
 129     virtual ~wxNotebook();
 130
 131     /**
 132         Creates a notebook control.
 133         See wxNotebook() for a description of the parameters.
 134     */
 135     bool Create(wxWindow* parent, wxWindowID id,
 136                 const wxPoint& pos = wxDefaultPosition,
 137                 const wxSize& size = wxDefaultSize,
 138                 long style = 0,
 139                 const wxString& name = wxNotebookNameStr);
 140
 141
 142     /**
 143         Returns the number of rows in the notebook control.
 144     */
 145     virtual int GetRowCount() const;
 146
 147     /**
 148         If running under Windows and themes are enabled for the application, this
 149         function returns a suitable colour for painting the background of a notebook
 150         page, and can be passed to SetBackgroundColour().
 151
 152         Otherwise, an uninitialised colour will be returned.
 153     */
 154     virtual wxColour GetThemeBackgroundColour() const;
 155
 156     /**
 157         An event handler function, called when the page selection is changed.
 158
 159         @see wxBookCtrlEvent
 160     */
 161     void OnSelChange(wxBookCtrlEvent& event);
 162
 163     /**
 164         Sets the amount of space around each page's icon and label, in pixels.
 165
 166         @note The vertical padding cannot be changed in wxGTK.
 167     */
 168     virtual void SetPadding(const wxSize& padding);
 169 };
 170