revised the documentation of the book controls; moved common API to wxBookCtrlBase

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56268 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/bookctrl.h

@@ -9,7 +9,18 @@
 /**
     @class wxBookCtrlBase
 
-    @todo Document this class.
+    A book control is a convenient way of displaying multiple pages of information,
+    displayed one page at a time. wxWidgets has five variants of this control:
+
+    @li wxChoicebook: controlled by a wxChoice
+    @li wxListbook: controlled by a wxListCtrl
+    @li wxNotebook: uses a row of tabs
+    @li wxTreebook: controlled by a wxTreeCtrl
+    @li wxToolbook: controlled by a wxToolBar
+
+    This abstract class is the parent of all these book controls, and provides
+    their basic interface.
+    This is a pure virtual class so you cannot allocate it directly.
 
     @library{wxcore}
     @category{miscwnd}
@@ -19,7 +30,310 @@
 class wxBookCtrlBase : public wxControl
 {
 public:
+    /**
+        Default ctor.
+    */
+    wxBookCtrlBase();
 
+    /**
+        Constructs the book control with the given parameters.
+        See Create() for two-step construction.
+    */
+    wxBookCtrlBase(wxWindow *parent,
+                   wxWindowID winid,
+                   const wxPoint& pos = wxDefaultPosition,
+                   const wxSize& size = wxDefaultSize,
+                   long style = 0,
+                   const wxString& name = wxEmptyString);
+
+    /**
+        Constructs the book control with the given parameters.
+    */
+    bool Create(wxWindow *parent,
+                wxWindowID winid,
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                long style = 0,
+                const wxString& name = wxEmptyString);
+
+
+    /**
+        @name Image list functions
+
+        Each page may have an attached image.
+        The functions of this group manipulate that image.
+    */
+    //@{
+
+    /**
+        Sets the image list for the page control and takes ownership of the list.
+
+        @see wxImageList, SetImageList()
+    */
+    void AssignImageList(wxImageList* imageList);
+
+    /**
+        Returns the associated image list.
+
+        @see wxImageList, SetImageList()
+    */
+    wxImageList* GetImageList() const;
+
+    /**
+        Returns the image index for the given page.
+    */
+    virtual int GetPageImage(size_t nPage) const;
+
+    /**
+        Sets the image list for the page control.
+        It does not take ownership of the image list, you must delete it yourself.
+
+        @see wxImageList, AssignImageList()
+    */
+    virtual void SetImageList(wxImageList* imageList);
+
+    /**
+        Sets the image index for the given page. @a image is an index into
+        the image list which was set with SetImageList().
+    */
+    virtual bool SetPageImage(size_t page, int image);
+
+    //@}
+
+
+
+    /**
+        @name Page text functions
+
+        Each page has a text string attached.
+        The functions of this group manipulate that text.
+    */
+    //@{
+
+    /**
+        Returns the string for the given page.
+    */
+    virtual wxString GetPageText(size_t nPage) const = 0;
+
+    /**
+        Sets the text for the given page.
+    */
+    virtual bool SetPageText(size_t page, const wxString& text) = 0;
+    //@}
+
+
+
+    /**
+        @name Selection functions
+
+        The functions of this group manipulate the selection.
+    */
+    //@{
+
+    /**
+        Returns the currently selected page, or @c wxNOT_FOUND if none was selected.
+
+        Note that this method may return either the previously or newly
+        selected page when called from the @c EVT_BOOKCTRL_PAGE_CHANGED handler
+        depending on the platform and so wxBookCtrlEvent::GetSelection should be
+        used instead in this case.
+    */
+    virtual int GetSelection() const = 0;
+
+    /**
+        Returns the currently selected page or @NULL.
+    */
+    wxWindow* GetCurrentPage() const;
+
+    /**
+        Sets the selection for the given page, returning the previous selection.
+        The call to this function generates the page changing events.
+
+        @deprecated
+        This function is deprecated and should not be used in new code.
+        Please use the ChangeSelection() function instead.
+
+        @see GetSelection()
+    */
+    virtual int SetSelection(size_t page);
+
+    /**
+        Cycles through the tabs.
+        The call to this function generates the page changing events.
+    */
+    void AdvanceSelection(bool forward = true);
+
+    /**
+        Changes the selection for the given page, returning the previous selection.
+
+        The call to this function does NOT generate the page changing events.
+        This is the only difference with SetSelection().
+        See @ref overview_eventhandling_prog for more infomation.
+    */
+    virtual int ChangeSelection(size_t page);
+
+    //@}
+
+
+
+    /**
+        Sets the width and height of the pages.
+
+        @note This method is currently not implemented for wxGTK.
+    */
+    virtual void SetPageSize(const wxSize& size);
+
+    /**
+        Returns the index of the tab at the specified position or @c wxNOT_FOUND
+        if none. If @a flags parameter is non-@NULL, the position of the point
+        inside the tab is returned as well.
+
+        @param pt
+            Specifies the point for the hit test.
+        @param flags
+            Return value for detailed information. One of the following values:
+            <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
+            <TD>There was no tab under this point.</TD></TR>
+            <TR><TD>wxBK_HITTEST_ONICON</TD>
+            <TD>The point was over an icon (currently wxMSW only).</TD></TR>
+            <TR><TD>wxBK_HITTEST_ONLABEL</TD>
+            <TD>The point was over a label (currently wxMSW only).</TD></TR>
+            <TR><TD>wxBK_HITTEST_ONITEM</TD>
+            <TD>The point was over an item, but not on the label or icon.</TD></TR>
+            <TR><TD>wxBK_HITTEST_ONPAGE</TD>
+            <TD>The point was over a currently selected page, not over any tab.
+            Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
+            </TABLE>
+
+        @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
+                tab at the specified position.
+    */
+    virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
+
+
+
+    /**
+        @name Page management functions
+
+        Functions for adding/removing pages from this control.
+    */
+    //@{
+
+    /**
+        Adds a new page.
+        The call to this function may generate the page changing events.
+
+        @param page
+            Specifies the new page.
+        @param text
+            Specifies the text for the new page.
+        @param select
+            Specifies whether the page should be selected.
+        @param imageId
+            Specifies the optional image index for the new page.
+
+        @return @true if successful, @false otherwise.
+
+        @remarks Do not delete the page, it will be deleted by the book control.
+
+        @see InsertPage()
+    */
+    bool AddPage(wxWindow* page,
+                 const wxString& text,
+                 bool select = false,
+                 int imageId = wxNOT_FOUND);
+
+    /**
+        Deletes all pages.
+    */
+    virtual bool DeleteAllPages();
+
+    /**
+        Deletes the specified page, and the associated window.
+        The call to this function generates the page changing events.
+    */
+    bool DeletePage(size_t page);
+
+    /**
+        Inserts a new page at the specified position.
+
+        @param index
+            Specifies the position for the new page.
+        @param page
+            Specifies the new page.
+        @param text
+            Specifies the text for the new page.
+        @param select
+            Specifies whether the page should be selected.
+        @param imageId
+            Specifies the optional image index for the new page.
+
+        @return @true if successful, @false otherwise.
+
+        @remarks Do not delete the page, it will be deleted by the book control.
+
+        @see AddPage()
+    */
+    virtual bool InsertPage(size_t index,
+                            wxWindow* page,
+                            const wxString& text,
+                            bool select = false,
+                            int imageId = wxNOT_FOUND) = 0;
+
+    /**
+        Deletes the specified page, without deleting the associated window.
+    */
+    bool RemovePage(size_t page);
+
+    /**
+        Returns the number of pages in the control.
+    */
+    size_t GetPageCount() const;
+
+    /**
+        Returns the window at the given page position.
+    */
+    wxWindow* GetPage(size_t page);
+
+    //@}
+
+
+/*
+    other functions which may be worth documenting:
+
+    // geometry
+    // --------
+
+    // calculate the size of the control from the size of its page
+    virtual wxSize CalcSizeFromPage(const wxSize& sizePage) const = 0;
+
+    // get/set size of area between book control area and page area
+    unsigned int GetInternalBorder() const { return m_internalBorder; }
+    void SetInternalBorder(unsigned int border) { m_internalBorder = border; }
+
+    // Sets/gets the margin around the controller
+    void SetControlMargin(int margin) { m_controlMargin = margin; }
+    int GetControlMargin() const { return m_controlMargin; }
+
+    // returns true if we have wxBK_TOP or wxBK_BOTTOM style
+    bool IsVertical() const { return HasFlag(wxBK_BOTTOM | wxBK_TOP); }
+
+    // set/get option to shrink to fit current page
+    void SetFitToCurrentPage(bool fit) { m_fitToCurrentPage = fit; }
+    bool GetFitToCurrentPage() const { return m_fitToCurrentPage; }
+
+    // returns the sizer containing the control, if any
+    wxSizer* GetControlSizer() const { return m_controlSizer; }
+
+    // we do have multiple pages
+    virtual bool HasMultiplePages() const { return true; }
+
+    // we don't want focus for ourselves
+    virtual bool AcceptsFocus() const { return false; }
+
+    // returns true if the platform should explicitly apply a theme border
+    virtual bool CanApplyThemeBorder() const { return false; }
+*/
 };
 
 
@@ -28,15 +342,15 @@ public:
 
     This class represents the events generated by book controls (wxNotebook,
     wxListbook, wxChoicebook, wxTreebook).
+
     The PAGE_CHANGING events are sent before the current page is changed.
     It allows the program to examine the current page (which can be retrieved
     with wxBookCtrlEvent::GetOldSelection) and to veto the page change by calling
     wxNotifyEvent::Veto if, for example, the current values in the controls
     of the old page are invalid.
 
-    The PAGE_CHANGED events are sent after the page has been changed and
+    The PAGE_CHANGED events are sent after the page has been changed and the
-    the program cannot veto it any more, it just informs it about the page
+    program cannot veto it any more, it just informs it about the page change.
-    change.
 
     To summarize, if the program is interested in validating the page values
     before allowing the user to change it, it should process the PAGE_CHANGING
@@ -46,9 +360,8 @@ public:
     @library{wxcore}
     @category{events}
 
-    @see wxNotebook, wxListbook, wxChoicebook, wxTreebook
+    @see wxNotebook, wxListbook, wxChoicebook, wxTreebook, wxToolbook
 */
-
 class wxBookCtrlEvent : public wxNotifyEvent
 {
 public:
@@ -56,7 +369,7 @@ public:
         Constructor (used internally by wxWidgets only).
     */
     wxBookCtrlEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
-                int sel = wxNOT_FOUND, int oldSel = wxNOT_FOUND);
+                    int sel = wxNOT_FOUND, int oldSel = wxNOT_FOUND);
 
     /**
         Returns the page that was selected before the change, @c wxNOT_FOUND if
@@ -67,9 +380,10 @@ public:
     /**
         Returns the currently selected page, or @c wxNOT_FOUND if none was
         selected.
+
         @note under Windows, GetSelection() will return the same value as
-        GetOldSelection() when called from @c EVT_NOTEBOOK_PAGE_CHANGING
+              GetOldSelection() when called from the @c EVT_BOOKCTRL_PAGE_CHANGING
-        handler and not the page which is going to be selected.
+              handler and not the page which is going to be selected.
     */
     int GetSelection() const;
 

interface/wx/choicebk.h

@@ -12,10 +12,9 @@
     wxChoicebook is a class similar to wxNotebook, but uses a wxChoice control
     to show the labels instead of the tabs.
 
-    There is no documentation for this class yet but its usage is identical to
+    For usage documentation of this class, please refer to the base abstract class
-    wxNotebook (except for the features clearly related to tabs only), so
+    wxBookCtrl. You can also use the @ref page_samples_notebook to see wxChoicebook in
-    please refer to that class documentation for now. You can also use the
+    action.
-    @ref page_samples_notebook to see wxChoicebook in action.
 
     wxChoicebook allows the use of wxBookCtrlBase::GetControlSizer(), allowing
     a program to add other controls next to the choice control. This is
@@ -38,21 +37,18 @@
 
     @beginEventTable{wxBookCtrlEvent}
     @event{EVT_CHOICEBOOK_PAGE_CHANGED(id, func)}
-           The page selection was changed. Processes a
+        The page selection was changed.
-           wxEVT_COMMAND_LISTBOOK_PAGE_CHANGED event.
+        Processes a @c wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGED event.
     @event{EVT_CHOICEBOOK_PAGE_CHANGING(id, func)}
-           The page selection is about to be changed. Processes a
+        The page selection is about to be changed.
-           wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING event. This event can be
+        Processes a @c wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING event.
-           vetoed (using wxNotifyEvent::Veto()).
+        This event can be vetoed (using wxNotifyEvent::Veto()).
     @endEventTable
 
     @library{wxcore}
     @category{miscwnd}
 
     @see @ref overview_bookctrl, wxNotebook, @ref page_samples_notebook
-
-    @todo Write up wxBookCtrlBase documentation, where most of this class'
-          functionality comes from.
 */
 class wxChoicebook : public wxBookCtrlBase
 {

interface/wx/listbook.h

@@ -9,18 +9,15 @@
 /**
     @class wxListbook
 
-    wxListbook is a class similar to wxNotebook but which
+    wxListbook is a class similar to wxNotebook but which uses a wxListCtrl
-    uses a wxListCtrl to show the labels instead of the
+    to show the labels instead of the tabs.
-    tabs.
 
     The underlying wxListCtrl displays page labels in a one-column report view
-    by default.  Calling wxListbook::SetImageList will implicitly switch the
+    by default. Calling wxBookCtrl::SetImageList will implicitly switch the
     control to use an icon view.
 
-    There is no documentation for this class yet but its usage is
+    For usage documentation of this class, please refer to the base abstract class
-    identical to wxNotebook (except for the features clearly related to tabs
+    wxBookCtrl. You can also use the @ref page_samples_notebook to see wxListbook in
-    only), so please refer to that class documentation for now. You can also
-    use the @ref overview_samplenotebook "notebook sample" to see wxListbook in
     action.
 
     @beginStyleTable
@@ -37,24 +34,41 @@
            Place labels below the page area.
     @endStyleTable
 
+    @beginEventTable{wxListbookEvent}
+    @event{EVT_LISTBOOK_PAGE_CHANGED(id, func)}
+        The page selection was changed.
+        Processes a @c wxEVT_COMMAND_LISTBOOK_PAGE_CHANGED event.
+    @event{EVT_LISTBOOK_PAGE_CHANGING(id, func)}
+        The page selection is about to be changed.
+        Processes a @c wxEVT_COMMAND_LISTBOOK_PAGE_CHANGING event.
+        This event can be vetoed.
+    @endEventTable
+
     @library{wxcore}
     @category{miscwnd}
 
-    @see wxBookCtrl(), wxNotebook, @ref overview_samplenotebook "notebook sample"
+    @see wxBookCtrl(), wxNotebook, @ref page_samples_notebook
 */
-class wxListbook : public wxBookCtrl overview
+class wxListbook : public wxBookCtrlBase
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxListbook();
+
     /**
         Constructs a listbook control.
     */
-    wxListbook();
     wxListbook(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = 0,
                const wxString& name = wxEmptyStr);
-    //@}
+
+    /**
+        Returns the wxListView associated with the control.
+    */
+    wxListView* GetListView() const;
 };
 

interface/wx/notebook.h

@@ -13,8 +13,8 @@
     associated tabs.
 
     To use the class, create a wxNotebook object and call wxNotebook::AddPage
-    or wxNotebook::InsertPage, passing a window to be used as the page. Do not
+    or wxNotebook::InsertPage, passing a window to be used as the page.
-    explicitly delete the window for a page that is currently managed by
+    Do not explicitly delete the window for a page that is currently managed by
     wxNotebook.
 
     @b wxNotebookPage is a typedef for wxWindow.
@@ -39,12 +39,57 @@
            (Windows CE only) Show tabs in a flat style.
     @endStyleTable
 
+    The styles wxNB_LEFT, RIGHT and BOTTOM are not supported under
+    Microsoft Windows XP when using visual themes.
+
+    @beginEventTable{wxBookCtrlEvent}
+    @event{EVT_NOTEBOOK_PAGE_CHANGED(id, func)}
+        The page selection was changed.
+        Processes a @c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED event.
+    @event{EVT_NOTEBOOK_PAGE_CHANGING(id, func)}
+        The page selection is about to be changed.
+        Processes a @c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING event.
+        This event can be vetoed.
+    @endEventTable
+
+
+    @section notebook_bg Page backgrounds
+
+    On Windows XP, the default theme paints a gradient on the notebook's pages.
+    If you wish to suppress this theme, for aesthetic or performance reasons,
+    there are three ways of doing it.
+    You can use @c wxNB_NOPAGETHEME to disable themed drawing for a particular
+    notebook, you can call wxSystemOptions::SetOption to disable it for the
+    whole application, or you can disable it for individual pages by using
+    SetBackgroundColour().
+
+    To disable themed pages globally:
+    @code
+    wxSystemOptions::SetOption(wxT("msw.notebook.themed-background"), 0);
+    @endcode
+
+    Set the value to 1 to enable it again.
+    To give a single page a solid background that more or less fits in with the
+    overall theme, use:
+    @code
+    wxColour col = notebook->GetThemeBackgroundColour();
+    if (col.Ok())
+    {
+        page->SetBackgroundColour(col);
+    }
+    @endcode
+
+    On platforms other than Windows, or if the application is not using Windows
+    themes, GetThemeBackgroundColour() will return an uninitialised colour object,
+    and the above code will therefore work on all platforms.
+
+
     @library{wxcore}
     @category{miscwnd}
 
     @see wxBookCtrl, wxBookCtrlEvent, wxImageList, @ref page_samples_notebook
 */
-class wxNotebook : public wxBookCtrl
+class wxNotebook : public wxBookCtrlBase
 {
 public:
 
@@ -82,51 +127,6 @@ public:
     */
     virtual ~wxNotebook();
 
-    /**
-        Adds a new page.
-        The call to this function may generate the page changing events.
-
-        @param page
-            Specifies the new page.
-        @param text
-            Specifies the text for the new page.
-        @param select
-            Specifies whether the page should be selected.
-        @param imageId
-            Specifies the optional image index for the new page.
-
-        @return @true if successful, @false otherwise.
-
-        @remarks Do not delete the page, it will be deleted by the notebook.
-
-        @see InsertPage()
-    */
-    bool AddPage(wxNotebookPage* page, const wxString& text,
-                 bool select = false,
-                 int imageId = -1);
-
-    /**
-        Cycles through the tabs.
-        The call to this function generates the page changing events.
-    */
-    void AdvanceSelection(bool forward = true);
-
-    /**
-        Sets the image list for the page control and takes ownership of the list.
-
-        @see wxImageList, SetImageList()
-    */
-    void AssignImageList(wxImageList* imageList);
-
-    /**
-        Changes the selection for the given page, returning the previous selection.
-
-        The call to this function does NOT generate the page changing events.
-        This is the only difference with SetSelection().
-        See @ref overview_eventhandling_prog for more infomation.
-    */
-    virtual int ChangeSelection(size_t page);
-
     /**
         Creates a notebook control.
         See wxNotebook() for a description of the parameters.
@@ -137,64 +137,12 @@ public:
                 long style = 0,
                 const wxString& name = wxNotebookNameStr);
 
-    /**
-        Deletes all pages.
-    */
-    virtual bool DeleteAllPages();
-
-    /**
-        Deletes the specified page, and the associated window.
-        The call to this function generates the page changing events.
-    */
-    bool DeletePage(size_t page);
-
-    /**
-        Returns the currently selected notebook page or @NULL.
-    */
-    wxWindow* GetCurrentPage() const;
-
-    /**
-        Returns the associated image list.
-
-        @see wxImageList, SetImageList()
-    */
-    wxImageList* GetImageList() const;
-
-    /**
-        Returns the window at the given page position.
-    */
-    wxNotebookPage* GetPage(size_t page);
-
-    /**
-        Returns the number of pages in the notebook control.
-    */
-    size_t GetPageCount() const;
-
-    /**
-        Returns the image index for the given page.
-    */
-    virtual int GetPageImage(size_t nPage) const;
-
-    /**
-        Returns the string for the given page.
-    */
-    virtual wxString GetPageText(size_t nPage) const;
 
     /**
         Returns the number of rows in the notebook control.
     */
     virtual int GetRowCount() const;
 
-    /**
-        Returns the currently selected page, or -1 if none was selected.
-
-        Note that this method may return either the previously or newly
-        selected page when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler
-        depending on the platform and so wxBookCtrlEvent::GetSelection should be
-        used instead in this case.
-    */
-    virtual int GetSelection() const;
-
     /**
         If running under Windows and themes are enabled for the application, this
         function returns a suitable colour for painting the background of a notebook
@@ -204,57 +152,6 @@ public:
     */
     virtual wxColour GetThemeBackgroundColour() const;
 
-    /**
-        Returns the index of the tab at the specified position or @c wxNOT_FOUND
-        if none. If @a flags parameter is non-@NULL, the position of the point
-        inside the tab is returned as well.
-
-        @param pt
-            Specifies the point for the hit test.
-        @param flags
-            Return value for detailed information. One of the following values:
-            <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
-            <TD>There was no tab under this point.</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONICON</TD>
-            <TD>The point was over an icon (currently wxMSW only).</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONLABEL</TD>
-            <TD>The point was over a label (currently wxMSW only).</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONITEM</TD>
-            <TD>The point was over an item, but not on the label or icon.</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONPAGE</TD>
-            <TD>The point was over a currently selected page, not over any tab.
-            Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
-            </TABLE>
-
-        @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
-                tab at the specified position.
-    */
-    virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
-
-    /**
-        Inserts a new page at the specified position.
-
-        @param index
-            Specifies the position for the new page.
-        @param page
-            Specifies the new page.
-        @param text
-            Specifies the text for the new page.
-        @param select
-            Specifies whether the page should be selected.
-        @param imageId
-            Specifies the optional image index for the new page.
-
-        @return @true if successful, @false otherwise.
-
-        @remarks Do not delete the page, it will be deleted by the notebook.
-
-        @see AddPage()
-    */
-    virtual bool InsertPage(size_t index, wxNotebookPage* page,
-                            const wxString& text, bool select = false,
-                            int imageId = -1);
-
     /**
         An event handler function, called when the page selection is changed.
 
@@ -262,54 +159,11 @@ public:
     */
     void OnSelChange(wxBookCtrlEvent& event);
 
-    /**
-        Deletes the specified page, without deleting the associated window.
-    */
-    bool RemovePage(size_t page);
-
-    /**
-        Sets the image list for the page control.
-        It does not take ownership of the image list, you must delete it yourself.
-
-        @see wxImageList, AssignImageList()
-    */
-    void SetImageList(wxImageList* imageList);
-
     /**
         Sets the amount of space around each page's icon and label, in pixels.
 
         @note The vertical padding cannot be changed in wxGTK.
     */
     virtual void SetPadding(const wxSize& padding);
-
-    /**
-        Sets the image index for the given page. @a image is an index into
-        the image list which was set with SetImageList().
-    */
-    virtual bool SetPageImage(size_t page, int image);
-
-    /**
-        Sets the width and height of the pages.
-
-        @note This method is currently not implemented for wxGTK.
-    */
-    virtual void SetPageSize(const wxSize& size);
-
-    /**
-        Sets the text for the given page.
-    */
-    virtual bool SetPageText(size_t page, const wxString& text);
-
-    /**
-        Sets the selection for the given page, returning the previous selection.
-        The call to this function generates the page changing events.
-
-        @deprecated
-        This function is deprecated and should not be used in new code.
-        Please use the ChangeSelection() function instead.
-
-        @see GetSelection()
-    */
-    virtual int SetSelection(size_t page);
 };
 

interface/wx/toolbook.h

@@ -23,13 +23,23 @@
         other platforms).
     @style{wxTBK_HORZ_LAYOUT}
         Shows the text and the icons alongside, not vertically stacked (only
-        implement under Windows and GTK 2 platforms as it relies on @c
+        implement under Windows and GTK 2 platforms as it relies on
-        wxTB_HORZ_LAYOUT flag support).
+        @c wxTB_HORZ_LAYOUT flag support).
     @endStyleTable
 
     The common wxBookCtrl styles described in the @ref overview_bookctrl are
     also supported.
 
+    @beginEventTable{wxBookCtrlEvent}
+    @event{EVT_TOOLBOOK_PAGE_CHANGED(id, func)}
+        The page selection was changed.
+        Processes a @c wxEVT_COMMAND_TOOLBOOK_PAGE_CHANGED event.
+    @event{EVT_TOOLBOOK_PAGE_CHANGING(id, func)}
+        The page selection is about to be changed.
+        Processes a @c wxEVT_COMMAND_TOOLBOOK_PAGE_CHANGING event.
+        This event can be vetoed (using wxNotifyEvent::Veto()).
+    @endEventTable
+
     @library{wxcore}
     @category{miscwnd}
 
@@ -39,6 +49,21 @@
 class wxToolbook : public wxBookCtrlBase
 {
 public:
+    //@{
+    /**
+        Constructs a choicebook control.
+    */
+    wxToolbook();
+    wxToolbook(wxWindow* parent, wxWindowID id,
+                 const wxPoint& pos = wxDefaultPosition,
+                 const wxSize& size = wxDefaultSize,
+                 long style = 0,
+                 const wxString& name = wxEmptyStr);
+    //@}
 
+    /**
+        Returns the wxToolBarBase associated with the control.
+    */
+    wxToolBarBase* GetToolBar() const;
 };
 

interface/wx/treebook.h

@@ -23,18 +23,18 @@
 
     @beginEventTable{wxBookCtrlEvent}
     @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
-        The page selection was changed. Processes a @c
+        The page selection was changed.
-        wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
+        Processes a @c wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
     @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
-        The page selection is about to be changed. Processes a @c
+        The page selection is about to be changed.
-        wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref
+        Processes a @c wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event.
-        wxNotifyEvent::Veto() "vetoed".
+        This event can be @ref wxNotifyEvent::Veto() "vetoed".
     @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
-        The page node is going to be collapsed. Processes a @c
+        The page node is going to be collapsed.
-        wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
+        Processes a @c wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
     @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
-        The page node is going to be expanded. Processes a @c
+        The page node is going to be expanded.
-        wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
+        Processes a @c wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
     @endEventTable
 
     @library{wxcore}
@@ -74,8 +74,8 @@ public:
                const wxString& name = wxEmptyString);
 
     /**
-        Destroys the wxTreebook object. Also deletes all the pages owned by the
+        Destroys the wxTreebook object.
-        control (inserted previously into it).
+        Also deletes all the pages owned by the control (inserted previously into it).
     */
     virtual ~wxTreebook();
 
@@ -93,23 +93,6 @@ public:
     virtual bool AddSubPage(wxWindow* page, const wxString& text,
                             bool bSelect = false, int imageId = wxNOT_FOUND);
 
-    /**
-        Sets the image list for the page control and takes ownership of the
-        list.
-
-        @see wxImageList, SetImageList()
-    */
-    virtual void AssignImageList(wxImageList* imageList);
-
-    /**
-        Changes the selection for the given page, returning the previous
-        selection.
-
-        The call to this function does not generate the page changing events.
-        This is the only difference with SetSelection(). See
-        @ref overview_eventhandling_prog for more info.
-    */
-    virtual int ChangeSelection(size_t page);
 
     /**
         Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId,
@@ -128,29 +111,19 @@ public:
                 const wxString& name = wxEmptyString);
 
     /**
-        Deletes all pages inserted into the treebook. No event is generated.
+        Deletes the page at the specified position and all its children.
-    */
+        Could trigger page selection change in a case when selected page is removed.
-    virtual bool DeleteAllPages();
-
-    /**
-        Deletes the page at the specified position and all its children. Could
-        trigger page selection change in a case when selected page is removed.
         In that case its parent is selected (or the next page if no parent).
     */
     virtual bool DeletePage(size_t pagePos);
 
     /**
-        Expands (collapses) the @a pageId node. Returns the previous state. May
+        Expands (collapses) the @a pageId node. Returns the previous state.
-        generate page changing events (if selected page is under the collapsed
+        May generate page changing events (if selected page is under the collapsed
         branch, then its parent is autoselected).
     */
     virtual bool ExpandNode(size_t pageId, bool expand = true);
 
-    /**
-        Returns the image index for the given page.
-    */
-    virtual int GetPageImage(size_t n) const;
-
     /**
         Returns the parent page of the given one or @c wxNOT_FOUND if this is a
         top-level page.
@@ -158,25 +131,19 @@ public:
     int GetPageParent(size_t page) const;
 
     /**
-        Returns the string for the given page.
+        Returns the currently selected page, or @c wxNOT_FOUND if none was selected.
-    */
-    virtual wxString GetPageText(size_t n) const;
-
-    /**
-        Returns the currently selected page, or @c wxNOT_FOUND if none was
-        selected.
 
         @note This method may return either the previously or newly selected
-            page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler
+              page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler
-            depending on the platform and so wxBookCtrlEvent::GetSelection()
+              depending on the platform and so wxBookCtrlEvent::GetSelection()
-            should be used instead in this case.
+              should be used instead in this case.
     */
     virtual int GetSelection() const;
 
     /**
-        Inserts a new page just before the page indicated by @a pagePos. The new
+        Inserts a new page just before the page indicated by @a pagePos.
-        page is placed before @a pagePos page and on the same level. @NULL could
+        The new page is placed before @a pagePos page and on the same level.
-        be specified for page to create an empty page.
+        @NULL could be specified for page to create an empty page.
     */
     virtual bool InsertPage(size_t pagePos, wxWindow* page,
                             const wxString& text, bool bSelect = false,
@@ -195,35 +162,5 @@ public:
         Returns @true if the page represented by @a pageId is expanded.
     */
     virtual bool IsNodeExpanded(size_t pageId) const;
-
-    /**
-        Sets the image list for the page control. It does not take ownership of
-        the image list, you must delete it yourself.
-
-        @see wxImageList, AssignImageList()
-    */
-    virtual void SetImageList(wxImageList* imageList);
-
-    /**
-        Sets the image index for the given @a page. @a imageId is an index into
-        the image list which was set with SetImageList().
-    */
-    virtual bool SetPageImage(size_t page, int imageId);
-
-    /**
-        Sets the @a text for the given @a page.
-    */
-    virtual bool SetPageText(size_t page, const wxString& text);
-
-    /**
-        @deprecated Please use ChangeSelection() instead.
-
-        Sets the selection for the given page, returning the previous selection.
-
-        The call to this function generates page changing events.
-
-        @see GetSelection(), ChangeSelection()
-    */
-    virtual int SetSelection(size_t n);
 };