interface/wx/bookctrl.h

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