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