docs/latex/wx/notebook.tex

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