TabView

class TabView(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, 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 TabBar, TabOverview and TabButton.

AdwTabView maintains a TabPage object for each page, which holds additional per-page properties. You can obtain the AdwTabPage for a page with get_page, and as the return value for 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 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 shortcuts property can be used to manage them.

See TabViewShortcuts for the list of the available shortcuts. All of the shortcuts are enabled by default.

add_shortcuts and remove_shortcuts can be used to manage shortcuts in a convenient way, for example:

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

class TabView

classmethod new() → TabView: Creates a new AdwTabView.

Methods

class TabView

add_page(child: Widget, parent: TabPage | None = None) → 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 close_page).

If parent is NULL, this function is equivalent to append.

Parameters:

child – a widget to add
parent – a parent page for child

add_shortcuts(shortcuts: TabViewShortcuts) → None

Adds shortcuts for self.

See shortcuts for details.

Added in version 1.2.

Parameters:: shortcuts – the shortcuts to add

append(child: Widget) → TabPage

Inserts child as the last non-pinned page.

Parameters:: child – a widget to add

append_pinned(child: Widget) → TabPage

Inserts child as the last pinned page.

Parameters:: child – a widget to add

close_other_pages(page: TabPage) → None

Requests to close all pages other than page.

Parameters:: page – a page of self

close_page(page: TabPage) → None

Requests to close page.

Calling this function will result in the close_page signal being emitted for page. Closing the page can then be confirmed or denied via close_page_finish.

If the page is waiting for a close_page_finish call, this function will do nothing.

The default handler for 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 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.

Parameters:: page – a page of self

close_page_finish(page: TabPage, confirm: bool) → None

Completes a 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 close_page can be called for it again.

This function should not be called unless a custom handler for close_page is used.

Parameters:

page – a page of self
confirm – whether to confirm or deny closing page

close_pages_after(page: TabPage) → None

Requests to close all pages after page.

Parameters:: page – a page of self

close_pages_before(page: TabPage) → None

Requests to close all pages before page.

Parameters:: page – a page of self

get_default_icon() → Icon: Gets the default icon of self.

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.

get_menu_model() → MenuModel | None: Gets the tab context menu model for self.

get_n_pages() → int: Gets the number of pages in self.

get_n_pinned_pages() → int

Gets the number of pinned pages in self.

See set_page_pinned.

get_nth_page(position: int) → TabPage

Gets the TabPage representing the child at position.

Parameters:: position – the index of the page in self, starting from 0

get_page(child: Widget) → TabPage

Gets the TabPage object representing child.

Parameters:: child – a child in self

get_page_position(page: TabPage) → int

Finds the position of page in self, starting from 0.

Parameters:: page – a page of self

get_pages() → SelectionModel

Returns a ListModel that contains the pages of self.

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

get_selected_page() → TabPage | None: Gets the currently selected page in self.

get_shortcuts() → TabViewShortcuts: Gets the enabled shortcuts for self.

Added in version 1.2.

insert(child: Widget, position: int) → 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 insert_pinned should be used instead.

Parameters:

child – a widget to add
position – the position to add child at, starting from 0

insert_pinned(child: Widget, position: int) → 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 insert should be used instead.

Parameters:

child – a widget to add
position – the position to add child at, starting from 0

invalidate_thumbnails() → None

Invalidates thumbnails for all pages in self.

This is a convenience method, equivalent to calling invalidate_thumbnail on each page.

Added in version 1.3.

prepend(child: Widget) → TabPage

Inserts child as the first non-pinned page.

Parameters:: child – a widget to add

prepend_pinned(child: Widget) → TabPage

Inserts child as the first pinned page.

Parameters:: child – a widget to add

remove_shortcuts(shortcuts: TabViewShortcuts) → None

Removes shortcuts from self.

See shortcuts for details.

Added in version 1.2.

Parameters:: shortcuts – the shortcuts to reomve

reorder_backward(page: TabPage) → bool

Reorders page to before its previous page if possible.

Parameters:: page – a page of self

reorder_first(page: TabPage) → bool

Reorders page to the first possible position.

Parameters:: page – a page of self

reorder_forward(page: TabPage) → bool

Reorders page to after its next page if possible.

Parameters:: page – a page of self

reorder_last(page: TabPage) → bool

Reorders page to the last possible position.

Parameters:: page – a page of self

reorder_page(page: 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.

Parameters:

page – a page of self
position – the position to insert the page at, starting at 0

select_next_page() → bool

Selects the page after the currently selected page.

If the last page was already selected, this function does nothing.

select_previous_page() → bool

Selects the page before the currently selected page.

If the first page was already selected, this function does nothing.

set_default_icon(default_icon: Icon) → None

Sets the default page icon for self.

If a page doesn’t provide its own icon via icon, a default icon may be used instead for contexts where having an icon is necessary.

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.

TabOverview will use default icon for pages with missing thumbnails.

By default, the adw-tab-icon-missing-symbolic icon is used.

Parameters:: default_icon – the default icon

set_menu_model(menu_model: 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 setup_menu signal to set up the menu actions for the particular tab.

Parameters:: menu_model – a menu model

set_page_pinned(page: 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 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.

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:

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 close_page for how to override that behavior.

Changes the value of the pinned property.

Parameters:

page – a page of self
pinned – whether page should be pinned

set_selected_page(selected_page: TabPage) → None

Sets the currently selected page in self.

Parameters:: selected_page – a page in self

set_shortcuts(shortcuts: TabViewShortcuts) → None

Sets the enabled shortcuts for self.

See TabViewShortcuts for the list of the available shortcuts. All of the shortcuts are enabled by default.

add_shortcuts and remove_shortcuts provide a convenient way to manage individual shortcuts.

Added in version 1.2.

Parameters:: shortcuts – the new shortcuts

transfer_page(page: TabPage, other_view: 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.

Parameters:

page – a page of self
other_view – the tab view to transfer the page to
position – the position to insert the page at, starting at 0

Properties

class TabView

props.default_icon: Icon

Default page icon.

If a page doesn’t provide its own icon via icon, a default icon may be used instead for contexts where having an icon is necessary.

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.

TabOverview will use default icon for pages with missing thumbnails.

By default, the adw-tab-icon-missing-symbolic icon is used.

props.is_transferring_page: 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.

props.menu_model: 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 setup_menu signal to set up the menu actions for the particular tab.

props.n_pages: int: The number of pages in the tab view.

props.n_pinned_pages: int

The number of pinned pages in the tab view.

See set_page_pinned.

props.pages: 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 SelectionModel and can be used to track and change the selected page.

props.selected_page: TabPage: The currently selected page.

props.shortcuts: TabViewShortcuts

The enabled shortcuts.

See TabViewShortcuts for the list of the available shortcuts. All of the shortcuts are enabled by default.

add_shortcuts and remove_shortcuts provide a convenient way to manage individual shortcuts.

Added in version 1.2.

Signals

class TabView.signals

close_page(page: TabPage) → bool

Emitted after close_page has been called for page.

The handler is expected to call 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:

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

Parameters:: page – a page of self

create_window() → 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.

indicator_activated(page: TabPage) → None

Emitted after the indicator icon on page has been activated.

See indicator_icon and indicator_activatable.

Parameters:: page – a page of self

page_attached(page: 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.

Parameters:

page – a page of self
position – the position of the page, starting from 0

page_detached(page: 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 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 close_page_finish calls.

Parameters:

page – a page of self
position – the position of the removed page, starting from 0

page_reordered(page: TabPage, position: int) → None

Emitted after page has been reordered to position.

Parameters:

page – a page of self
position – the position page was moved to, starting at 0

setup_menu(page: 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.

Parameters:: page – a page of self