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