interface/wx/bookctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        bookctrl.h
   3 // Purpose:     interface of wxBookCtrlBase
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Bit flags returned by wxBookCtrl::HitTest().
  11
  12     Notice that wxOSX currently only returns wxBK_HITTEST_ONLABEL or
  13     wxBK_HITTEST_NOWHERE and never the other values, so you should only test
  14     for these two in the code that should be portable under OS X.
  15  */
  16 enum
  17 {
  18     /// No tab at the specified point.
  19     wxBK_HITTEST_NOWHERE = 1,
  20
  21     /// The point is over an icon.
  22     wxBK_HITTEST_ONICON  = 2,
  23
  24     /// The point is over a tab label.
  25     wxBK_HITTEST_ONLABEL = 4,
  26
  27     /// The point if over a tab item but not over its icon or label.
  28     wxBK_HITTEST_ONITEM  = wxBK_HITTEST_ONICON | wxBK_HITTEST_ONLABEL,
  29
  30     /// The point is over the page area.
  31     wxBK_HITTEST_ONPAGE  = 8
  32 };
  33
  34 /**
  35     @class wxBookCtrlBase
  36
  37     A book control is a convenient way of displaying multiple pages of information,
  38     displayed one page at a time. wxWidgets has five variants of this control:
  39
  40     @li wxChoicebook: controlled by a wxChoice
  41     @li wxListbook: controlled by a wxListCtrl
  42     @li wxNotebook: uses a row of tabs
  43     @li wxTreebook: controlled by a wxTreeCtrl
  44     @li wxToolbook: controlled by a wxToolBar
  45
  46     This abstract class is the parent of all these book controls, and provides
  47     their basic interface.
  48     This is a pure virtual class so you cannot allocate it directly.
  49
  50     @library{wxcore}
  51     @category{bookctrl}
  52
  53     @see @ref overview_bookctrl
  54 */
  55 class wxBookCtrlBase : public wxControl, public wxWithImages
  56 {
  57 public:
  58     enum
  59     {
  60         /// Symbolic constant indicating that no image should be used.
  61         NO_IMAGE = -1
  62     };
  63
  64     /**
  65         Default ctor.
  66     */
  67     wxBookCtrlBase();
  68
  69     /**
  70         Constructs the book control with the given parameters.
  71         See Create() for two-step construction.
  72     */
  73     wxBookCtrlBase(wxWindow *parent,
  74                    wxWindowID winid,
  75                    const wxPoint& pos = wxDefaultPosition,
  76                    const wxSize& size = wxDefaultSize,
  77                    long style = 0,
  78                    const wxString& name = wxEmptyString);
  79
  80     /**
  81         Constructs the book control with the given parameters.
  82     */
  83     bool Create(wxWindow *parent,
  84                 wxWindowID winid,
  85                 const wxPoint& pos = wxDefaultPosition,
  86                 const wxSize& size = wxDefaultSize,
  87                 long style = 0,
  88                 const wxString& name = wxEmptyString);
  89
  90
  91     /**
  92         @name Image list functions
  93
  94         Each page may have an attached image.
  95         The functions of this group manipulate that image.
  96     */
  97     //@{
  98
  99
 100     /**
 101         Returns the image index for the given page.
 102     */
 103     virtual int GetPageImage(size_t nPage) const = 0;
 104
 105     /**
 106         Sets the image index for the given page. @a image is an index into
 107         the image list which was set with SetImageList().
 108     */
 109     virtual bool SetPageImage(size_t page, int image) = 0;
 110
 111     //@}
 112
 113
 114
 115     /**
 116         @name Page text functions
 117
 118         Each page has a text string attached.
 119         The functions of this group manipulate that text.
 120     */
 121     //@{
 122
 123     /**
 124         Returns the string for the given page.
 125     */
 126     virtual wxString GetPageText(size_t nPage) const = 0;
 127
 128     /**
 129         Sets the text for the given page.
 130     */
 131     virtual bool SetPageText(size_t page, const wxString& text) = 0;
 132     //@}
 133
 134
 135
 136     /**
 137         @name Selection functions
 138
 139         The functions of this group manipulate the selection.
 140     */
 141     //@{
 142
 143     /**
 144         Returns the currently selected page, or @c wxNOT_FOUND if none was selected.
 145
 146         Note that this method may return either the previously or newly
 147         selected page when called from the @c EVT_BOOKCTRL_PAGE_CHANGED handler
 148         depending on the platform and so wxBookCtrlEvent::GetSelection should be
 149         used instead in this case.
 150     */
 151     virtual int GetSelection() const = 0;
 152
 153     /**
 154         Returns the currently selected page or @NULL.
 155     */
 156     wxWindow* GetCurrentPage() const;
 157
 158     /**
 159         Sets the selection for the given page, returning the previous selection.
 160
 161         Notice that the call to this function generates the page changing
 162         events, use the ChangeSelection() function if you don't want these
 163         events to be generated.
 164
 165         @see GetSelection()
 166     */
 167     virtual int SetSelection(size_t page) = 0;
 168
 169     /**
 170         Cycles through the tabs.
 171         The call to this function generates the page changing events.
 172     */
 173     void AdvanceSelection(bool forward = true);
 174
 175     /**
 176         Changes the selection for the given page, returning the previous selection.
 177
 178         This function behaves as SetSelection() but does @em not generate the
 179         page changing events.
 180
 181         See @ref overview_events_prog for more information.
 182     */
 183     virtual int ChangeSelection(size_t page) = 0;
 184
 185     //@}
 186
 187
 188
 189     /**
 190         Sets the width and height of the pages.
 191
 192         @note This method is currently not implemented for wxGTK.
 193     */
 194     virtual void SetPageSize(const wxSize& size);
 195
 196     /**
 197         Returns the index of the tab at the specified position or @c wxNOT_FOUND
 198         if none. If @a flags parameter is non-@NULL, the position of the point
 199         inside the tab is returned as well.
 200
 201         @param pt
 202             Specifies the point for the hit test.
 203         @param flags
 204             Return more details about the point, see returned value is a
 205             combination of ::wxBK_HITTEST_NOWHERE, ::wxBK_HITTEST_ONICON,
 206             ::wxBK_HITTEST_ONLABEL, ::wxBK_HITTEST_ONITEM,
 207             ::wxBK_HITTEST_ONPAGE.
 208
 209         @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
 210                 tab at the specified position.
 211     */
 212     virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
 213
 214
 215
 216     /**
 217         @name Page management functions
 218
 219         Functions for adding/removing pages from this control.
 220     */
 221     //@{
 222
 223     /**
 224         Adds a new page.
 225
 226         The page must have the book control itself as the parent and must not
 227         have been added to this control previously.
 228
 229         The call to this function may generate the page changing events.
 230
 231         @param page
 232             Specifies the new page.
 233         @param text
 234             Specifies the text for the new page.
 235         @param select
 236             Specifies whether the page should be selected.
 237         @param imageId
 238             Specifies the optional image index for the new page.
 239
 240         @return @true if successful, @false otherwise.
 241
 242         @remarks Do not delete the page, it will be deleted by the book control.
 243
 244         @see InsertPage()
 245     */
 246     virtual bool AddPage(wxWindow* page, const wxString& text,
 247                          bool select = false, int imageId = NO_IMAGE);
 248
 249     /**
 250         Deletes all pages.
 251     */
 252     virtual bool DeleteAllPages();
 253
 254     /**
 255         Deletes the specified page, and the associated window.
 256         The call to this function generates the page changing events.
 257     */
 258     virtual bool DeletePage(size_t page);
 259
 260     /**
 261         Inserts a new page at the specified position.
 262
 263         @param index
 264             Specifies the position for the new page.
 265         @param page
 266             Specifies the new page.
 267         @param text
 268             Specifies the text for the new page.
 269         @param select
 270             Specifies whether the page should be selected.
 271         @param imageId
 272             Specifies the optional image index for the new page.
 273
 274         @return @true if successful, @false otherwise.
 275
 276         @remarks Do not delete the page, it will be deleted by the book control.
 277
 278         @see AddPage()
 279     */
 280     virtual bool InsertPage(size_t index,
 281                             wxWindow* page,
 282                             const wxString& text,
 283                             bool select = false,
 284                             int imageId = NO_IMAGE) = 0;
 285
 286     /**
 287         Deletes the specified page, without deleting the associated window.
 288     */
 289     virtual bool RemovePage(size_t page);
 290
 291     /**
 292         Returns the number of pages in the control.
 293     */
 294     virtual size_t GetPageCount() const;
 295
 296     /**
 297         Returns the window at the given page position.
 298     */
 299     wxWindow* GetPage(size_t page) const;
 300
 301     //@}
 302
 303
 304 /*
 305     other functions which may be worth documenting:
 306
 307     // geometry
 308     // --------
 309
 310     // calculate the size of the control from the size of its page
 311     virtual wxSize CalcSizeFromPage(const wxSize& sizePage) const = 0;
 312
 313     // get/set size of area between book control area and page area
 314     unsigned int GetInternalBorder() const { return m_internalBorder; }
 315     void SetInternalBorder(unsigned int border) { m_internalBorder = border; }
 316
 317     // Sets/gets the margin around the controller
 318     void SetControlMargin(int margin) { m_controlMargin = margin; }
 319     int GetControlMargin() const { return m_controlMargin; }
 320
 321     // returns true if we have wxBK_TOP or wxBK_BOTTOM style
 322     bool IsVertical() const { return HasFlag(wxBK_BOTTOM | wxBK_TOP); }
 323
 324     // set/get option to shrink to fit current page
 325     void SetFitToCurrentPage(bool fit) { m_fitToCurrentPage = fit; }
 326     bool GetFitToCurrentPage() const { return m_fitToCurrentPage; }
 327
 328     // returns the sizer containing the control, if any
 329     wxSizer* GetControlSizer() const { return m_controlSizer; }
 330
 331     // we do have multiple pages
 332     virtual bool HasMultiplePages() const { return true; }
 333
 334     // we don't want focus for ourselves
 335     virtual bool AcceptsFocus() const { return false; }
 336
 337     // returns true if the platform should explicitly apply a theme border
 338     virtual bool CanApplyThemeBorder() const { return false; }
 339 */
 340 };
 341
 342 /**
 343     wxBookCtrl is defined to one of the 'real' book controls.
 344
 345     See @ref overview_bookctrl for more info.
 346 */
 347 #define wxBookCtrl      TheBestBookCtrlForTheCurrentPlatform
 348
 349
 350 /**
 351     @class wxBookCtrlEvent
 352
 353     This class represents the events generated by book controls (wxNotebook,
 354     wxListbook, wxChoicebook, wxTreebook, wxAuiNotebook).
 355
 356     The PAGE_CHANGING events are sent before the current page is changed.
 357     It allows the program to examine the current page (which can be retrieved
 358     with wxBookCtrlEvent::GetOldSelection) and to veto the page change by calling
 359     wxNotifyEvent::Veto if, for example, the current values in the controls
 360     of the old page are invalid.
 361
 362     The PAGE_CHANGED events are sent after the page has been changed and the
 363     program cannot veto it any more, it just informs it about the page change.
 364
 365     To summarize, if the program is interested in validating the page values
 366     before allowing the user to change it, it should process the PAGE_CHANGING
 367     event, otherwise PAGE_CHANGED is probably enough. In any case, it is
 368     probably unnecessary to process both events at once.
 369
 370     @library{wxcore}
 371     @category{events,bookctrl}
 372
 373     @see wxNotebook, wxListbook, wxChoicebook, wxTreebook, wxToolbook, wxAuiNotebook
 374 */
 375 class wxBookCtrlEvent : public wxNotifyEvent
 376 {
 377 public:
 378     /**
 379         Constructor (used internally by wxWidgets only).
 380     */
 381     wxBookCtrlEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
 382                     int sel = wxNOT_FOUND, int oldSel = wxNOT_FOUND);
 383
 384     /**
 385         Returns the page that was selected before the change, @c wxNOT_FOUND if
 386         none was selected.
 387     */
 388     int GetOldSelection() const;
 389
 390     /**
 391         Returns the currently selected page, or @c wxNOT_FOUND if none was
 392         selected.
 393
 394         @note under Windows, GetSelection() will return the same value as
 395               GetOldSelection() when called from the @c EVT_BOOKCTRL_PAGE_CHANGING
 396               handler and not the page which is going to be selected.
 397     */
 398     int GetSelection() const;
 399
 400     /**
 401         Sets the id of the page selected before the change.
 402     */
 403     void SetOldSelection(int page);
 404
 405     /**
 406         Sets the selection member variable.
 407     */
 408     void SetSelection(int page);
 409 };
 410