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. Processes a @c
  27         wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
  28     @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
  29         The page selection is about to be changed. Processes a @c
  30         wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref
  31         wxNotifyEvent::Veto() "vetoed".
  32     @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
  33         The page node is going to be collapsed. Processes a @c
  34         wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
  35     @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
  36         The page node is going to be expanded. Processes a @c
  37         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. Also deletes all the pages owned by the
  78         control (inserted previously into it).
  79     */
  80     ~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     bool AddPage(wxWindow* page, const wxString& text,
  87                  bool bSelect = false,
  88                  int imageId = wxNOT_FOUND);
  89
  90     /**
  91         Adds a new child-page to the last top-level page. @NULL could be
  92         specified for page to create an empty page.
  93     */
  94     bool AddSubPage(wxWindow* page, const wxString& text,
  95                     bool bSelect = false,
  96                     int imageId = wxNOT_FOUND);
  97
  98     /**
  99         Sets the image list for the page control and takes ownership of the
 100         list.
 101
 102         @see wxImageList, SetImageList()
 103     */
 104     void AssignImageList(wxImageList* imageList);
 105
 106     /**
 107         Changes the selection for the given page, returning the previous
 108         selection.
 109
 110         The call to this function does not generate the page changing events.
 111         This is the only difference with SetSelection(). See
 112         @ref overview_eventhandling_prog for more info.
 113     */
 114     int ChangeSelection(size_t page);
 115
 116     /**
 117         Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId,
 118         @false ).
 119     */
 120     bool CollapseNode(size_t pageId);
 121
 122     /**
 123         Creates a treebook control. See wxTreebook::wxTreebook() for the
 124         description of the parameters.
 125     */
 126     bool Create(wxWindow* parent, wxWindowID id,
 127                 const wxPoint& pos = wxDefaultPosition,
 128                 const wxSize& size = wxDefaultSize,
 129                 long style = wxBK_DEFAULT,
 130                 const wxString& name = wxEmptyString);
 131
 132     /**
 133         Deletes all pages inserted into the treebook. No event is generated.
 134     */
 135     bool DeleteAllPages();
 136
 137     /**
 138         Deletes the page at the specified position and all its children. Could
 139         trigger page selection change in a case when selected page is removed.
 140         In that case its parent is selected (or the next page if no parent).
 141     */
 142     bool DeletePage(size_t pagePos);
 143
 144     /**
 145         Expands (collapses) the @a pageId node. Returns the previous state. May
 146         generate page changing events (if selected page is under the collapsed
 147         branch, then its parent is autoselected).
 148     */
 149     bool ExpandNode(size_t pageId, bool expand = true);
 150
 151     /**
 152         Returns the image index for the given page.
 153     */
 154     int GetPageImage(size_t n) const;
 155
 156     /**
 157         Returns the parent page of the given one or @c wxNOT_FOUND if this is a
 158         top-level page.
 159     */
 160     int GetPageParent(size_t page) const;
 161
 162     /**
 163         Returns the string for the given page.
 164     */
 165     wxString GetPageText(size_t n) const;
 166
 167     /**
 168         Returns the currently selected page, or @c wxNOT_FOUND if none was
 169         selected.
 170
 171         @note This method may return either the previously or newly selected
 172             page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler
 173             depending on the platform and so wxBookCtrlEvent::GetSelection()
 174             should be used instead in this case.
 175     */
 176     int GetSelection() const;
 177
 178     /**
 179         Inserts a new page just before the page indicated by @a pagePos. The new
 180         page is placed before @a pagePos page and on the same level. @NULL could
 181         be specified for page to create an empty page.
 182     */
 183     bool InsertPage(size_t pagePos, wxWindow* page,
 184                     const wxString& text,
 185                     bool bSelect = false,
 186                     int imageId = wxNOT_FOUND);
 187
 188     /**
 189         Inserts a sub page under the specified page.
 190
 191         @NULL could be specified for page to create an empty page.
 192     */
 193     bool InsertSubPage(size_t pagePos, wxWindow* page,
 194                        const wxString& text,
 195                        bool bSelect = false,
 196                        int imageId = wxNOT_FOUND);
 197
 198     /**
 199         Returns @true if the page represented by @a pageId is expanded.
 200     */
 201     bool IsNodeExpanded(size_t pageId) const;
 202
 203     /**
 204         Sets the image list for the page control. It does not take ownership of
 205         the image list, you must delete it yourself.
 206
 207         @see wxImageList, AssignImageList()
 208     */
 209     void SetImageList(wxImageList* imageList);
 210
 211     /**
 212         Sets the image index for the given @a page. @a imageId is an index into
 213         the image list which was set with SetImageList().
 214     */
 215     bool SetPageImage(size_t page, int imageId);
 216
 217     /**
 218         Sets the @a text for the given @a page.
 219     */
 220     bool SetPageText(size_t page, const wxString& text);
 221
 222     /**
 223         @deprecated Please use ChangeSelection() instead.
 224
 225         Sets the selection for the given page, returning the previous selection.
 226
 227         The call to this function generates page changing events.
 228
 229         @see GetSelection(), ChangeSelection()
 230     */
 231     int SetSelection(size_t n);
 232 };
 233