mac paths updated

[wxWidgets.git] / interface / treebook.h

diff --git a/interface/treebook.h b/interface/treebook.h
index c79325f1fdbbe13504326b1a2d552c47c61cf09a..c950031b2dad34e80f3cb5885ae28bd5cc7e9d86 100644 (file)
--- a/interface/treebook.h
+++ b/interface/treebook.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        treebook.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        treebook.h

-// Purpose:     documentation for wxTreebookEvent class
+// Purpose:     interface of wxTreebookEvent

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -11,157 +11,184 @@
     @wxheader{treebook.h}
 
     This class represents the events generated by a treebook control: currently,
     @wxheader{treebook.h}
 
     This class represents the events generated by a treebook control: currently,

-    there are four of them. The PAGE_CHANGING and PAGE_CHANGED - have exactly the
-    same
-    behaviour as wxNotebookEvent.
-
-    The other two NODE_COLLAPSED and NODE_EXPANDED are triggered when page node in
-    the tree control
-    is collapsed/expanded. The page index could be retreived by calling
-    wxTreebookEvent::GetSelection.
-
-
+    there are four of them. The EVT_TREEBOOK_PAGE_CHANGING() and
+    EVT_TREEBOOK_PAGE_CHANGED() - have exactly the same behaviour as
+    wxNotebookEvent.
+
+    The other two EVT_TREEBOOK_NODE_COLLAPSED() and EVT_TREEBOOK_NODE_EXPANDED()
+    are triggered when page node in the tree control is collapsed/expanded. The
+    page index could be retreived by calling GetSelection().
+
+    @beginEventTable{wxTreebookEvent}
+    @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
+        The page selection was changed. 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
+        wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. 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
+        wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
+    @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
+        The page node is going to be expanded. Processes a @c
+        wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
+    @endEventTable
+    

     @library{wxcore}
     @category{events}
 
     @library{wxcore}
     @category{events}
 

-    @seealso
-    wxNotebookEvent, wxTreebook
+    @see wxTreebook, wxNotebookEvent

 */
 class wxTreebookEvent : public wxNotifyEvent
 {
 public:
     /**
 */
 class wxTreebookEvent : public wxNotifyEvent
 {
 public:
     /**

-        @sa wxNotebookEvent
+        @see wxNotebookEvent

     */
     */

-    wxTreebookEvent(wxEventType commandType = wxEVT_@NULL, int id = 0,
+    wxTreebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,

                     int nSel = wxNOT_FOUND,
                     int nOldSel = wxNOT_FOUND);
 
     /**
                     int nSel = wxNOT_FOUND,
                     int nOldSel = wxNOT_FOUND);
 
     /**

-        Returns the page that was selected before the change, wxNOT_FOUND if none was
-        selected.
+        Returns the page that was selected before the change, @c wxNOT_FOUND if
+        none was selected.

     */
     */

-    int GetOldSelection();
+    int GetOldSelection() const;

 
     /**
 
     /**

-        Returns the currently selected page, or wxNOT_FOUND if none was selected.
+        Returns the currently selected page, or @c wxNOT_FOUND if none was
+        selected.
+
+        @see wxNotebookEvent::GetSelection()

     */
     */

-    int GetSelection();
+    int GetSelection() const;

 };
 
 
 };
 
 

+

 /**
     @class wxTreebook
     @wxheader{treebook.h}
 
 /**
     @class wxTreebook
     @wxheader{treebook.h}
 

-    This class is an extension of the Notebook class that allows a tree structured
-    set of pages to be shown in a control.
-    A classic example is a netscape preferences dialog that shows a tree
-    of preference sections on the left and select section page on the right.
+    This class is an extension of the wxNotebook class that allows a tree
+    structured set of pages to be shown in a control. A classic example is a
+    netscape preferences dialog that shows a tree of preference sections on
+    the left and select section page on the right.

 
     To use the class simply create it and populate with pages using
 
     To use the class simply create it and populate with pages using

-    wxTreebook::InsertPage,
-    wxTreebook::InsertSubPage,
-    wxTreebook::AddPage,
-    wxTreebook::AddSubPage.
-
-    If your tree is no more than 1 level in depth then you could
-    simply use wxTreebook::AddPage and
-    wxTreebook::AddSubPage to sequentially populate your tree
-    by adding at every step a page or a subpage to the end of the tree.
+    InsertPage(), InsertSubPage(), AddPage(), AddSubPage().
+
+    If your tree is no more than 1 level in depth then you could simply use
+    AddPage() and AddSubPage() to sequentially populate your tree by adding at
+    every step a page or a subpage to the end of the tree.
+
+    @beginEventTable{wxTreebookEvent}
+    @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
+        The page selection was changed. 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
+        wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. 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
+        wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
+    @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
+        The page node is going to be expanded. Processes a @c
+        wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
+    @endEventTable

 
     @library{wxcore}
     @category{miscwnd}
 
 
     @library{wxcore}
     @category{miscwnd}
 

-    @seealso
-    wxNotebook, wxTreebookEvent, wxImageList, @ref overview_samplenotebook
-    "notebook sample"
+    @see wxTreebookEvent, wxNotebook, wxTreeCtrl, wxImageList,
+         @ref overview_bookctrl, @ref page_samples_notebook

 */
 */

-class wxTreebook : public wxBookCtrl overview
+class wxTreebook : public wxBookCtrlBase

 {
 public:
 {
 public:

-    //@{

     /**
     /**

-        Creates an empty TreeBook control.
-        
+        Default constructor.
+    */
+    wxTreebook();
+
+    /**
+        Creates an empty wxTreebook.
+

         @param parent
         @param parent

-        The parent window. Must be non-@NULL.
-        
+            The parent window. Must be non-@NULL.

         @param id
         @param id

-        The window identifier.
-        
+            The window identifier.

         @param pos
         @param pos

-        The window position.
-        
+            The window position.

         @param size
         @param size

-        The window size.
-        
+            The window size.

         @param style
         @param style

-        The window style. See wxNotebook.
-        
+            The window style. See wxNotebook.

         @param name
         @param name

-        The name of the control (used only under Motif).
+            The name of the control (used only under Motif).

     */
     */

-    wxTreebook();

     wxTreebook(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
     wxTreebook(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,

-               long style = wxTBK_DEFAULT,
+               long style = wxBK_DEFAULT,

                const wxString& name = wxEmptyString);
                const wxString& name = wxEmptyString);

-    //@}

 
     /**
 
     /**

-        Destroys the wxTreebook object.
-        
-        Also deletes all the pages owned by the control (inserted previously into it).
+        Destroys the wxTreebook object. Also deletes all the pages owned by the
+        control (inserted previously into it).

     */
     ~wxTreebook();
 
     /**
     */
     ~wxTreebook();
 
     /**

-        Adds a new page. The page is placed at the topmost level after all other pages.
-        @NULL could be specified for page to create an empty page.
+        Adds a new page. The page is placed at the topmost level after all other
+        pages. @NULL could be specified for page to create an empty page.

     */
     bool AddPage(wxWindow* page, const wxString& text,
     */
     bool AddPage(wxWindow* page, const wxString& text,

-                 bool bSelect = @false,
+                 bool bSelect = false,

                  int imageId = wxNOT_FOUND);
 
     /**
                  int imageId = wxNOT_FOUND);
 
     /**

-        Adds a new child-page to the last top-level page.
-        @NULL could be specified for page to create an empty page.
+        Adds a new child-page to the last top-level page. @NULL could be
+        specified for page to create an empty page.

     */
     bool AddSubPage(wxWindow* page, const wxString& text,
     */
     bool AddSubPage(wxWindow* page, const wxString& text,

-                    bool bSelect = @false,
+                    bool bSelect = false,

                     int imageId = wxNOT_FOUND);
 
     /**
                     int imageId = wxNOT_FOUND);
 
     /**

-        Sets the image list for the page control and takes ownership of the list.
-        
-        @sa wxImageList, SetImageList()
+        Sets the image list for the page control and takes ownership of the
+        list.
+
+        @see wxImageList, SetImageList()

     */
     void AssignImageList(wxImageList* imageList);
 
     /**
     */
     void AssignImageList(wxImageList* imageList);
 
     /**

-        Changes the selection for the given page, returning the previous selection.
-        
+        Changes the selection for the given page, returning the previous
+        selection.
+

         The call to this function does not generate the page changing events.
         The call to this function does not generate the page changing events.

-        This is the only difference with SetSelection().
-        See @ref overview_progevent "this topic" for more info.
+        This is the only difference with SetSelection(). See
+        @ref overview_eventhandling_prog for more info.

     */
     int ChangeSelection(size_t page);
 
     /**
     */
     int ChangeSelection(size_t page);
 
     /**

-        Shortcut for wxTreebook::ExpandNode(pageId, @false).
+        Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId,
+        @false ).

     */
     bool CollapseNode(size_t pageId);
 
     /**
     */
     bool CollapseNode(size_t pageId);
 
     /**

-        Creates a treebook control. See wxTreebook() for the description of the
-        parameters.
+        Creates a treebook control. See wxTreebook::wxTreebook() for the
+        description of the parameters.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,

-                long style = wxTBK_DEFAULT,
+                long style = wxBK_DEFAULT,

                 const wxString& name = wxEmptyString);
 
     /**
                 const wxString& name = wxEmptyString);
 
     /**


@@ -170,99 +197,99 @@ public:
     bool DeleteAllPages();
 
     /**
     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).
+        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).

     */
     bool DeletePage(size_t pagePos);
 
     /**
     */
     bool DeletePage(size_t pagePos);
 
     /**

-        Expands (collapses) the pageId node. Returns the previous state.
-        May generate page changing events (if selected page
-        is under the collapsed branch, then its parent is autoselected).
+        Expands (collapses) the @a pageId node. Returns the previous state. May
+        generate page changing events (if selected page is under the collapsed
+        branch, then its parent is autoselected).

     */
     */

-    bool ExpandNode(size_t pageId, bool expand = @true);
+    bool ExpandNode(size_t pageId, bool expand = true);

 
     /**
         Returns the image index for the given page.
     */
 
     /**
         Returns the image index for the given page.
     */

-    int GetPageImage(size_t n);
+    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.
     */
 
     /**
         Returns the parent page of the given one or @c wxNOT_FOUND if this is a
         top-level page.
     */

-    int GetPageParent(size_t page);
+    int GetPageParent(size_t page) const;

 
     /**
         Returns the string for the given page.
     */
 
     /**
         Returns the string for the given page.
     */

-    wxString GetPageText(size_t n);
+    wxString GetPageText(size_t n) const;

 
     /**
 
     /**

-        Returns the currently selected page, or wxNOT_FOUND if none was selected.
-        
-        Note that this method may return either the previously or newly selected page
-        when called from the EVT_TREEBOOK_PAGE_CHANGED handler
-        depending on the platform and so wxTreebookEvent::GetSelection should be used
-        instead in this case.
+        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
+            depending on the platform and so wxTreebookEvent::GetSelection()
+            should be used instead in this case.

     */
     */

-    int GetSelection();
+    int GetSelection() const;

 
     /**
 
     /**

-        Inserts a new page just before the page indicated by pagePos.
-        The new page is placed before pagePos page and on the same level.
-        @NULL could be specified for page to create an empty page.
+        Inserts a new page just before the page indicated by @a pagePos. The new
+        page is placed before @a pagePos page and on the same level. @NULL could
+        be specified for page to create an empty page.

     */
     bool InsertPage(size_t pagePos, wxWindow* page,
                     const wxString& text,
     */
     bool InsertPage(size_t pagePos, wxWindow* page,
                     const wxString& text,

-                    bool bSelect = @false,
+                    bool bSelect = false,

                     int imageId = wxNOT_FOUND);
 
     /**
         Inserts a sub page under the specified page.
                     int imageId = wxNOT_FOUND);
 
     /**
         Inserts a sub page under the specified page.

-        
+

         @NULL could be specified for page to create an empty page.
     */
     bool InsertSubPage(size_t pagePos, wxWindow* page,
                        const wxString& text,
         @NULL could be specified for page to create an empty page.
     */
     bool InsertSubPage(size_t pagePos, wxWindow* page,
                        const wxString& text,

-                       bool bSelect = @false,
+                       bool bSelect = false,

                        int imageId = wxNOT_FOUND);
 
     /**
                        int imageId = wxNOT_FOUND);
 
     /**

-        Gets the pagePos page state -- whether it is expanded or collapsed
+        Returns @true if the page represented by @a pageId is expanded.

     */
     */

-    bool IsNodeExpanded(size_t pageId);
+    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.
-        
-        @sa wxImageList, AssignImageList()
+        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);
 
     /**
     */
     void SetImageList(wxImageList* imageList);
 
     /**

-        Sets the image index for the given page. ImageId is an index into the image list
-        which was set with SetImageList().
+        Sets the image index for the given @a page. @a imageId is an index into
+        the image list which was set with SetImageList().

     */
     bool SetPageImage(size_t page, int imageId);
 
     /**
     */
     bool SetPageImage(size_t page, int imageId);
 
     /**

-        Sets the text for the given page.
+        Sets the @a text for the given @a page.

     */
     bool SetPageText(size_t page, const wxString& text);
 
     /**
     */
     bool SetPageText(size_t page, const wxString& text);
 
     /**

+        @deprecated Please use ChangeSelection() instead.
+

         Sets the selection for the given page, returning the previous selection.
         Sets the selection for the given page, returning the previous selection.

-        
-        The call to this function generates the page changing events.
-        
-        This function is deprecated and should not be used in new code. Please use the
-        ChangeSelection() function instead.
-        
-        @sa GetSelection()
+
+        The call to this function generates page changing events.
+
+        @see GetSelection(), ChangeSelection()

     */
     int SetSelection(size_t n);
 };
     */
     int SetSelection(size_t n);
 };

+