:right-sidebar: True TabView =================================================================== .. currentmodule:: gi.repository.Adw .. class:: TabView(**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` A dynamic tabbed container. ``AdwTabView`` is a container which shows one child at a time. While it provides keyboard shortcuts for switching between pages, it does not provide a visible tab switcher and relies on external widgets for that, such as :obj:`~gi.repository.Adw.TabBar`\, :obj:`~gi.repository.Adw.TabOverview` and :obj:`~gi.repository.Adw.TabButton`\. ``AdwTabView`` maintains a :obj:`~gi.repository.Adw.TabPage` object for each page, which holds additional per-page properties. You can obtain the ``AdwTabPage`` for a page with :obj:`~gi.repository.TabView.get_page`\, and as the return value for :obj:`~gi.repository.TabView.append` and other functions for adding children. ``AdwTabView`` only aims to be useful for dynamic tabs in multi-window document-based applications, such as web browsers, file managers, text editors or terminals. It does not aim to replace :obj:`~gi.repository.Gtk.Notebook` for use cases such as tabbed dialogs. As such, it does not support disabling page reordering or detaching. ``AdwTabView`` adds a number of global page switching and reordering shortcuts. The :obj:`~gi.repository.Adw.TabView.props.shortcuts` property can be used to manage them. See :obj:`~gi.repository.Adw.TabViewShortcuts` for the list of the available shortcuts. All of the shortcuts are enabled by default. :obj:`~gi.repository.TabView.add_shortcuts` and :obj:`~gi.repository.TabView.remove_shortcuts` can be used to manage shortcuts in a convenient way, for example: .. code-block:: c :dedent: adw_tab_view_remove_shortcuts (view, ADW_TAB_VIEW_SHORTCUT_CONTROL_HOME | ADW_TAB_VIEW_SHORTCUT_CONTROL_END); CSS nodes -------------------------------------------------------------------------------- ``AdwTabView`` has a main CSS node with the name ``tabview``\. Accessibility -------------------------------------------------------------------------------- ``AdwTabView`` uses the ``GTK_ACCESSIBLE_ROLE_TAB_PANEL`` for the tab pages which are the accessible parent objects of the child widgets. Constructors ------------ .. rst-class:: interim-class .. class:: TabView :no-index: .. classmethod:: new() -> ~gi.repository.Adw.TabView Creates a new ``AdwTabView``\. Methods ------- .. rst-class:: interim-class .. class:: TabView :no-index: .. method:: add_page(child: ~gi.repository.Gtk.Widget, parent: ~gi.repository.Adw.TabPage | None = None) -> ~gi.repository.Adw.TabPage Adds ``child`` to ``self`` with ``parent`` as the parent. This function can be used to automatically position new pages, and to select the correct page when this page is closed while being selected (see :obj:`~gi.repository.TabView.close_page`\). If ``parent`` is ``NULL``\, this function is equivalent to :obj:`~gi.repository.TabView.append`\. :param child: a widget to add :param parent: a parent page for ``child`` .. method:: add_shortcuts(shortcuts: ~gi.repository.Adw.TabViewShortcuts) -> None Adds ``shortcuts`` for ``self``\. See :obj:`~gi.repository.Adw.TabView.props.shortcuts` for details. .. versionadded:: 1.2 :param shortcuts: the shortcuts to add .. method:: append(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Adw.TabPage Inserts ``child`` as the last non-pinned page. :param child: a widget to add .. method:: append_pinned(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Adw.TabPage Inserts ``child`` as the last pinned page. :param child: a widget to add .. method:: close_other_pages(page: ~gi.repository.Adw.TabPage) -> None Requests to close all pages other than ``page``\. :param page: a page of ``self`` .. method:: close_page(page: ~gi.repository.Adw.TabPage) -> None Requests to close ``page``\. Calling this function will result in the :obj:`~gi.repository.Adw.TabView.signals.close_page` signal being emitted for ``page``\. Closing the page can then be confirmed or denied via :obj:`~gi.repository.TabView.close_page_finish`\. If the page is waiting for a :obj:`~gi.repository.TabView.close_page_finish` call, this function will do nothing. The default handler for :obj:`~gi.repository.Adw.TabView.signals.close_page` will immediately confirm closing the page if it's non-pinned, or reject it if it's pinned. This behavior can be changed by registering your own handler for that signal. If ``page`` was selected, another page will be selected instead: If the :obj:`~gi.repository.Adw.TabPage.props.parent` value is ``NULL``\, the next page will be selected when possible, or if the page was already last, the previous page will be selected instead. If it's not ``NULL``\, the previous page will be selected if it's a descendant (possibly indirect) of the parent. If both the previous page and the parent are pinned, the parent will be selected instead. :param page: a page of ``self`` .. method:: close_page_finish(page: ~gi.repository.Adw.TabPage, confirm: bool) -> None Completes a :obj:`~gi.repository.TabView.close_page` call for ``page``\. If ``confirm`` is ``TRUE``\, ``page`` will be closed. If it's ``FALSE``\, it will be reverted to its previous state and :obj:`~gi.repository.TabView.close_page` can be called for it again. This function should not be called unless a custom handler for :obj:`~gi.repository.Adw.TabView.signals.close_page` is used. :param page: a page of ``self`` :param confirm: whether to confirm or deny closing ``page`` .. method:: close_pages_after(page: ~gi.repository.Adw.TabPage) -> None Requests to close all pages after ``page``\. :param page: a page of ``self`` .. method:: close_pages_before(page: ~gi.repository.Adw.TabPage) -> None Requests to close all pages before ``page``\. :param page: a page of ``self`` .. method:: get_default_icon() -> ~gi.repository.Gio.Icon Gets the default icon of ``self``\. .. method:: get_is_transferring_page() -> bool Whether a page is being transferred. The corresponding property will be set to ``TRUE`` when a drag-n-drop tab transfer starts on any ``AdwTabView``\, and to ``FALSE`` after it ends. During the transfer, children cannot receive pointer input and a tab can be safely dropped on the tab view. .. method:: get_menu_model() -> ~gi.repository.Gio.MenuModel | None Gets the tab context menu model for ``self``\. .. method:: get_n_pages() -> int Gets the number of pages in ``self``\. .. method:: get_n_pinned_pages() -> int Gets the number of pinned pages in ``self``\. See :obj:`~gi.repository.TabView.set_page_pinned`\. .. method:: get_nth_page(position: int) -> ~gi.repository.Adw.TabPage Gets the :obj:`~gi.repository.Adw.TabPage` representing the child at ``position``\. :param position: the index of the page in ``self``\, starting from 0 .. method:: get_page(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Adw.TabPage Gets the :obj:`~gi.repository.Adw.TabPage` object representing ``child``\. :param child: a child in ``self`` .. method:: get_page_position(page: ~gi.repository.Adw.TabPage) -> int Finds the position of ``page`` in ``self``\, starting from 0. :param page: a page of ``self`` .. method:: get_pages() -> ~gi.repository.Gtk.SelectionModel Returns a :obj:`~gi.repository.Gio.ListModel` that contains the pages of ``self``\. 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 change the selected page. .. method:: get_selected_page() -> ~gi.repository.Adw.TabPage | None Gets the currently selected page in ``self``\. .. method:: get_shortcuts() -> ~gi.repository.Adw.TabViewShortcuts Gets the enabled shortcuts for ``self``\. .. versionadded:: 1.2 .. method:: insert(child: ~gi.repository.Gtk.Widget, position: int) -> ~gi.repository.Adw.TabPage Inserts a non-pinned page at ``position``\. It's an error to try to insert a page before a pinned page, in that case :obj:`~gi.repository.TabView.insert_pinned` should be used instead. :param child: a widget to add :param position: the position to add ``child`` at, starting from 0 .. method:: insert_pinned(child: ~gi.repository.Gtk.Widget, position: int) -> ~gi.repository.Adw.TabPage Inserts a pinned page at ``position``\. It's an error to try to insert a pinned page after a non-pinned page, in that case :obj:`~gi.repository.TabView.insert` should be used instead. :param child: a widget to add :param position: the position to add ``child`` at, starting from 0 .. method:: invalidate_thumbnails() -> None Invalidates thumbnails for all pages in ``self``\. This is a convenience method, equivalent to calling :obj:`~gi.repository.TabPage.invalidate_thumbnail` on each page. .. versionadded:: 1.3 .. method:: prepend(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Adw.TabPage Inserts ``child`` as the first non-pinned page. :param child: a widget to add .. method:: prepend_pinned(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Adw.TabPage Inserts ``child`` as the first pinned page. :param child: a widget to add .. method:: remove_shortcuts(shortcuts: ~gi.repository.Adw.TabViewShortcuts) -> None Removes ``shortcuts`` from ``self``\. See :obj:`~gi.repository.Adw.TabView.props.shortcuts` for details. .. versionadded:: 1.2 :param shortcuts: the shortcuts to remove .. method:: reorder_backward(page: ~gi.repository.Adw.TabPage) -> bool Reorders ``page`` to before its previous page if possible. :param page: a page of ``self`` .. method:: reorder_first(page: ~gi.repository.Adw.TabPage) -> bool Reorders ``page`` to the first possible position. :param page: a page of ``self`` .. method:: reorder_forward(page: ~gi.repository.Adw.TabPage) -> bool Reorders ``page`` to after its next page if possible. :param page: a page of ``self`` .. method:: reorder_last(page: ~gi.repository.Adw.TabPage) -> bool Reorders ``page`` to the last possible position. :param page: a page of ``self`` .. method:: reorder_page(page: ~gi.repository.Adw.TabPage, position: int) -> bool Reorders ``page`` to ``position``\. It's a programmer error to try to reorder a pinned page after a non-pinned one, or a non-pinned page before a pinned one. :param page: a page of ``self`` :param position: the position to insert the page at, starting at 0 .. method:: select_next_page() -> bool Selects the page after the currently selected page. If the last page was already selected, this function does nothing. .. method:: select_previous_page() -> bool Selects the page before the currently selected page. If the first page was already selected, this function does nothing. .. method:: set_default_icon(default_icon: ~gi.repository.Gio.Icon) -> None Sets the default page icon for ``self``\. If a page doesn't provide its own icon via :obj:`~gi.repository.Adw.TabPage.props.icon`\, a default icon may be used instead for contexts where having an icon is necessary. :obj:`~gi.repository.Adw.TabBar` will use default icon for pinned tabs in case the page is not loading, doesn't have an icon and an indicator. Default icon is never used for tabs that aren't pinned. :obj:`~gi.repository.Adw.TabOverview` will use default icon for pages with missing thumbnails. By default, the ``adw-tab-icon-missing-symbolic`` icon is used. :param default_icon: the default icon .. method:: set_menu_model(menu_model: ~gi.repository.Gio.MenuModel | None = None) -> None Sets the tab context menu model for ``self``\. When a context menu is shown for a tab, it will be constructed from the provided menu model. Use the :obj:`~gi.repository.Adw.TabView.signals.setup_menu` signal to set up the menu actions for the particular tab. :param menu_model: a menu model .. method:: set_page_pinned(page: ~gi.repository.Adw.TabPage, pinned: bool) -> None Pins or unpins ``page``\. Pinned pages are guaranteed to be placed before all non-pinned pages; at any given moment the first :obj:`~gi.repository.Adw.TabView.props.n_pinned_pages` pages in ``self`` are guaranteed to be pinned. When a page is pinned or unpinned, it's automatically reordered: pinning a page moves it after other pinned pages; unpinning a page moves it before other non-pinned pages. Pinned pages can still be reordered between each other. :obj:`~gi.repository.Adw.TabBar` will display pinned pages in a compact form, never showing the title or close button, and only showing a single icon, selected in the following order: - :obj:`~gi.repository.Adw.TabPage.props.indicator_icon` - A spinner if :obj:`~gi.repository.Adw.TabPage.props.loading` is ``TRUE`` - :obj:`~gi.repository.Adw.TabPage.props.icon` - :obj:`~gi.repository.Adw.TabView.props.default_icon` :obj:`~gi.repository.Adw.TabOverview` will not show a thumbnail for pinned pages, and replace the close button with an unpin button. Unlike ``AdwTabBar``\, it will still display the page's title, icon and indicator separately. Pinned pages cannot be closed by default, see :obj:`~gi.repository.Adw.TabView.signals.close_page` for how to override that behavior. Changes the value of the :obj:`~gi.repository.Adw.TabPage.props.pinned` property. :param page: a page of ``self`` :param pinned: whether ``page`` should be pinned .. method:: set_selected_page(selected_page: ~gi.repository.Adw.TabPage) -> None Sets the currently selected page in ``self``\. :param selected_page: a page in ``self`` .. method:: set_shortcuts(shortcuts: ~gi.repository.Adw.TabViewShortcuts) -> None Sets the enabled shortcuts for ``self``\. See :obj:`~gi.repository.Adw.TabViewShortcuts` for the list of the available shortcuts. All of the shortcuts are enabled by default. :obj:`~gi.repository.TabView.add_shortcuts` and :obj:`~gi.repository.TabView.remove_shortcuts` provide a convenient way to manage individual shortcuts. .. versionadded:: 1.2 :param shortcuts: the new shortcuts .. method:: transfer_page(page: ~gi.repository.Adw.TabPage, other_view: ~gi.repository.Adw.TabView, position: int) -> None Transfers ``page`` from ``self`` to ``other_view``\. The ``page`` object will be reused. It's a programmer error to try to insert a pinned page after a non-pinned one, or a non-pinned page before a pinned one. :param page: a page of ``self`` :param other_view: the tab view to transfer the page to :param position: the position to insert the page at, starting at 0 Properties ---------- .. rst-class:: interim-class .. class:: TabView :no-index: .. attribute:: props.default_icon :type: ~gi.repository.Gio.Icon The type of the None singleton. .. attribute:: props.is_transferring_page :type: bool The type of the None singleton. .. attribute:: props.menu_model :type: ~gi.repository.Gio.MenuModel The type of the None singleton. .. attribute:: props.n_pages :type: int The type of the None singleton. .. attribute:: props.n_pinned_pages :type: int The type of the None singleton. .. attribute:: props.pages :type: ~gi.repository.Gtk.SelectionModel The type of the None singleton. .. attribute:: props.selected_page :type: ~gi.repository.Adw.TabPage The type of the None singleton. .. attribute:: props.shortcuts :type: ~gi.repository.Adw.TabViewShortcuts The type of the None singleton. .. versionadded:: 1.2 Signals ------- .. rst-class:: interim-class .. class:: TabView.signals :no-index: .. method:: close_page(page: ~gi.repository.Adw.TabPage) -> bool The type of the None singleton. :param page: a page of ``self`` .. method:: create_window() -> ~gi.repository.Adw.TabView | None The type of the None singleton. .. method:: indicator_activated(page: ~gi.repository.Adw.TabPage) -> None The type of the None singleton. :param page: a page of ``self`` .. method:: page_attached(page: ~gi.repository.Adw.TabPage, position: int) -> None The type of the None singleton. :param page: a page of ``self`` :param position: the position of the page, starting from 0 .. method:: page_detached(page: ~gi.repository.Adw.TabPage, position: int) -> None The type of the None singleton. :param page: a page of ``self`` :param position: the position of the removed page, starting from 0 .. method:: page_reordered(page: ~gi.repository.Adw.TabPage, position: int) -> None The type of the None singleton. :param page: a page of ``self`` :param position: the position ``page`` was moved to, starting at 0 .. method:: setup_menu(page: ~gi.repository.Adw.TabPage | None = None) -> None The type of the None singleton. :param page: a page of ``self``