Gtk.Notebook¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

Switches between children using tabs.

There are many configuration options for GtkNotebook. Among other things, you can choose on which edge the tabs appear (see Notebook.set_tab_pos), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see Notebook.set_scrollable), and whether there will be a popup menu allowing the users to switch pages. (see Notebook.popup_enable).

GtkNotebook as GtkBuildable¶

The GtkNotebook implementation of the GtkBuildable interface supports placing children into tabs by specifying “tab” as the “type” attribute of a <child> element. Note that the content of the tab must be created before the tab can be filled. A tab child can be specified without specifying a <child> type attribute.

To add a child widget in the notebooks action area, specify "action-start" or “action-end” as the “type” attribute of the <child> element.

An example of a UI definition fragment with GtkNotebook:

<object class="GtkNotebook">
  <child>
    <object class="GtkLabel" id="notebook-content">
      <property name="label">Content</property>
    </object>
  </child>
  <child type="tab">
    <object class="GtkLabel" id="notebook-tab">
      <property name="label">Tab</property>
    </object>
  </child>
</object>

Shortcuts and Gestures¶

GtkNotebook supports the following keyboard shortcuts:

<kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu.
<kbd>Home</kbd> moves the focus to the first tab.
<kbd>End</kbd> moves the focus to the last tab.

Additionally, the following signals have default keybindings:

Tabs support drag-and-drop between notebooks sharing the same group-name, or to new windows by handling the ::create-window signal.

Actions¶

GtkNotebook defines a set of built-in actions:

menu.popup opens the tabs context menu.

CSS nodes¶

notebook
├── header.top
│   ├── [<action widget>]
│   ├── tabs
│   │   ├── [arrow]
│   │   ├── tab
│   │   │   ╰── <tab label>
┊   ┊   ┊
│   │   ├── tab[.reorderable-page]
│   │   │   ╰── <tab label>
│   │   ╰── [arrow]
│   ╰── [<action widget>]
│
╰── stack
    ├── <child>
    ┊
    ╰── <child>

GtkNotebook has a main CSS node with name notebook, a subnode with name header and below that a subnode with name tabs which contains one subnode per tab with name tab.

If action widgets are present, their CSS nodes are placed next to the tabs node. If the notebook is scrollable, CSS nodes with name arrow are placed as first and last child of the tabs node.

The main node gets the .frame style class when the notebook has a border (see Notebook.set_show_border).

The header node gets one of the style class .top, .bottom, .left or .right, depending on where the tabs are placed. For reorderable pages, the tab node gets the .reorderable-page class.

A tab node gets the .dnd style class while it is moved with drag-and-drop.

The nodes are always arranged from left-to-right, regardless of text direction.

Accessibility¶

GtkNotebook uses the following roles:

AccessibleRole.group for the notebook widget
AccessibleRole.tab_list for the list of tabs
AccessibleRole.tab role for each tab
AccessibleRole.tab_panel for each page

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new GtkNotebook widget with no pages.

Methods¶

append_page¶

def append_page(self, child: Widget, tab_label: Widget | None = ...) -> int

Appends a page to notebook.

Parameters:

child — the GtkWidget to use as the contents of the page
tab_label — the GtkWidget to be used as the label for the page, or None to use the default label, “page N”

append_page_menu¶

def append_page_menu(self, child: Widget, tab_label: Widget | None = ..., menu_label: Widget | None = ...) -> int

Appends a page to notebook, specifying the widget to use as the label in the popup menu.

Parameters:

child — the GtkWidget to use as the contents of the page
tab_label — the GtkWidget to be used as the label for the page, or None to use the default label, “page N”
menu_label — the widget to use as a label for the page-switch menu, if that is enabled. If None, and tab_label is a GtkLabel or None, then the menu label will be a newly created label with the same text as tab_label; if tab_label is not a GtkLabel, menu_label must be specified if the page-switch menu is to be used.

detach_tab¶

def detach_tab(self, child: Widget) -> None

Removes the child from the notebook.

This function is very similar to Notebook.remove_page, but additionally informs the notebook that the removal is happening as part of a tab DND operation, which should not be cancelled.

Parameters:

child — a child

get_action_widget¶

def get_action_widget(self, pack_type: PackType | int) -> Widget | None

Gets one of the action widgets.

See Notebook.set_action_widget.

Parameters:

pack_type — pack type of the action widget to receive

get_current_page¶

def get_current_page(self) -> int

Returns the page number of the current page.

get_group_name¶

def get_group_name(self) -> str | None

Gets the current group name for notebook.

get_menu_label¶

def get_menu_label(self, child: Widget) -> Widget | None

Retrieves the menu label widget of the page containing child.

Parameters:

child — a widget contained in a page of notebook

get_menu_label_text¶

def get_menu_label_text(self, child: Widget) -> str | None

Retrieves the text of the menu label for the page containing child.

Parameters:

child — the child widget of a page of the notebook.

get_n_pages¶

def get_n_pages(self) -> int

Gets the number of pages in a notebook.

get_nth_page¶

def get_nth_page(self, page_num: int) -> Widget | None

Returns the child widget contained in page number page_num.

Parameters:

page_num — the index of a page in the notebook, or -1 to get the last page

get_page¶

def get_page(self, child: Widget) -> NotebookPage

Returns the GtkNotebookPage for child.

Parameters:

child — a child of notebook

get_pages¶

def get_pages(self) -> Gio.ListModel

Returns a GListModel that contains the pages of the notebook.

This can be used to keep an up-to-date view. The model also implements SelectionModel and can be used to track and modify the visible page.

get_scrollable¶

def get_scrollable(self) -> bool

Returns whether the tab label area has arrows for scrolling.

get_show_border¶

def get_show_border(self) -> bool

Returns whether a bevel will be drawn around the notebook pages.

get_show_tabs¶

def get_show_tabs(self) -> bool

Returns whether the tabs of the notebook are shown.

get_tab_detachable¶

def get_tab_detachable(self, child: Widget) -> bool

Returns whether the tab contents can be detached from notebook.

Parameters:

child — a child GtkWidget

get_tab_label¶

def get_tab_label(self, child: Widget) -> Widget | None

Returns the tab label widget for the page child.

None is returned if child is not in notebook or if no tab label has specifically been set for child.

Parameters:

child — the page

get_tab_label_text¶

def get_tab_label_text(self, child: Widget) -> str | None

Retrieves the text of the tab label for the page containing child.

Parameters:

child — a widget contained in a page of notebook

get_tab_pos¶

def get_tab_pos(self) -> PositionType

Gets the edge at which the tabs are drawn.

get_tab_reorderable¶

def get_tab_reorderable(self, child: Widget) -> bool

Gets whether the tab can be reordered via drag and drop or not.

Parameters:

child — a child GtkWidget

insert_page¶

def insert_page(self, child: Widget, tab_label: Widget | None, position: int) -> int

Insert a page into notebook at the given position.

Parameters:

child — the GtkWidget to use as the contents of the page
tab_label — the GtkWidget to be used as the label for the page, or None to use the default label, “page N”
position — the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages

insert_page_menu¶

def insert_page_menu(self, child: Widget, tab_label: Widget | None, menu_label: Widget | None, position: int) -> int

Insert a page into notebook at the given position, specifying the widget to use as the label in the popup menu.

Parameters:

child — the GtkWidget to use as the contents of the page
tab_label — the GtkWidget to be used as the label for the page, or None to use the default label, “page N”
menu_label — the widget to use as a label for the page-switch menu, if that is enabled. If None, and tab_label is a GtkLabel or None, then the menu label will be a newly created label with the same text as tab_label; if tab_label is not a GtkLabel, menu_label must be specified if the page-switch menu is to be used.
position — the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages.

next_page¶

def next_page(self) -> None

Switches to the next page.

Nothing happens if the current page is the last page.

page_num¶

def page_num(self, child: Widget) -> int

Finds the index of the page which contains the given child widget.

Parameters:

child — a GtkWidget

popup_disable¶

def popup_disable(self) -> None

Disables the popup menu.

popup_enable¶

def popup_enable(self) -> None

Enables the popup menu.

If the user clicks with the right mouse button on the tab labels, a menu with all the pages will be popped up.

prepend_page¶

def prepend_page(self, child: Widget, tab_label: Widget | None = ...) -> int

Prepends a page to notebook.

Parameters:

child — the GtkWidget to use as the contents of the page
tab_label — the GtkWidget to be used as the label for the page, or None to use the default label, “page N”

prepend_page_menu¶

def prepend_page_menu(self, child: Widget, tab_label: Widget | None = ..., menu_label: Widget | None = ...) -> int

Prepends a page to notebook, specifying the widget to use as the label in the popup menu.

Parameters:

child — the GtkWidget to use as the contents of the page
tab_label — the GtkWidget to be used as the label for the page, or None to use the default label, “page N”
menu_label — the widget to use as a label for the page-switch menu, if that is enabled. If None, and tab_label is a GtkLabel or None, then the menu label will be a newly created label with the same text as tab_label; if tab_label is not a GtkLabel, menu_label must be specified if the page-switch menu is to be used.

prev_page¶

def prev_page(self) -> None

Switches to the previous page.

Nothing happens if the current page is the first page.

remove_page¶

def remove_page(self, page_num: int) -> None

Removes a page from the notebook given its index in the notebook.

Parameters:

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

reorder_child¶

def reorder_child(self, child: Widget, position: int) -> None

Reorders the page containing child, so that it appears in position 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.

Parameters:

child — the child to move
position — the new position, or -1 to move to the end

set_action_widget¶

def set_action_widget(self, widget: Widget, pack_type: PackType | int) -> None

Sets widget as one of the action widgets.

Depending on the pack type the widget will be placed before or after the tabs. You can use a GtkBox if you need to pack more than one widget on the same side.

Parameters:

widget — a GtkWidget
pack_type — pack type of the action widget

set_current_page¶

def set_current_page(self, page_num: int) -> None

Switches to the page number page_num.

Note that due to historical reasons, GtkNotebook refuses to switch to a page unless the child widget is visible. Therefore, it is recommended to show child widgets before adding them to a notebook.

Parameters:

page_num — 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.

set_group_name¶

def set_group_name(self, group_name: str | None = ...) -> None

Sets a group name for notebook.

Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a None group name will not be able to exchange tabs with any other notebook.

Parameters:

group_name — the name of the notebook group, or None to unset it

set_menu_label¶

def set_menu_label(self, child: Widget, menu_label: Widget | None = ...) -> None

Changes the menu label for the page containing child.

Parameters:

child — the child widget
menu_label — the menu label, or None for default

set_menu_label_text¶

def set_menu_label_text(self, child: Widget, menu_text: str) -> None

Creates a new label and sets it as the menu label of child.

Parameters:

child — the child widget
menu_text — the label text

set_scrollable¶

def set_scrollable(self, scrollable: bool) -> None

Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area.

Parameters:

scrollable — True if scroll arrows should be added

set_show_border¶

def set_show_border(self, show_border: bool) -> None

Sets whether a bevel will be drawn around the notebook pages.

This only has a visual effect when the tabs are not shown.

Parameters:

show_border — True if a bevel should be drawn around the notebook

set_show_tabs¶

def set_show_tabs(self, show_tabs: bool) -> None

Sets whether to show the tabs for the notebook or not.

Parameters:

show_tabs — True if the tabs should be shown

set_tab_detachable¶

def set_tab_detachable(self, child: Widget, detachable: bool) -> None

Sets whether the tab can be detached from notebook to another notebook or widget.

Note that two notebooks must share a common group identifier (see Notebook.set_group_name) to allow automatic tabs interchange between them.

If you want a widget to interact with a notebook through DnD (i.e.: accept dragged tabs from it) it must be set as a drop destination by adding to it a DropTarget controller that accepts the GType GTK_TYPE_NOTEBOOK_PAGE. The :value of said drop target will be preloaded with a NotebookPage object that corresponds to the dropped tab, so you can process the value via ::accept or ::drop signals.

Note that you should use Notebook.detach_tab instead of Notebook.remove_page if you want to remove the tab from the source notebook as part of accepting a drop. Otherwise, the source notebook will think that the dragged tab was removed from underneath the ongoing drag operation, and will initiate a drag cancel animation.

static void
on_drag_data_received (GtkWidget        *widget,
                       GdkDrop          *drop,
                       GtkSelectionData *data,
                       guint             time,
                       gpointer          user_data)
{
  GtkDrag *drag;
  GtkWidget *notebook;
  GtkWidget **child;

  drag = gtk_drop_get_drag (drop);
  notebook = g_object_get_data (drag, "gtk-notebook-drag-origin");
  child = (void*) gtk_selection_data_get_data (data);

  // process_widget (*child);

  gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
}

If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do it.

Parameters:

child — a child GtkWidget
detachable — whether the tab is detachable or not

set_tab_label¶

def set_tab_label(self, child: Widget, tab_label: Widget | None = ...) -> None

Changes the tab label for child.

If None is specified for tab_label, then the page will have the label “page N”.

Parameters:

child — the page
tab_label — the tab label widget to use, or None for default tab label

set_tab_label_text¶

def set_tab_label_text(self, child: Widget, tab_text: str) -> None

Creates a new label and sets it as the tab label for the page containing child.

Parameters:

child — the page
tab_text — the label text

set_tab_pos¶

def set_tab_pos(self, pos: PositionType | int) -> None

Sets the edge at which the tabs are drawn.

Parameters:

pos — the edge to draw the tabs at

set_tab_reorderable¶

def set_tab_reorderable(self, child: Widget, reorderable: bool) -> None

Sets whether the notebook tab can be reordered via drag and drop or not.

Parameters:

child — a child GtkWidget
reorderable — whether the tab is reorderable or not

Properties¶

enable_popup¶

enable_popup: bool  # read/write

If True, pressing the right mouse button on the notebook shows a page switching menu.

group_name¶

group_name: str  # read/write

Group name for tab drag and drop.

page¶

page: int  # read/write

The index of the current page.

pages¶

pages: Gio.ListModel  # read-only

A selection model with the pages.

scrollable¶

scrollable: bool  # read/write

If True, scroll arrows are added if there are too many pages to fit.

show_border¶

show_border: bool  # read/write

Whether the border should be shown.

show_tabs¶

show_tabs: bool  # read/write

Whether tabs should be shown.

tab_pos¶

tab_pos: PositionType | int  # read/write

Which side of the notebook holds the tabs.

Signals¶

change-current-page¶

def on_change_current_page(self, page: int) -> bool: ...

Emitted when the current page should be changed.

The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgDn</kbd>, <kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>.

create-window¶

def on_create_window(self, page: Widget) -> Notebook | None: ...

The ::create-window signal is emitted when a detachable tab is dropped on the root window.

A handler for this signal can create a window containing a notebook where the tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook (e.g. the GtkNotebook:group-name ).

focus-tab¶

def on_focus_tab(self, tab: NotebookTab) -> bool: ...

Emitted when a tab should be focused.

move-focus-out¶

def on_move_focus_out(self, direction: DirectionType) -> None: ...

Emitted when focus was moved out.

The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>Ctrl</kbd>+<kbd>→</kbd>, <kbd>Ctrl</kbd>+<kbd>↑</kbd> and <kbd>Ctrl</kbd>+<kbd>↓</kbd>.

page-added¶

def on_page_added(self, child: Widget, page_num: int) -> None: ...

the ::page-added signal is emitted in the notebook right after a page is added to the notebook.

page-removed¶

def on_page_removed(self, child: Widget, page_num: int) -> None: ...

the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook.

page-reordered¶

def on_page_reordered(self, child: Widget, page_num: int) -> None: ...

the ::page-reordered signal is emitted in the notebook right after a page has been reordered.

reorder-tab¶

def on_reorder_tab(self, direction: DirectionType, move_to_last: bool) -> bool: ...

Emitted when the tab should be reordered.

The default bindings for this signal are <kbd>Alt</kbd>+<kbd>Home</kbd>, <kbd>Alt</kbd>+<kbd>End</kbd>, <kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Alt</kbd>+<kbd>PgDn</kbd>, <kbd>Alt</kbd>+<kbd>←</kbd>, <kbd>Alt</kbd>+<kbd>→</kbd>, <kbd>Alt</kbd>+<kbd>↑</kbd> and <kbd>Alt</kbd>+<kbd>↓</kbd>.

select-page¶

def on_select_page(self, move_focus: bool) -> bool: ...

Emitted when a page should be selected.

The default binding for this signal is <kbd>␣</kbd>.

switch-page¶

def on_switch_page(self, page: Widget, page_num: int) -> None: ...

Emitted when the user or a function changes the current page.