interface/wx/treebook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treebook.h
   3 // Purpose:     interface of wxTreebook
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTreebook
  11
  12     This class is an extension of the wxNotebook class that allows a tree
  13     structured set of pages to be shown in a control. A classic example is a
  14     netscape preferences dialog that shows a tree of preference sections on
  15     the left and select section page on the right.
  16
  17     To use the class simply create it and populate with pages using
  18     InsertPage(), InsertSubPage(), AddPage(), AddSubPage().
  19
  20     If your tree is no more than 1 level in depth then you could simply use
  21     AddPage() and AddSubPage() to sequentially populate your tree by adding at
  22     every step a page or a subpage to the end of the tree.
  23
  24     @beginEventTable{wxBookCtrlEvent}
  25     @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
  26         The page selection was changed.
  27         Processes a @c wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
  28     @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
  29         The page selection is about to be changed.
  30         Processes a @c wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event.
  31         This event can be @ref wxNotifyEvent::Veto() "vetoed".
  32     @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
  33         The page node is going to be collapsed.
  34         Processes a @c wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
  35     @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
  36         The page node is going to be expanded.
  37         Processes a @c wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
  38     @endEventTable
  39
  40     @library{wxcore}
  41     @category{miscwnd}
  42
  43     @see wxBookCtrl, wxBookCtrlEvent, wxNotebook, wxTreeCtrl, wxImageList,
  44          @ref overview_bookctrl, @ref page_samples_notebook
  45 */
  46 class wxTreebook : public wxBookCtrlBase
  47 {
  48 public:
  49     /**
  50         Default constructor.
  51     */
  52     wxTreebook();
  53
  54     /**
  55         Creates an empty wxTreebook.
  56
  57         @param parent
  58             The parent window. Must be non-@NULL.
  59         @param id
  60             The window identifier.
  61         @param pos
  62             The window position.
  63         @param size
  64             The window size.
  65         @param style
  66             The window style. See wxNotebook.
  67         @param name
  68             The name of the control (used only under Motif).
  69     */
  70     wxTreebook(wxWindow* parent, wxWindowID id,
  71                const wxPoint& pos = wxDefaultPosition,
  72                const wxSize& size = wxDefaultSize,
  73                long style = wxBK_DEFAULT,
  74                const wxString& name = wxEmptyString);
  75
  76     /**
  77         Destroys the wxTreebook object.
  78         Also deletes all the pages owned by the control (inserted previously into it).
  79     */
  80     virtual ~wxTreebook();
  81
  82     /**
  83         Adds a new page. The page is placed at the topmost level after all other
  84         pages. @NULL could be specified for page to create an empty page.
  85     */
  86     virtual bool AddPage(wxWindow* page, const wxString& text,
  87                          bool bSelect = false, int imageId = wxNOT_FOUND);
  88
  89     /**
  90         Adds a new child-page to the last top-level page. @NULL could be
  91         specified for page to create an empty page.
  92     */
  93     virtual bool AddSubPage(wxWindow* page, const wxString& text,
  94                             bool bSelect = false, int imageId = wxNOT_FOUND);
  95
  96
  97     /**
  98         Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId,
  99         @false ).
 100     */
 101     bool CollapseNode(size_t pageId);
 102
 103     /**
 104         Creates a treebook control. See wxTreebook::wxTreebook() for the
 105         description of the parameters.
 106     */
 107     bool Create(wxWindow* parent, wxWindowID id,
 108                 const wxPoint& pos = wxDefaultPosition,
 109                 const wxSize& size = wxDefaultSize,
 110                 long style = wxBK_DEFAULT,
 111                 const wxString& name = wxEmptyString);
 112
 113     /**
 114         Deletes the page at the specified position and all its children.
 115         Could trigger page selection change in a case when selected page is removed.
 116         In that case its parent is selected (or the next page if no parent).
 117     */
 118     virtual bool DeletePage(size_t pagePos);
 119
 120     /**
 121         Expands (collapses) the @a pageId node. Returns the previous state.
 122         May generate page changing events (if selected page is under the collapsed
 123         branch, then its parent is autoselected).
 124     */
 125     virtual bool ExpandNode(size_t pageId, bool expand = true);
 126
 127     /**
 128         Returns the parent page of the given one or @c wxNOT_FOUND if this is a
 129         top-level page.
 130     */
 131     int GetPageParent(size_t page) const;
 132
 133     /**
 134         Returns the currently selected page, or @c wxNOT_FOUND if none was selected.
 135
 136         @note This method may return either the previously or newly selected
 137               page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler
 138               depending on the platform and so wxBookCtrlEvent::GetSelection()
 139               should be used instead in this case.
 140     */
 141     virtual int GetSelection() const;
 142
 143     /**
 144         Inserts a new page just before the page indicated by @a pagePos.
 145         The new page is placed before @a pagePos page and on the same level.
 146         @NULL could be specified for page to create an empty page.
 147     */
 148     virtual bool InsertPage(size_t pagePos, wxWindow* page,
 149                             const wxString& text, bool bSelect = false,
 150                             int imageId = wxNOT_FOUND);
 151
 152     /**
 153         Inserts a sub page under the specified page.
 154
 155         @NULL could be specified for page to create an empty page.
 156     */
 157     virtual bool InsertSubPage(size_t pagePos, wxWindow* page,
 158                                const wxString& text, bool bSelect = false,
 159                                int imageId = wxNOT_FOUND);
 160
 161     /**
 162         Returns @true if the page represented by @a pageId is expanded.
 163     */
 164     virtual bool IsNodeExpanded(size_t pageId) const;
 165 };
 166