:right-sidebar: True Notebook =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Notebook(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` ``GtkNotebook`` is a container whose children are pages switched between using tabs. .. image:: https://docs.gtk.org/gtk4/notebook.png There are many configuration options for ``GtkNotebook``. Among other things, you can choose on which edge the tabs appear (see :obj:`~gi.repository.Gtk.Notebook.set_tab_pos`), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see :obj:`~gi.repository.Gtk.Notebook.set_scrollable`), and whether there will be a popup menu allowing the users to switch pages. (see :obj:`~gi.repository.Gtk.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 ```` 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 ```` type attribute. To add a child widget in the notebooks action area, specify "action-start" or “action-end” as the “type” attribute of the ```` element. An example of a UI definition fragment with ``GtkNotebook``: .. code-block:: :dedent:

CSS nodes --------- .. code-block:: :dedent: notebook ├── header.top │ ├── [] │ ├── tabs │ │ ├── [arrow] │ │ ├── tab │ │ │ ╰── ┊ ┊ ┊ │ │ ├── tab[.reorderable-page] │ │ │ ╰── │ │ ╰── [arrow] │ ╰── [] │ ╰── stack ├── ┊ ╰── ``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 :obj:`~gi.repository.Gtk.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: - :const:`~gi.repository.Gtk.AccessibleRole.GROUP` for the notebook widget - :const:`~gi.repository.Gtk.AccessibleRole.TAB_LIST` for the list of tabs - :const:`~gi.repository.Gtk.AccessibleRole.TAB` role for each tab - :const:`~gi.repository.Gtk.AccessibleRole.TAB_PANEL` for each page Constructors ------------ .. rst-class:: interim-class .. class:: Notebook :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``GtkNotebook`` widget with no pages. Methods ------- .. rst-class:: interim-class .. class:: Notebook :no-index: .. method:: append_page(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None = None) -> int Appends a page to ``notebook``. :param child: the ``GtkWidget`` to use as the contents of the page :param tab_label: the ``GtkWidget`` to be used as the label for the page, or :const:`None` to use the default label, “page N” .. method:: append_page_menu(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None = None, menu_label: ~gi.repository.Gtk.Widget | None = None) -> int Appends a page to ``notebook``, specifying the widget to use as the label in the popup menu. :param child: the ``GtkWidget`` to use as the contents of the page :param tab_label: the ``GtkWidget`` to be used as the label for the page, or :const:`None` to use the default label, “page N” :param menu_label: the widget to use as a label for the page-switch menu, if that is enabled. If :const:`None`, and ``tab_label`` is a ``GtkLabel`` or :const:`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. .. method:: detach_tab(child: ~gi.repository.Gtk.Widget) -> None Removes the child from the notebook. This function is very similar to :obj:`~gi.repository.Gtk.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. :param child: a child .. method:: get_action_widget(pack_type: ~gi.repository.Gtk.PackType) -> ~gi.repository.Gtk.Widget | None Gets one of the action widgets. See :obj:`~gi.repository.Gtk.Notebook.set_action_widget`. :param pack_type: pack type of the action widget to receive .. method:: get_current_page() -> int Returns the page number of the current page. .. method:: get_group_name() -> str | None Gets the current group name for ``notebook``. .. method:: get_menu_label(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.Widget | None Retrieves the menu label widget of the page containing ``child``. :param child: a widget contained in a page of ``notebook`` .. method:: get_menu_label_text(child: ~gi.repository.Gtk.Widget) -> str | None Retrieves the text of the menu label for the page containing ``child``. :param child: the child widget of a page of the notebook. .. method:: get_n_pages() -> int Gets the number of pages in a notebook. .. method:: get_nth_page(page_num: int) -> ~gi.repository.Gtk.Widget | None Returns the child widget contained in page number ``page_num``. :param page_num: the index of a page in the notebook, or -1 to get the last page .. method:: get_page(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.NotebookPage Returns the ``GtkNotebookPage`` for ``child``. :param child: a child of ``notebook`` .. method:: get_pages() -> ~gi.repository.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 :obj:`~gi.repository.Gtk.SelectionModel` and can be used to track and modify the visible page. .. method:: get_scrollable() -> bool Returns whether the tab label area has arrows for scrolling. .. method:: get_show_border() -> bool Returns whether a bevel will be drawn around the notebook pages. .. method:: get_show_tabs() -> bool Returns whether the tabs of the notebook are shown. .. method:: get_tab_detachable(child: ~gi.repository.Gtk.Widget) -> bool Returns whether the tab contents can be detached from ``notebook``. :param child: a child ``GtkWidget`` .. method:: get_tab_label(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.Widget | None Returns the tab label widget for the page ``child``. :const:`None` is returned if ``child`` is not in ``notebook`` or if no tab label has specifically been set for ``child``. :param child: the page .. method:: get_tab_label_text(child: ~gi.repository.Gtk.Widget) -> str | None Retrieves the text of the tab label for the page containing ``child``. :param child: a widget contained in a page of ``notebook`` .. method:: get_tab_pos() -> ~gi.repository.Gtk.PositionType Gets the edge at which the tabs are drawn. .. method:: get_tab_reorderable(child: ~gi.repository.Gtk.Widget) -> bool Gets whether the tab can be reordered via drag and drop or not. :param child: a child ``GtkWidget`` .. method:: insert_page(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None, position: int) -> int Insert a page into ``notebook`` at the given position. :param child: the ``GtkWidget`` to use as the contents of the page :param tab_label: the ``GtkWidget`` to be used as the label for the page, or :const:`None` to use the default label, “page N” :param position: the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages .. method:: insert_page_menu(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None, menu_label: ~gi.repository.Gtk.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. :param child: the ``GtkWidget`` to use as the contents of the page :param tab_label: the ``GtkWidget`` to be used as the label for the page, or :const:`None` to use the default label, “page N” :param menu_label: the widget to use as a label for the page-switch menu, if that is enabled. If :const:`None`, and ``tab_label`` is a ``GtkLabel`` or :const:`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. :param position: the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages. .. method:: next_page() -> None Switches to the next page. Nothing happens if the current page is the last page. .. method:: page_num(child: ~gi.repository.Gtk.Widget) -> int Finds the index of the page which contains the given child widget. :param child: a ``GtkWidget`` .. method:: popup_disable() -> None Disables the popup menu. .. method:: popup_enable() -> 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. .. method:: prepend_page(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None = None) -> int Prepends a page to ``notebook``. :param child: the ``GtkWidget`` to use as the contents of the page :param tab_label: the ``GtkWidget`` to be used as the label for the page, or :const:`None` to use the default label, “page N” .. method:: prepend_page_menu(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None = None, menu_label: ~gi.repository.Gtk.Widget | None = None) -> int Prepends a page to ``notebook``, specifying the widget to use as the label in the popup menu. :param child: the ``GtkWidget`` to use as the contents of the page :param tab_label: the ``GtkWidget`` to be used as the label for the page, or :const:`None` to use the default label, “page N” :param menu_label: the widget to use as a label for the page-switch menu, if that is enabled. If :const:`None`, and ``tab_label`` is a ``GtkLabel`` or :const:`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. .. method:: prev_page() -> None Switches to the previous page. Nothing happens if the current page is the first page. .. method:: remove_page(page_num: int) -> None Removes a page from the notebook given its index in the notebook. :param page_num: the index of a notebook page, starting from 0. If -1, the last page will be removed. .. method:: reorder_child(child: ~gi.repository.Gtk.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. :param child: the child to move :param position: the new position, or -1 to move to the end .. method:: set_action_widget(widget: ~gi.repository.Gtk.Widget, pack_type: ~gi.repository.Gtk.PackType) -> 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. :param widget: a ``GtkWidget`` :param pack_type: pack type of the action widget .. method:: set_current_page(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. :param 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. .. method:: set_group_name(group_name: str | None = 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 :const:`None` group name will not be able to exchange tabs with any other notebook. :param group_name: the name of the notebook group, or :const:`None` to unset it .. method:: set_menu_label(child: ~gi.repository.Gtk.Widget, menu_label: ~gi.repository.Gtk.Widget | None = None) -> None Changes the menu label for the page containing ``child``. :param child: the child widget :param menu_label: the menu label, or :const:`None` for default .. method:: set_menu_label_text(child: ~gi.repository.Gtk.Widget, menu_text: str) -> None Creates a new label and sets it as the menu label of ``child``. :param child: the child widget :param menu_text: the label text .. method:: set_scrollable(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. :param scrollable: :const:`True` if scroll arrows should be added .. method:: set_show_border(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. :param show_border: :const:`True` if a bevel should be drawn around the notebook .. method:: set_show_tabs(show_tabs: bool) -> None Sets whether to show the tabs for the notebook or not. :param show_tabs: :const:`True` if the tabs should be shown .. method:: set_tab_detachable(child: ~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.DropTarget` controller that accepts the GType ``GTK_TYPE_NOTEBOOK_PAGE``. The ``:value`` of said drop target will be preloaded with a :obj:`~gi.repository.Gtk.NotebookPage` object that corresponds to the dropped tab, so you can process the value via ``::accept`` or ``::drop`` signals. Note that you should use :obj:`~gi.repository.Gtk.Notebook.detach_tab` instead of :obj:`~gi.repository.Gtk.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. .. code-block:: :dedent: 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. :param child: a child ``GtkWidget`` :param detachable: whether the tab is detachable or not .. method:: set_tab_label(child: ~gi.repository.Gtk.Widget, tab_label: ~gi.repository.Gtk.Widget | None = None) -> None Changes the tab label for ``child``. If :const:`None` is specified for ``tab_label``, then the page will have the label “page N”. :param child: the page :param tab_label: the tab label widget to use, or :const:`None` for default tab label .. method:: set_tab_label_text(child: ~gi.repository.Gtk.Widget, tab_text: str) -> None Creates a new label and sets it as the tab label for the page containing ``child``. :param child: the page :param tab_text: the label text .. method:: set_tab_pos(pos: ~gi.repository.Gtk.PositionType) -> None Sets the edge at which the tabs are drawn. :param pos: the edge to draw the tabs at .. method:: set_tab_reorderable(child: ~gi.repository.Gtk.Widget, reorderable: bool) -> None Sets whether the notebook tab can be reordered via drag and drop or not. :param child: a child ``GtkWidget`` :param reorderable: whether the tab is reorderable or not Properties ---------- .. rst-class:: interim-class .. class:: Notebook :no-index: .. attribute:: props.enable_popup :type: bool If :const:`True`, pressing the right mouse button on the notebook shows a page switching menu. .. attribute:: props.group_name :type: str Group name for tab drag and drop. .. attribute:: props.page :type: int The index of the current page. .. attribute:: props.pages :type: ~gi.repository.Gio.ListModel A selection model with the pages. .. attribute:: props.scrollable :type: bool If :const:`True`, scroll arrows are added if there are too many pages to fit. .. attribute:: props.show_border :type: bool Whether the border should be shown. .. attribute:: props.show_tabs :type: bool Whether tabs should be shown. .. attribute:: props.tab_pos :type: ~gi.repository.Gtk.PositionType Which side of the notebook holds the tabs. Signals ------- .. rst-class:: interim-class .. class:: Notebook.signals :no-index: .. method:: change_current_page(object: int) -> bool :param object: .. method:: create_window(page: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.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 ). :param page: the tab of ``notebook`` that is being detached .. method:: focus_tab(object: ~gi.repository.Gtk.NotebookTab) -> bool :param object: .. method:: move_focus_out(object: ~gi.repository.Gtk.DirectionType) -> None :param object: .. method:: page_added(child: ~gi.repository.Gtk.Widget, page_num: int) -> None the ::page-added signal is emitted in the notebook right after a page is added to the notebook. :param child: the child ``GtkWidget`` affected :param page_num: the new page number for ``child`` .. method:: page_removed(child: ~gi.repository.Gtk.Widget, page_num: int) -> None the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook. :param child: the child ``GtkWidget`` affected :param page_num: the ``child`` page number .. method:: page_reordered(child: ~gi.repository.Gtk.Widget, page_num: int) -> None the ::page-reordered signal is emitted in the notebook right after a page has been reordered. :param child: the child ``GtkWidget`` affected :param page_num: the new page number for ``child`` .. method:: reorder_tab(object: ~gi.repository.Gtk.DirectionType, p0: bool) -> bool :param object: :param p0: .. method:: select_page(object: bool) -> bool :param object: .. method:: switch_page(page: ~gi.repository.Gtk.Widget, page_num: int) -> None Emitted when the user or a function changes the current page. :param page: the new current page :param page_num: the index of the page