interface/wx/treebook.h

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