: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` :Constructors: :: TabView(**properties) new() -> Adw.TabView 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 reomve .. 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: 1. :obj:`~gi.repository.Adw.TabPage.props.indicator_icon` 2. A spinner if :obj:`~gi.repository.Adw.TabPage.props.loading` is ``TRUE`` 3. :obj:`~gi.repository.Adw.TabPage.props.icon` 4. :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 Default page icon. 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. .. attribute:: props.is_transferring_page :type: bool Whether a page is being transferred. This 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. .. attribute:: props.menu_model :type: ~gi.repository.Gio.MenuModel Tab context menu model. 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. .. attribute:: props.n_pages :type: int The number of pages in the tab view. .. attribute:: props.n_pinned_pages :type: int The number of pinned pages in the tab view. See :obj:`~gi.repository.TabView.set_page_pinned`. .. attribute:: props.pages :type: ~gi.repository.Gtk.SelectionModel A selection model with the tab view's pages. 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. .. attribute:: props.selected_page :type: ~gi.repository.Adw.TabPage The currently selected page. .. attribute:: props.shortcuts :type: ~gi.repository.Adw.TabViewShortcuts The enabled shortcuts. 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 Signals ------- .. rst-class:: interim-class .. class:: TabView.signals :no-index: .. method:: close_page(page: ~gi.repository.Adw.TabPage) -> bool Emitted after :obj:`~gi.repository.TabView.close_page` has been called for ``page``. The handler is expected to call :obj:`~gi.repository.TabView.close_page_finish` to confirm or reject the closing. The default handler will immediately confirm closing for non-pinned pages, or reject it for pinned pages, equivalent to the following example: .. code-block:: c :dedent: static gboolean close_page_cb (AdwTabView *view, AdwTabPage *page, gpointer user_data) { adw_tab_view_close_page_finish (view, page, !adw_tab_page_get_pinned (page)); return GDK_EVENT_STOP; } The :obj:`~gi.repository.TabView.close_page_finish` call doesn't have to happen inside the handler, so can be used to do asynchronous checks before confirming the closing. A typical reason to connect to this signal is to show a confirmation dialog for closing a tab. The signal handler should return ``GDK_EVENT_STOP`` to stop propagation or ``GDK_EVENT_CONTINUE`` to invoke the default handler. :param page: a page of ``self`` .. method:: create_window() -> ~gi.repository.Adw.TabView | None Emitted when a tab should be transferred into a new window. This can happen after a tab has been dropped on desktop. The signal handler is expected to create a new window, position it as needed and return its ``AdwTabView`` that the page will be transferred into. .. method:: indicator_activated(page: ~gi.repository.Adw.TabPage) -> None Emitted after the indicator icon on ``page`` has been activated. See :obj:`~gi.repository.Adw.TabPage.props.indicator_icon` and :obj:`~gi.repository.Adw.TabPage.props.indicator_activatable`. :param page: a page of ``self`` .. method:: page_attached(page: ~gi.repository.Adw.TabPage, position: int) -> None Emitted when a page has been created or transferred to ``self``. A typical reason to connect to this signal would be to connect to page signals for things such as updating window title. :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 Emitted when a page has been removed or transferred to another view. A typical reason to connect to this signal would be to disconnect signal handlers connected in the :obj:`~gi.repository.Adw.TabView.signals.page_attached` handler. It is important not to try and destroy the page child in the handler of this function as the child might merely be moved to another window; use child dispose handler for that or do it in sync with your :obj:`~gi.repository.TabView.close_page_finish` calls. :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 Emitted after ``page`` has been reordered to ``position``. :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 Emitted when a context menu is opened or closed for ``page``. If the menu has been closed, ``page`` will be set to ``NULL``. It can be used to set up menu actions before showing the menu, for example disable actions not applicable to ``page``. :param page: a page of ``self``