interface/wx/notebook.h

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