]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/treebook.h
Moved wxPGChoices m_choices member from various property classes to base wxPGProperty...
[wxWidgets.git] / 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