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