TabView
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
Methods
- class TabView
- add_page(child: Widget, parent: TabPage | None = None) TabPage
Adds
child
toself
withparent
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
isNULL
, this function is equivalent toappend
.- Parameters:
child – a widget to add
parent – a parent page for
child
- add_shortcuts(shortcuts: TabViewShortcuts) None
Adds
shortcuts
forself
.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 forpage
. Closing the page can then be confirmed or denied viaclose_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 isNULL
, 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 forpage
.If
confirm
isTRUE
,page
will be closed. If it’sFALSE
, it will be reverted to its previous state andclose_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_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 anyAdwTabView
, and toFALSE
after it ends.During the transfer, children cannot receive pointer input and a tab can be safely dropped on the tab view.
Gets the tab context menu model for
self
.
- get_nth_page(position: int) TabPage
Gets the
TabPage
representing the child atposition
.- Parameters:
position – the index of the page in
self
, starting from 0
- get_page(child: Widget) TabPage
Gets the
TabPage
object representingchild
.- Parameters:
child – a child in
self
- get_page_position(page: TabPage) int
Finds the position of
page
inself
, starting from 0.- Parameters:
page – a page of
self
- get_pages() SelectionModel
Returns a
ListModel
that contains the pages ofself
.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_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
fromself
.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
toposition
.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
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 inself
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:A spinner if
loading
isTRUE
TabOverview
will not show a thumbnail for pinned pages, and replace the close button with an unpin button. UnlikeAdwTabBar
, 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
andremove_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
fromself
toother_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 anyAdwTabView
, and toFALSE
after it ends.During the transfer, children cannot receive pointer input and a tab can be safely dropped on the tab view.
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.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.shortcuts: TabViewShortcuts
The enabled shortcuts.
See
TabViewShortcuts
for the list of the available shortcuts. All of the shortcuts are enabled by default.add_shortcuts
andremove_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 forpage
.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
GDK_EVENT_STOP
to stop propagation orGDK_EVENT_CONTINUE
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
andindicator_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 toposition
.- Parameters:
page – a page of
self
position – the position
page
was moved to, starting at 0
Emitted when a context menu is opened or closed for
page
.If the menu has been closed,
page
will be set toNULL
.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