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