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