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. Do not
  17     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     @library{wxcore}
  43     @category{miscwnd}
  44
  45     @see wxBookCtrl, wxBookCtrlEvent, wxImageList, @ref page_samples_notebook
  46 */
  47 class wxNotebook : public wxBookCtrl
  48 {
  49 public:
  50
  51     /**
  52         Constructs a notebook control.
  53     */
  54     wxNotebook();
  55
  56     /**
  57         Constructs a notebook control.
  58         Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN
  59         window style.
  60
  61         @param parent
  62             The parent window. Must be non-@NULL.
  63         @param id
  64             The window identifier.
  65         @param pos
  66             The window position.
  67         @param size
  68             The window size.
  69         @param style
  70             The window style. See wxNotebook.
  71         @param name
  72             The name of the control.
  73     */
  74     wxNotebook(wxWindow* parent, wxWindowID id,
  75                const wxPoint& pos = wxDefaultPosition,
  76                const wxSize& size = wxDefaultSize,
  77                long style = 0,
  78                const wxString& name = wxNotebookNameStr);
  79
  80     /**
  81         Destroys the wxNotebook object.
  82     */
  83     virtual ~wxNotebook();
  84
  85     /**
  86         Adds a new page.
  87         The call to this function may generate the page changing events.
  88
  89         @param page
  90             Specifies the new page.
  91         @param text
  92             Specifies the text for the new page.
  93         @param select
  94             Specifies whether the page should be selected.
  95         @param imageId
  96             Specifies the optional image index for the new page.
  97
  98         @return @true if successful, @false otherwise.
  99
 100         @remarks Do not delete the page, it will be deleted by the notebook.
 101
 102         @see InsertPage()
 103     */
 104     bool AddPage(wxNotebookPage* page, const wxString& text,
 105                  bool select = false,
 106                  int imageId = -1);
 107
 108     /**
 109         Cycles through the tabs.
 110         The call to this function generates the page changing events.
 111     */
 112     void AdvanceSelection(bool forward = true);
 113
 114     /**
 115         Sets the image list for the page control and takes ownership of the list.
 116
 117         @see wxImageList, SetImageList()
 118     */
 119     void AssignImageList(wxImageList* imageList);
 120
 121     /**
 122         Changes the selection for the given page, returning the previous selection.
 123
 124         The call to this function does NOT generate the page changing events.
 125         This is the only difference with SetSelection().
 126         See @ref overview_eventhandling_prog for more infomation.
 127     */
 128     virtual int ChangeSelection(size_t page);
 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         Deletes all pages.
 142     */
 143     virtual bool DeleteAllPages();
 144
 145     /**
 146         Deletes the specified page, and the associated window.
 147         The call to this function generates the page changing events.
 148     */
 149     bool DeletePage(size_t page);
 150
 151     /**
 152         Returns the currently selected notebook page or @NULL.
 153     */
 154     wxWindow* GetCurrentPage() const;
 155
 156     /**
 157         Returns the associated image list.
 158
 159         @see wxImageList, SetImageList()
 160     */
 161     wxImageList* GetImageList() const;
 162
 163     /**
 164         Returns the window at the given page position.
 165     */
 166     wxNotebookPage* GetPage(size_t page);
 167
 168     /**
 169         Returns the number of pages in the notebook control.
 170     */
 171     size_t GetPageCount() const;
 172
 173     /**
 174         Returns the image index for the given page.
 175     */
 176     virtual int GetPageImage(size_t nPage) const;
 177
 178     /**
 179         Returns the string for the given page.
 180     */
 181     virtual wxString GetPageText(size_t nPage) const;
 182
 183     /**
 184         Returns the number of rows in the notebook control.
 185     */
 186     virtual int GetRowCount() const;
 187
 188     /**
 189         Returns the currently selected page, or -1 if none was selected.
 190
 191         Note that this method may return either the previously or newly
 192         selected page when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler
 193         depending on the platform and so wxBookCtrlEvent::GetSelection should be
 194         used instead in this case.
 195     */
 196     virtual int GetSelection() const;
 197
 198     /**
 199         If running under Windows and themes are enabled for the application, this
 200         function returns a suitable colour for painting the background of a notebook
 201         page, and can be passed to SetBackgroundColour().
 202
 203         Otherwise, an uninitialised colour will be returned.
 204     */
 205     virtual wxColour GetThemeBackgroundColour() const;
 206
 207     /**
 208         Returns the index of the tab at the specified position or @c wxNOT_FOUND
 209         if none. If @a flags parameter is non-@NULL, the position of the point
 210         inside the tab is returned as well.
 211
 212         @param pt
 213             Specifies the point for the hit test.
 214         @param flags
 215             Return value for detailed information. One of the following values:
 216             <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
 217             <TD>There was no tab under this point.</TD></TR>
 218             <TR><TD>wxBK_HITTEST_ONICON</TD>
 219             <TD>The point was over an icon (currently wxMSW only).</TD></TR>
 220             <TR><TD>wxBK_HITTEST_ONLABEL</TD>
 221             <TD>The point was over a label (currently wxMSW only).</TD></TR>
 222             <TR><TD>wxBK_HITTEST_ONITEM</TD>
 223             <TD>The point was over an item, but not on the label or icon.</TD></TR>
 224             <TR><TD>wxBK_HITTEST_ONPAGE</TD>
 225             <TD>The point was over a currently selected page, not over any tab.
 226             Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
 227             </TABLE>
 228
 229         @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
 230                 tab at the specified position.
 231     */
 232     virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
 233
 234     /**
 235         Inserts a new page at the specified position.
 236
 237         @param index
 238             Specifies the position for the new page.
 239         @param page
 240             Specifies the new page.
 241         @param text
 242             Specifies the text for the new page.
 243         @param select
 244             Specifies whether the page should be selected.
 245         @param imageId
 246             Specifies the optional image index for the new page.
 247
 248         @return @true if successful, @false otherwise.
 249
 250         @remarks Do not delete the page, it will be deleted by the notebook.
 251
 252         @see AddPage()
 253     */
 254     virtual bool InsertPage(size_t index, wxNotebookPage* page,
 255                             const wxString& text, bool select = false,
 256                             int imageId = -1);
 257
 258     /**
 259         An event handler function, called when the page selection is changed.
 260
 261         @see wxBookCtrlEvent
 262     */
 263     void OnSelChange(wxBookCtrlEvent& event);
 264
 265     /**
 266         Deletes the specified page, without deleting the associated window.
 267     */
 268     bool RemovePage(size_t page);
 269
 270     /**
 271         Sets the image list for the page control.
 272         It does not take ownership of the image list, you must delete it yourself.
 273
 274         @see wxImageList, AssignImageList()
 275     */
 276     void SetImageList(wxImageList* imageList);
 277
 278     /**
 279         Sets the amount of space around each page's icon and label, in pixels.
 280
 281         @note The vertical padding cannot be changed in wxGTK.
 282     */
 283     virtual void SetPadding(const wxSize& padding);
 284
 285     /**
 286         Sets the image index for the given page. @a image is an index into
 287         the image list which was set with SetImageList().
 288     */
 289     virtual bool SetPageImage(size_t page, int image);
 290
 291     /**
 292         Sets the width and height of the pages.
 293
 294         @note This method is currently not implemented for wxGTK.
 295     */
 296     virtual void SetPageSize(const wxSize& size);
 297
 298     /**
 299         Sets the text for the given page.
 300     */
 301     virtual bool SetPageText(size_t page, const wxString& text);
 302
 303     /**
 304         Sets the selection for the given page, returning the previous selection.
 305         The call to this function generates the page changing events.
 306
 307         @deprecated
 308         This function is deprecated and should not be used in new code.
 309         Please use the ChangeSelection() function instead.
 310
 311         @see GetSelection()
 312     */
 313     virtual int SetSelection(size_t page);
 314 };
 315