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