Class notebook - cl-cffi-gtk4 API documentation

Package: gtk

Class gtk:notebook

Superclasses

gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

The enable-popup property of type :boolean (Read / Write)
If true, pressing the right mouse button on the notebook pops up a menu that you can use to go to a page.
Default value: false

group-name

The group-name property of type :string (Read / Write)
The group name for drag and drop operations of the notebook tab.
Default value: nil

page

The page property of type :int (Read / Write)
The index of the current page.
Allowed values: >= -1
Default value: -1

pages

The pages property of type g:list-model (Read)
The pages of the notebook.

scrollable

The scrollable property of type :boolean (Read / Write)
If true, scroll arrows are added if there are too many notebook tabs to fit.
Default value: false

show-border

The show-border property of type :boolean (Read / Write)
Whether the border should be shown.
Default value: true

show-tabs

The show-tabs property of type :boolean (Read / Write)
Whether tabs should be shown.
Default value: true

tab-pos

The tab-pos property of type gtk:position-type (Read / Write)
Which side of the notebook holds the notebook tabs.
Default value: :top

Details

The gtk:notebook widget is a layout container whose children are pages that can be switched between using notebook tab labels along one edge.

Figure: GtkNotebook

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

GtkNotebook as GtkBuildable

The gtk:notebook implementation of the gtk:buildable interface supports placing children into notebook tabs by specifying "tab" as the "type" attribute of a <child> element. Note that the content of the notebook tab must be created before the notebook tab can be filled. A notebook 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.

Example: A UI definition fragment with the gtk:notebook widget

<object class="GtkNotebook">
  <child>
    <object class="GtkLabel" id="notebook-content">
      <property name="label">Content</property>
    </object>
  </child>
  <child type="tab">
    <object class="GtkLabel" id="notebook-tab">
      <property name="label">Tab</property>
    </object>
  </child>
</object>

CSS nodes

notebook
├── header.top
│   ├── [<action widget>]
│   ├── tabs
│   │   ├── [arrow]
│   │   ├── tab
│   │   │   ╰── <tab label>
│   │   │
│   │   ├── tab[.reorderable-page]
│   │   │   ╰── <tab label>
│   │   ╰── [arrow]
│   ╰── [<action widget>]
│
╰── stack
    ├── <child>
    │
    ╰── <child>

The gtk:notebook implementation 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 notebook tab with name tab. If action widgets are present, their CSS nodes are placed next to the notebook tabs node. If the notebook is scrollable, CSS nodes with name arrow are placed as first and last child of the notebook tabs node. The main node gets the .frame style class when the notebook has a border, see the gtk:notebook-show-border function. The header node gets one of the .top, .bottom, .left or .right style classes, depending on where the notebook tabs are placed. For reorderable pages, the notebook tab node gets the .reorderable-page style class. A notebook 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

The gtk:notebook implementation uses the following roles:

The :group role for the notebook widget.
The :tab-list role for the list of notebook tabs.
The :tab role for each notebook tab.
The :tab-panel role for each page.

Signal Details

The "change-current-page" signal

lambda (notebook page)    :action

notebook: The gtk:notebook widget emitting the signal.
page: The integer with the page index.
Returns: Whether the page was changed.

Emitted when the current page should be changed. The default bindings for this signal are the Ctrl+Alt+PgUp, Ctrl+Alt+PgDn, Ctrl+PgUp and Ctrl+PgDn keys.

The "create-window" signal

lambda (notebook page)    :run-last

notebook: The gtk:notebook widget emitting the signal.
page: The gtk:widget object for the notebook tab of notebook that is being detached.
Returns: The gtk:notebook widget that page should be added to, or nil.

The signal is emitted when a detachable notebook tab is dropped on the root window. A handler for this signal can create a window containing a notebook where the notebook tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook, for example, the group-name property.

The "focus-tab" signal

lambda (notebook tab)    :action

notebook: The gtk:notebook widget emitting the signal.
tab: The value of the gtk:notebook-tab enumeration.
Returns: Whether the notebook tab has been focused.

Emitted when a tab should be focused.

The "move-focus-out" signal

lambda (notebook direction)    :action

notebook: The gtk:notebook widget emitting the signal.
direction: The gtk:direction-type value with the direction to move the focus.

Emitted when focus was moved out. The default bindings for this signal are the Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+←, Ctrl+→, Ctrl+↑ and Ctrl+↓.

The "page-added" signal

lambda (notebook child num)    :run-last

notebook: The gtk:notebook widget emitting the signal.
child: The gtk:widget child page affected.
num: The unsigned integer with the child page number.

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

The "page-removed" signal

lambda (notebook child num)   :run-last

notebook: The gtk:notebook widget emitting the signal.
child: The gtk:widget child page affected.
num: The unsigned integer with the child page number.

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

The "page-reordered" signal

lambda (notebook child num)    :run-last

notebook: The gtk:notebook widget emitting the signal.
child: The gtk:widget child page affected.
num: The unsigned integer with the child page number.

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

The "reorder-tab" signal

lambda (notebook direction move-to-last)   :action

notebook: The gtk:notebook widget emitting the signal.
direction: The value of the gtk:direction-type enumeration.
move-to-last: Whether to move to the last position.
Returns: Whether the notebook tab was moved.

Emitted when the notebook tab should be reordered. The default bindings for this signal are the Alt+Home, Alt+End, Alt+PgUp, Alt+PgDn, Alt+←, Alt+→, Alt+↑ and Alt+↓ keys.