interface/notebook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        notebook.h
   3 // Purpose:     documentation for wxNotebookEvent class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxNotebookEvent
  11     @wxheader{notebook.h}
  12
  13     This class represents the events generated by a notebook control: currently,
  14     there are two of them. The PAGE_CHANGING event is sent before the current
  15     page is changed. It allows the program to examine the current page (which
  16     can be retrieved with
  17     wxNotebookEvent::GetOldSelection) and to veto the page
  18     change by calling wxNotifyEvent::Veto if, for example, the
  19     current values in the controls of the old page are invalid.
  20
  21     The second event - PAGE_CHANGED - is sent after the page has been changed and
  22     the program cannot veto it any more, it just informs it about the page change.
  23
  24     To summarize, if the program is interested in validating the page values
  25     before allowing the user to change it, it should process the PAGE_CHANGING
  26     event, otherwise PAGE_CHANGED is probably enough. In any case, it is probably
  27     unnecessary to process both events at once.
  28
  29     @library{wxcore}
  30     @category{events}
  31
  32     @seealso
  33     wxNotebook
  34 */
  35 class wxNotebookEvent : public wxNotifyEvent
  36 {
  37 public:
  38     /**
  39         Constructor (used internally by wxWidgets only).
  40     */
  41     wxNotebookEvent(wxEventType eventType = wxEVT_@NULL, int id = 0,
  42                     int sel = -1,
  43                     int oldSel = -1);
  44
  45     /**
  46         Returns the page that was selected before the change, -1 if none was selected.
  47     */
  48     int GetOldSelection();
  49
  50     /**
  51         Returns the currently selected page, or -1 if none was selected.
  52
  53         @b NB: under Windows, GetSelection() will return the same value as
  54         GetOldSelection() when called from
  55         @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to
  56         be selected. Also note that the values of selection and old selection returned
  57         for an event generated in response to a call to
  58         wxNotebook::SetSelection shouldn't be trusted
  59         as they are currently inconsistent under different platforms (but in this case
  60         you presumably don't need them anyhow as you already have the corresponding
  61         information).
  62     */
  63     int GetSelection();
  64
  65     /**
  66         Sets the id of the page selected before the change.
  67     */
  68     void SetOldSelection(int page);
  69
  70     /**
  71         Sets the selection member variable.
  72     */
  73     void SetSelection(int page);
  74 };
  75
  76
  77 /**
  78     @class wxNotebook
  79     @wxheader{notebook.h}
  80
  81     This class represents a notebook control, which manages multiple windows with
  82     associated tabs.
  83
  84     To use the class, create a wxNotebook object and call wxNotebook::AddPage or
  85     wxNotebook::InsertPage,
  86     passing a window to be used as the page. Do not explicitly delete the window
  87     for a page that is currently
  88     managed by wxNotebook.
  89
  90     @b wxNotebookPage is a typedef for wxWindow.
  91
  92     @beginStyleTable
  93     @style{wxNB_TOP}:
  94            Place tabs on the top side.
  95     @style{wxNB_LEFT}:
  96            Place tabs on the left side.
  97     @style{wxNB_RIGHT}:
  98            Place tabs on the right side.
  99     @style{wxNB_BOTTOM}:
 100            Place tabs under instead of above the notebook pages.
 101     @style{wxNB_FIXEDWIDTH}:
 102            (Windows only) All tabs will have same width.
 103     @style{wxNB_MULTILINE}:
 104            (Windows only) There can be several rows of tabs.
 105     @style{wxNB_NOPAGETHEME}:
 106            (Windows only) Display a solid colour on notebook pages, and not a
 107            gradient, which can reduce performance.
 108     @style{wxNB_FLAT}:
 109            (Windows CE only) Show tabs in a flat style.
 110     @endStyleTable
 111
 112     @library{wxcore}
 113     @category{miscwnd}
 114
 115     @seealso
 116     wxBookCtrl, wxNotebookEvent, wxImageList, @ref overview_samplenotebook
 117     "notebook sample"
 118 */
 119 class wxNotebook : public wxBookCtrl overview
 120 {
 121 public:
 122     //@{
 123     /**
 124         Constructs a notebook control.
 125
 126         Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN
 127         window style.
 128
 129         @param parent
 130         The parent window. Must be non-@NULL.
 131
 132         @param id
 133         The window identifier.
 134
 135         @param pos
 136         The window position.
 137
 138         @param size
 139         The window size.
 140
 141         @param style
 142         The window style. See wxNotebook.
 143
 144         @param name
 145         The name of the control (used only under Motif).
 146     */
 147     wxNotebook();
 148     wxNotebook(wxWindow* parent, wxWindowID id,
 149                const wxPoint& pos = wxDefaultPosition,
 150                const wxSize& size = wxDefaultSize,
 151                long style = 0,
 152                const wxString& name = wxNotebookNameStr);
 153     //@}
 154
 155     /**
 156         Destroys the wxNotebook object.
 157     */
 158     ~wxNotebook();
 159
 160     /**
 161         Adds a new page.
 162
 163         The call to this function may generate the page changing events.
 164
 165         @param page
 166         Specifies the new page.
 167
 168         @param text
 169         Specifies the text for the new page.
 170
 171         @param select
 172         Specifies whether the page should be selected.
 173
 174         @param imageId
 175         Specifies the optional image index for the new page.
 176
 177         @returns @true if successful, @false otherwise.
 178
 179         @remarks Do not delete the page, it will be deleted by the notebook.
 180
 181         @sa InsertPage()
 182     */
 183     bool AddPage(wxNotebookPage* page, const wxString& text,
 184                  bool select = @false,
 185                  int imageId = -1);
 186
 187     /**
 188         Cycles through the tabs.
 189
 190         The call to this function generates the page changing events.
 191     */
 192     void AdvanceSelection(bool forward = @true);
 193
 194     /**
 195         Sets the image list for the page control and takes ownership of
 196         the list.
 197
 198         @sa wxImageList, SetImageList()
 199     */
 200     void AssignImageList(wxImageList* imageList);
 201
 202     /**
 203         Changes the selection for the given page, returning the previous selection.
 204
 205         The call to this function does not generate the page changing events.
 206         This is the only difference with SetSelection().
 207         See @ref overview_progevent "this topic" for more info.
 208     */
 209     int ChangeSelection(size_t page);
 210
 211     /**
 212         Creates a notebook control. See wxNotebook() for a description
 213         of the parameters.
 214     */
 215     bool Create(wxWindow* parent, wxWindowID id,
 216                 const wxPoint& pos = wxDefaultPosition,
 217                 const wxSize& size, long style = 0,
 218                 const wxString& name = wxNotebookNameStr);
 219
 220     /**
 221         Deletes all pages.
 222     */
 223     bool DeleteAllPages();
 224
 225     /**
 226         Deletes the specified page, and the associated window.
 227
 228         The call to this function generates the page changing events.
 229     */
 230     bool DeletePage(size_t page);
 231
 232     /**
 233         Returns the currently selected notebook page or @NULL.
 234     */
 235     wxWindow * GetCurrentPage();
 236
 237     /**
 238         Returns the associated image list.
 239
 240         @sa wxImageList, SetImageList()
 241     */
 242     wxImageList* GetImageList();
 243
 244     /**
 245         Returns the window at the given page position.
 246     */
 247     wxNotebookPage* GetPage(size_t page);
 248
 249     /**
 250         Returns the number of pages in the notebook control.
 251     */
 252     size_t GetPageCount();
 253
 254     /**
 255         Returns the image index for the given page.
 256     */
 257     int GetPageImage(size_t nPage);
 258
 259     /**
 260         Returns the string for the given page.
 261     */
 262     wxString GetPageText(size_t nPage);
 263
 264     /**
 265         Returns the number of rows in the notebook control.
 266     */
 267     int GetRowCount();
 268
 269     /**
 270         Returns the currently selected page, or -1 if none was selected.
 271
 272         Note that this method may return either the previously or newly selected page
 273         when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on
 274         the platform and so
 275         wxNotebookEvent::GetSelection should be
 276         used instead in this case.
 277     */
 278     int GetSelection();
 279
 280     /**
 281         If running under Windows and themes are enabled for the application, this
 282         function
 283         returns a suitable colour for painting the background of a notebook page, and
 284         can be passed
 285         to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned.
 286     */
 287     wxColour GetThemeBackgroundColour();
 288
 289     /**
 290         Returns the index of the tab at the specified position or @c wxNOT_FOUND
 291         if none. If @e flags parameter is non-@NULL, the position of the point
 292         inside the tab is returned as well.
 293
 294         @param pt
 295         Specifies the point for the hit test.
 296
 297         @param flags
 298         Return value for detailed information. One of the following values:
 299
 300         wxBK_HITTEST_NOWHERE
 301
 302
 303         There was no tab under this point.
 304
 305         wxBK_HITTEST_ONICON
 306
 307
 308         The point was over an icon (currently wxMSW only).
 309
 310         wxBK_HITTEST_ONLABEL
 311
 312
 313         The point was over a label (currently wxMSW only).
 314
 315         wxBK_HITTEST_ONITEM
 316
 317
 318         The point was over an item, but not on the label or icon.
 319
 320         wxBK_HITTEST_ONPAGE
 321
 322
 323         The point was over a currently selected page, not over any tab. Note that this
 324         flag is present only if wxNOT_FOUND is returned.
 325
 326         @returns Returns the zero-based tab index or wxNOT_FOUND if there is no
 327                    tab is at the specified position.
 328     */
 329     int HitTest(const wxPoint& pt, long flags = @NULL);
 330
 331     /**
 332         Inserts a new page at the specified position.
 333
 334         @param index
 335         Specifies the position for the new page.
 336
 337         @param page
 338         Specifies the new page.
 339
 340         @param text
 341         Specifies the text for the new page.
 342
 343         @param select
 344         Specifies whether the page should be selected.
 345
 346         @param imageId
 347         Specifies the optional image index for the new page.
 348
 349         @returns @true if successful, @false otherwise.
 350
 351         @remarks Do not delete the page, it will be deleted by the notebook.
 352
 353         @sa AddPage()
 354     */
 355     bool InsertPage(size_t index, wxNotebookPage* page,
 356                     const wxString& text,
 357                     bool select = @false,
 358                     int imageId = -1);
 359
 360     /**
 361         An event handler function, called when the page selection is changed.
 362
 363         @sa wxNotebookEvent
 364     */
 365     void OnSelChange(wxNotebookEvent& event);
 366
 367     /**
 368         Deletes the specified page, without deleting the associated window.
 369     */
 370     bool RemovePage(size_t page);
 371
 372     /**
 373         Sets the image list for the page control. It does not take
 374         ownership of the image list, you must delete it yourself.
 375
 376         @sa wxImageList, AssignImageList()
 377     */
 378     void SetImageList(wxImageList* imageList);
 379
 380     /**
 381         Sets the amount of space around each page's icon and label, in pixels.
 382
 383         @b NB: The vertical padding cannot be changed in wxGTK.
 384     */
 385     void SetPadding(const wxSize& padding);
 386
 387     /**
 388         Sets the image index for the given page. @e image is an index into
 389         the image list which was set with SetImageList().
 390     */
 391     bool SetPageImage(size_t page, int image);
 392
 393     /**
 394         Sets the width and height of the pages.
 395
 396         @b NB: This method is currently not implemented for wxGTK.
 397     */
 398     void SetPageSize(const wxSize& size);
 399
 400     /**
 401         Sets the text for the given page.
 402     */
 403     bool SetPageText(size_t page, const wxString& text);
 404
 405     /**
 406         Sets the selection for the given page, returning the previous selection.
 407
 408         The call to this function generates the page changing events.
 409
 410         This function is deprecated and should not be used in new code. Please use the
 411         ChangeSelection() function instead.
 412
 413         @sa GetSelection()
 414     */
 415     int SetSelection(size_t page);
 416 };