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 tab-panel role 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 implements SectionModel, with one section for pinned pages and one for the rest of the pages.

It 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 remove

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:

• indicator_icon

• A spinner if loading is TRUE

• icon

• default_icon

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 list model with the tab view’s pages.

This can be used to keep an up-to-date view.

The model implements SectionModel, with one section for pinned pages and one for the rest of the pages.

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

The signal handler should return EVENT_STOP to stop propagation or EVENT_PROPAGATE to invoke the default handler.

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