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.Ok())
  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
  90     @see wxBookCtrl, wxBookCtrlEvent, wxImageList, @ref page_samples_notebook
  91 */
  92 class wxNotebook : public wxBookCtrlBase
  93 {
  94 public:
  95
  96     /**
  97         Constructs a notebook control.
  98     */
  99     wxNotebook();
 100
 101     /**
 102         Constructs a notebook control.
 103         Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN
 104         window style.
 105
 106         @param parent
 107             The parent window. Must be non-@NULL.
 108         @param id
 109             The window identifier.
 110         @param pos
 111             The window position.
 112         @param size
 113             The window size.
 114         @param style
 115             The window style. See wxNotebook.
 116         @param name
 117             The name of the control.
 118     */
 119     wxNotebook(wxWindow* parent, wxWindowID id,
 120                const wxPoint& pos = wxDefaultPosition,
 121                const wxSize& size = wxDefaultSize,
 122                long style = 0,
 123                const wxString& name = wxNotebookNameStr);
 124
 125     /**
 126         Destroys the wxNotebook object.
 127     */
 128     virtual ~wxNotebook();
 129
 130     /**
 131         Creates a notebook control.
 132         See wxNotebook() for a description of the parameters.
 133     */
 134     bool Create(wxWindow* parent, wxWindowID id,
 135                 const wxPoint& pos = wxDefaultPosition,
 136                 const wxSize& size = wxDefaultSize,
 137                 long style = 0,
 138                 const wxString& name = wxNotebookNameStr);
 139
 140
 141     /**
 142         Returns the number of rows in the notebook control.
 143     */
 144     virtual int GetRowCount() const;
 145
 146     /**
 147         If running under Windows and themes are enabled for the application, this
 148         function returns a suitable colour for painting the background of a notebook
 149         page, and can be passed to SetBackgroundColour().
 150
 151         Otherwise, an uninitialised colour will be returned.
 152     */
 153     virtual wxColour GetThemeBackgroundColour() const;
 154
 155     /**
 156         An event handler function, called when the page selection is changed.
 157
 158         @see wxBookCtrlEvent
 159     */
 160     void OnSelChange(wxBookCtrlEvent& event);
 161
 162     /**
 163         Sets the amount of space around each page's icon and label, in pixels.
 164
 165         @note The vertical padding cannot be changed in wxGTK.
 166     */
 167     virtual void SetPadding(const wxSize& padding);
 168 };
 169