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 license
   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{miscwnd}
  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         The call to this function generates the page changing events.
 151
 152         @deprecated
 153         This function is deprecated and should not be used in new code.
 154         Please use the ChangeSelection() function instead.
 155
 156         @see GetSelection()
 157     */
 158     virtual int SetSelection(size_t page) = 0;
 159
 160     /**
 161         Cycles through the tabs.
 162         The call to this function generates the page changing events.
 163     */
 164     void AdvanceSelection(bool forward = true);
 165
 166     /**
 167         Changes the selection for the given page, returning the previous selection.
 168
 169         The call to this function does NOT generate the page changing events.
 170         This is the only difference with SetSelection().
 171         See @ref overview_eventhandling_prog for more infomation.
 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         The call to this function may generate the page changing events.
 225
 226         @param page
 227             Specifies the new page.
 228         @param text
 229             Specifies the text for the new page.
 230         @param select
 231             Specifies whether the page should be selected.
 232         @param imageId
 233             Specifies the optional image index for the new page.
 234
 235         @return @true if successful, @false otherwise.
 236
 237         @remarks Do not delete the page, it will be deleted by the book control.
 238
 239         @see InsertPage()
 240     */
 241     virtual bool AddPage(wxWindow* page, const wxString& text,
 242                          bool select = false, int imageId = wxNOT_FOUND);
 243
 244     /**
 245         Deletes all pages.
 246     */
 247     virtual bool DeleteAllPages();
 248
 249     /**
 250         Deletes the specified page, and the associated window.
 251         The call to this function generates the page changing events.
 252     */
 253     virtual bool DeletePage(size_t page);
 254
 255     /**
 256         Inserts a new page at the specified position.
 257
 258         @param index
 259             Specifies the position for the new page.
 260         @param page
 261             Specifies the new page.
 262         @param text
 263             Specifies the text for the new page.
 264         @param select
 265             Specifies whether the page should be selected.
 266         @param imageId
 267             Specifies the optional image index for the new page.
 268
 269         @return @true if successful, @false otherwise.
 270
 271         @remarks Do not delete the page, it will be deleted by the book control.
 272
 273         @see AddPage()
 274     */
 275     virtual bool InsertPage(size_t index,
 276                             wxWindow* page,
 277                             const wxString& text,
 278                             bool select = false,
 279                             int imageId = wxNOT_FOUND) = 0;
 280
 281     /**
 282         Deletes the specified page, without deleting the associated window.
 283     */
 284     virtual bool RemovePage(size_t page);
 285
 286     /**
 287         Returns the number of pages in the control.
 288     */
 289     virtual size_t GetPageCount() const;
 290
 291     /**
 292         Returns the window at the given page position.
 293     */
 294     wxWindow* GetPage(size_t page) const;
 295
 296     //@}
 297
 298
 299 /*
 300     other functions which may be worth documenting:
 301
 302     // geometry
 303     // --------
 304
 305     // calculate the size of the control from the size of its page
 306     virtual wxSize CalcSizeFromPage(const wxSize& sizePage) const = 0;
 307
 308     // get/set size of area between book control area and page area
 309     unsigned int GetInternalBorder() const { return m_internalBorder; }
 310     void SetInternalBorder(unsigned int border) { m_internalBorder = border; }
 311
 312     // Sets/gets the margin around the controller
 313     void SetControlMargin(int margin) { m_controlMargin = margin; }
 314     int GetControlMargin() const { return m_controlMargin; }
 315
 316     // returns true if we have wxBK_TOP or wxBK_BOTTOM style
 317     bool IsVertical() const { return HasFlag(wxBK_BOTTOM | wxBK_TOP); }
 318
 319     // set/get option to shrink to fit current page
 320     void SetFitToCurrentPage(bool fit) { m_fitToCurrentPage = fit; }
 321     bool GetFitToCurrentPage() const { return m_fitToCurrentPage; }
 322
 323     // returns the sizer containing the control, if any
 324     wxSizer* GetControlSizer() const { return m_controlSizer; }
 325
 326     // we do have multiple pages
 327     virtual bool HasMultiplePages() const { return true; }
 328
 329     // we don't want focus for ourselves
 330     virtual bool AcceptsFocus() const { return false; }
 331
 332     // returns true if the platform should explicitly apply a theme border
 333     virtual bool CanApplyThemeBorder() const { return false; }
 334 */
 335 };
 336
 337 /**
 338     wxBookCtrl is defined to one of the 'real' book controls.
 339
 340     See @ref overview_bookctrl for more info.
 341 */
 342 #define wxBookCtrl      TheBestBookCtrlForTheCurrentPlatform
 343
 344
 345 /**
 346     @class wxBookCtrlEvent
 347
 348     This class represents the events generated by book controls (wxNotebook,
 349     wxListbook, wxChoicebook, wxTreebook).
 350
 351     The PAGE_CHANGING events are sent before the current page is changed.
 352     It allows the program to examine the current page (which can be retrieved
 353     with wxBookCtrlEvent::GetOldSelection) and to veto the page change by calling
 354     wxNotifyEvent::Veto if, for example, the current values in the controls
 355     of the old page are invalid.
 356
 357     The PAGE_CHANGED events are sent after the page has been changed and the
 358     program cannot veto it any more, it just informs it about the page change.
 359
 360     To summarize, if the program is interested in validating the page values
 361     before allowing the user to change it, it should process the PAGE_CHANGING
 362     event, otherwise PAGE_CHANGED is probably enough. In any case, it is
 363     probably unnecessary to process both events at once.
 364
 365     @library{wxcore}
 366     @category{events}
 367
 368     @see wxNotebook, wxListbook, wxChoicebook, wxTreebook, wxToolbook
 369 */
 370 class wxBookCtrlEvent : public wxNotifyEvent
 371 {
 372 public:
 373     /**
 374         Constructor (used internally by wxWidgets only).
 375     */
 376     wxBookCtrlEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
 377                     int sel = wxNOT_FOUND, int oldSel = wxNOT_FOUND);
 378
 379     /**
 380         Returns the page that was selected before the change, @c wxNOT_FOUND if
 381         none was selected.
 382     */
 383     int GetOldSelection() const;
 384
 385     /**
 386         Returns the currently selected page, or @c wxNOT_FOUND if none was
 387         selected.
 388
 389         @note under Windows, GetSelection() will return the same value as
 390               GetOldSelection() when called from the @c EVT_BOOKCTRL_PAGE_CHANGING
 391               handler and not the page which is going to be selected.
 392     */
 393     int GetSelection() const;
 394
 395     /**
 396         Sets the id of the page selected before the change.
 397     */
 398     void SetOldSelection(int page);
 399
 400     /**
 401         Sets the selection member variable.
 402     */
 403     void SetSelection(int page);
 404 };
 405