]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/treebook.h
generate a size event from ShowWithEffect() for consistency with Show()
[wxWidgets.git] / interface / wx / treebook.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: treebook.h
3// Purpose: interface of wxTreebookEvent
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxTreebookEvent
11
12 This class represents the events generated by a treebook control: currently,
13 there are four of them. The EVT_TREEBOOK_PAGE_CHANGING() and
14 EVT_TREEBOOK_PAGE_CHANGED() - have exactly the same behaviour as
15 wxNotebookEvent.
16
17 The other two EVT_TREEBOOK_NODE_COLLAPSED() and EVT_TREEBOOK_NODE_EXPANDED()
18 are triggered when page node in the tree control is collapsed/expanded. The
19 page index could be retreived by calling GetSelection().
20
21 @beginEventTable{wxTreebookEvent}
22 @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
23 The page selection was changed. Processes a @c
24 wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
25 @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
26 The page selection is about to be changed. Processes a @c
27 wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref
28 wxNotifyEvent::Veto() "vetoed".
29 @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
30 The page node is going to be collapsed. Processes a @c
31 wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
32 @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
33 The page node is going to be expanded. Processes a @c
34 wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
35 @endEventTable
36
37 @library{wxcore}
38 @category{events}
39
40 @see wxTreebook, wxNotebookEvent
41*/
42class wxTreebookEvent : public wxNotifyEvent
43{
44public:
45 /**
46 @see wxNotebookEvent
47 */
48 wxTreebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,
49 int nSel = wxNOT_FOUND,
50 int nOldSel = wxNOT_FOUND);
51
52 /**
53 Returns the page that was selected before the change, @c wxNOT_FOUND if
54 none was selected.
55 */
56 int GetOldSelection() const;
57
58 /**
59 Returns the currently selected page, or @c wxNOT_FOUND if none was
60 selected.
61
62 @see wxNotebookEvent::GetSelection()
63 */
64 int GetSelection() const;
65};
66
67
68
69/**
70 @class wxTreebook
71
72 This class is an extension of the wxNotebook class that allows a tree
73 structured set of pages to be shown in a control. A classic example is a
74 netscape preferences dialog that shows a tree of preference sections on
75 the left and select section page on the right.
76
77 To use the class simply create it and populate with pages using
78 InsertPage(), InsertSubPage(), AddPage(), AddSubPage().
79
80 If your tree is no more than 1 level in depth then you could simply use
81 AddPage() and AddSubPage() to sequentially populate your tree by adding at
82 every step a page or a subpage to the end of the tree.
83
84 @beginEventTable{wxTreebookEvent}
85 @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
86 The page selection was changed. Processes a @c
87 wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
88 @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
89 The page selection is about to be changed. Processes a @c
90 wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref
91 wxNotifyEvent::Veto() "vetoed".
92 @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
93 The page node is going to be collapsed. Processes a @c
94 wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
95 @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
96 The page node is going to be expanded. Processes a @c
97 wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
98 @endEventTable
99
100 @library{wxcore}
101 @category{miscwnd}
102
103 @see wxTreebookEvent, wxNotebook, wxTreeCtrl, wxImageList,
104 @ref overview_bookctrl, @ref page_samples_notebook
105*/
106class wxTreebook : public wxBookCtrlBase
107{
108public:
109 /**
110 Default constructor.
111 */
112 wxTreebook();
113
114 /**
115 Creates an empty wxTreebook.
116
117 @param parent
118 The parent window. Must be non-@NULL.
119 @param id
120 The window identifier.
121 @param pos
122 The window position.
123 @param size
124 The window size.
125 @param style
126 The window style. See wxNotebook.
127 @param name
128 The name of the control (used only under Motif).
129 */
130 wxTreebook(wxWindow* parent, wxWindowID id,
131 const wxPoint& pos = wxDefaultPosition,
132 const wxSize& size = wxDefaultSize,
133 long style = wxBK_DEFAULT,
134 const wxString& name = wxEmptyString);
135
136 /**
137 Destroys the wxTreebook object. Also deletes all the pages owned by the
138 control (inserted previously into it).
139 */
140 ~wxTreebook();
141
142 /**
143 Adds a new page. The page is placed at the topmost level after all other
144 pages. @NULL could be specified for page to create an empty page.
145 */
146 bool AddPage(wxWindow* page, const wxString& text,
147 bool bSelect = false,
148 int imageId = wxNOT_FOUND);
149
150 /**
151 Adds a new child-page to the last top-level page. @NULL could be
152 specified for page to create an empty page.
153 */
154 bool AddSubPage(wxWindow* page, const wxString& text,
155 bool bSelect = false,
156 int imageId = wxNOT_FOUND);
157
158 /**
159 Sets the image list for the page control and takes ownership of the
160 list.
161
162 @see wxImageList, SetImageList()
163 */
164 void AssignImageList(wxImageList* imageList);
165
166 /**
167 Changes the selection for the given page, returning the previous
168 selection.
169
170 The call to this function does not generate the page changing events.
171 This is the only difference with SetSelection(). See
172 @ref overview_eventhandling_prog for more info.
173 */
174 int ChangeSelection(size_t page);
175
176 /**
177 Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId,
178 @false ).
179 */
180 bool CollapseNode(size_t pageId);
181
182 /**
183 Creates a treebook control. See wxTreebook::wxTreebook() for the
184 description of the parameters.
185 */
186 bool Create(wxWindow* parent, wxWindowID id,
187 const wxPoint& pos = wxDefaultPosition,
188 const wxSize& size = wxDefaultSize,
189 long style = wxBK_DEFAULT,
190 const wxString& name = wxEmptyString);
191
192 /**
193 Deletes all pages inserted into the treebook. No event is generated.
194 */
195 bool DeleteAllPages();
196
197 /**
198 Deletes the page at the specified position and all its children. Could
199 trigger page selection change in a case when selected page is removed.
200 In that case its parent is selected (or the next page if no parent).
201 */
202 bool DeletePage(size_t pagePos);
203
204 /**
205 Expands (collapses) the @a pageId node. Returns the previous state. May
206 generate page changing events (if selected page is under the collapsed
207 branch, then its parent is autoselected).
208 */
209 bool ExpandNode(size_t pageId, bool expand = true);
210
211 /**
212 Returns the image index for the given page.
213 */
214 int GetPageImage(size_t n) const;
215
216 /**
217 Returns the parent page of the given one or @c wxNOT_FOUND if this is a
218 top-level page.
219 */
220 int GetPageParent(size_t page) const;
221
222 /**
223 Returns the string for the given page.
224 */
225 wxString GetPageText(size_t n) const;
226
227 /**
228 Returns the currently selected page, or @c wxNOT_FOUND if none was
229 selected.
230
231 @note This method may return either the previously or newly selected
232 page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler
233 depending on the platform and so wxTreebookEvent::GetSelection()
234 should be used instead in this case.
235 */
236 int GetSelection() const;
237
238 /**
239 Inserts a new page just before the page indicated by @a pagePos. The new
240 page is placed before @a pagePos page and on the same level. @NULL could
241 be specified for page to create an empty page.
242 */
243 bool InsertPage(size_t pagePos, wxWindow* page,
244 const wxString& text,
245 bool bSelect = false,
246 int imageId = wxNOT_FOUND);
247
248 /**
249 Inserts a sub page under the specified page.
250
251 @NULL could be specified for page to create an empty page.
252 */
253 bool InsertSubPage(size_t pagePos, wxWindow* page,
254 const wxString& text,
255 bool bSelect = false,
256 int imageId = wxNOT_FOUND);
257
258 /**
259 Returns @true if the page represented by @a pageId is expanded.
260 */
261 bool IsNodeExpanded(size_t pageId) const;
262
263 /**
264 Sets the image list for the page control. It does not take ownership of
265 the image list, you must delete it yourself.
266
267 @see wxImageList, AssignImageList()
268 */
269 void SetImageList(wxImageList* imageList);
270
271 /**
272 Sets the image index for the given @a page. @a imageId is an index into
273 the image list which was set with SetImageList().
274 */
275 bool SetPageImage(size_t page, int imageId);
276
277 /**
278 Sets the @a text for the given @a page.
279 */
280 bool SetPageText(size_t page, const wxString& text);
281
282 /**
283 @deprecated Please use ChangeSelection() instead.
284
285 Sets the selection for the given page, returning the previous selection.
286
287 The call to this function generates page changing events.
288
289 @see GetSelection(), ChangeSelection()
290 */
291 int SetSelection(size_t n);
292};
293