1\section{\class{wxNotebook}}\label{wxnotebook}
2
3This class represents a notebook control, which manages multiple windows with associated tabs.
4
5To use the class, create a wxNotebook object and call \helpref{AddPage}{wxnotebookaddpage} or \helpref{InsertPage}{wxnotebookinsertpage},
6passing a window to be used as the page. Do not explicitly delete the window for a page that is currently
7managed by wxNotebook.
8
9{\bf wxNotebookPage} is a typedef for wxWindow.
10
11\wxheading{Derived from}
12
13\helpref{wxControl}{wxcontrol}\\
14\helpref{wxWindow}{wxwindow}\\
15\helpref{wxEvtHandler}{wxevthandler}\\
16\helpref{wxObject}{wxobject}
17
18\wxheading{Include files}
19
20<wx/notebook.h>
21
22\wxheading{Window styles}
23
24\twocolwidtha{5cm}
25\begin{twocollist}\itemsep=0pt
26\twocolitem{\windowstyle{wxNB\_TOP}}{Place tabs on the top side.}
27\twocolitem{\windowstyle{wxNB\_LEFT}}{Place tabs on the left side.}
28\twocolitem{\windowstyle{wxNB\_RIGHT}}{Place tabs on the right side.}
29\twocolitem{\windowstyle{wxNB\_BOTTOM}}{Place tabs under instead of above the notebook pages.}
30\twocolitem{\windowstyle{wxNB\_FIXEDWIDTH}}{(Windows only) All tabs will have same width.}
31\twocolitem{\windowstyle{wxNB\_MULTILINE}}{(Windows only) There can be several rows of tabs.}
32\twocolitem{\windowstyle{wxNB\_NOPAGETHEME}}{(Windows only) Display a solid colour on notebook pages, and not a gradient, which can reduce performance.}
33\twocolitem{\windowstyle{wxNB\_FLAT}}{(Windows CE only) Show tabs in a flat style.}
34
35\end{twocollist}
36
37The styles \texttt{wxNB\_LEFT}, \texttt{RIGHT} and \texttt{BOTTOM} are not
38supported under Microsoft Windows XP when using visual themes.
39
40See also \helpref{window styles overview}{windowstyles}.
41
42\input noteevt.inc
43
44\wxheading{Page backgrounds}
45
46On Windows XP, the default theme paints a gradient on the notebook's pages.
47If you wish to suppress this theme, for aesthetic or performance reasons,
48there are three ways of doing it. You can use wxNB\_NOPAGETHEME to disable
49themed drawing for a particular notebook, you can call {\tt wxSystemOptions::SetOption}
50to disable it for the whole application, or you can disable it for individual
51pages by using {\tt SetBackgroundColour}.
52
53To disable themed pages globally:
54
55\begin{verbatim}
56    wxSystemOptions::SetOption(wxT("msw.notebook.themed-background"), 0);
57\end{verbatim}
58
59Set the value to 1 to enable it again.
60
61To give a single page a solid background that more or less fits in with the
62overall theme, use:
63
64\begin{verbatim}
65    wxColour col = notebook->GetThemeBackgroundColour();
66    if (col.Ok())
67    {
68        page->SetBackgroundColour(col);
69    }
70\end{verbatim}
71
72On platforms other than Windows, or if the application is not using Windows
73themes, {\tt GetThemeBackgroundColour} will return an uninitialised colour object,
74and the above code will therefore work on all platforms.
75
76\wxheading{See also}
77
78\helpref{wxBookCtrl}{wxbookctrloverview}, \helpref{wxNotebookEvent}{wxnotebookevent}, \helpref{wxImageList}{wximagelist}, \helpref{notebook sample}{samplenotebook}\rtfsp
79
80\latexignore{\rtfignore{\wxheading{Members}}}
81
82\membersection{wxNotebook::wxNotebook}\label{wxnotebookctor}
83
84\func{}{wxNotebook}{\void}
85
86Default constructor.
87
88\func{}{wxNotebook}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},
89 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = 0}, \param{const wxString\& }{name = wxNotebookNameStr}}
90
91Constructs a notebook control.
92
93Note that sometimes you can reduce flicker by passing the wxCLIP\_CHILDREN window style.
94
95\wxheading{Parameters}
96
97\docparam{parent}{The parent window. Must be non-NULL.}
98
99\docparam{id}{The window identifier.}
100
101\docparam{pos}{The window position.}
102
103\docparam{size}{The window size.}
104
105\docparam{style}{The window style. See \helpref{wxNotebook}{wxnotebook}.}
106
107\docparam{name}{The name of the control (used only under Motif).}
108
109
110\membersection{wxNotebook::\destruct{wxNotebook}}\label{wxnotebookdtor}
111
112\func{}{\destruct{wxNotebook}}{\void}
113
114Destroys the wxNotebook object.
115
116
117\membersection{wxNotebook::AddPage}\label{wxnotebookaddpage}
118
119\func{bool}{AddPage}{\param{wxNotebookPage*}{ page},
120 \param{const wxString\&}{ text},
121 \param{bool}{ select = false},
122 \param{int}{ imageId = -1}}
123
124Adds a new page.
125
126The call to this function may generate the page changing events.
127
128\wxheading{Parameters}
129
130\docparam{page}{Specifies the new page.}
131
132\docparam{text}{Specifies the text for the new page.}
133
134\docparam{select}{Specifies whether the page should be selected.}
135
136\docparam{imageId}{Specifies the optional image index for the new page.}
137
138\wxheading{Return value}
139
140true if successful, false otherwise.
141
142\wxheading{Remarks}
143
144Do not delete the page, it will be deleted by the notebook.
145
146\wxheading{See also}
147
148\helpref{wxNotebook::InsertPage}{wxnotebookinsertpage}
149
150
151\membersection{wxNotebook::AdvanceSelection}\label{wxnotebookadvanceselection}
152
153\func{void}{AdvanceSelection}{\param{bool}{ forward = true}}
154
155Cycles through the tabs.
156
157The call to this function generates the page changing events.
158
159
160\membersection{wxNotebook::AssignImageList}\label{wxnotebookassignimagelist}
161
162\func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
163
164Sets the image list for the page control and takes ownership of
165the list.
166
167\wxheading{See also}
168
169\helpref{wxImageList}{wximagelist},
170\helpref{SetImageList}{wxnotebooksetimagelist}
171
172
173\membersection{wxNotebook::ChangeSelection}\label{wxnotebookchangeselection}
174
175\func{int}{ChangeSelection}{\param{size\_t}{ page}}
176
177Changes the selection for the given page, returning the previous selection.
178
179The call to this function \emph{does not} generate the page changing events.
180This is the only difference with \helpref{SetSelection}{wxnotebooksetselection}.
181See \helpref{this topic}{progevent} for more info.
182
183
184
185\membersection{wxNotebook::Create}\label{wxnotebookcreate}
186
187\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},
188 \param{const wxSize\&}{ size}, \param{long}{ style = 0}, \param{const wxString\& }{name = wxNotebookNameStr}}
189
190Creates a notebook control. See \helpref{wxNotebook::wxNotebook}{wxnotebookctor} for a description
191of the parameters.
192
193
194\membersection{wxNotebook::DeleteAllPages}\label{wxnotebookdeleteallpages}
195
196\func{bool}{DeleteAllPages}{\void}
197
198Deletes all pages.
199
200
201\membersection{wxNotebook::DeletePage}\label{wxnotebookdeletepage}
202
203\func{bool}{DeletePage}{\param{size\_t}{ page}}
204
205Deletes the specified page, and the associated window.
206
207The call to this function generates the page changing events.
208
209
210\membersection{wxNotebook::GetCurrentPage}\label{wxnotebookgetcurrentpage}
211
212\constfunc{wxWindow *}{GetCurrentPage}{\void}
213
214Returns the currently selected notebook page or \NULL.
215
216
217\membersection{wxNotebook::GetImageList}\label{wxnotebookgetimagelist}
218
219\constfunc{wxImageList*}{GetImageList}{\void}
220
221Returns the associated image list.
222
223\wxheading{See also}
224
225\helpref{wxImageList}{wximagelist}, \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}
226
227
228\membersection{wxNotebook::GetPage}\label{wxnotebookgetpage}
229
230\func{wxNotebookPage*}{GetPage}{\param{size\_t}{ page}}
231
232Returns the window at the given page position.
233
234
235\membersection{wxNotebook::GetPageCount}\label{wxnotebookgetpagecount}
236
237\constfunc{size\_t}{GetPageCount}{\void}
238
239Returns the number of pages in the notebook control.
240
241
242\membersection{wxNotebook::GetPageImage}\label{wxnotebookgetpageimage}
243
244\constfunc{int}{GetPageImage}{\param{size\_t }{nPage}}
245
246Returns the image index for the given page.
247
248
249\membersection{wxNotebook::GetPageText}\label{wxnotebookgetpagetext}
250
251\constfunc{wxString}{GetPageText}{\param{size\_t }{nPage}}
252
253Returns the string for the given page.
254
255
256\membersection{wxNotebook::GetRowCount}\label{wxnotebookgetrowcount}
257
258\constfunc{int}{GetRowCount}{\void}
259
260Returns the number of rows in the notebook control.
261
262
263\membersection{wxNotebook::GetSelection}\label{wxnotebookgetselection}
264
265\constfunc{int}{GetSelection}{\void}
266
267Returns the currently selected page, or $-1$ if none was selected.
268
269Note that this method may return either the previously or newly selected page
270when called from the {\tt EVT\_NOTEBOOK\_PAGE\_CHANGED} handler depending on
271the platform and so\rtfsp
272\helpref{wxNotebookEvent::GetSelection}{wxnotebookeventgetselection} should be
273used instead in this case.
274
275\membersection{wxNotebook::GetThemeBackgroundColour}\label{wxnotebookgetthemebackgroundcolour}
276
277\constfunc{wxColour}{GetThemeBackgroundColour}{\void}
278
279If running under Windows and themes are enabled for the application, this function
280returns a suitable colour for painting the background of a notebook page, and can be passed
281to {\tt SetBackgroundColour}. Otherwise, an uninitialised colour will be returned.
282
283\membersection{wxNotebook::HitTest}\label{wxnotebookhittest}
284
285\func{int}{HitTest}{\param{const wxPoint\&}{ pt}, \param{long}{ *flags = {\tt NULL}}}
286
287Returns the index of the tab at the specified position or {\tt wxNOT\_FOUND}
288if none. If {\it flags} parameter is non-{\tt NULL}, the position of the point
289inside the tab is returned as well.
290
291\wxheading{Parameters}
292
293\docparam{pt}{Specifies the point for the hit test.}
294
295\docparam{flags}{Return value for detailed information. One of the following values:
296\twocolwidtha{7cm}
297\begin{twocollist}\itemsep=0pt
298\twocolitem{{\bf wxBK\_HITTEST\_NOWHERE}}{There was no tab under this point.}
299\twocolitem{{\bf wxBK\_HITTEST\_ONICON}}{The point was over an icon (currently wxMSW only).}
300\twocolitem{{\bf wxBK\_HITTEST\_ONLABEL}}{The point was over a label (currently wxMSW only).}
301\twocolitem{{\bf wxBK\_HITTEST\_ONITEM}}{The point was over an item, but not on the label or icon.}
302\twocolitem{{\bf wxBK\_HITTEST\_ONPAGE}}{The point was over a currently selected page, not over any tab. Note that this flag is present only if {\tt wxNOT\_FOUND} is returned.}
303\end{twocollist}
304}
305
306\wxheading{Return value}
307
308Returns the zero-based tab index or {\tt wxNOT\_FOUND} if there is no tab is at
309the specified position.
310
311
312
313\membersection{wxNotebook::InsertPage}\label{wxnotebookinsertpage}
314
315\func{bool}{InsertPage}{\param{size\_t}{ index}, \param{wxNotebookPage*}{ page},
316 \param{const wxString\&}{ text},
317 \param{bool}{ select = false},
318 \param{int}{ imageId = -1}}
319
320Inserts a new page at the specified position.
321
322\wxheading{Parameters}
323
324\docparam{index}{Specifies the position for the new page.}
325
326\docparam{page}{Specifies the new page.}
327
328\docparam{text}{Specifies the text for the new page.}
329
330\docparam{select}{Specifies whether the page should be selected.}
331
332\docparam{imageId}{Specifies the optional image index for the new page.}
333
334\wxheading{Return value}
335
336true if successful, false otherwise.
337
338\wxheading{Remarks}
339
340Do not delete the page, it will be deleted by the notebook.
341
342\wxheading{See also}
343
344\helpref{wxNotebook::AddPage}{wxnotebookaddpage}
345
346
347\membersection{wxNotebook::OnSelChange}\label{wxnotebookonselchange}
348
349\func{void}{OnSelChange}{\param{wxNotebookEvent\&}{ event}}
350
351An event handler function, called when the page selection is changed.
352
353\wxheading{See also}
354
355\helpref{wxNotebookEvent}{wxnotebookevent}
356
357
358\membersection{wxNotebook::RemovePage}\label{wxnotebookremovepage}
359
360\func{bool}{RemovePage}{\param{size\_t}{ page}}
361
362Deletes the specified page, without deleting the associated window.
363
364
365\membersection{wxNotebook::SetImageList}\label{wxnotebooksetimagelist}
366
367\func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
368
369Sets the image list for the page control. It does not take
370ownership of the image list, you must delete it yourself.
371
372\wxheading{See also}
373
374\helpref{wxImageList}{wximagelist},
375\helpref{AssignImageList}{wxnotebookassignimagelist}
376
377
378\membersection{wxNotebook::SetPadding}\label{wxnotebooksetpadding}
379
380\func{void}{SetPadding}{\param{const wxSize\&}{ padding}}
381
382Sets the amount of space around each page's icon and label, in pixels.
383
384{\bf NB:} The vertical padding cannot be changed in wxGTK.
385
386
387\membersection{wxNotebook::SetPageSize}\label{wxnotebooksetpagesize}
388
389\func{void}{SetPageSize}{\param{const wxSize\&}{ size}}
390
391Sets the width and height of the pages.
392
393{\bf NB:} This method is currently not implemented for wxGTK.
394
395
396\membersection{wxNotebook::SetPageImage}\label{wxnotebooksetpageimage}
397
398\func{bool}{SetPageImage}{\param{size\_t}{ page}, \param{int }{image}}
399
400Sets the image index for the given page. {\it image} is an index into
401the image list which was set with \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}.
402
403
404\membersection{wxNotebook::SetPageText}\label{wxnotebooksetpagetext}
405
406\func{bool}{SetPageText}{\param{size\_t}{ page}, \param{const wxString\& }{text}}
407
408Sets the text for the given page.
409
410
411\membersection{wxNotebook::SetSelection}\label{wxnotebooksetselection}
412
413\func{int}{SetSelection}{\param{size\_t}{ page}}
414
415Sets the selection for the given page, returning the previous selection.
416
417The call to this function generates the page changing events.
418
419This function is deprecated and should not be used in new code. Please use the
420\helpref{ChangeSelection}{wxnotebookchangeselection} function instead.
421
422\wxheading{See also}
423
424\helpref{wxNotebook::GetSelection}{wxnotebookgetselection}
425