interface/wx/notebook.h

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