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