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