*********** wx.Notebook *********** Inheritance diagram for `wx.Notebook`: | .. inheritance-diagram:: wx.Notebook | Description =========== This class represents a notebook control, which manages multiple windows with associated tabs. To use the class, create a `wx.Notebook` object and call `AddPage <#AddPage>`_ or `InsertPage <#InsertPage>`_, passing a window to be used as the page. Do not explicitly delete the window for a page that is currently managed by `wx.Notebook`. `wx.NotebookPage` is a typedef for `wx.Window `_. .. seealso:: `wx.NotebookEvent <../Events/wx.NotebookEvent.html>`_, `wx.ImageList `_ Themes on Windows XP ^^^^^^^^^^^^^^^^^^^^ On Windows XP, the default theme paints a gradient on the notebook's pages. If you wish to suppress this theme, for aesthetic or performance reasons, there are three ways of doing it. You can use ``wx.NB_NOPAGETHEME`` to disable themed drawing for a particular notebook, you can call `wx.SystemOptions.SetOption `_ to disable it for the whole application, or you can disable it for individual pages by using `SetBackgroundColour `_. To disable themed pages globally:: wx.SystemOptions.SetOption("msw.notebook.themed-background", 0) Set the value to 1 to enable it again. To give a single page a solid background that more or less fits in with the overall theme, use:: col = notebook.GetThemeBackgroundColour() if col.IsOk(): page.SetBackgroundColour(col) On platforms other than Windows, or if the application is not using Windows themes, `GetThemeBackgroundColour <#GetThemeBackgroundColour>`_ will return an uninitialised colour object, and the above code will therefore work on all platforms. Derived From ^^^^^^^^^^^^^ * `wx.Control `_ * `wx.Window `_ * `wx.EvtHandler `_ * `wx.Object `_ Window Styles ^^^^^^^^^^^^^ ================================================== ================================================== Window Style Description ================================================== ================================================== ``wx.NB_TOP`` Place tabs on the top side. ``wx.NB_LEFT`` Place tabs on the left side. ``wx.NB_RIGHT`` Place tabs on the right side. ``wx.NB_BOTTOM`` Place tabs under instead of above the notebook pages. ``wx.NB_FIXEDWIDTH`` (Windows only) All tabs will have same width. ``wx.NB_MULTILINE`` (Windows only) There can be several rows of tabs. ``wx.NB_NOPAGETHEME`` (Windows only) Display a solid colour on notebook pages, and not a gradient, which can reduce performance. ``wx.NB_FLAT`` (Windows CE only) Show tabs in a flat style. ================================================== ================================================== Event Handling ^^^^^^^^^^^^^^ ================================================== ================================================== Event Name Description ================================================== ================================================== wx.EVT_NOTEBOOK_PAGE_CHANGED(id, func) The page selection was changed. Processes a ``wx.wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED`` event. wx.EVT_NOTEBOOK_PAGE_CHANGING(id, func) The page selection is about to be changed. Processes a ``wx.wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING`` event. This event can be vetoed. ================================================== ================================================== | Control Appearance ^^^^^^^^^^^^^^^^^^ | .. figure:: ../images/wxWidgets/wxmsw/notebook.png :alt: wxMSW :figclass: floatleft **wxMSW** .. figure:: ../images/wxWidgets/wxmac/notebook.png :alt: wxMAC :figclass: floatright **wxMAC** .. figure:: ../images/wxWidgets/wxgtk/notebook.png :alt: wxGTK :figclass: floatcenter **wxGTK** | Methods Summary ^^^^^^^^^^^^^^^ * `__init__ <#__init__>`_ * `AddPage <#AddPage>`_ * `AdvanceSelection <#AdvanceSelection>`_ * `AssignImageList <#AssignImageList>`_ * `ChangeSelection <#ChangeSelection>`_ * `DeleteAllPages <#DeleteAllPages>`_ * `DeletePage <#DeletePage>`_ * `GetCurrentPage <#GetCurrentPage>`_ * `GetImageList <#GetImageList>`_ * `GetPage <#GetPage>`_ * `GetPageCount <#GetPageCount>`_ * `GetPageImage <#GetPageImage>`_ * `GetPageText <#GetPageText>`_ * `GetRowCount <#GetRowCount>`_ * `GetSelection <#GetSelection>`_ * `GetThemeBackgroundColour <#GetThemeBackgroundColour>`_ * `HitTest <#HitTest>`_ * `InsertPage <#InsertPage>`_ * `RemovePage <#RemovePage>`_ * `SendPageChangedEvent <#SendPageChangedEvent>`_ * `SendPageChangingEvent <#SendPageChangingEvent>`_ * `SetImageList <#SetImageList>`_ * `SetPadding <#SetPadding>`_ * `SetPageImage <#SetPageImage>`_ * `SetPageSize <#SetPageSize>`_ * `SetPageText <#SetPageText>`_ * `SetSelection <#SetSelection>`_ * `SetTabSize <#SetTabSize>`_ Properties Summary ^^^^^^^^^^^^^^^^^^ * `RowCount <#RowCount>`_ * `ThemeBackgroundColour <#ThemeBackgroundColour>`_ Class API ========= Methods ^^^^^^^ .. method:: __init__(parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name=wx.NotebookNameStr) Constructor. **Parameters:** * `parent` (`wx.Window `_) * `id` (int) * `pos` (`wx.Point `_) * `size` (`wx.Size `_) * `style` (long) * `name` (string) | **Returns:** `wx.Notebook `_ -------- .. method:: AddPage(page, text, select=False, imageId=-1) Adds a new page. **Parameters:** * `page` (`wx.Window `_): Specifies the new page. * `text` (string): Specifies the text for the new page. * `select` (bool): Specifies whether the page should be selected. * `imageId` (int): Specifies the optional image index for the new page. | **Returns:** `bool` .. note:: Do not delete the page, it will be deleted by the notebook. .. note:: The call to this function may generate the page changing events. .. seealso:: `InsertPage <#InsertPage>`_ -------- .. method:: AdvanceSelection() Cycles through the tabs. .. note:: The call to this function generates the page changing events. -------- .. method:: AssignImageList(imageList) Sets the image list for the page control and takes ownership of the list. **Parameters:** * `imageList` (`wx.ImageList `_): The image list to assign. .. seealso:: `wx.ImageList `_, `SetImageList <#SetImageList>`_ -------- .. method:: ChangeSelection(page) Changes the selection for the given page, returning the previous selection. **Parameters:** * `page` (int): The new selection | **Returns:** `int` .. note:: The call to this function **does not** generate the page changing events. This is the only difference with `SetSelection <#SetSelection>`_. -------- .. method:: DeleteAllPages() Deletes all pages. | **Returns:** `bool` -------- .. method:: DeletePage(page) Deletes the specified page, and the associated window. **Parameters:** * `page` (int): The page to delete. | **Returns:** `bool` .. note:: The call to this function generates the page changing events. -------- .. method:: GetCurrentPage() Returns the currently selected notebook page or ``None``. | **Returns:** `wx.Window `_ -------- .. method:: GetImageList() Returns the associated image list. | **Returns:** `wx.ImageList `_ .. seealso:: `wx.ImageList `_, `SetImageList <#SetImageList>`_ -------- .. method:: GetPage(page) Returns the window at the given page position. **Parameters:** * `page` (int): The index of the page. | **Returns:** `wx.Window `_ -------- .. method:: GetPageCount() Returns the number of pages in the notebook control. | **Returns:** `long` -------- .. method:: GetPageImage(page) Returns the image index for the given page. **Parameters:** * `page` (int): The page index. | **Returns:** `int` -------- .. method:: GetPageText(page) Returns the string for the given page. **Parameters:** * `page` (int): The page index. | **Returns:** `string` -------- .. method:: GetRowCount() Returns the number of rows in the notebook control. | **Returns:** `int` -------- .. method:: GetSelection() Returns the currently selected page, or -1 if none was selected. | **Returns:** `int` .. note:: Note that this method may return either the previously or newly selected page when called from the ``wx.EVT_NOTEBOOK_PAGE_CHANGED`` handler depending on the platform and so `wx.NotebookEvent.GetSelection <../Events/wx.NotebookEvent.html#GetSelection>`_ should be used instead in this case. -------- .. method:: GetThemeBackgroundColour() If running under Windows and themes are enabled for the application, this function returns a suitable colour for painting the background of a notebook page, and can be passed to `SetBackgroundColour `_. Otherwise, an uninitialised colour will be returned. | **Returns:** `wx.Colour `_ -------- .. method:: HitTest(pt) Returns the page/tab which is hit, and flags indicating where using ``wx.NB_HITTEST`` flags. The return value `tab` is one of the following values: ============================== =================================== Tab HitTest Flags Description ============================== =================================== ``wx.BK_HITTEST_NOWHERE`` There was no tab under this point. ``wx.BK_HITTEST_ONICON`` The point was over an icon (currently wxMSW only). ``wx.BK_HITTEST_ONLABEL`` The point was over a label (currently wxMSW only). ``wx.BK_HITTEST_ONITEM`` The point was over an item, but not on the label or icon. ``wx.BK_HITTEST_ONPAGE`` The point was over a currently selected page, not over any tab. Note that this flag is present only if ``wx.NOT_FOUND`` is returned. ============================== =================================== | **Parameters:** * `pt` (`wx.Point `_) Specifies the point for the hit test. | **Returns:** `(tab, where)` -------- .. method:: InsertPage(index, page, text, select=False, imageId=-1) Inserts a new page at the specified position. **Parameters:** * `index` (long): Specifies the position for the new page. * `page` (`wx.Window `_): Specifies the new page. * `text` (string): Specifies the text for the new page. * `select` (bool): Specifies whether the page should be selected. * `imageId` (int): Specifies the optional image index for the new page. | **Returns:** `bool` .. note:: Do not delete the page, it will be deleted by the notebook. .. seealso:: `AddPage <#AddPage>`_ -------- .. method:: RemovePage(page) Deletes the specified page, without deleting the associated window. **Parameters:** * `page` (int): The page index. | **Returns:** `bool` -------- .. method:: SendPageChangedEvent(nPageOld, nPageNew=-1) | **Parameters:** * `nPageOld` (int) * `nPageNew` (int) -------- .. method:: SendPageChangingEvent(nPage) | **Parameters:** * `nPage` (int) | **Returns:** `bool` -------- .. method:: SetImageList(imageList) Sets the image list for the page control. It does not take ownership of the image list, you must delete it yourself. **Parameters:** * `imageList` (`wx.ImageList `_): The image list to set. .. seealso:: `wx.ImageList `_, `AssignImageList <#AssignImageList>`_ -------- .. method:: SetPadding(padding) Sets the amount of space around each page's icon and label, in pixels. **Parameters:** * `padding` (`wx.Size `_) .. note:: The vertical padding cannot be changed in wxGTK. -------- .. method:: SetPageImage(page, image) Sets the image index for the given page. `image` is an index into the image list which was set with `SetImageList <#SetImageList>`_. **Parameters:** * `page` (int): The page index. * `image` (int): The image index. | **Returns:** `bool` -------- .. method:: SetPageSize(size) Sets the width and height of the pages. **Parameters:** * `size` (`wx.Size `_): The page size. .. note:: This method is currently not implemented for wxGTK. -------- .. method:: SetPageText(page, text) Sets the text for the given page. **Parameters:** * `page` (int): The page index. * `text` (string): The page text. | **Returns:** `bool` -------- .. method:: SetSelection(page) Sets the selection for the given page, returning the previous selection. **Parameters:** * `page` (int): The new page index. .. warning:: This function is deprecated and should not be used in new code. Please use the `ChangeSelection <#ChangeSelection>`_ function instead. .. note:: The call to this function generates the page changing events. .. seealso:: `GetSelection <#GetSelection>`_ --------- .. method:: SetTabSize(sz) | **Parameters:** * `sz` (`wx.Size `_) -------- Properties ^^^^^^^^^^ .. attribute:: RowCount See `GetRowCount <#GetRowCount>`_ .. attribute:: ThemeBackgroundColour See `GetThemeBackgroundColour <#GetThemeBackgroundColour>`_