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 \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
  37 The styles \texttt{wxNB\_LEFT}, \texttt{RIGHT} and \texttt{BOTTOM} are not
  38 supported under Microsoft Windows XP when using visual themes.
  39
  40 See also \helpref{window styles overview}{windowstyles}.
  41
  42 \input noteevt.inc
  43
  44 \wxheading{Page backgrounds}
  45
  46 On Windows XP, the default theme paints a gradient on the notebook's pages.
  47 If you wish to suppress this theme, for aesthetic or performance reasons,
  48 there are three ways of doing it. You can use wxNB\_NOPAGETHEME to disable
  49 themed drawing for a particular notebook, you can call {\tt wxSystemOptions::SetOption}
  50 to disable it for the whole application, or you can disable it for individual
  51 pages by using {\tt SetBackgroundColour}.
  52
  53 To disable themed pages globally:
  54
  55 \begin{verbatim}
  56     wxSystemOptions::SetOption(wxT("msw.notebook.themed-background"), 0);
  57 \end{verbatim}
  58
  59 Set the value to 1 to enable it again.
  60
  61 To give a single page a solid background that more or less fits in with the
  62 overall 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
  72 On platforms other than Windows, or if the application is not using Windows
  73 themes, {\tt GetThemeBackgroundColour} will return an uninitialised colour object,
  74 and 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
  86 Default 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
  91 Constructs a notebook control.
  92
  93 Note 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
 114 Destroys 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
 124 Adds a new page.
 125
 126 The 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
 140 true if successful, false otherwise.
 141
 142 \wxheading{Remarks}
 143
 144 Do 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
 155 Cycles through the tabs.
 156
 157 The 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
 164 Sets the image list for the page control and takes ownership of
 165 the list.
 166
 167 \wxheading{See also}
 168
 169 \helpref{wxImageList}{wximagelist},
 170 \helpref{SetImageList}{wxnotebooksetimagelist}
 171
 172
 173 \membersection{wxNotebook::Create}\label{wxnotebookcreate}
 174
 175 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\&}{ pos = wxDefaultPosition},
 176  \param{const wxSize\&}{ size}, \param{long}{ style = 0}, \param{const wxString\& }{name = wxNotebookNameStr}}
 177
 178 Creates a notebook control. See \helpref{wxNotebook::wxNotebook}{wxnotebookctor} for a description
 179 of the parameters.
 180
 181
 182 \membersection{wxNotebook::DeleteAllPages}\label{wxnotebookdeleteallpages}
 183
 184 \func{bool}{DeleteAllPages}{\void}
 185
 186 Deletes all pages.
 187
 188
 189 \membersection{wxNotebook::DeletePage}\label{wxnotebookdeletepage}
 190
 191 \func{bool}{DeletePage}{\param{size\_t}{ page}}
 192
 193 Deletes the specified page, and the associated window.
 194
 195 The call to this function generates the page changing events.
 196
 197
 198 \membersection{wxNotebook::GetCurrentPage}\label{wxnotebookgetcurrentpage}
 199
 200 \constfunc{wxWindow *}{GetCurrentPage}{\void}
 201
 202 Returns the currently selected notebook page or \NULL.
 203
 204
 205 \membersection{wxNotebook::GetImageList}\label{wxnotebookgetimagelist}
 206
 207 \constfunc{wxImageList*}{GetImageList}{\void}
 208
 209 Returns the associated image list.
 210
 211 \wxheading{See also}
 212
 213 \helpref{wxImageList}{wximagelist}, \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}
 214
 215
 216 \membersection{wxNotebook::GetPage}\label{wxnotebookgetpage}
 217
 218 \func{wxNotebookPage*}{GetPage}{\param{size\_t}{ page}}
 219
 220 Returns the window at the given page position.
 221
 222
 223 \membersection{wxNotebook::GetPageCount}\label{wxnotebookgetpagecount}
 224
 225 \constfunc{size\_t}{GetPageCount}{\void}
 226
 227 Returns the number of pages in the notebook control.
 228
 229
 230 \membersection{wxNotebook::GetPageImage}\label{wxnotebookgetpageimage}
 231
 232 \constfunc{int}{GetPageImage}{\param{size\_t }{nPage}}
 233
 234 Returns the image index for the given page.
 235
 236
 237 \membersection{wxNotebook::GetPageText}\label{wxnotebookgetpagetext}
 238
 239 \constfunc{wxString}{GetPageText}{\param{size\_t }{nPage}}
 240
 241 Returns the string for the given page.
 242
 243
 244 \membersection{wxNotebook::GetRowCount}\label{wxnotebookgetrowcount}
 245
 246 \constfunc{int}{GetRowCount}{\void}
 247
 248 Returns the number of rows in the notebook control.
 249
 250
 251 \membersection{wxNotebook::GetSelection}\label{wxnotebookgetselection}
 252
 253 \constfunc{int}{GetSelection}{\void}
 254
 255 Returns the currently selected page, or $-1$ if none was selected.
 256
 257 Note that this method may return either the previously or newly selected page
 258 when called from the {\tt EVT\_NOTEBOOK\_PAGE\_CHANGED} handler depending on
 259 the platform and so\rtfsp
 260 \helpref{wxNotebookEvent::GetSelection}{wxnotebookeventgetselection} should be
 261 used instead in this case.
 262
 263 \membersection{wxNotebook::GetThemeBackgroundColour}\label{wxnotebookgetthemebackgroundcolour}
 264
 265 \constfunc{wxColour}{GetThemeBackgroundColour}{\void}
 266
 267 If running under Windows and themes are enabled for the application, this function
 268 returns a suitable colour for painting the background of a notebook page, and can be passed
 269 to {\tt SetBackgroundColour}. Otherwise, an uninitialised colour will be returned.
 270
 271 \membersection{wxNotebook::HitTest}\label{wxnotebookhittest}
 272
 273 \func{int}{HitTest}{\param{const wxPoint\&}{ pt}, \param{long}{ *flags = {\tt NULL}}}
 274
 275 Returns the index of the tab at the specified position or {\tt wxNOT\_FOUND}
 276 if none. If {\it flags} parameter is non-{\tt NULL}, the position of the point
 277 inside the tab is returned as well.
 278
 279 \wxheading{Parameters}
 280
 281 \docparam{pt}{Specifies the point for the hit test.}
 282
 283 \docparam{flags}{Return value for detailed information. One of the following values:
 284 \twocolwidtha{7cm}
 285 \begin{twocollist}\itemsep=0pt
 286 \twocolitem{{\bf wxBK\_HITTEST\_NOWHERE}}{There was no tab under this point.}
 287 \twocolitem{{\bf wxBK\_HITTEST\_ONICON}}{The point was over an icon (currently wxMSW only).}
 288 \twocolitem{{\bf wxBK\_HITTEST\_ONLABEL}}{The point was over a label (currently wxMSW only).}
 289 \twocolitem{{\bf wxBK\_HITTEST\_ONITEM}}{The point was over an item, but not on the label or icon.}
 290 \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.}
 291 \end{twocollist}
 292 }
 293
 294 \wxheading{Return value}
 295
 296 Returns the zero-based tab index or {\tt wxNOT\_FOUND} if there is no tab is at
 297 the specified position.
 298
 299
 300
 301 \membersection{wxNotebook::InsertPage}\label{wxnotebookinsertpage}
 302
 303 \func{bool}{InsertPage}{\param{size\_t}{ index}, \param{wxNotebookPage*}{ page},
 304  \param{const wxString\&}{ text},
 305  \param{bool}{ select = false},
 306  \param{int}{ imageId = -1}}
 307
 308 Inserts a new page at the specified position.
 309
 310 \wxheading{Parameters}
 311
 312 \docparam{index}{Specifies the position for the new page.}
 313
 314 \docparam{page}{Specifies the new page.}
 315
 316 \docparam{text}{Specifies the text for the new page.}
 317
 318 \docparam{select}{Specifies whether the page should be selected.}
 319
 320 \docparam{imageId}{Specifies the optional image index for the new page.}
 321
 322 \wxheading{Return value}
 323
 324 true if successful, false otherwise.
 325
 326 \wxheading{Remarks}
 327
 328 Do not delete the page, it will be deleted by the notebook.
 329
 330 \wxheading{See also}
 331
 332 \helpref{wxNotebook::AddPage}{wxnotebookaddpage}
 333
 334
 335 \membersection{wxNotebook::OnSelChange}\label{wxnotebookonselchange}
 336
 337 \func{void}{OnSelChange}{\param{wxNotebookEvent\&}{ event}}
 338
 339 An event handler function, called when the page selection is changed.
 340
 341 \wxheading{See also}
 342
 343 \helpref{wxNotebookEvent}{wxnotebookevent}
 344
 345
 346 \membersection{wxNotebook::RemovePage}\label{wxnotebookremovepage}
 347
 348 \func{bool}{RemovePage}{\param{size\_t}{ page}}
 349
 350 Deletes the specified page, without deleting the associated window.
 351
 352
 353 \membersection{wxNotebook::SetImageList}\label{wxnotebooksetimagelist}
 354
 355 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 356
 357 Sets the image list for the page control. It does not take
 358 ownership of the image list, you must delete it yourself.
 359
 360 \wxheading{See also}
 361
 362 \helpref{wxImageList}{wximagelist},
 363 \helpref{AssignImageList}{wxnotebookassignimagelist}
 364
 365
 366 \membersection{wxNotebook::SetPadding}\label{wxnotebooksetpadding}
 367
 368 \func{void}{SetPadding}{\param{const wxSize\&}{ padding}}
 369
 370 Sets the amount of space around each page's icon and label, in pixels.
 371
 372 {\bf NB:} The vertical padding cannot be changed in wxGTK.
 373
 374
 375 \membersection{wxNotebook::SetPageSize}\label{wxnotebooksetpagesize}
 376
 377 \func{void}{SetPageSize}{\param{const wxSize\&}{ size}}
 378
 379 Sets the width and height of the pages.
 380
 381 {\bf NB:} This method is currently not implemented for wxGTK.
 382
 383
 384 \membersection{wxNotebook::SetPageImage}\label{wxnotebooksetpageimage}
 385
 386 \func{bool}{SetPageImage}{\param{size\_t}{ page}, \param{int }{image}}
 387
 388 Sets the image index for the given page. {\it image} is an index into
 389 the image list which was set with \helpref{wxNotebook::SetImageList}{wxnotebooksetimagelist}.
 390
 391
 392 \membersection{wxNotebook::SetPageText}\label{wxnotebooksetpagetext}
 393
 394 \func{bool}{SetPageText}{\param{size\_t}{ page}, \param{const wxString\& }{text}}
 395
 396 Sets the text for the given page.
 397
 398
 399 \membersection{wxNotebook::SetSelection}\label{wxnotebooksetselection}
 400
 401 \func{int}{SetSelection}{\param{size\_t}{ page}}
 402
 403 Sets the selection for the given page, returning the previous selection.
 404
 405 The call to this function generates the page changing events.
 406
 407 This function is deprecated and should not be used in new code. Please use the
 408 \helpref{ChangeSelection}{wxnotebookchangeselection} function instead.
 409
 410 \wxheading{See also}
 411
 412 \helpref{wxNotebook::GetSelection}{wxnotebookgetselection}
 413
 414
 415 \membersection{wxNotebook::ChangeSelection}\label{wxnotebookchangeselection}
 416
 417 \func{int}{ChangeSelection}{\param{size\_t}{ page}}
 418
 419 Changes the selection for the given page, returning the previous selection.
 420
 421 The call to this function \emph{does not} generate the page changing events.
 422 This is the only difference with \helpref{SetSelection}{wxnotebooksetselection}.
 423 See \helpref{this topic}{progevent} for more info.
 424