]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/bookctrl.h
Add new sample project files.
[wxWidgets.git] / interface / wx / bookctrl.h
CommitLineData
7977b62a
BP
1/////////////////////////////////////////////////////////////////////////////
2// Name: bookctrl.h
3// Purpose: interface of wxBookCtrlBase
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
7977b62a
BP
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxBookCtrlBase
7977b62a 11
340e9651
FM
12 A book control is a convenient way of displaying multiple pages of information,
13 displayed one page at a time. wxWidgets has five variants of this control:
14
15 @li wxChoicebook: controlled by a wxChoice
16 @li wxListbook: controlled by a wxListCtrl
17 @li wxNotebook: uses a row of tabs
18 @li wxTreebook: controlled by a wxTreeCtrl
19 @li wxToolbook: controlled by a wxToolBar
20
21 This abstract class is the parent of all these book controls, and provides
22 their basic interface.
23 This is a pure virtual class so you cannot allocate it directly.
7977b62a
BP
24
25 @library{wxcore}
3c99e2fd 26 @category{bookctrl}
7977b62a
BP
27
28 @see @ref overview_bookctrl
29*/
30class wxBookCtrlBase : public wxControl
31{
32public:
340e9651
FM
33 /**
34 Default ctor.
35 */
36 wxBookCtrlBase();
37
38 /**
39 Constructs the book control with the given parameters.
40 See Create() for two-step construction.
41 */
42 wxBookCtrlBase(wxWindow *parent,
43 wxWindowID winid,
44 const wxPoint& pos = wxDefaultPosition,
45 const wxSize& size = wxDefaultSize,
46 long style = 0,
47 const wxString& name = wxEmptyString);
48
49 /**
50 Constructs the book control with the given parameters.
51 */
52 bool Create(wxWindow *parent,
53 wxWindowID winid,
54 const wxPoint& pos = wxDefaultPosition,
55 const wxSize& size = wxDefaultSize,
56 long style = 0,
57 const wxString& name = wxEmptyString);
58
59
60 /**
61 @name Image list functions
62
63 Each page may have an attached image.
64 The functions of this group manipulate that image.
65 */
66 //@{
67
68 /**
69 Sets the image list for the page control and takes ownership of the list.
70
71 @see wxImageList, SetImageList()
72 */
73 void AssignImageList(wxImageList* imageList);
74
75 /**
76 Returns the associated image list.
77
78 @see wxImageList, SetImageList()
79 */
80 wxImageList* GetImageList() const;
81
82 /**
83 Returns the image index for the given page.
84 */
382f12e4 85 virtual int GetPageImage(size_t nPage) const = 0;
340e9651
FM
86
87 /**
88 Sets the image list for the page control.
89 It does not take ownership of the image list, you must delete it yourself.
90
91 @see wxImageList, AssignImageList()
92 */
93 virtual void SetImageList(wxImageList* imageList);
94
95 /**
96 Sets the image index for the given page. @a image is an index into
97 the image list which was set with SetImageList().
98 */
382f12e4 99 virtual bool SetPageImage(size_t page, int image) = 0;
340e9651
FM
100
101 //@}
102
103
104
105 /**
106 @name Page text functions
107
108 Each page has a text string attached.
109 The functions of this group manipulate that text.
110 */
111 //@{
112
113 /**
114 Returns the string for the given page.
115 */
116 virtual wxString GetPageText(size_t nPage) const = 0;
117
118 /**
119 Sets the text for the given page.
120 */
121 virtual bool SetPageText(size_t page, const wxString& text) = 0;
122 //@}
123
124
125
126 /**
127 @name Selection functions
128
129 The functions of this group manipulate the selection.
130 */
131 //@{
132
133 /**
134 Returns the currently selected page, or @c wxNOT_FOUND if none was selected.
135
136 Note that this method may return either the previously or newly
137 selected page when called from the @c EVT_BOOKCTRL_PAGE_CHANGED handler
138 depending on the platform and so wxBookCtrlEvent::GetSelection should be
139 used instead in this case.
140 */
141 virtual int GetSelection() const = 0;
142
143 /**
144 Returns the currently selected page or @NULL.
145 */
146 wxWindow* GetCurrentPage() const;
147
148 /**
149 Sets the selection for the given page, returning the previous selection.
340e9651 150
4863e551
VZ
151 Notice that the call to this function generates the page changing
152 events, use the ChangeSelection() function if you don't want these
153 events to be generated.
340e9651
FM
154
155 @see GetSelection()
156 */
382f12e4 157 virtual int SetSelection(size_t page) = 0;
340e9651
FM
158
159 /**
160 Cycles through the tabs.
161 The call to this function generates the page changing events.
162 */
163 void AdvanceSelection(bool forward = true);
7977b62a 164
340e9651
FM
165 /**
166 Changes the selection for the given page, returning the previous selection.
167
4863e551
VZ
168 This function behaves as SetSelection() but does @em not generate the
169 page changing events.
170
3e083d65 171 See @ref overview_events_prog for more information.
340e9651 172 */
382f12e4 173 virtual int ChangeSelection(size_t page) = 0;
340e9651
FM
174
175 //@}
176
177
178
179 /**
180 Sets the width and height of the pages.
181
182 @note This method is currently not implemented for wxGTK.
183 */
184 virtual void SetPageSize(const wxSize& size);
185
186 /**
187 Returns the index of the tab at the specified position or @c wxNOT_FOUND
188 if none. If @a flags parameter is non-@NULL, the position of the point
189 inside the tab is returned as well.
190
191 @param pt
192 Specifies the point for the hit test.
193 @param flags
194 Return value for detailed information. One of the following values:
195 <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
196 <TD>There was no tab under this point.</TD></TR>
197 <TR><TD>wxBK_HITTEST_ONICON</TD>
198 <TD>The point was over an icon (currently wxMSW only).</TD></TR>
199 <TR><TD>wxBK_HITTEST_ONLABEL</TD>
200 <TD>The point was over a label (currently wxMSW only).</TD></TR>
201 <TR><TD>wxBK_HITTEST_ONITEM</TD>
202 <TD>The point was over an item, but not on the label or icon.</TD></TR>
203 <TR><TD>wxBK_HITTEST_ONPAGE</TD>
204 <TD>The point was over a currently selected page, not over any tab.
205 Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
206 </TABLE>
207
208 @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
209 tab at the specified position.
210 */
211 virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
212
213
214
215 /**
216 @name Page management functions
217
218 Functions for adding/removing pages from this control.
219 */
220 //@{
221
222 /**
223 Adds a new page.
1dfe47d0
VZ
224
225 The page must have the book control itself as the parent and must not
226 have been added to this control previously.
227
340e9651
FM
228 The call to this function may generate the page changing events.
229
230 @param page
231 Specifies the new page.
232 @param text
233 Specifies the text for the new page.
234 @param select
235 Specifies whether the page should be selected.
236 @param imageId
237 Specifies the optional image index for the new page.
238
239 @return @true if successful, @false otherwise.
240
241 @remarks Do not delete the page, it will be deleted by the book control.
242
243 @see InsertPage()
244 */
382f12e4
FM
245 virtual bool AddPage(wxWindow* page, const wxString& text,
246 bool select = false, int imageId = wxNOT_FOUND);
340e9651
FM
247
248 /**
249 Deletes all pages.
250 */
251 virtual bool DeleteAllPages();
252
253 /**
254 Deletes the specified page, and the associated window.
255 The call to this function generates the page changing events.
256 */
382f12e4 257 virtual bool DeletePage(size_t page);
340e9651
FM
258
259 /**
260 Inserts a new page at the specified position.
261
262 @param index
263 Specifies the position for the new page.
264 @param page
265 Specifies the new page.
266 @param text
267 Specifies the text for the new page.
268 @param select
269 Specifies whether the page should be selected.
270 @param imageId
271 Specifies the optional image index for the new page.
272
273 @return @true if successful, @false otherwise.
274
275 @remarks Do not delete the page, it will be deleted by the book control.
276
277 @see AddPage()
278 */
279 virtual bool InsertPage(size_t index,
280 wxWindow* page,
281 const wxString& text,
282 bool select = false,
283 int imageId = wxNOT_FOUND) = 0;
284
285 /**
286 Deletes the specified page, without deleting the associated window.
287 */
382f12e4 288 virtual bool RemovePage(size_t page);
340e9651
FM
289
290 /**
291 Returns the number of pages in the control.
292 */
382f12e4 293 virtual size_t GetPageCount() const;
340e9651
FM
294
295 /**
296 Returns the window at the given page position.
297 */
382f12e4 298 wxWindow* GetPage(size_t page) const;
340e9651
FM
299
300 //@}
301
302
303/*
304 other functions which may be worth documenting:
305
306 // geometry
307 // --------
308
309 // calculate the size of the control from the size of its page
310 virtual wxSize CalcSizeFromPage(const wxSize& sizePage) const = 0;
311
312 // get/set size of area between book control area and page area
313 unsigned int GetInternalBorder() const { return m_internalBorder; }
314 void SetInternalBorder(unsigned int border) { m_internalBorder = border; }
315
316 // Sets/gets the margin around the controller
317 void SetControlMargin(int margin) { m_controlMargin = margin; }
318 int GetControlMargin() const { return m_controlMargin; }
319
320 // returns true if we have wxBK_TOP or wxBK_BOTTOM style
321 bool IsVertical() const { return HasFlag(wxBK_BOTTOM | wxBK_TOP); }
322
323 // set/get option to shrink to fit current page
324 void SetFitToCurrentPage(bool fit) { m_fitToCurrentPage = fit; }
325 bool GetFitToCurrentPage() const { return m_fitToCurrentPage; }
326
327 // returns the sizer containing the control, if any
328 wxSizer* GetControlSizer() const { return m_controlSizer; }
329
330 // we do have multiple pages
331 virtual bool HasMultiplePages() const { return true; }
332
333 // we don't want focus for ourselves
334 virtual bool AcceptsFocus() const { return false; }
335
336 // returns true if the platform should explicitly apply a theme border
337 virtual bool CanApplyThemeBorder() const { return false; }
338*/
7977b62a
BP
339};
340
d8231db2
FM
341/**
342 wxBookCtrl is defined to one of the 'real' book controls.
343
344 See @ref overview_bookctrl for more info.
345*/
346#define wxBookCtrl TheBestBookCtrlForTheCurrentPlatform
347
3e97a905
VZ
348
349/**
350 @class wxBookCtrlEvent
351
352 This class represents the events generated by book controls (wxNotebook,
353 wxListbook, wxChoicebook, wxTreebook).
340e9651 354
3e97a905
VZ
355 The PAGE_CHANGING events are sent before the current page is changed.
356 It allows the program to examine the current page (which can be retrieved
357 with wxBookCtrlEvent::GetOldSelection) and to veto the page change by calling
358 wxNotifyEvent::Veto if, for example, the current values in the controls
359 of the old page are invalid.
360
340e9651
FM
361 The PAGE_CHANGED events are sent after the page has been changed and the
362 program cannot veto it any more, it just informs it about the page change.
3e97a905
VZ
363
364 To summarize, if the program is interested in validating the page values
365 before allowing the user to change it, it should process the PAGE_CHANGING
366 event, otherwise PAGE_CHANGED is probably enough. In any case, it is
367 probably unnecessary to process both events at once.
368
369 @library{wxcore}
3c99e2fd 370 @category{events,bookctrl}
3e97a905 371
340e9651 372 @see wxNotebook, wxListbook, wxChoicebook, wxTreebook, wxToolbook
3e97a905 373*/
3e97a905
VZ
374class wxBookCtrlEvent : public wxNotifyEvent
375{
376public:
377 /**
378 Constructor (used internally by wxWidgets only).
379 */
380 wxBookCtrlEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
340e9651 381 int sel = wxNOT_FOUND, int oldSel = wxNOT_FOUND);
3e97a905
VZ
382
383 /**
384 Returns the page that was selected before the change, @c wxNOT_FOUND if
385 none was selected.
386 */
387 int GetOldSelection() const;
388
389 /**
390 Returns the currently selected page, or @c wxNOT_FOUND if none was
391 selected.
340e9651 392
3e97a905 393 @note under Windows, GetSelection() will return the same value as
340e9651
FM
394 GetOldSelection() when called from the @c EVT_BOOKCTRL_PAGE_CHANGING
395 handler and not the page which is going to be selected.
3e97a905
VZ
396 */
397 int GetSelection() const;
398
399 /**
400 Sets the id of the page selected before the change.
401 */
402 void SetOldSelection(int page);
403
404 /**
405 Sets the selection member variable.
406 */
407 void SetSelection(int page);
408};
409