gtk.Notebook

gtk.Notebook
Prev	The gtk Class Reference	Next

gtk.Notebook — a tabbed notebook container.

Synopsis

class gtk.Notebook(gtk.Container):
    gtk.Notebook()
    def append_page(child, tab_label=None)
    def append_page_menu(child, tab_label=None, menu_label=None)
    def prepend_page(child, tab_label=None)
    def prepend_page_menu(child, tab_label=None, menu_label=None)
    def insert_page(child, tab_label=None, position=-1)
    def insert_page_menu(child, tab_label=None, menu_label=None, position=-1)
    def remove_page(page_num)
    def get_current_page()
    def get_nth_page(page_num)
    def get_n_pages()
    def page_num(child)
    def set_current_page(page_num)
    def next_page()
    def prev_page()
    def set_show_border(show_border)
    def get_show_border()
    def set_show_tabs(show_tabs)
    def get_show_tabs()
    def set_tab_pos(pos)
    def get_tab_pos()
    def set_scrollable(scrollable)
    def get_scrollable()
    def popup_enable()
    def popup_disable()
    def get_tab_label(child)
    def set_tab_label(child, tab_label=None)
    def set_tab_label_text(child, tab_text)
    def get_tab_label_text(child)
    def get_menu_label(child)
    def set_menu_label(child, menu_label=None)
    def set_menu_label_text(child, menu_text)
    def get_menu_label_text(child)
    def query_tab_label_packing(child)
    def set_tab_label_packing(child, expand, fill, pack_type)
    def reorder_child(child, position)

Ancestry

+-- gobject.GObject
  +-- gtk.Object
    +-- gtk.Widget
      +-- gtk.Container
        +-- gtk.Notebook

Properties

"enable-popup"	Read-Write	If `TRUE`, pressing the right mouse button on the notebook pops up a menu that you can use to go to a page
"homogeneous"	Read-Write	If `TRUE`, tabs should have homogeneous sizes
"page"	Read-Write	The index of the current page
"scrollable"	Read-Write	If `TRUE`, scroll arrows are added if there are too many tabs to fit
"show-border"	Read-Write	If `TRUE`, the border should be shown
"show-tabs"	Read-Write	If `TRUE`, tabs should be shown
"tab-border"	Write	The width of the border around the tab labels
"tab-hborder"	Read-Write	The width of the horizontal border of tab labels
"tab-pos"	Read-Write	The side of the notebook that holds the tabs: `gtk.POS_LEFT`, `gtk.POS_RIGHT`, `gtk.POS_TOP` or `gtk.POS_BOTTOM`
"tab-vborder"	Read-Write	The width of the vertical border of tab labels

Child Properties

"menu-label"	Read-Write	The string displayed in the child's menu entry
"position"	Read-Write	The index of the child in the parent
"tab-expand"	Read-Write	If `TRUE`, expand the child's tabs
"tab-fill"	Read-Write	If `TRUE`, the child's tab should fill the allocated area
"tab-label"	Read-Write	The string displayed on the child's tab label
tab-pack""	Read-Write	A pack type indicating whether the child is packed with reference to the start or end of the parent: `gtk.PACK_START` or `gtk.PACK_END`.

Style Properties

Note

These style properties are available in PyGTK 2.4 and above.

"has-backward-stepper"	Read-Write	If `TRUE` the standard backward arrow button is displayed.
"has-forward-stepper"	Read-Write	If `TRUE` the standard forward arrow button is displayed.
"has-secondary-backward-stepper"	Read-Write	If `TRUE` a second backward arrow button is displayed on the opposite end of the tab area.
"has-secondary-forward-stepper"	Read-Write	If `TRUE` a second forward arrow button is displayed on the opposite end of the tab area.

Attributes

"tab_pos" Read The side of the notebook that holds the tabs: gtk.POS_LEFT, gtk.POS_RIGHT, gtk.POS_TOP or gtk.POS_BOTTOM

Signal Prototypes

"change-current-page"	`def callback(notebook, offset, user_param1, ...)`
"focus-tab"	`def callback(notebook, type, user_param1, ...)`
"move-focus-out"	`def callback(notebook, direction_type, user_param1, ...)`
"select-page"	`def callback(notebook, move_focus, user_param1, ...)`
"switch-page"	`def callback(notebook, page, page_num, user_param1, ...)`

Description

The gtk.Notebook widget is a gtk.Container whose children are overlapping pages that can be switched between by using tab labels along one edge. There are many configuration options for the gtk.Notebook. You can choose on which edge the tabs appear (see set_tab_pos()); whether the notebook should be made bigger or scrolling arrows added if there are too many tabs to fit (see set_scrollable()); and, whether there will be a popup menu allowing the users to switch pages. (see popup_enable(), popup_disable()).

The gtk.Notebook is particularly useful for displaying a large number of application controls that can be grouped into several functional areas. The typical example is the user preferences dialog in some applications. For example, a notebook page can be setup for each of font selection, color selection, formating, etc.

Constructor

    gtk.Notebook()

Returns : the newly created gtk.Notebook

Creates a new gtk.Notebook widget with no pages.

Methods

gtk.Notebook.append_page

    def append_page(child, tab_label=None)

`child` :	the `gtk.Widget` to use as the contents of the page.
`tab_label` :	the `gtk.Widget` to be used as the label for the page.
Returns :	in PyGTK 2.0 and 2.2 returns `None`. In PyGTK 2.4 and above returns the index number of the page in the notebook

The append_page() method appends a page to the notebook using the widget specified by child and the widget specified by tab_label as the label on the tab.

In PyGTK 2.4 and above tab_label can be None to use a default label. Also if tab_label is not specified it will default to None.

gtk.Notebook.append_page_menu

    def append_page_menu(child, tab_label=None, menu_label=None)

`child` :	the `gtk.Widget` to use as the contents of the page.
`tab_label` :	the `gtk.Widget` to be used as the label for the page.
`menu_label` :	the widget to use as a label for the page-switch menu, if that is enabled.
Returns :	in PyGTK 2.0 and 2.2 returns `None`. In PyGTK 2.4 and above returns the index number of the page in the notebook

The append_page_menu() method appends a page to the notebook and specifying the widget to use as the label in the popup menu. child specifies the widget to use as the contents of the page; tab_label specifies the widget to be used as the tab label; and, menu_label specifies the widget to use in the popup menu.

In PyGTK 2.4 and above tab_label can be None to use a default label. If tab_label is a gtk.Label or None and menu_label is None then the menu label will have the same text as the tab label. Otherwise, menu_label must be specified and not None. These parameters will default to None in PyGTK 2.4 as well.

gtk.Notebook.prepend_page

    def prepend_page(child, tab_label=None)

`child` :	the `gtk.Widget` to use as the contents of the page.
`tab_label` :	the `gtk.Widget` to be used as the label for the page.
Returns :	in PyGTK 2.0 and 2.2 returns `None`. In PyGTK 2.4 and above returns the index number of the page in the notebook

The prepend_page() method prepends a page to the notebook. child specifies the widget to use as the contents of the page and tab_label specifies the widget to be used as the tab label.

In PyGTK 2.4 and above tab_label can be None to use a default label. Also if tab_label is not specified it will default to None.

gtk.Notebook.prepend_page_menu

    def prepend_page_menu(child, tab_label=None, menu_label=None)

`child` :	the `gtk.Widget` to use as the contents of the page.
`tab_label` :	the `gtk.Widget` to be used as the label for the page.
`menu_label` :	the widget to use as a label for the page-switch menu, if that is enabled.
Returns :	in PyGTK 2.0 and 2.2 returns `None`. In PyGTK 2.4 and above returns the index number of the page in the notebook

The prepend_page_menu() method prepends a page to the notebook specifying the widget to use as the label in the popup menu. child specifies the widget to use as the contents of the page; tab_label specifies the widget to use as the tab label; and, menu_label specifies the widget to use in the popup menu.

gtk.Notebook.insert_page

    def insert_page(child, tab_label=None, position=None)

`child` :	the `gtk.Widget` to use as the contents of the page.
`tab_label` :	the `gtk.Widget` to be used as the label for the page.
`position` :	the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages.
Returns :	in PyGTK 2.0 and 2.2 returns `None`. In PyGTK 2.4 and above returns the index number of the page in the notebook

The insert_page() method inserts a page into the notebook at the location specified by position (0 is the first page). child is the widget to use as the contents of the page and tab_label specifies the widget to be used as the tab label. If position is -1 the page is appended to the notebook. In PyGTK 2.4 and above if tab_label is None a default label if "page N" is used.

In PyGTK 2.4 and above tab_label can be None to use a default label. Also if tab_label is not specified it will default to None.

In Pygtk 2.4 and above position will default to -1 if not specified.

gtk.Notebook.insert_page_menu

    def insert_page_menu(child, tab_label=None, menu_label=None, position=None)

`child` :	the `gtk.Widget` to use as the contents of the page.
`tab_label` :	the `gtk.Widget` to be used as the label for the page.
`menu_label` :	the widget to use as a label for the page-switch menu, if that is enabled.
`position` :	the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages.
Returns :	in PyGTK 2.0 and 2.2 returns `None`. In PyGTK 2.4 and above returns the index number of the page in the notebook

The insert_page_menu() method inserts a page into the notebook at the location specified by position. child specifies the widget to use as the contents of the page; tab_label specifies the widget to use as the tab label; and menu_label specifies the widget to use as the label in the popup menu.

In Pygtk 2.4 and above position will default to -1 if not specified.

gtk.Notebook.remove_page

    def remove_page(page_num)

page_num : the index of a notebook page, starting from 0. If -1, the last page will be removed.

The remove_page() method removes from the notebook the page at the location specified by index. The value of index starts from 0. If index is -1 the last page of the notebook will be removed.

gtk.Notebook.get_current_page

    def get_current_page()

Returns :

the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned.

The get_current_page() method returns the page index of the current page numbered from 0.

gtk.Notebook.get_nth_page

    def get_nth_page(page_num)

`page_num` :	the index of a page in the notebook
Returns :	the child widget, or `None` if `page_num` is out of bounds.

The get_nth_page() method returns the child widget contained in the page with the index specified by page_num. If page_num is out of bounds for the page range of the notebook this method returns None.

gtk.Notebook.get_n_pages

    def get_n_pages()

Returns :

the number of pages in the notebook.

Note

This method is available in PyGTK 2.4 and above.

The get_n_pages() method returns the number of pages in a notebook.

gtk.Notebook.page_num

    def page_num(child)

`child` :	a `gtk.Widget`
Returns :	the index of the page containing `child`, or -1 if `child` is not in the notebook.

The page_num() method returns the index of the page which contains the widget specified by child or None if no page contains child.

gtk.Notebook.set_current_page

    def set_current_page(page_num)

page_num : the index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the notebook, nothing will be done.

The set_current_page() method switches to the page number specified by page_num. If page_num is negative the last page is selected.

gtk.Notebook.next_page

    def next_page()

The next_page() method switches to the next page. Nothing happens if the current page is the last page.

gtk.Notebook.prev_page

    def prev_page()

The prev_page() method switches to the previous page. Nothing happens if the current page is the first page.

gtk.Notebook.set_show_border

    def set_show_border(show_border)

show_border : if TRUE a bevel should be drawn around the notebook.

The show_border() method sets the "show-border" property to the value of show_border. If show_border is TRUE a bevel will be drawn around the notebook pages. This only has a visual effect when the tabs are not shown. See set_show_tabs().

gtk.Notebook.get_show_border

    def get_show_border()

Returns : TRUE if the bevel should be drawn

The get_show_border() method returns the value of the "show-border" property. If "show-border" is TRUE a bevel will be drawn around the notebook pages when tabs are not shown. See set_show_border().

gtk.Notebook.set_show_tabs

    def set_show_tabs(show_tabs)

show_tabs : if TRUE the tabs should be shown.

The set_show_tabs() method sets the "show-tabs" property to the value of show_tabs. If show_tabs is TRUE the notebook tabs will be displayed.

gtk.Notebook.get_show_tabs

    def get_show_tabs()

Returns : TRUE if the tabs are shown

The get_show_tabs() method returns the value of the "show-tabs" property. If "show-tabs" is TRUE the tabs of the notebook are shown. See set_show_tabs().

gtk.Notebook.set_tab_pos

    def set_tab_pos(pos)

pos : the edge to draw the tabs at: gtk.POS_LEFT, gtk.POS_RIGHT, gtk.POS_TOP or gtk.POS_BOTTOM.

The set_tab_pos() method sets the edge at which the tabs for switching pages in the notebook are drawn as specified by pos. The value of pos can be one of: gtk.POS_LEFT, gtk.POS_RIGHT, gtk.POS_TOP or gtk.POS_BOTTOM.

gtk.Notebook.get_tab_pos

    def get_tab_pos()

Returns :

the edge at which the tabs are drawn

The get_tab_pos() method returns the edge at which the tabs for switching pages in the notebook are drawn. The return value is one of: gtk.POS_LEFT, gtk.POS_RIGHT, gtk.POS_TOP or gtk.POS_BOTTOM.

gtk.Notebook.set_scrollable

    def set_scrollable(scrollable)

scrollable : if TRUE scroll arrows should be added

The set_scrollable() method sets the "scrollable" property to the value specified by scrollable. If scrollable is TRUE the tab label area will have arrows for scrolling if there are too many tabs to fit in the area.

gtk.Notebook.get_scrollable

    def get_scrollable()

Returns : TRUE if arrows for scrolling are enabled

The get_scrollable() method returns the value of the "scrollable" property. If "scrollable" is TRUE the tab label area has scrolling arrows enabled and displayed if there are too many tabs to fit in the display area. See set_scrollable().

gtk.Notebook.popup_enable

    def popup_enable()

The popup_enable() method enables the popup menu: if the user clicks with the right mouse button on the tabs, a menu with all the pages will be popped up.

gtk.Notebook.popup_disable

    def popup_disable()

The popup_disable() method disables the popup menu.

gtk.Notebook.get_tab_label

    def get_tab_label(child)

`child` :	a widget contained in a notebook page
Returns :	the tab label widget for the page containing `child`

The get_tab_label() method returns the tab label widget for the page containing the widget child. None is returned if child is not in the notebook.

gtk.Notebook.set_tab_label

    def set_tab_label(child, tab_label=None)

`child` :	a widget contained in a notebook page
`tab_label` :	the tab label widget to use or `None`.

The set_tab_label() method replaces the tab label for the notebook page containing child with the widget specified by tab_label.

In PyGTK 2.4 and above tab_label can be None to use a default label. Also if tab_label is not specified it will default to None.

gtk.Notebook.set_tab_label_text

    def set_tab_label_text(child, tab_text)

`child` :	a widget contained in a notebook page
`tab_text` :	the new label text

The set_tab_label_text() method creates a new label with the text specified by tab_text and sets it as the tab label for the page containing child.

gtk.Notebook.get_tab_label_text

    def get_tab_label_text(child)

`child` :	a widget contained in a notebook page
Returns :	value: the text of the tab label, or `None` if the tab label widget is not a `gtk.Label` or `child` is not in a notebook page.

The get_tab_label_text() retrieves the text of the tab label for the page containing child. This method returns None if child is not in a notebook page or the page tab label is not a gtk.Label widget.

gtk.Notebook.get_menu_label

    def get_menu_label(child)

`child` :	a widget contained in a notebook page
Returns :	the menu label, or `None` if the notebook page does not have a menu label other than the default (the tab label) or if child is not in a notebook page.

The get_menu_label() method retrieves the menu label widget of the page containing child. If child is not in a notebook page or the menu label has not been set (it defaults to the tab label), this method returns None.

gtk.Notebook.set_menu_label

    def set_menu_label(child, menu_label=None)

`child` :	a widget contained in a notebook page
`menu_label` :	a widget to be used as the new menu label

The set_menu_label() replaces the menu label for the page containing child with the widget specified by menu_label.

In PyGTK 2.4 and above menu_label can be None to use a default label. Also if menu_label is not specified it will default to None. See the append_page_menu() method for more information.

gtk.Notebook.set_menu_label_text

    def set_menu_label_text(child, menu_text)

`child` :	a widget contained in a notebook page
`menu_text` :	the new menu label text

The set_menu_label_text() method creates a new label widget and replaces the menu label of the page containingchild.

gtk.Notebook.get_menu_label_text

    def get_menu_label_text(child)

`child` :	a child widget of a notebook page.
Returns :	value: the text of the tab label, or `None` if the widget does not have a menu label other than the default menu label, or the menu label widget is not a `gtk.Label` or `child` is not contained in a notebook page.

The get_menu_label_text() method retrieves the text of the menu label for the page containing child. If child is not in a notebook page or the menu label is not a gtk.Label widget or the menu label has not been set (it default to the tab label), the return value is None.

gtk.Notebook.query_tab_label_packing

    def query_tab_label_packing(child)

`child` :	the page
Returns :	a tuple containing: the expand value, the fill value and the pack type

The query_tab_label_packing() method returns a tuple containing the packing attributes (expand, fill, pack type) for the tab label of the page containing child. If the expand attribute is TRUE the tab can expand to take up the free space in the tab area. If fill is TRUE the label widget in the tab can use up all the space in the tab. The pack type can be one of gtk.PACK_START or gtk.PACK_END to specify whether the tab is packed to the left or right if tabs are on the top or bottom edge (top or bottom if the tabs are on the left or right edge).

gtk.Notebook.set_tab_label_packing

    def set_tab_label_packing(child, expand, fill, pack_type)

`child` :	a widget contained in a notebook page
`expand` :	if `TRUE` the tab can expand to fill the free space in the tab area
`fill` :	if `TRUE` the label widget can fill the space in the tab
`pack_type` :	the position of the tab: `gtk.PACK_START` or `gtk.PACK_END`

The set_tab_label_packing() method sets the packing parameters for the tab label of the page containing child. If expand is TRUE the tab can expand to take up the free space in the tab area. If fill is TRUE the label widget in the tab can use up all the space in the tab. The pack_type can be one of gtk.PACK_START or gtk.PACK_END to specify whether the tab is packed to the left or right if tabs are on the top or bottom edge (top or bottom if the tabs are on the left or right edge).See gtk.Box.pack_start() for the exact meaning of the parameters.

gtk.Notebook.reorder_child

    def reorder_child(child, position)

`child` :	the child widget to move
`position` :	the index of the page that `child` is to move to, or -1 to move to the end

The reorder_child() method reorders the notebook pages so that child appears in the page whose index is specified by position. If position is greater than or equal to the number of children in the list or negative, child will be moved to the end of the list.

Signals

The "change-current-page" gtk.Notebook Signal

    def callback(notebook, offset, user_param1, ...)

`notebook` :	the notebook that received the signal
`offset` :	the count of pages to move (negative count is backward)
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "change-current-page" signal is emitted when the page forward or page backward request is issued.

The "focus-tab" gtk.Notebook Signal

    def callback(notebook, type, user_param1, ...)

`notebook` :	the notebook that received the signal
`type` :	the type of tab: `gtk.NOTEBOOK_TAB_FIRST` or `gtk.NOTEBOOK_TAB_LAST`
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)
Returns :	`TRUE` if the signal was handled

The "focus-tab" signal is emitted when the focus is changed by tabbing.

The "move-focus-out" gtk.Notebook Signal

    def callback(notebook, direction_type, user_param1, ...)

`notebook` :	the notebook that received the signal
`direction_type` :	the direction type of the focus move: `gtk.DIR_TAB_FORWARD`, `gtk.DIR_TAB_BACKWARD`, `gtk.DIR_UP`, `gtk.DIR_DOWN`, `gtk.DIR_LEFT` or `gtk.DIR_RIGHT`
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "move-focus-out" signal is emitted when the focus is moved out of the notebook with the specified direction_type.

The "select-page" gtk.Notebook Signal

    def callback(notebook, move_focus, user_param1, ...)

`notebook` :	the notebook that received the signal
`move_focus` :	if `TRUE` move the focus to a child widget
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)
Returns :	`TRUE` if the signal was handled

The "select-page" signal is emitted when a new child page is selected.

The "switch-page" gtk.Notebook Signal

    def callback(notebook, page, page_num, user_param1, ...)

`notebook` :	the notebook that received the signal
`page` :	the new current page
`page_num` :	the index of the new current page
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "switch-page" signal is emitted when the notebook page is changed. Note the page parameter is a GPointer and not usable within PyGTK. Use the page_num parameter to retrieve the new current page using the get_nth_page() method.