Next / Previous / Contents

37. ttk.Notebook

The purpose of a Notebook widget is to provide an area where the user can select pages of content by clicking on tabs at the top of the area, like these:

  • Each time the user clicks on one of these tabs, the widget will display the child pane associated with that tab. Typically, each pane will be a Frame widget, although a pane can be any widget.

  • The tab for the child pane that is currently showing is referred to as the selected tab.

  • You will use the Notebook widget's .add() method to attach a new tab, and its related content. Other methods let you remove or temporarily hide tabs.

  • Each tab has its own set of options that control its appearance and behavior. These options are described in Table 51, “Tab options for the ttk.Notebook widget”.

  • A number of the methods of this widget use the idea of a tabId to refer to one of the tabs. Different values for a tabId may be any of:

    • Integer values refer to the position of the tab: 0 for the first tab, 1 for the second, and so forth.

    • You can always refer to a tab by using the child widget itself.

    • A string of the form "@x,y" refers to the tab that currently contains the point (x,y) relative to the widget. For example, the string "@37,0" would specify the tab containing a point 37 pixels from the left side of the widget, along the top edge of the tab.

    • The string "current" refers to whichever tab is currently selected.

    • In a call to the Notebook widget's .index() method, use the string "end" to determine the current number of tabs displayed.

To create a Notebook widget as the child of some parent widget, use this constructor:

    w = ttk.Notebook(parent, option=value, ...)

Options include:

Table 50. ttk.Notebook options

class_ The widget class name. This may be specified when the widget is created, but cannot be changed later. For an explanation of widget classes, see Section 27, “Standardizing appearance”.
cursor The cursor that will appear when the mouse is over the notebook; see Section 5.8, “Cursors”.
height The height in pixels to be allocated to the widget.
padding To add some extra space around the outside of the widget, set this option to that amount of space as a dimension.
style The style to be used in rendering this menubutton; see Section 49, “Using and customizing ttk styles”.
takefocus By default, a ttk.Notebook will be included in focus traversal; see Section 53, “Focus: routing keyboard input”. To remove the widget from focus traversal, use takefocus=False.
width The width in pixels to be allocated to the widget.

Methods on a ttk.Notebook widget include all those described in Section 46, “Methods common to all ttk widgets”, plus:

.add(child, **kw)

The child argument is a widget, usually a Frame, that wraps the content of one child pane. If child is not one of the Notebook widget's child panes, child is added as the next available tab, and the keyword arguments kw define the tab options for the new pane. These options are defined it Table 51, “Tab options for the ttk.Notebook widget”.

If child is a currently hidden pane, that tab will reappear in its former position.

.enable_traversal()

Once you call this method, a few additional key bindings will work:

  • Control-Tab will select the tab after the one currently selected. If the last tab was currently selected, selection will rotate back to the first tab.

  • Shift-Control-Tab does the reverse: it moves to the previous tab, wrapping around to the last tab if the first tab was selected.

  • You can configure a particular hot key that directly selects a tab. To do this, use the text and underline tab options to underline one of the characters in each tab. Then the user can jump to a tab by typing Alt-x where x is the underlined character on that tab.

If you have multiple Notebook widgets in the same application, these features will not work correctly unless each child pane widget is created with its Notebook widget as the parent.

.forget(child)

This method permanently removes the specified child from the widget's set of tabs.

.hide(tabId)

The tab identified by tabId is temporarily removed from the set of visible tabs in the Notebook. You may reinstate it by calling the .add() method again.

.index(tabId)

For a given tabId, this method returns the numeric index of the corresponding tab. There is one exception: if the argument is the string "end", the method will return the total number of tabs.

.insert(where, child,**kw)

This method inserts the widget child at the position specified by where, using any keyword arguments to describe the new tab and pane. For the keyword options, see Table 51, “Tab options for the ttk.Notebook widget”.

The where argument may be any of:

  • "end" to place the new tab after all the existing tabs.

  • An existing child widget; in this case the new child is inserted just before that existing widget.

.select([tabId])

If you call this method without an argument, it will return the window name of the widget whose tab is currently displayed.

To display a specific pane in the Notebook, call this method with a tabId as the argument.

.tab(tabId, option=None, **kw)

Use this method either to set tab options for the child panes described by tabId, or to find out what options are set for that child pane. The tab options are described in Table 51, “Tab options for the ttk.Notebook widget”.

If you call the method with no keyword arguments, it will return a dictionary of the tab options currently in effect for the pane specified by tagId.

To find out the current value of a specific tab option X, call this method with the argument “option=X”, and the method will return the value of that tab option.

To set one or more tab options for the child described by tagId, call this method with keyword arguments. For example, if self.nb is a Notebook, this call would change the text displayed on the first tab:

    self.nb.tab(0, text='Crunchy frog')
.tabs()

This method returns a list of the window names of the Notebook's child panes, in order from first to last.

Here are the tab options used in the .add() and .tab() methods.

Table 51. Tab options for the ttk.Notebook widget

compound If you supply both image and text to be displayed on the tab, the compound option specifies how to display them. Allowable values describe the position of the image relative to the text, and may be any of tk.BOTTOM, tk.TOP, tk.LEFT, tk.RIGHT, or tk.CENTER. For example, compound=tk.LEFT would position the image to the left of the text.
padding Use this option to add extra space around all four sides of the panel's content. The value is a dimension. For example, padding='0.1i' would add a 0.1″ space around each side of the panel content.
sticky Use this option to specify where the panel content is positioned if it does not completely fill the panel area. Values are the same as for the sticky argument described in Section 4.1, “The .grid() method”. For example, sticky=tk.E+tk.S would position the content in the lower right (southeast) corner.
image To make a graphic image appear on the tab, supply an image as the value of this option. Refer to the compound option above to specify the relative positions of image and text when you specify both.
text The text to appear on the tab.
underline If this option has a nonnegative value n, an underline will appear under the character at position n of the text on the tab.