]> git.saurik.com Git - wxWidgets.git/blob - interface/notebook.h
Compilation fixes for mingw-w64.
[wxWidgets.git] / interface / notebook.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: notebook.h
3 // Purpose: interface of wxNotebookEvent
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxNotebookEvent
11 @wxheader{notebook.h}
12
13 This class represents the events generated by a notebook control: currently,
14 there are two of them. The PAGE_CHANGING event is sent before the current
15 page is changed. It allows the program to examine the current page (which
16 can be retrieved with
17 wxNotebookEvent::GetOldSelection) and to veto the page
18 change by calling wxNotifyEvent::Veto if, for example, the
19 current values in the controls of the old page are invalid.
20
21 The second event - PAGE_CHANGED - is sent after the page has been changed and
22 the program cannot veto it any more, it just informs it about the page change.
23
24 To summarize, if the program is interested in validating the page values
25 before allowing the user to change it, it should process the PAGE_CHANGING
26 event, otherwise PAGE_CHANGED is probably enough. In any case, it is probably
27 unnecessary to process both events at once.
28
29 @library{wxcore}
30 @category{events}
31
32 @see wxNotebook
33 */
34 class wxNotebookEvent : public wxNotifyEvent
35 {
36 public:
37 /**
38 Constructor (used internally by wxWidgets only).
39 */
40 wxNotebookEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
41 int sel = -1,
42 int oldSel = -1);
43
44 /**
45 Returns the page that was selected before the change, -1 if none was selected.
46 */
47 int GetOldSelection() const;
48
49 /**
50 Returns the currently selected page, or -1 if none was selected.
51 @note under Windows, GetSelection() will return the same value as
52 GetOldSelection() when called from
53 @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to
54 be selected. Also note that the values of selection and old selection returned
55 for an event generated in response to a call to
56 wxNotebook::SetSelection shouldn't be trusted
57 as they are currently inconsistent under different platforms (but in this case
58 you presumably don't need them anyhow as you already have the corresponding
59 information).
60 */
61 int GetSelection() const;
62
63 /**
64 Sets the id of the page selected before the change.
65 */
66 void SetOldSelection(int page);
67
68 /**
69 Sets the selection member variable.
70 */
71 void SetSelection(int page);
72 };
73
74
75
76 /**
77 @class wxNotebook
78 @wxheader{notebook.h}
79
80 This class represents a notebook control, which manages multiple windows with
81 associated tabs.
82
83 To use the class, create a wxNotebook object and call wxNotebook::AddPage or
84 wxNotebook::InsertPage,
85 passing a window to be used as the page. Do not explicitly delete the window
86 for a page that is currently
87 managed by wxNotebook.
88
89 @b wxNotebookPage is a typedef for wxWindow.
90
91 @beginStyleTable
92 @style{wxNB_TOP}
93 Place tabs on the top side.
94 @style{wxNB_LEFT}
95 Place tabs on the left side.
96 @style{wxNB_RIGHT}
97 Place tabs on the right side.
98 @style{wxNB_BOTTOM}
99 Place tabs under instead of above the notebook pages.
100 @style{wxNB_FIXEDWIDTH}
101 (Windows only) All tabs will have same width.
102 @style{wxNB_MULTILINE}
103 (Windows only) There can be several rows of tabs.
104 @style{wxNB_NOPAGETHEME}
105 (Windows only) Display a solid colour on notebook pages, and not a
106 gradient, which can reduce performance.
107 @style{wxNB_FLAT}
108 (Windows CE only) Show tabs in a flat style.
109 @endStyleTable
110
111 @library{wxcore}
112 @category{miscwnd}
113
114 @see wxBookCtrl(), wxNotebookEvent, wxImageList, @ref overview_samplenotebook
115 "notebook sample"
116 */
117 class wxNotebook : public wxBookCtrl overview
118 {
119 public:
120 //@{
121 /**
122 Constructs a notebook control.
123 Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN
124 window style.
125
126 @param parent
127 The parent window. Must be non-@NULL.
128 @param id
129 The window identifier.
130 @param pos
131 The window position.
132 @param size
133 The window size.
134 @param style
135 The window style. See wxNotebook.
136 @param name
137 The name of the control (used only under Motif).
138 */
139 wxNotebook();
140 wxNotebook(wxWindow* parent, wxWindowID id,
141 const wxPoint& pos = wxDefaultPosition,
142 const wxSize& size = wxDefaultSize,
143 long style = 0,
144 const wxString& name = wxNotebookNameStr);
145 //@}
146
147 /**
148 Destroys the wxNotebook object.
149 */
150 virtual ~wxNotebook();
151
152 /**
153 Adds a new page.
154 The call to this function may generate the page changing events.
155
156 @param page
157 Specifies the new page.
158 @param text
159 Specifies the text for the new page.
160 @param select
161 Specifies whether the page should be selected.
162 @param imageId
163 Specifies the optional image index for the new page.
164
165 @return @true if successful, @false otherwise.
166
167 @remarks Do not delete the page, it will be deleted by the notebook.
168
169 @see InsertPage()
170 */
171 bool AddPage(wxNotebookPage* page, const wxString& text,
172 bool select = false,
173 int imageId = -1);
174
175 /**
176 Cycles through the tabs.
177 The call to this function generates the page changing events.
178 */
179 void AdvanceSelection(bool forward = true);
180
181 /**
182 Sets the image list for the page control and takes ownership of
183 the list.
184
185 @see wxImageList, SetImageList()
186 */
187 void AssignImageList(wxImageList* imageList);
188
189 /**
190 Changes the selection for the given page, returning the previous selection.
191 The call to this function does not generate the page changing events.
192 This is the only difference with SetSelection().
193 See @ref overview_progevent "this topic" for more info.
194 */
195 virtual int ChangeSelection(size_t page);
196
197 /**
198 Creates a notebook control. See wxNotebook() for a description
199 of the parameters.
200 */
201 bool Create(wxWindow* parent, wxWindowID id,
202 const wxPoint& pos = wxDefaultPosition,
203 const wxSize& size = wxDefaultSize,
204 long style = 0,
205 const wxString& name = wxNotebookNameStr);
206
207 /**
208 Deletes all pages.
209 */
210 virtual bool DeleteAllPages();
211
212 /**
213 Deletes the specified page, and the associated window.
214 The call to this function generates the page changing events.
215 */
216 bool DeletePage(size_t page);
217
218 /**
219 Returns the currently selected notebook page or @NULL.
220 */
221 wxWindow* GetCurrentPage() const;
222
223 /**
224 Returns the associated image list.
225
226 @see wxImageList, SetImageList()
227 */
228 wxImageList* GetImageList() const;
229
230 /**
231 Returns the window at the given page position.
232 */
233 wxNotebookPage* GetPage(size_t page);
234
235 /**
236 Returns the number of pages in the notebook control.
237 */
238 size_t GetPageCount() const;
239
240 /**
241 Returns the image index for the given page.
242 */
243 virtual int GetPageImage(size_t nPage) const;
244
245 /**
246 Returns the string for the given page.
247 */
248 virtual wxString GetPageText(size_t nPage) const;
249
250 /**
251 Returns the number of rows in the notebook control.
252 */
253 virtual int GetRowCount() const;
254
255 /**
256 Returns the currently selected page, or -1 if none was selected.
257 Note that this method may return either the previously or newly selected page
258 when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on
259 the platform and so
260 wxNotebookEvent::GetSelection should be
261 used instead in this case.
262 */
263 virtual int GetSelection() const;
264
265 /**
266 If running under Windows and themes are enabled for the application, this
267 function
268 returns a suitable colour for painting the background of a notebook page, and
269 can be passed
270 to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned.
271 */
272 virtual wxColour GetThemeBackgroundColour() const;
273
274 /**
275 Returns the index of the tab at the specified position or @c wxNOT_FOUND
276 if none. If @a flags parameter is non-@NULL, the position of the point
277 inside the tab is returned as well.
278
279 @param pt
280 Specifies the point for the hit test.
281 @param flags
282 Return value for detailed information. One of the following values:
283
284
285
286
287
288
289
290 wxBK_HITTEST_NOWHERE
291
292
293
294
295 There was no tab under this point.
296
297
298
299
300
301 wxBK_HITTEST_ONICON
302
303
304
305
306 The point was over an icon (currently wxMSW only).
307
308
309
310
311
312 wxBK_HITTEST_ONLABEL
313
314
315
316
317 The point was over a label (currently wxMSW only).
318
319
320
321
322
323 wxBK_HITTEST_ONITEM
324
325
326
327
328 The point was over an item, but not on the label or icon.
329
330
331
332
333
334 wxBK_HITTEST_ONPAGE
335
336
337
338
339 The point was over a currently selected page, not over any tab. Note that
340 this flag is present only if wxNOT_FOUND is returned.
341
342 @return Returns the zero-based tab index or wxNOT_FOUND if there is no
343 tab is at the specified position.
344 */
345 virtual int HitTest(const wxPoint& pt, long* = NULL) const;
346
347 /**
348 Inserts a new page at the specified position.
349
350 @param index
351 Specifies the position for the new page.
352 @param page
353 Specifies the new page.
354 @param text
355 Specifies the text for the new page.
356 @param select
357 Specifies whether the page should be selected.
358 @param imageId
359 Specifies the optional image index for the new page.
360
361 @return @true if successful, @false otherwise.
362
363 @remarks Do not delete the page, it will be deleted by the notebook.
364
365 @see AddPage()
366 */
367 bool InsertPage(size_t index, wxNotebookPage* page,
368 const wxString& text,
369 bool select = false,
370 int imageId = -1);
371
372 /**
373 An event handler function, called when the page selection is changed.
374
375 @see wxNotebookEvent
376 */
377 void OnSelChange(wxNotebookEvent& event);
378
379 /**
380 Deletes the specified page, without deleting the associated window.
381 */
382 bool RemovePage(size_t page);
383
384 /**
385 Sets the image list for the page control. It does not take
386 ownership of the image list, you must delete it yourself.
387
388 @see wxImageList, AssignImageList()
389 */
390 void SetImageList(wxImageList* imageList);
391
392 /**
393 Sets the amount of space around each page's icon and label, in pixels.
394 @note The vertical padding cannot be changed in wxGTK.
395 */
396 void SetPadding(const wxSize& padding);
397
398 /**
399 Sets the image index for the given page. @a image is an index into
400 the image list which was set with SetImageList().
401 */
402 virtual bool SetPageImage(size_t page, int image);
403
404 /**
405 Sets the width and height of the pages.
406 @note This method is currently not implemented for wxGTK.
407 */
408 virtual void SetPageSize(const wxSize& size);
409
410 /**
411 Sets the text for the given page.
412 */
413 virtual bool SetPageText(size_t page, const wxString& text);
414
415 /**
416 Sets the selection for the given page, returning the previous selection.
417 The call to this function generates the page changing events.
418 This function is deprecated and should not be used in new code. Please use the
419 ChangeSelection() function instead.
420
421 @see GetSelection()
422 */
423 virtual int SetSelection(size_t page);
424 };
425