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