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