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