Description

Gnome::Gtk4::Notebook is a container whose children are pages switched between using tabs.

There are many configuration options for Gnome::Gtk4::Notebook. Among other things, you can choose on which edge the tabs appear (see .set-tab-pos()), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see .set-scrollable()), and whether there will be a popup menu allowing the users to switch pages. (see .popup-enable()).

GtkNotebook as GtkBuildable

The Gnome::Gtk4::Notebook implementation of the Gnome::Gtk4::R-Buildable interface supports placing children into tabs by specifying “tab” as the “type” attribute of a `<child>` element. Note that the content of the tab must be created before the tab can be filled. A tab child can be specified without specifying a `<child>` type attribute.

To add a child widget in the notebooks action area, specify "action-start" or “action-end” as the “type” attribute of the `<child>` element.

An example of a UI definition fragment with Gnome::Gtk4::Notebook:

CSS nodes

Gnome::Gtk4::Notebook has a main CSS node with name notebook, a subnode with name header and below that a subnode with name tabs which contains one subnode per tab with name tab.

If action widgets are present, their CSS nodes are placed next to the tabs node. If the notebook is scrollable, CSS nodes with name arrow are placed as first and last child of the tabs node.

The main node gets the `.frame` style class when the notebook has a border (see .set-show-border()).

The header node gets one of the style class `.top`, `.bottom`, `.left` or `.right`, depending on where the tabs are placed. For reorderable pages, the tab node gets the `.reorderable-page` class.

A tab node gets the `.dnd` style class while it is moved with drag-and-drop.

The nodes are always arranged from left-to-right, regardless of text direction.

Accessibility

Gnome::Gtk4::Notebook uses the following roles:

• GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget

• GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs

• GTK_ACCESSIBLE_ROLE_TAB role for each tab

• GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-notebook

Creates a new Gnome::Gtk4::Notebook widget with no pages.

method new-notebook ( --> Gnome::Gtk4::Notebook \)

Methods

append-page

Appends a page to $notebook.

method append-page ( N-Object() $child, N-Object() $tab-label --> Int )

• $child; the Gnome::Gtk4::Widget to use as the contents of the page.

• $tab-label; the Gnome::Gtk4::Widget to be used as the label for the page, or undefined to use the default label, “page N”.

Return value; the index (starting from 0) of the appended page in the notebook, or -1 if function fails.

append-page-menu

Appends a page to $notebook, specifying the widget to use as the label in the popup menu.

method append-page-menu ( N-Object() $child, N-Object() $tab-label, N-Object() $menu-label --> Int )

• $child; the Gnome::Gtk4::Widget to use as the contents of the page.

• $tab-label; the Gnome::Gtk4::Widget to be used as the label for the page, or undefined to use the default label, “page N”.

• $menu-label; the widget to use as a label for the page-switch menu, if that is enabled. If undefined, and $tab-label is a Gnome::Gtk4::Label or undefined, then the menu label will be a newly created label with the same text as $tab-label; if $tab-label is not a Gnome::Gtk4::Label, $menu-label must be specified if the page-switch menu is to be used..

Return value; the index (starting from 0) of the appended page in the notebook, or -1 if function fails.

detach-tab

Removes the child from the notebook.

This function is very similar to .remove-page(), but additionally informs the notebook that the removal is happening as part of a tab DND operation, which should not be cancelled.

method detach-tab ( N-Object() $child )

• $child; a child.

get-action-widget

Gets one of the action widgets.

See .set-action-widget().

method get-action-widget ( GtkPackType $pack-type --> N-Object )

• $pack-type; pack type of the action widget to receive.

Return value; The action widget with the given $pack-type or undefined when this action widget has not been set.

get-current-page

Returns the page number of the current page.

method get-current-page (--> Int )

Return value; the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned..

get-group-name

Gets the current group name for $notebook.

method get-group-name (--> Str )

Return value; the group name, or undefined if none is set.

get-menu-label

Retrieves the menu label widget of the page containing $child.

method get-menu-label ( N-Object() $child --> N-Object )

• $child; a widget contained in a page of $notebook.

Return value; the menu label, or undefined if the notebook page does not have a menu label other than the default (the tab label)..

get-menu-label-text

Retrieves the text of the menu label for the page containing $child.

method get-menu-label-text ( N-Object() $child --> Str )

• $child; the child widget of a page of the notebook..

Return value; the text of the tab label, or undefined if the widget does not have a menu label other than the default menu label, or the menu label widget is not a Gnome::Gtk4::Label. The string is owned by the widget and must not be freed..

get-n-pages

Gets the number of pages in a notebook.

method get-n-pages (--> Int )

Return value; the number of pages in the notebook.

get-nth-page

Returns the child widget contained in page number $page-num.

method get-nth-page ( Int() $page-num --> N-Object )

• $page-num; the index of a page in the notebook, or -1 to get the last page.

Return value; the child widget, or undefined if $page-num is out of bounds.

get-page

Returns the Gnome::Gtk4::NotebookPage for $child.

method get-page ( N-Object() $child --> N-Object )

• $child; a child of $notebook.

Return value; the Gnome::Gtk4::NotebookPage for $child.

get-pages

Returns a Gnome::Gio::R-ListModel that contains the pages of the notebook.

This can be used to keep an up-to-date view. The model also implements Gnome::Gtk4::R-SelectionModel and can be used to track and modify the visible page.

method get-pages (--> N-List )

Return value; a Gnome::Gio::R-ListModel for the notebook's children.

get-scrollable

Returns whether the tab label area has arrows for scrolling.

method get-scrollable (--> Bool )

Return value; True if arrows for scrolling are present.

get-show-border

Returns whether a bevel will be drawn around the notebook pages.

method get-show-border (--> Bool )

Return value; True if the bevel is drawn.

get-show-tabs

Returns whether the tabs of the notebook are shown.

method get-show-tabs (--> Bool )

Return value; True if the tabs are shown.

get-tab-detachable

Returns whether the tab contents can be detached from $notebook.

method get-tab-detachable ( N-Object() $child --> Bool )

• $child; a child Gnome::Gtk4::Widget.

Return value; True if the tab is detachable..

get-tab-label

Returns the tab label widget for the page $child.

undefined is returned if $child is not in $notebook or if no tab label has specifically been set for $child.

method get-tab-label ( N-Object() $child --> N-Object )

• $child; the page.

Return value; the tab label.

get-tab-label-text

Retrieves the text of the tab label for the page containing $child.

method get-tab-label-text ( N-Object() $child --> Str )

• $child; a widget contained in a page of $notebook.

Return value; the text of the tab label, or undefined if the tab label widget is not a Gnome::Gtk4::Label. The string is owned by the widget and must not be freed..

get-tab-pos

Gets the edge at which the tabs are drawn.

method get-tab-pos (--> GtkPositionType )

Return value; the edge at which the tabs are drawn.

get-tab-reorderable

Gets whether the tab can be reordered via drag and drop or not.

method get-tab-reorderable ( N-Object() $child --> Bool )

• $child; a child Gnome::Gtk4::Widget.

Return value; True if the tab is reorderable..

insert-page

Insert a page into $notebook at the given position.

method insert-page ( N-Object() $child, N-Object() $tab-label, Int() $position --> Int )

• $child; the Gnome::Gtk4::Widget to use as the contents of the page.

• $tab-label; the Gnome::Gtk4::Widget to be used as the label for the page, or undefined to use the default label, “page N”.

• $position; the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages.

Return value; the index (starting from 0) of the inserted page in the notebook, or -1 if function fails.

insert-page-menu

Insert a page into $notebook at the given position, specifying the widget to use as the label in the popup menu.

method insert-page-menu ( N-Object() $child, N-Object() $tab-label, N-Object() $menu-label, Int() $position --> Int )

• $child; the Gnome::Gtk4::Widget to use as the contents of the page.

• $tab-label; the Gnome::Gtk4::Widget to be used as the label for the page, or undefined to use the default label, “page N”.

• $menu-label; the widget to use as a label for the page-switch menu, if that is enabled. If undefined, and $tab-label is a Gnome::Gtk4::Label or undefined, then the menu label will be a newly created label with the same text as $tab-label; if $tab-label is not a Gnome::Gtk4::Label, $menu-label must be specified if the page-switch menu is to be used..

• $position; the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages..

Return value; the index (starting from 0) of the inserted page in the notebook.

next-page

Switches to the next page.

Nothing happens if the current page is the last page.

method next-page ( )

page-num

Finds the index of the page which contains the given child widget.

method page-num ( N-Object() $child --> Int )

• $child; a Gnome::Gtk4::Widget.

Return value; the index of the page containing $child, or -1 if $child is not in the notebook.

popup-disable

Disables the popup menu.

method popup-disable ( )

popup-enable

Enables the popup menu.

If the user clicks with the right mouse button on the tab labels, a menu with all the pages will be popped up.

method popup-enable ( )

prepend-page

Prepends a page to $notebook.

method prepend-page ( N-Object() $child, N-Object() $tab-label --> Int )

• $child; the Gnome::Gtk4::Widget to use as the contents of the page.

• $tab-label; the Gnome::Gtk4::Widget to be used as the label for the page, or undefined to use the default label, “page N”.

Return value; the index (starting from 0) of the prepended page in the notebook, or -1 if function fails.

prepend-page-menu

Prepends a page to $notebook, specifying the widget to use as the label in the popup menu.

method prepend-page-menu ( N-Object() $child, N-Object() $tab-label, N-Object() $menu-label --> Int )

• $child; the Gnome::Gtk4::Widget to use as the contents of the page.

• $tab-label; the Gnome::Gtk4::Widget to be used as the label for the page, or undefined to use the default label, “page N”.

• $menu-label; the widget to use as a label for the page-switch menu, if that is enabled. If undefined, and $tab-label is a Gnome::Gtk4::Label or undefined, then the menu label will be a newly created label with the same text as $tab-label; if $tab-label is not a Gnome::Gtk4::Label, $menu-label must be specified if the page-switch menu is to be used..

Return value; the index (starting from 0) of the prepended page in the notebook, or -1 if function fails.

prev-page

Switches to the previous page.

Nothing happens if the current page is the first page.

method prev-page ( )

remove-page

Removes a page from the notebook given its index in the notebook.

method remove-page ( Int() $page-num )

• $page-num; the index of a notebook page, starting from 0. If -1, the last page will be removed..

reorder-child

Reorders the page containing $child, so that it appears in position $position.

If $position is greater than or equal to the number of children in the list or negative, $child will be moved to the end of the list.

method reorder-child ( N-Object() $child, Int() $position )

• $child; the child to move.

• $position; the new position, or -1 to move to the end.

set-action-widget

Sets $widget as one of the action widgets.

Depending on the pack type the widget will be placed before or after the tabs. You can use a Gnome::Gtk4::Box if you need to pack more than one widget on the same side.

method set-action-widget ( N-Object() $widget, GtkPackType $pack-type )

• $widget; a Gnome::Gtk4::Widget.

• $pack-type; pack type of the action widget.

set-current-page

Switches to the page number $page-num.

Note that due to historical reasons, GtkNotebook refuses to switch to a page unless the child widget is visible. Therefore, it is recommended to show child widgets before adding them to a notebook.

method set-current-page ( Int() $page-num )

• $page-num; index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the notebook, nothing will be done..

set-group-name

Sets a group name for $notebook.

Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a undefined group name will not be able to exchange tabs with any other notebook.

method set-group-name ( Str $group-name )

• $group-name; the name of the notebook group, or undefined to unset it.

set-menu-label

Changes the menu label for the page containing $child.

method set-menu-label ( N-Object() $child, N-Object() $menu-label )

• $child; the child widget.

• $menu-label; the menu label, or undefined for default.

set-menu-label-text

Creates a new label and sets it as the menu label of $child.

method set-menu-label-text ( N-Object() $child, Str $menu-text )

• $child; the child widget.

• $menu-text; the label text.

set-scrollable

Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area.

method set-scrollable ( Bool() $scrollable )

• $scrollable; True if scroll arrows should be added.

set-show-border

Sets whether a bevel will be drawn around the notebook pages.

This only has a visual effect when the tabs are not shown.

method set-show-border ( Bool() $show-border )

• $show-border; True if a bevel should be drawn around the notebook.

set-show-tabs

Sets whether to show the tabs for the notebook or not.

method set-show-tabs ( Bool() $show-tabs )

• $show-tabs; True if the tabs should be shown.

set-tab-detachable

Sets whether the tab can be detached from $notebook to another notebook or widget.

Note that two notebooks must share a common group identifier (see .set-group-name()) to allow automatic tabs interchange between them.

If you want a widget to interact with a notebook through DnD (i.e.: accept dragged tabs from it) it must be set as a drop destination by adding to it a Gnome::Gtk4::DropTarget controller that accepts the GType GTK_TYPE_NOTEBOOK_PAGE. The `:value` of said drop target will be preloaded with a Gnome::Gtk4::NotebookPage object that corresponds to the dropped tab, so you can process the value via `::accept` or `::drop` signals.

Note that you should use .detach-tab() instead of .remove-page() if you want to remove the tab from the source notebook as part of accepting a drop. Otherwise, the source notebook will think that the dragged tab was removed from underneath the ongoing drag operation, and will initiate a drag cancel animation.

If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do it.

method set-tab-detachable ( N-Object() $child, Bool() $detachable )

• $child; a child Gnome::Gtk4::Widget.

• $detachable; whether the tab is detachable or not.

set-tab-label

Changes the tab label for $child.

If undefined is specified for $tab-label, then the page will have the label “page N”.

method set-tab-label ( N-Object() $child, N-Object() $tab-label )

• $child; the page.

• $tab-label; the tab label widget to use, or undefined for default tab label.

set-tab-label-text

Creates a new label and sets it as the tab label for the page containing $child.

method set-tab-label-text ( N-Object() $child, Str $tab-text )

• $child; the page.

• $tab-text; the label text.

set-tab-pos

Sets the edge at which the tabs are drawn.

method set-tab-pos ( GtkPositionType $pos )

• $pos; the edge to draw the tabs at.

set-tab-reorderable

Sets whether the notebook tab can be reordered via drag and drop or not.

method set-tab-reorderable ( N-Object() $child, Bool() $reorderable )

• $child; a child Gnome::Gtk4::Widget.

• $reorderable; whether the tab is reorderable or not.

Signals

change-current-page

method handler (
  gint $object,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
  --> gboolean
)

• $object; .

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value;

create-window

The create-window signal is emitted when a detachable tab is dropped on the root window.

A handler for this signal can create a window containing a notebook where the tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook (e.g. the Gnome::Gtk4::Notebook:group-name ).

method handler (
  N-Object $page,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
  --> N-Object
)

• $page; the tab of $notebook that is being detached.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value; a Gnome::Gtk4::Notebook that $page should be added to

focus-tab

method handler (
   $object,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
  --> gboolean
)

• $object; .

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value;

move-focus-out

method handler (
   $object,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
)

• $object; .

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

page-added

the page-added signal is emitted in the notebook right after a page is added to the notebook.

method handler (
  N-Object $child,
  guint $page-num,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
)

• $child; the child Gnome::Gtk4::Widget affected.

• $page-num; the new page number for $child.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

page-removed

the page-removed signal is emitted in the notebook right after a page is removed from the notebook.

method handler (
  N-Object $child,
  guint $page-num,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
)

• $child; the child Gnome::Gtk4::Widget affected.

• $page-num; the $child page number.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

page-reordered

the page-reordered signal is emitted in the notebook right after a page has been reordered.

method handler (
  N-Object $child,
  guint $page-num,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
)

• $child; the child Gnome::Gtk4::Widget affected.

• $page-num; the new page number for $child.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

reorder-tab

method handler (
   $object,
  gboolean $p0,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
  --> gboolean
)

• $object; .

• $p0; .

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value;

select-page

method handler (
  gboolean $object,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
  --> gboolean
)

• $object; .

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value;

switch-page

Emitted when the user or a function changes the current page.

method handler (
  N-Object $page,
  guint $page-num,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Notebook :$_widget,
  *C<user>-options
)

• $page; the new current page.

• $page-num; the index of the page.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Notebook object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.