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 to 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 to 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         Returns the index of the specified tab window or @c wxNOT_FOUND
 198         if not found.
 199
 200         @param page One of the control pages.
 201         @return The zero-based tab index or @c wxNOT_FOUND if not found.
 202
 203         @since 2.9.5
 204     */
 205     int FindPage(const wxWindow* page) const;
 206
 207     //@}
 208
 209
 210
 211     /**
 212         Sets the width and height of the pages.
 213
 214         @note This method is currently not implemented for wxGTK.
 215     */
 216     virtual void SetPageSize(const wxSize& size);
 217
 218     /**
 219         Returns the index of the tab at the specified position or @c wxNOT_FOUND
 220         if none. If @a flags parameter is non-@NULL, the position of the point
 221         inside the tab is returned as well.
 222
 223         @param pt
 224             Specifies the point for the hit test.
 225         @param flags
 226             Return more details about the point, see returned value is a
 227             combination of ::wxBK_HITTEST_NOWHERE, ::wxBK_HITTEST_ONICON,
 228             ::wxBK_HITTEST_ONLABEL, ::wxBK_HITTEST_ONITEM,
 229             ::wxBK_HITTEST_ONPAGE.
 230
 231         @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
 232                 tab at the specified position.
 233     */
 234     virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
 235
 236
 237
 238     /**
 239         @name Page management functions
 240
 241         Functions for adding/removing pages from this control.
 242     */
 243     //@{
 244
 245     /**
 246         Adds a new page.
 247
 248         The page must have the book control itself as the parent and must not
 249         have been added to this control previously.
 250
 251         The call to this function may generate the page changing events.
 252
 253         @param page
 254             Specifies the new page.
 255         @param text
 256             Specifies the text for the new page.
 257         @param select
 258             Specifies whether the page should be selected.
 259         @param imageId
 260             Specifies the optional image index for the new page.
 261
 262         @return @true if successful, @false otherwise.
 263
 264         @remarks Do not delete the page, it will be deleted by the book control.
 265
 266         @see InsertPage()
 267     */
 268     virtual bool AddPage(wxWindow* page, const wxString& text,
 269                          bool select = false, int imageId = NO_IMAGE);
 270
 271     /**
 272         Deletes all pages.
 273     */
 274     virtual bool DeleteAllPages();
 275
 276     /**
 277         Deletes the specified page, and the associated window.
 278         The call to this function generates the page changing events.
 279     */
 280     virtual bool DeletePage(size_t page);
 281
 282     /**
 283         Inserts a new page at the specified position.
 284
 285         @param index
 286             Specifies the position for the new page.
 287         @param page
 288             Specifies the new page.
 289         @param text
 290             Specifies the text for the new page.
 291         @param select
 292             Specifies whether the page should be selected.
 293         @param imageId
 294             Specifies the optional image index for the new page.
 295
 296         @return @true if successful, @false otherwise.
 297
 298         @remarks Do not delete the page, it will be deleted by the book control.
 299
 300         @see AddPage()
 301     */
 302     virtual bool InsertPage(size_t index,
 303                             wxWindow* page,
 304                             const wxString& text,
 305                             bool select = false,
 306                             int imageId = NO_IMAGE) = 0;
 307
 308     /**
 309         Deletes the specified page, without deleting the associated window.
 310     */
 311     virtual bool RemovePage(size_t page);
 312
 313     /**
 314         Returns the number of pages in the control.
 315     */
 316     virtual size_t GetPageCount() const;
 317
 318     /**
 319         Returns the window at the given page position.
 320     */
 321     wxWindow* GetPage(size_t page) const;
 322
 323     //@}
 324
 325
 326 /*
 327     other functions which may be worth documenting:
 328
 329     // geometry
 330     // --------
 331
 332     // calculate the size of the control from the size of its page
 333     virtual wxSize CalcSizeFromPage(const wxSize& sizePage) const = 0;
 334
 335     // get/set size of area between book control area and page area
 336     unsigned int GetInternalBorder() const { return m_internalBorder; }
 337     void SetInternalBorder(unsigned int border) { m_internalBorder = border; }
 338
 339     // Sets/gets the margin around the controller
 340     void SetControlMargin(int margin) { m_controlMargin = margin; }
 341     int GetControlMargin() const { return m_controlMargin; }
 342
 343     // returns true if we have wxBK_TOP or wxBK_BOTTOM style
 344     bool IsVertical() const { return HasFlag(wxBK_BOTTOM | wxBK_TOP); }
 345
 346     // set/get option to shrink to fit current page
 347     void SetFitToCurrentPage(bool fit) { m_fitToCurrentPage = fit; }
 348     bool GetFitToCurrentPage() const { return m_fitToCurrentPage; }
 349
 350     // returns the sizer containing the control, if any
 351     wxSizer* GetControlSizer() const { return m_controlSizer; }
 352
 353     // we do have multiple pages
 354     virtual bool HasMultiplePages() const { return true; }
 355
 356     // we don't want focus for ourselves
 357     virtual bool AcceptsFocus() const { return false; }
 358
 359     // returns true if the platform should explicitly apply a theme border
 360     virtual bool CanApplyThemeBorder() const { return false; }
 361 */
 362 };
 363
 364 /**
 365     wxBookCtrl is defined to one of the 'real' book controls.
 366
 367     See @ref overview_bookctrl for more info.
 368 */
 369 #define wxBookCtrl      TheBestBookCtrlForTheCurrentPlatform
 370
 371
 372 /**
 373     @class wxBookCtrlEvent
 374
 375     This class represents the events generated by book controls (wxNotebook,
 376     wxListbook, wxChoicebook, wxTreebook, wxAuiNotebook).
 377
 378     The PAGE_CHANGING events are sent before the current page is changed.
 379     It allows the program to examine the current page (which can be retrieved
 380     with wxBookCtrlEvent::GetOldSelection) and to veto the page change by calling
 381     wxNotifyEvent::Veto if, for example, the current values in the controls
 382     of the old page are invalid.
 383
 384     The PAGE_CHANGED events are sent after the page has been changed and the
 385     program cannot veto it any more, it just informs it about the page change.
 386
 387     To summarize, if the program is interested in validating the page values
 388     before allowing the user to change it, it should process the PAGE_CHANGING
 389     event, otherwise PAGE_CHANGED is probably enough. In any case, it is
 390     probably unnecessary to process both events at once.
 391
 392     @library{wxcore}
 393     @category{events,bookctrl}
 394
 395     @see wxNotebook, wxListbook, wxChoicebook, wxTreebook, wxToolbook, wxAuiNotebook
 396 */
 397 class wxBookCtrlEvent : public wxNotifyEvent
 398 {
 399 public:
 400     /**
 401         Constructor (used internally by wxWidgets only).
 402     */
 403     wxBookCtrlEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
 404                     int sel = wxNOT_FOUND, int oldSel = wxNOT_FOUND);
 405
 406     /**
 407         Returns the page that was selected before the change, @c wxNOT_FOUND if
 408         none was selected.
 409     */
 410     int GetOldSelection() const;
 411
 412     /**
 413         Returns the currently selected page, or @c wxNOT_FOUND if none was
 414         selected.
 415
 416         @note under Windows, GetSelection() will return the same value as
 417               GetOldSelection() when called from the @c EVT_BOOKCTRL_PAGE_CHANGING
 418               handler and not the page which is going to be selected.
 419     */
 420     int GetSelection() const;
 421
 422     /**
 423         Sets the id of the page selected before the change.
 424     */
 425     void SetOldSelection(int page);
 426
 427     /**
 428         Sets the selection member variable.
 429     */
 430     void SetSelection(int page);
 431 };
 432