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,
 113     @ref page_samples_notebook "Notebook Sample"
 114 */
 115 class wxNotebook : public wxBookCtrl overview
 116 {
 117 public:
 118
 119     /**
 120         Constructs a notebook control.
 121     */
 122     wxNotebook();
 123
 124     /**
 125         Constructs a notebook control.
 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         @param id
 132             The window identifier.
 133         @param pos
 134             The window position.
 135         @param size
 136             The window size.
 137         @param style
 138             The window style. See wxNotebook.
 139         @param name
 140             The name of the control (used only under Motif).
 141     */
 142     wxNotebook(wxWindow* parent, wxWindowID id,
 143                const wxPoint& pos = wxDefaultPosition,
 144                const wxSize& size = wxDefaultSize,
 145                long style = 0,
 146                const wxString& name = wxNotebookNameStr);
 147
 148     /**
 149         Destroys the wxNotebook object.
 150     */
 151     virtual ~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         @return @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(). See
 194         @ref overview_eventhandling_prog "User Generated Events"
 195         for more infomation.
 196     */
 197     virtual int ChangeSelection(size_t page);
 198
 199     /**
 200         Creates a notebook control. See wxNotebook() for a description
 201         of the parameters.
 202     */
 203     bool Create(wxWindow* parent, wxWindowID id,
 204                 const wxPoint& pos = wxDefaultPosition,
 205                 const wxSize& size = wxDefaultSize,
 206                 long style = 0,
 207                 const wxString& name = wxNotebookNameStr);
 208
 209     /**
 210         Deletes all pages.
 211     */
 212     virtual bool DeleteAllPages();
 213
 214     /**
 215         Deletes the specified page, and the associated window.
 216         The call to this function generates the page changing events.
 217     */
 218     bool DeletePage(size_t page);
 219
 220     /**
 221         Returns the currently selected notebook page or @NULL.
 222     */
 223     wxWindow* GetCurrentPage() const;
 224
 225     /**
 226         Returns the associated image list.
 227
 228         @see wxImageList, SetImageList()
 229     */
 230     wxImageList* GetImageList() const;
 231
 232     /**
 233         Returns the window at the given page position.
 234     */
 235     wxNotebookPage* GetPage(size_t page);
 236
 237     /**
 238         Returns the number of pages in the notebook control.
 239     */
 240     size_t GetPageCount() const;
 241
 242     /**
 243         Returns the image index for the given page.
 244     */
 245     virtual int GetPageImage(size_t nPage) const;
 246
 247     /**
 248         Returns the string for the given page.
 249     */
 250     virtual wxString GetPageText(size_t nPage) const;
 251
 252     /**
 253         Returns the number of rows in the notebook control.
 254     */
 255     virtual int GetRowCount() const;
 256
 257     /**
 258         Returns the currently selected page, or -1 if none was selected.
 259         Note that this method may return either the previously or newly selected page
 260         when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on
 261         the platform and so
 262         wxNotebookEvent::GetSelection should be
 263         used instead in this case.
 264     */
 265     virtual int GetSelection() const;
 266
 267     /**
 268         If running under Windows and themes are enabled for the application, this
 269         function
 270         returns a suitable colour for painting the background of a notebook page, and
 271         can be passed
 272         to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned.
 273     */
 274     virtual wxColour GetThemeBackgroundColour() const;
 275
 276     /**
 277         Returns the index of the tab at the specified position or @c wxNOT_FOUND
 278         if none. If @a flags parameter is non-@NULL, the position of the point
 279         inside the tab is returned as well.
 280
 281         @param pt
 282             Specifies the point for the hit test.
 283         @param flags
 284             Return value for detailed information. One of the following values:
 285             <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
 286             <TD>There was no tab under this point.</TD></TR>
 287             <TR><TD>wxBK_HITTEST_ONICON</TD>
 288             <TD>The point was over an icon (currently wxMSW only).</TD></TR>
 289             <TR><TD>wxBK_HITTEST_ONLABEL</TD>
 290             <TD>The point was over a label (currently wxMSW only).</TD></TR>
 291             <TR><TD>wxBK_HITTEST_ONITEM</TD>
 292             <TD>The point was over an item, but not on the label or icon.</TD></TR>
 293             <TR><TD>wxBK_HITTEST_ONPAGE</TD>
 294             <TD>The point was over a currently selected page, not over any tab.
 295             Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
 296             </TABLE>
 297 @return Returns the zero-based tab index or wxNOT_FOUND if there is no
 298                  tab at the specified position.
 299     */
 300     virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
 301
 302     /**
 303         Inserts a new page at the specified position.
 304
 305         @param index
 306             Specifies the position for the new page.
 307         @param page
 308             Specifies the new page.
 309         @param text
 310             Specifies the text for the new page.
 311         @param select
 312             Specifies whether the page should be selected.
 313         @param imageId
 314             Specifies the optional image index for the new page.
 315
 316         @return @true if successful, @false otherwise.
 317
 318         @remarks Do not delete the page, it will be deleted by the notebook.
 319
 320         @see AddPage()
 321     */
 322     bool InsertPage(size_t index, wxNotebookPage* page,
 323                     const wxString& text,
 324                     bool select = false,
 325                     int imageId = -1);
 326
 327     /**
 328         An event handler function, called when the page selection is changed.
 329
 330         @see wxNotebookEvent
 331     */
 332     void OnSelChange(wxNotebookEvent& event);
 333
 334     /**
 335         Deletes the specified page, without deleting the associated window.
 336     */
 337     bool RemovePage(size_t page);
 338
 339     /**
 340         Sets the image list for the page control. It does not take
 341         ownership of the image list, you must delete it yourself.
 342
 343         @see wxImageList, AssignImageList()
 344     */
 345     void SetImageList(wxImageList* imageList);
 346
 347     /**
 348         Sets the amount of space around each page's icon and label, in pixels.
 349         @note The vertical padding cannot be changed in wxGTK.
 350     */
 351     void SetPadding(const wxSize& padding);
 352
 353     /**
 354         Sets the image index for the given page. @a image is an index into
 355         the image list which was set with SetImageList().
 356     */
 357     virtual bool SetPageImage(size_t page, int image);
 358
 359     /**
 360         Sets the width and height of the pages.
 361         @note This method is currently not implemented for wxGTK.
 362     */
 363     virtual void SetPageSize(const wxSize& size);
 364
 365     /**
 366         Sets the text for the given page.
 367     */
 368     virtual bool SetPageText(size_t page, const wxString& text);
 369
 370     /**
 371         Sets the selection for the given page, returning the previous selection.
 372         The call to this function generates the page changing events.
 373         This function is deprecated and should not be used in new code. Please use the
 374         ChangeSelection() function instead.
 375
 376         @see GetSelection()
 377     */
 378     virtual int SetSelection(size_t page);
 379 };
 380