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