Class Notebook

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.Notebook
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class Notebook extends Widget implements Accessible, Buildable, ConstraintTarget

Switches between children using tabs.

An example GtkNotebook

There are many configuration options for GtkNotebook. Among other things, you can choose on which edge the tabs appear (see setTabPos(PositionType)), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see setScrollable(boolean)), and whether there will be a popup menu allowing the users to switch pages. (see popupEnable()).

GtkNotebook as GtkBuildable

The GtkNotebook implementation of the GtkBuildable 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 GtkNotebook:

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

Shortcuts and Gestures

GtkNotebook supports the following keyboard shortcuts:

  • Shift+F10 or Menu opens the context menu.
  • Home moves the focus to the first tab.
  • End moves the focus to the last tab.

Additionally, the following signals have default keybindings:

  • Gtk.Notebook::change-current-page
  • Gtk.Notebook::focus-tab
  • Gtk.Notebook::move-focus-out
  • Gtk.Notebook::reorder-tab
  • Gtk.Notebook::select-page

Tabs support drag-and-drop between notebooks sharing the same group-name, or to new windows by handling the ::create-window signal.

Actions

GtkNotebook defines a set of built-in actions:

  • menu.popup opens the tabs context menu.

CSS nodes

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

GtkNotebook 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 setShowBorder(boolean)).

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

GtkNotebook uses the following roles:

  • Gtk.AccessibleRole.group for the notebook widget
  • Gtk.AccessibleRole.tab_list for the list of tabs
  • Gtk.AccessibleRole.tab role for each tab
  • Gtk.AccessibleRole.tab_panel for each page

  • Constructor Details

    • Notebook

      public Notebook(MemorySegment address)
      Create a Notebook instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Notebook

      public Notebook()
      Create a new Notebook.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Notebook class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Notebook asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • appendPage

      public int appendPage(Widget child, @Nullable Widget tabLabel)
      Appends a page to notebook.
      Parameters:
      child - the GtkWidget to use as the contents of the page
      tabLabel - the GtkWidget to be used as the label for the page, or null to use the default label, “page N”
      Returns:
      the index (starting from 0) of the appended page in the notebook, or -1 if function fails

    • appendPageMenu

      public int appendPageMenu(Widget child, @Nullable Widget tabLabel, @Nullable Widget menuLabel)
      Appends a page to notebook, specifying the widget to use as the label in the popup menu.
      Parameters:
      child - the GtkWidget to use as the contents of the page
      tabLabel - the GtkWidget to be used as the label for the page, or null to use the default label, “page N”
      menuLabel - the widget to use as a label for the page-switch menu, if that is enabled. If null, and tabLabel is a GtkLabel or null, then the menu label will be a newly created label with the same text as tabLabel; if tabLabel is not a GtkLabel, menuLabel must be specified if the page-switch menu is to be used.
      Returns:
      the index (starting from 0) of the appended page in the notebook, or -1 if function fails

    • detachTab

      public void detachTab(Widget child)

      Removes the child from the notebook.

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

      Parameters:
      child - a child

    • getActionWidget

      public @Nullable Widget getActionWidget(PackType packType)

      Gets one of the action widgets.

      See setActionWidget(Widget, PackType).

      Parameters:
      packType - pack type of the action widget to receive
      Returns:
      The action widget with the given packType or null when this action widget has not been set

    • getCurrentPage

      public int getCurrentPage()
      Returns the page number of the current page.
      Returns:
      the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned.

    • getGroupName

      public @Nullable String getGroupName()
      Gets the current group name for notebook.
      Returns:
      the group name, or null if none is set

    • getMenuLabel

      public @Nullable Widget getMenuLabel(Widget child)
      Retrieves the menu label widget of the page containing child.
      Parameters:
      child - a widget contained in a page of this Notebook
      Returns:
      the menu label, or null if the notebook page does not have a menu label other than the default (the tab label).

    • getMenuLabelText

      public @Nullable String getMenuLabelText(Widget child)
      Retrieves the text of the menu label for the page containing child.
      Parameters:
      child - the child widget of a page of the notebook.
      Returns:
      the text of the tab label, or null if the widget does not have a menu label other than the default menu label, or the menu label widget is not a GtkLabel. The string is owned by the widget and must not be freed.

    • getNPages

      public int getNPages()
      Gets the number of pages in a notebook.
      Returns:
      the number of pages in the notebook

    • getNthPage

      public @Nullable Widget getNthPage(int pageNum)
      Returns the child widget contained in page number pageNum.
      Parameters:
      pageNum - the index of a page in the notebook, or -1 to get the last page
      Returns:
      the child widget, or null if pageNum is out of bounds

    • getPage

      public NotebookPage getPage(Widget child)
      Returns the GtkNotebookPage for child.
      Parameters:
      child - a child of this Notebook
      Returns:
      the GtkNotebookPage for child

    • getPages

      public ListModel getPages()

      Returns a GListModel that contains the pages of the notebook.

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

      Returns:
      a GListModel for the notebook's children

    • getScrollable

      public boolean getScrollable()
      Returns whether the tab label area has arrows for scrolling.
      Returns:
      true if arrows for scrolling are present

    • getShowBorder

      public boolean getShowBorder()
      Returns whether a bevel will be drawn around the notebook pages.
      Returns:
      true if the bevel is drawn

    • getShowTabs

      public boolean getShowTabs()
      Returns whether the tabs of the notebook are shown.
      Returns:
      true if the tabs are shown

    • getTabDetachable

      public boolean getTabDetachable(Widget child)
      Returns whether the tab contents can be detached from notebook.
      Parameters:
      child - a child GtkWidget
      Returns:
      true if the tab is detachable.

    • getTabLabel

      public @Nullable Widget getTabLabel(Widget child)

      Returns the tab label widget for the page child.

      null is returned if child is not in this Notebook or if no tab label has specifically been set for child.

      Parameters:
      child - the page
      Returns:
      the tab label

    • getTabLabelText

      public @Nullable String getTabLabelText(Widget child)
      Retrieves the text of the tab label for the page containing child.
      Parameters:
      child - a widget contained in a page of this Notebook
      Returns:
      the text of the tab label, or null if the tab label widget is not a GtkLabel. The string is owned by the widget and must not be freed.

    • getTabPos

      public PositionType getTabPos()
      Gets the edge at which the tabs are drawn.
      Returns:
      the edge at which the tabs are drawn

    • getTabReorderable

      public boolean getTabReorderable(Widget child)
      Gets whether the tab can be reordered via drag and drop or not.
      Parameters:
      child - a child GtkWidget
      Returns:
      true if the tab is reorderable.

    • insertPage

      public int insertPage(Widget child, @Nullable Widget tabLabel, int position)
      Insert a page into this Notebook at the given position.
      Parameters:
      child - the GtkWidget to use as the contents of the page
      tabLabel - the GtkWidget to be used as the label for the page, or null 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
      Returns:
      the index (starting from 0) of the inserted page in the notebook, or -1 if function fails

    • insertPageMenu

      public int insertPageMenu(Widget child, @Nullable Widget tabLabel, @Nullable Widget menuLabel, int position)
      Insert a page into this Notebook at the given position, specifying the widget to use as the label in the popup menu.
      Parameters:
      child - the GtkWidget to use as the contents of the page
      tabLabel - the GtkWidget to be used as the label for the page, or null to use the default label, “page N”
      menuLabel - the widget to use as a label for the page-switch menu, if that is enabled. If null, and tabLabel is a GtkLabel or null, then the menu label will be a newly created label with the same text as tabLabel; if tabLabel is not a GtkLabel, menuLabel 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.
      Returns:
      the index (starting from 0) of the inserted page in the notebook

    • nextPage

      public void nextPage()

      Switches to the next page.

      Nothing happens if the current page is the last page.

    • pageNum

      public int pageNum(Widget child)
      Finds the index of the page which contains the given child widget.
      Parameters:
      child - a GtkWidget
      Returns:
      the index of the page containing child, or -1 if child is not in the notebook

    • popupDisable

      public void popupDisable()
      Disables the popup menu.

    • popupEnable

      public void popupEnable()

      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.

    • prependPage

      public int prependPage(Widget child, @Nullable Widget tabLabel)
      Prepends a page to notebook.
      Parameters:
      child - the GtkWidget to use as the contents of the page
      tabLabel - the GtkWidget to be used as the label for the page, or null to use the default label, “page N”
      Returns:
      the index (starting from 0) of the prepended page in the notebook, or -1 if function fails

    • prependPageMenu

      public int prependPageMenu(Widget child, @Nullable Widget tabLabel, @Nullable Widget menuLabel)
      Prepends a page to notebook, specifying the widget to use as the label in the popup menu.
      Parameters:
      child - the GtkWidget to use as the contents of the page
      tabLabel - the GtkWidget to be used as the label for the page, or null to use the default label, “page N”
      menuLabel - the widget to use as a label for the page-switch menu, if that is enabled. If null, and tabLabel is a GtkLabel or null, then the menu label will be a newly created label with the same text as tabLabel; if tabLabel is not a GtkLabel, menuLabel must be specified if the page-switch menu is to be used.
      Returns:
      the index (starting from 0) of the prepended page in the notebook, or -1 if function fails

    • prevPage

      public void prevPage()

      Switches to the previous page.

      Nothing happens if the current page is the first page.

    • removePage

      public void removePage(int pageNum)
      Removes a page from the notebook given its index in the notebook.
      Parameters:
      pageNum - the index of a notebook page, starting from 0. If -1, the last page will be removed.

    • reorderChild

      public void reorderChild(Widget child, int position)

      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.

      Parameters:
      child - the child to move
      position - the new position, or -1 to move to the end

    • setActionWidget

      public void setActionWidget(Widget widget, PackType packType)

      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 GtkBox if you need to pack more than one widget on the same side.

      Parameters:
      widget - a GtkWidget
      packType - pack type of the action widget

    • setCurrentPage

      public void setCurrentPage(int pageNum)

      Switches to the page number pageNum.

      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.

      Parameters:
      pageNum - 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.

    • setGroupName

      public void setGroupName(@Nullable String groupName)

      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 null group name will not be able to exchange tabs with any other notebook.

      Parameters:
      groupName - the name of the notebook group, or null to unset it

    • setMenuLabel

      public void setMenuLabel(Widget child, @Nullable Widget menuLabel)
      Changes the menu label for the page containing child.
      Parameters:
      child - the child widget
      menuLabel - the menu label, or null for default

    • setMenuLabelText

      public void setMenuLabelText(Widget child, String menuText)
      Creates a new label and sets it as the menu label of child.
      Parameters:
      child - the child widget
      menuText - the label text

    • setScrollable

      public void setScrollable(boolean scrollable)
      Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area.
      Parameters:
      scrollable - true if scroll arrows should be added

    • setShowBorder

      public void setShowBorder(boolean showBorder)

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

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

      Parameters:
      showBorder - true if a bevel should be drawn around the notebook

    • setShowTabs

      public void setShowTabs(boolean showTabs)
      Sets whether to show the tabs for the notebook or not.
      Parameters:
      showTabs - true if the tabs should be shown

    • setTabDetachable

      public void setTabDetachable(Widget child, boolean detachable)

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

      Note that two notebooks must share a common group identifier (see setGroupName(String)) 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 DropTarget controller that accepts the GType GTK_TYPE_NOTEBOOK_PAGE. The :value of said drop target will be preloaded with a NotebookPage object that corresponds to the dropped tab, so you can process the value via ::accept or ::drop signals.

      Note that you should use detachTab(Widget) instead of removePage(int) 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.

      static void
on_drag_data_received (GtkWidget        *widget,
                       GdkDrop          *drop,
                       GtkSelectionData *data,
                       guint             time,
                       gpointer          user_data)
{
  GtkDrag *drag;
  GtkWidget *notebook;
  GtkWidget **child;

  drag = gtk_drop_get_drag (drop);
  notebook = g_object_get_data (drag, "gtk-notebook-drag-origin");
  child = (void*) gtk_selection_data_get_data (data);

  // process_widget (*child);

  gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
}

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

      Parameters:
      child - a child GtkWidget
      detachable - whether the tab is detachable or not

    • setTabLabel

      public void setTabLabel(Widget child, @Nullable Widget tabLabel)

      Changes the tab label for child.

      If null is specified for tabLabel, then the page will have the label “page N”.

      Parameters:
      child - the page
      tabLabel - the tab label widget to use, or null for default tab label

    • setTabLabelText

      public void setTabLabelText(Widget child, String tabText)
      Creates a new label and sets it as the tab label for the page containing child.
      Parameters:
      child - the page
      tabText - the label text

    • setTabPos

      public void setTabPos(PositionType pos)
      Sets the edge at which the tabs are drawn.
      Parameters:
      pos - the edge to draw the tabs at

    • setTabReorderable

      public void setTabReorderable(Widget child, boolean reorderable)
      Sets whether the notebook tab can be reordered via drag and drop or not.
      Parameters:
      child - a child GtkWidget
      reorderable - whether the tab is reorderable or not

    • onChangeCurrentPage

      public SignalConnection<Notebook.ChangeCurrentPageCallback> onChangeCurrentPage(Notebook.ChangeCurrentPageCallback handler)

      Emitted when the current page should be changed.

      The default bindings for this signal are Ctrl+Alt+PgUp, Ctrl+Alt+PgDn, Ctrl+PgUp and Ctrl+PgDn.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitChangeCurrentPage

      public boolean emitChangeCurrentPage(int page)
      Emits the "change-current-page" signal. See onChangeCurrentPage(Notebook.ChangeCurrentPageCallback).

    • onCreateWindow

      public SignalConnection<Notebook.CreateWindowCallback> onCreateWindow(Notebook.CreateWindowCallback handler)

      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 GtkNotebook:group-name ).

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitCreateWindow

      public Notebook emitCreateWindow(@Nullable Widget page)
      Emits the "create-window" signal. See onCreateWindow(Notebook.CreateWindowCallback).

    • onFocusTab

      public SignalConnection<Notebook.FocusTabCallback> onFocusTab(Notebook.FocusTabCallback handler)
      Emitted when a tab should be focused.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitFocusTab

      public boolean emitFocusTab(NotebookTab tab)
      Emits the "focus-tab" signal. See onFocusTab(Notebook.FocusTabCallback).

    • onMoveFocusOut

      public SignalConnection<Notebook.MoveFocusOutCallback> onMoveFocusOut(Notebook.MoveFocusOutCallback handler)

      Emitted when focus was moved out.

      The default bindings for this signal are Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+←, Ctrl+→, Ctrl+↑ and Ctrl+↓.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitMoveFocusOut

      public void emitMoveFocusOut(DirectionType direction)
      Emits the "move-focus-out" signal. See onMoveFocusOut(Notebook.MoveFocusOutCallback).

    • onPageAdded

      public SignalConnection<Notebook.PageAddedCallback> onPageAdded(Notebook.PageAddedCallback handler)
      the ::page-added signal is emitted in the notebook right after a page is added to the notebook.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPageAdded

      public void emitPageAdded(@Nullable Widget child, int pageNum)
      Emits the "page-added" signal. See onPageAdded(Notebook.PageAddedCallback).

    • onPageRemoved

      public SignalConnection<Notebook.PageRemovedCallback> onPageRemoved(Notebook.PageRemovedCallback handler)
      the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPageRemoved

      public void emitPageRemoved(@Nullable Widget child, int pageNum)
      Emits the "page-removed" signal. See onPageRemoved(Notebook.PageRemovedCallback).

    • onPageReordered

      public SignalConnection<Notebook.PageReorderedCallback> onPageReordered(Notebook.PageReorderedCallback handler)
      the ::page-reordered signal is emitted in the notebook right after a page has been reordered.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPageReordered

      public void emitPageReordered(@Nullable Widget child, int pageNum)
      Emits the "page-reordered" signal. See onPageReordered(Notebook.PageReorderedCallback).

    • onReorderTab

      public SignalConnection<Notebook.ReorderTabCallback> onReorderTab(Notebook.ReorderTabCallback handler)

      Emitted when the tab should be reordered.

      The default bindings for this signal are Alt+Home, Alt+End, Alt+PgUp, Alt+PgDn, Alt+←, Alt+→, Alt+↑ and Alt+↓.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitReorderTab

      public boolean emitReorderTab(DirectionType direction, boolean moveToLast)
      Emits the "reorder-tab" signal. See onReorderTab(Notebook.ReorderTabCallback).

    • onSelectPage

      public SignalConnection<Notebook.SelectPageCallback> onSelectPage(Notebook.SelectPageCallback handler)

      Emitted when a page should be selected.

      The default binding for this signal is ␣.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSelectPage

      public boolean emitSelectPage(boolean moveFocus)
      Emits the "select-page" signal. See onSelectPage(Notebook.SelectPageCallback).

    • onSwitchPage

      public SignalConnection<Notebook.SwitchPageCallback> onSwitchPage(Notebook.SwitchPageCallback handler)
      Emitted when the user or a function changes the current page.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSwitchPage

      public void emitSwitchPage(@Nullable Widget page, int pageNum)
      Emits the "switch-page" signal. See onSwitchPage(Notebook.SwitchPageCallback).

    • builder

      public static Notebook.Builder<? extends Notebook.Builder> builder()
      A Notebook.Builder object constructs a Notebook with the specified properties. Use the various set...() methods to set properties, and finish construction with Notebook.Builder.build().
      Returns:
      the builder object