Handy.TabView¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Bin (1), Gtk.Container (35), Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10)
Structs:: Gtk.ContainerClass (5), Gtk.WidgetClass (12), GObject.ObjectClass (5)

class	`new` ()
	`add_page` (child, parent)
	`append` (child)
	`append_pinned` (child)
	`close_other_pages` (page)
	`close_page` (page)
	`close_page_finish` (page, confirm)
	`close_pages_after` (page)
	`close_pages_before` (page)
	`get_default_icon` ()
	`get_is_transferring_page` ()
	`get_menu_model` ()
	`get_n_pages` ()
	`get_n_pinned_pages` ()
	`get_nth_page` (position)
	`get_page` (child)
	`get_page_position` (page)
	`get_pages` ()
	`get_selected_page` ()
	`get_shortcut_widget` ()
	`insert` (child, position)
	`insert_pinned` (child, position)
	`prepend` (child)
	`prepend_pinned` (child)
	`reorder_backward` (page)
	`reorder_first` (page)
	`reorder_forward` (page)
	`reorder_last` (page)
	`reorder_page` (page, position)
	`select_next_page` ()
	`select_previous_page` ()
	`set_default_icon` (default_icon)
	`set_menu_model` (menu_model)
	`set_page_pinned` (page, pinned)
	`set_selected_page` (selected_page)
	`set_shortcut_widget` (widget)
	`transfer_page` (page, other_view, position)

Virtual Methods¶

Inherited:: Gtk.Container (10), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10)

Properties¶

Inherited:: Gtk.Container (3), Gtk.Widget (39)

Name	Type	Flags	Short Description
`default-icon`	`Gio.Icon`	r/w/en	Default page icon
`is-transferring-page`	`bool`	r/en	Whether a page is being transferred
`menu-model`	`Gio.MenuModel`	r/w/en	Tab context menu model
`n-pages`	`int`	r/en	The number of pages in the tab view
`n-pinned-pages`	`int`	r/en	The number of pinned pages in the tab view
`selected-page`	`Handy.TabPage`	r/w/en	The currently selected page
`shortcut-widget`	`Gtk.Widget`	r/w/en	Tab shortcut widget

Style Properties¶

Inherited:: Gtk.Widget (17)

Signals¶

Inherited:: Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Short Description
`close-page`	Emitted after [method`TabView`.close_page] has been called for page.
`create-window`	Emitted when a tab should be transferred into a new window.
`indicator-activated`	Emitted after the indicator icon on page has been activated.
`page-attached`	Emitted when a page has been created or transferred to the view.
`page-detached`	Emitted when a page has been removed or transferred to another view.
`page-reordered`	This signal is emitted after page has been reordered to position.
`setup-menu`	Emitted when a context menu is opened or closed for page.

Fields¶

Inherited:: Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Class Details¶

class Handy.TabView(**kwargs)¶

Bases:: Gtk.Bin
Abstract:: No
Structure:: Handy.TabViewClass

A dynamic tabbed container.

HdyTabView 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 bar and relies on external widgets for that, such as [class`TabBar`].

HdyTabView maintains a [class`TabPage`] object for each page,which holds additional per-page properties. You can obtain the [class`TabPage`] for a page with [method`TabView`.get_page], and as return value for [method`TabView`.append] and other functions for adding children.

HdyTabView 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 [class`Gtk`.Notebook] for use cases such as tabbed dialogs.

As such, it does not support disabling page reordering or detaching, or adding children via [iface`Gtk`.Buildable].

CSS nodes

HdyTabView has a main CSS node with the name tabview.

It contains the subnode overlay, which contains subnodes stack and widget. The stack subnode contains the added pages.

`` tabview ╰── overlay

├── stack │ ╰── [ Children ] ╰── widget

``

New in version 1.2.

classmethod new()¶

Returns:: the newly created HdyTabView
Return type:: Handy.TabView

Creates a new HdyTabView.

New in version 1.2.

add_page(child, parent)¶

Parameters:

child (Gtk.Widget) – a widget to add
parent (Handy.TabPage or None) – a parent page for child

Returns:

the page object representing child

Return type:

Handy.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 [method`TabView`.close_page].

If parent is NULL, this function is equivalent to [method`TabView`.append].

New in version 1.2.

append(child)¶

Parameters:: child (Gtk.Widget) – a widget to add
Returns:: the page object representing child
Return type:: Handy.TabPage

Inserts child as the last non-pinned page.

New in version 1.2.

append_pinned(child)¶

Parameters:: child (Gtk.Widget) – a widget to add
Returns:: the page object representing child
Return type:: Handy.TabPage

Inserts child as the last pinned page.

New in version 1.2.

close_other_pages(page)¶

Parameters:: page (Handy.TabPage) – a page of self

Requests to close all pages other than page.

New in version 1.2.

close_page(page)¶

Parameters:: page (Handy.TabPage) – a page of self

Requests to close page.

Calling this function will result in [signal`TabView`:py:func:::close-page<Handy.TabView.signals.close_page>] signal being emitted for page. Closing the page can then be confirmed or denied via [method`TabView`.close_page_finish].

If the page is waiting for a [method`TabView`.close_page_finish] call, this function will do nothing.

The default handler for [signal`TabView`:py:func:::close-page<Handy.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 [property`TabPage`:py:data::parent<Handy.TabView.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.

New in version 1.2.

close_page_finish(page, confirm)¶

Parameters:

page (Handy.TabPage) – a page of self
confirm (bool) – whether to confirm or deny closing page

Completes a [method`TabView`.close_page] call for page.

If confirm is TRUE, page will be closed. If it’s FALSE, ite will be reverted to its previous state and [method`TabView`.close_page] can be called for it again.

This function should not be called unless a custom handler for [signal`TabView`:py:func:::close-page<Handy.TabView.signals.close_page>] is used.

New in version 1.2.

close_pages_after(page)¶

Parameters:: page (Handy.TabPage) – a page of self

Requests to close all pages after page.

New in version 1.2.

close_pages_before(page)¶

Parameters:: page (Handy.TabPage) – a page of self

Requests to close all pages before page.

New in version 1.2.

get_default_icon()¶

Returns:: the default icon of self
Return type:: Gio.Icon

Gets default icon of self.

New in version 1.2.

get_is_transferring_page()¶

Returns:: whether a page is being transferred
Return type:: bool

Whether a page is being transferred.

Gets the value of [property`TabView`:py:data::is-transferring-page<Handy.TabView.props.is_transferring_page>] property.

New in version 1.2.

get_menu_model()¶

Returns:: the tab context menu model for self
Return type:: Gio.MenuModel or None

Gets the tab context menu model for self.

New in version 1.2.

get_n_pages()¶

Returns:: the number of pages in self
Return type:: int

Gets the number of pages in self.

New in version 1.2.

get_n_pinned_pages()¶

Returns:: the number of pinned pages in self
Return type:: int

Gets the number of pinned pages in self.

See [method`TabView`.set_page_pinned].

New in version 1.2.

get_nth_page(position)¶

Parameters:: position (int) – the index of the page in self, starting from 0
Returns:: the page object at position
Return type:: Handy.TabPage

Gets the [class`TabPage`] representing the child at position.

New in version 1.2.

get_page(child)¶

Parameters:: child (Gtk.Widget) – a child in self
Returns:: the [class`TabPage`] representing child
Return type:: Handy.TabPage

Gets the [class`TabPage`] object representing child.

New in version 1.2.

get_page_position(page)¶

Parameters:: page (Handy.TabPage) – a page of self
Returns:: the position of page in self
Return type:: int

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

New in version 1.2.

get_pages()¶

Returns:: the model containing pages of self
Return type:: Gio.ListModel

Returns a [iface`Gio`.ListModel] containing the pages of self.

This model can be used to keep an up to date view of the pages.

New in version 1.2.

get_selected_page()¶

Returns:: the selected page in self
Return type:: Handy.TabPage or None

Gets the currently selected page in self.

New in version 1.2.

get_shortcut_widget()¶

Returns:: the shortcut widget for self
Return type:: Gtk.Widget or None

Gets the shortcut widget for self.

New in version 1.2.

insert(child, position)¶

Parameters:

child (Gtk.Widget) – a widget to add
position (int) – the position to add child at, starting from 0

Returns:

the page object representing child

Return type:

Handy.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 [method`TabView`.insert_pinned] should be used instead.

New in version 1.2.

insert_pinned(child, position)¶

Parameters:

child (Gtk.Widget) – a widget to add
position (int) – the position to add child at, starting from 0

Returns:

the page object representing child

Return type:

Handy.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 [method`TabView`.insert] should be used instead.

New in version 1.2.

prepend(child)¶

Parameters:: child (Gtk.Widget) – a widget to add
Returns:: the page object representing child
Return type:: Handy.TabPage

Inserts child as the first non-pinned page.

New in version 1.2.

prepend_pinned(child)¶

Parameters:: child (Gtk.Widget) – a widget to add
Returns:: the page object representing child
Return type:: Handy.TabPage

Inserts child as the first pinned page.

New in version 1.2.

reorder_backward(page)¶

Parameters:: page (Handy.TabPage) – a page of self
Returns:: whether page was moved
Return type:: bool

Reorders page to before its previous page if possible.

New in version 1.2.

reorder_first(page)¶

Parameters:: page (Handy.TabPage) – a page of self
Returns:: whether page was moved
Return type:: bool

Reorders page to the first possible position.

New in version 1.2.

reorder_forward(page)¶

Parameters:: page (Handy.TabPage) – a page of self
Returns:: whether page was moved
Return type:: bool

Reorders page to after its next page if possible.

New in version 1.2.

reorder_last(page)¶

Parameters:: page (Handy.TabPage) – a page of self
Returns:: whether page was moved
Return type:: bool

Reorders page to the last possible position.

New in version 1.2.

reorder_page(page, position)¶

Parameters:

page (Handy.TabPage) – a page of self
position (int) – the position to insert the page at, starting at 0

Returns:

whether page was moved

Return type:

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.

New in version 1.2.

select_next_page()¶

Returns:: whether the selected page was changed
Return type:: bool

Selects the page after the currently selected page.

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

New in version 1.2.

select_previous_page()¶

Returns:: whether the selected page was changed
Return type:: bool

Selects the page before the currently selected page.

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

New in version 1.2.

set_default_icon(default_icon)¶

Parameters:: default_icon (Gio.Icon) – the default icon

Sets default page icon for self.

If a page doesn’t provide its own icon via [property`TabPage`:py:data::icon<Handy.TabView.props.icon>], default icon may be used instead for contexts where having an icon is necessary.

[class`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.

By default, hdy-tab-icon-missing-symbolic icon is used.

New in version 1.2.

set_menu_model(menu_model)¶

Parameters:: menu_model (Gio.MenuModel or None) – a menu model

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 [signal`TabView`:py:func:::setup-menu<Handy.TabView.signals.setup_menu>] signal to set up the menu actions for the particular tab.

New in version 1.2.

set_page_pinned(page, pinned)¶

Parameters:

page (Handy.TabPage) – a page of self
pinned (bool) – whether page should be pinned

Pins or unpins page.

Pinned pages are guaranteed to be placed before all non-pinned pages; at any given moment the first [property`TabView`:py:data::n-pinned-pages<Handy.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.

[class`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:

[property`TabPage`:py:data::indicator-icon<Handy.TabView.props.indicator_icon>]

A spinner if [property`TabPage`:py:data::loading<Handy.TabView.props.loading>] is TRUE

[property`TabPage`:py:data::icon<Handy.TabView.props.icon>]

[property`TabView`:py:data::default-icon<Handy.TabView.props.default_icon>]

Pinned pages cannot be closed by default, see [signal`TabView`:py:func:::close-page<Handy.TabView.signals.close_page>] for how to override that behavior.

New in version 1.2.

set_selected_page(selected_page)¶

Parameters:: selected_page (Handy.TabPage) – a page in self

Sets the currently selected page in self.

New in version 1.2.

set_shortcut_widget(widget)¶

Parameters:: widget (Gtk.Widget or None) – a shortcut widget

Sets the shortcut widget for self.

New in version 1.2.

transfer_page(page, other_view, position)¶

Parameters:

page (Handy.TabPage) – a page of self
other_view (Handy.TabView) – the tab view to transfer the page to
position (int) – the position to insert the page at, starting at 0

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.

New in version 1.2.

Signal Details¶

Handy.TabView.signals.close_page(tab_view, page)¶

Signal Name:

close-page

Flags:

RUN_LAST

Parameters:

tab_view (Handy.TabView) – The object which received the signal
page (Handy.TabPage) – a page of the view

Return type:

bool

Emitted after [method`TabView`.close_page] has been called for page.

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

```c static bool close_page_cb (Handy.TabView *view, Handy.TabPage *page, object user_data) { Handy.TabView.close_page_finish (view, page, !:obj:Handy.TabPage.get_pinned (page));

return Gdk.EVENT_STOP; } ```

The [method`TabView`.close_page_finish] doesn’t have to happen during 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.

New in version 1.2.

Handy.TabView.signals.create_window(tab_view)¶

Signal Name:: create-window
Flags:: RUN_LAST
Parameters:: tab_view (Handy.TabView) – The object which received the signal
Returns:: the [class`TabView`] from the new window
Return type:: Handy.TabView or 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 ``HdyTabView``that the page will be transferred into.

New in version 1.2.

Handy.TabView.signals.indicator_activated(tab_view, page)¶

Signal Name:

indicator-activated

Flags:

RUN_LAST

Parameters:

tab_view (Handy.TabView) – The object which received the signal
page (Handy.TabPage) – a page of the view

Emitted after the indicator icon on page has been activated.

See [property`TabPage`:py:data::indicator-icon<Handy.TabView.props.indicator_icon>] and [property`TabPage`:py:data::indicator-activatable<Handy.TabView.props.indicator_activatable>].

New in version 1.2.

Handy.TabView.signals.page_attached(tab_view, page, position)¶

Signal Name:

page-attached

Flags:

RUN_LAST

Parameters:

tab_view (Handy.TabView) – The object which received the signal
page (Handy.TabPage) – a page of the view
position (int) – the position of the page, starting from 0

Emitted when a page has been created or transferred to the view.

A typical reason to connect to this signal would be to connect to page signals for things such as updating window title.

New in version 1.2.

Handy.TabView.signals.page_detached(tab_view, page, position)¶

Signal Name:

page-detached

Flags:

RUN_LAST

Parameters:

tab_view (Handy.TabView) – The object which received the signal
page (Handy.TabPage) – a page of the view
position (int) – the position of the removed page, starting from 0

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 [signal`TabView`:py:func:::page-attached<Handy.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 [method`TabView`.close_page_finish] calls.

New in version 1.2.

Handy.TabView.signals.page_reordered(tab_view, page, position)¶

Signal Name:

page-reordered

Flags:

RUN_LAST

Parameters:

tab_view (Handy.TabView) – The object which received the signal
page (Handy.TabPage) – a page of the view
position (int) – the position page was moved to, starting at 0

This signal is emitted after page has been reordered to position.

New in version 1.2.

Handy.TabView.signals.setup_menu(tab_view, page)¶

Signal Name:

setup-menu

Flags:

RUN_LAST

Parameters:

tab_view (Handy.TabView) – The object which received the signal
page (Handy.TabPage) – a page of self

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.

New in version 1.2.

Property Details¶

Handy.TabView.props.default_icon¶

Name:: default-icon
Type:: Gio.Icon
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Default page icon.

If a page doesn’t provide its own icon via [property`TabPage`:py:data::icon<Handy.TabView.props.icon>], default icon may be used instead for contexts where having an icon is necessary.

[class`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.

New in version 1.2.

Handy.TabView.props.is_transferring_page¶

Name:: is-transferring-page
Type:: bool
Default Value:: False
Flags:: READABLE, EXPLICIT_NOTIFY

Whether a page is being transferred.

This property will be set to TRUE when a drag-n-drop tab transfer starts on any [class`TabView`], 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.

New in version 1.2.

Handy.TabView.props.menu_model¶

Name:: menu-model
Type:: Gio.MenuModel
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Tab context menu model.

When a context menu is shown for a tab, it will be constructed from the provided menu model. Use [signal`TabView`:py:func:::setup-menu<Handy.TabView.signals.setup_menu>] signal to set up the menu actions for the particular tab.

New in version 1.2.

Handy.TabView.props.n_pages¶

Name:: n-pages
Type:: int
Default Value:: 0
Flags:: READABLE, EXPLICIT_NOTIFY

The number of pages in the tab view.

New in version 1.2.

Handy.TabView.props.n_pinned_pages¶

Name:: n-pinned-pages
Type:: int
Default Value:: 0
Flags:: READABLE, EXPLICIT_NOTIFY

The number of pinned pages in the tab view.

See [method`TabView`.set_page_pinned].

New in version 1.2.

Handy.TabView.props.selected_page¶

Name:: selected-page
Type:: Handy.TabPage
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The currently selected page.

New in version 1.2.

Handy.TabView.props.shortcut_widget¶

Name:: shortcut-widget
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Tab shortcut widget.

Has the following shortcuts:

<kbd>Ctrl</kbd>+<kbd>Page Up</kbd> - switch to the previous page
<kbd>Ctrl</kbd>+<kbd>Page Down</kbd> - switch to the next page
<kbd>Ctrl</kbd>+<kbd>Home</kbd> - switch to the first page
<kbd>Ctrl</kbd>+<kbd>End</kbd> - switch to the last page
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Up</kbd> - move the current page backward
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Down</kbd> - move the current page forward
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Home</kbd> - move the current page at the start
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>End</kbd> - move the current page at the end
<kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the next page, with looping
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd> - switch to the previous page, with looping
<kbd>Alt</kbd>+<kbd>1</kbd>⋯<kbd>9</kbd> - switch to pages 1-9
<kbd>Alt</kbd>+<kbd>0</kbd> - switch to page 10

These shortcuts are always available on self, this property is useful if they should be available globally.

New in version 1.2.