Next: , Previous: GtkLayout, Up: Top


100 GtkNotebook

A tabbed notebook container

100.1 Overview

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

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

100.2 Usage

— Class: <gtk-notebook>

Derives from <gtk-container>.

This class defines the following slots:

tab-pos
Which side of the notebook holds the tabs
show-tabs
Whether tabs should be shown or not
show-border
Whether the border should be shown or not
scrollable
If TRUE, scroll arrows are added if there are too many tabs to fit
tab-border
Width of the border around the tab labels
tab-hborder
Width of the horizontal border of tab labels
tab-vborder
Width of the vertical border of tab labels
page
The index of the current page
enable-popup
If TRUE, pressing the right mouse button on the notebook pops up a menu that you can use to go to a page
group-id
Group ID for tabs drag and drop
group
Group for tabs drag and drop
homogeneous
Whether tabs should have homogeneous sizes
— Signal on <gtk-notebook>: switch-page (arg0 <gpointer>) (arg1 <guint>)

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

— Signal on <gtk-notebook>: focus-tab (arg0 <gtk-notebook-tab>) ⇒ <gboolean>
— Signal on <gtk-notebook>: select-page (arg0 <gboolean>) ⇒ <gboolean>
— Signal on <gtk-notebook>: change-current-page (arg0 <gint>) ⇒ <gboolean>
— Signal on <gtk-notebook>: move-focus-out (arg0 <gtk-direction-type>)
— Signal on <gtk-notebook>: reorder-tab (arg0 <gtk-direction-type>) (arg1 <gboolean>) ⇒ <gboolean>
— Signal on <gtk-notebook>: page-reordered (arg0 <gtk-widget>) (arg1 <guint>)

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

Since 2.10

— Signal on <gtk-notebook>: page-removed (arg0 <gtk-widget>) (arg1 <guint>)

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

Since 2.10

— Signal on <gtk-notebook>: page-added (arg0 <gtk-widget>) (arg1 <guint>)

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

Since 2.10

— Signal on <gtk-notebook>: create-window (arg0 <gtk-widget>) (arg1 <gint>) (arg2 <gint>) ⇒ <gtk-notebook>

undocumented

— Function: gtk-notebook-new ⇒  (ret <gtk-widget>)

Creates a new <gtk-notebook> widget with no pages.

ret
the newly created <gtk-notebook>
— Function: gtk-notebook-append-page (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>) ⇒  (ret int)
— Method: append-page

Appends a page to notebook.

notebook
a <gtk-notebook>
child
the <gtk-widget> to use as the contents of the page.
tab-label
the <gtk-widget> to be used as the label for the page, or ‘#f’ to use the default label, 'page N'.
ret
the index (starting from 0) of the appended page in the notebook, or -1 if function fails
— Function: gtk-notebook-append-page-menu (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>) (menu_label <gtk-widget>) ⇒  (ret int)
— Method: append-page-menu

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

notebook
a <gtk-notebook>
child
the <gtk-widget> to use as the contents of the page.
tab-label
the <gtk-widget> to be used as the label for the page, or ‘#f’ 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 ‘#f’, and tab-label is a <gtk-label> or ‘#f’, then the menu label will be a newly created label with the same text as tab-label; If tab-label is not a <gtk-label>, menu-label must be specified if the page-switch menu is to be used.
ret
the index (starting from 0) of the appended page in the notebook, or -1 if function fails
— Function: gtk-notebook-prepend-page (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>) ⇒  (ret int)
— Method: prepend-page

Prepends a page to notebook.

notebook
a <gtk-notebook>
child
the <gtk-widget> to use as the contents of the page.
tab-label
the <gtk-widget> to be used as the label for the page, or ‘#f’ to use the default label, 'page N'.
ret
the index (starting from 0) of the prepended page in the notebook, or -1 if function fails
— Function: gtk-notebook-prepend-page-menu (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>) (menu_label <gtk-widget>) ⇒  (ret int)
— Method: prepend-page-menu

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

notebook
a <gtk-notebook>
child
the <gtk-widget> to use as the contents of the page.
tab-label
the <gtk-widget> to be used as the label for the page, or ‘#f’ 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 ‘#f’, and tab-label is a <gtk-label> or ‘#f’, then the menu label will be a newly created label with the same text as tab-label; If tab-label is not a <gtk-label>, menu-label must be specified if the page-switch menu is to be used.
ret
the index (starting from 0) of the prepended page in the notebook, or -1 if function fails
— Function: gtk-notebook-insert-page (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>) (position int) ⇒  (ret int)
— Method: insert-page

Insert a page into notebook at the given position.

notebook
a <gtk-notebook>
child
the <gtk-widget> to use as the contents of the page.
tab-label
the <gtk-widget> to be used as the label for the page, or ‘#f’ 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.
ret
the index (starting from 0) of the inserted page in the notebook, or -1 if function fails
— Function: gtk-notebook-insert-page-menu (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>) (menu_label <gtk-widget>) (position int) ⇒  (ret int)
— Method: insert-page-menu

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

notebook
a <gtk-notebook>
child
the <gtk-widget> to use as the contents of the page.
tab-label
the <gtk-widget> to be used as the label for the page, or ‘#f’ 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 ‘#f’, and tab-label is a <gtk-label> or ‘#f’, then the menu label will be a newly created label with the same text as tab-label; If tab-label is not a <gtk-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.
ret
the index (starting from 0) of the inserted page in the notebook
— Function: gtk-notebook-remove-page (self <gtk-notebook>) (page_num int)
— Method: remove-page

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

notebook
a <gtk-notebook>.
page-num
the index of a notebook page, starting from 0. If -1, the last page will be removed.
— Function: gtk-notebook-page-num (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret int)
— Method: page-num

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

notebook
a <gtk-notebook>
child
a <gtk-widget>
ret
the index of the page containing child, or -1 if child is not in the notebook.
— Function: gtk-notebook-next-page (self <gtk-notebook>)
— Method: next-page

Switches to the next page. Nothing happens if the current page is the last page.

notebook
a <gtk-notebook>
— Function: gtk-notebook-prev-page (self <gtk-notebook>)
— Method: prev-page

Switches to the previous page. Nothing happens if the current page is the first page.

notebook
a <gtk-notebook>
— Function: gtk-notebook-reorder-child (self <gtk-notebook>) (child <gtk-widget>) (position int)
— Method: 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.

notebook
a <gtk-notebook>
child
the child to move
position
the new position, or -1 to move to the end
— Function: gtk-notebook-set-tab-pos (self <gtk-notebook>) (pos <gtk-position-type>)
— Method: set-tab-pos

Sets the edge at which the tabs for switching pages in the notebook are drawn.

notebook
a <gtk-notebook>.
pos
the edge to draw the tabs at.
— Function: gtk-notebook-set-show-tabs (self <gtk-notebook>) (show_tabs bool)
— Method: set-show-tabs

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

notebook
a <gtk-notebook>
show-tabs
#t’ if the tabs should be shown.
— Function: gtk-notebook-set-show-border (self <gtk-notebook>) (show_border bool)
— Method: 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. See gtk-notebook-set-show-tabs.

notebook
a <gtk-notebook>
show-border
#t’ if a bevel should be drawn around the notebook.
— Function: gtk-notebook-set-scrollable (self <gtk-notebook>) (scrollable bool)
— Method: set-scrollable

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

notebook
a <gtk-notebook>
scrollable
#t’ if scroll arrows should be added
— Function: gtk-notebook-popup-enable (self <gtk-notebook>)
— Method: popup-enable

Enables the popup menu: if the user clicks with the right mouse button on the bookmarks, a menu with all the pages will be popped up.

notebook
a <gtk-notebook>
— Function: gtk-notebook-popup-disable (self <gtk-notebook>)
— Method: popup-disable

Disables the popup menu.

notebook
a <gtk-notebook>
— Function: gtk-notebook-get-current-page (self <gtk-notebook>) ⇒  (ret int)
— Method: get-current-page

Returns the page number of the current page.

notebook
a <gtk-notebook>
ret
the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned.
— Function: gtk-notebook-get-menu-label (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret <gtk-widget>)
— Method: get-menu-label

Retrieves the menu label widget of the page containing child.

notebook
a <gtk-notebook>
child
a widget contained in a page of notebook
ret
the menu label, or ‘#f’ if the notebook page does not have a menu label other than the default (the tab label).
— Function: gtk-notebook-get-nth-page (self <gtk-notebook>) (page_num int) ⇒  (ret <gtk-widget>)
— Method: get-nth-page

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

notebook
a <gtk-notebook>
page-num
the index of a page in the noteobok, or -1 to get the last page.
ret
the child widget, or ‘#f’ if page-num is out of bounds.
— Function: gtk-notebook-get-n-pages (self <gtk-notebook>) ⇒  (ret int)
— Method: get-n-pages

Gets the number of pages in a notebook.

notebook
a <gtk-notebook>
ret
the number of pages in the notebook.

Since 2.2

— Function: gtk-notebook-get-tab-label (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret <gtk-widget>)
— Method: get-tab-label

Returns the tab label widget for the page child. ‘#f’ is returned if child is not in notebook or if no tab label has specifically been set for child.

notebook
a <gtk-notebook>
child
the page
ret
the tab label
— Function: gtk-notebook-set-menu-label (self <gtk-notebook>) (child <gtk-widget>) (menu_label <gtk-widget>)
— Method: set-menu-label

Changes the menu label for the page containing child.

notebook
a <gtk-notebook>
child
the child widget
menu-label
the menu label, or NULL for default
— Function: gtk-notebook-set-menu-label-text (self <gtk-notebook>) (child <gtk-widget>) (menu_text mchars)
— Method: set-menu-label-text

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

notebook
a <gtk-notebook>
child
the child widget
menu-text
the label text
— Function: gtk-notebook-set-tab-label (self <gtk-notebook>) (child <gtk-widget>) (tab_label <gtk-widget>)
— Method: set-tab-label

Changes the tab label for child. If ‘#f’ is specified for tab-label, then the page will have the label 'page N'.

notebook
a <gtk-notebook>
child
the page
tab-label
the tab label widget to use, or ‘#f’ for default tab label.
— Function: gtk-notebook-set-tab-label-packing (self <gtk-notebook>) (child <gtk-widget>) (expand bool) (fill bool) (pack_type <gtk-pack-type>)
— Method: set-tab-label-packing

Sets the packing parameters for the tab label of the page containing child. See gtk-box-pack-start for the exact meaning of the parameters.

notebook
a <gtk-notebook>
child
the child widget
expand
whether to expand the bookmark or not
fill
whether the bookmark should fill the allocated area or not
pack-type
the position of the bookmark
— Function: gtk-notebook-set-tab-label-text (self <gtk-notebook>) (child <gtk-widget>) (tab_text mchars)
— Method: set-tab-label-text

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

notebook
a <gtk-notebook>
child
the page
tab-text
the label text
— Function: gtk-notebook-set-tab-reorderable (self <gtk-notebook>) (child <gtk-widget>) (reorderable bool)
— Method: set-tab-reorderable

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

notebook
a <gtk-notebook>
child
a child <gtk-widget>
reorderable
whether the tab is reorderable or not.

Since 2.10

— Function: gtk-notebook-set-tab-detachable (self <gtk-notebook>) (child <gtk-widget>) (detachable bool)
— Method: set-tab-detachable

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

Note that 2 notebooks must share a common group identificator (see gtk-notebook-set-group-id) 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 and accept the target "GTK_NOTEBOOK_TAB". The notebook will fill the selection with a GtkWidget** pointing to the child widget that corresponds to the dropped tab.

          
           static void
           on_drop_zone_drag_data_received (GtkWidget        *widget,
                                            GdkDragContext   *context,
                                            gint              x,
                                            gint              y,
                                            GtkSelectionData *selection_data,
                                            guint             info,
                                            guint             time,
                                            gpointer          user_data)
           {
             GtkWidget *notebook;
             GtkWidget **child;
          
             notebook = gtk_drag_get_source_widget (context);
             child = (void*) selection_data->data;
          
             process_widget (*child);
             gtk_container_remove (GTK_CONTAINER (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.

notebook
a <gtk-notebook>
child
a child <gtk-widget>
detachable
whether the tab is detachable or not

Since 2.10

— Function: gtk-notebook-get-menu-label-text (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret mchars)
— Method: get-menu-label-text

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

notebook
a <gtk-notebook>
child
the child widget of a page of the notebook.
ret
value: the text of the tab label, or ‘#f’ if the widget does not have a menu label other than the default menu label, or the menu label widget is not a <gtk-label>. The string is owned by the widget and must not be freed.
— Function: gtk-notebook-get-scrollable (self <gtk-notebook>) ⇒  (ret bool)
— Method: get-scrollable

Returns whether the tab label area has arrows for scrolling. See gtk-notebook-set-scrollable.

notebook
a <gtk-notebook>
ret
#t’ if arrows for scrolling are present
— Function: gtk-notebook-get-show-border (self <gtk-notebook>) ⇒  (ret bool)
— Method: get-show-border

Returns whether a bevel will be drawn around the notebook pages. See gtk-notebook-set-show-border.

notebook
a <gtk-notebook>
ret
#t’ if the bevel is drawn
— Function: gtk-notebook-get-show-tabs (self <gtk-notebook>) ⇒  (ret bool)
— Method: get-show-tabs

Returns whether the tabs of the notebook are shown. See gtk-notebook-set-show-tabs.

notebook
a <gtk-notebook>
ret
#t’ if the tabs are shown
— Function: gtk-notebook-get-tab-label-text (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret mchars)
— Method: get-tab-label-text

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

notebook
a <gtk-notebook>
child
a widget contained in a page of notebook
ret
value: the text of the tab label, or ‘#f’ if the tab label widget is not a <gtk-label>. The string is owned by the widget and must not be freed.
— Function: gtk-notebook-get-tab-pos (self <gtk-notebook>) ⇒  (ret <gtk-position-type>)
— Method: get-tab-pos

Gets the edge at which the tabs for switching pages in the notebook are drawn.

notebook
a <gtk-notebook>
ret
the edge at which the tabs are drawn
— Function: gtk-notebook-get-tab-reorderable (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret bool)
— Method: get-tab-reorderable

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

notebook
a <gtk-notebook>
child
a child <gtk-widget>
ret
#t’ if the tab is reorderable.

Since 2.10

— Function: gtk-notebook-get-tab-detachable (self <gtk-notebook>) (child <gtk-widget>) ⇒  (ret bool)
— Method: get-tab-detachable

Returns whether the tab contents can be detached from notebook.

notebook
a <gtk-notebook>
child
a child <gtk-widget>
ret
TRUE if the tab is detachable.

Since 2.10

— Function: gtk-notebook-set-current-page (self <gtk-notebook>) (page_num int)
— Method: 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.

notebook
a <gtk-notebook>
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.
— Function: gtk-notebook-set-group-id (self <gtk-notebook>) (group_id int)
— Method: set-group-id

Sets an group identificator for notebook, notebooks sharing the same group identificator will be able to exchange tabs via drag and drop. A notebook with group identificator -1 will not be able to exchange tabs with any other notebook.

notebook
a <gtk-notebook>
group-id
a group identificator, or -1 to unset it

Since 2.10

— Function: gtk-notebook-get-group-id (self <gtk-notebook>) ⇒  (ret int)
— Method: get-group-id

Gets the current group identificator for notebook.

notebook
a <gtk-notebook>
ret
the group identificator, or -1 if none is set.

Since 2.10