GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkNotebook

## Name

GtkNotebook -- Set of pages with bookmarks.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkNotebook;
    #define     GTK_NOTEBOOK_PAGE               (_glist_)
    struct      GtkNotebookPage;
    GtkWidget*  gtk_notebook_new                (void);
    void        gtk_notebook_append_page        (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label);
    void        gtk_notebook_append_page_menu   (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 GtkWidget *menu_label);
    void        gtk_notebook_prepend_page       (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label);
    void        gtk_notebook_prepend_page_menu  (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 GtkWidget *menu_label);
    void        gtk_notebook_insert_page        (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 gint position);
    void        gtk_notebook_insert_page_menu   (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 GtkWidget *menu_label,
                                                 gint position);
    void        gtk_notebook_remove_page        (GtkNotebook *notebook,
                                                 gint page_num);
    #define     gtk_notebook_current_page
    gint        gtk_notebook_page_num           (GtkNotebook *notebook,
                                                 GtkWidget *child);
    void        gtk_notebook_set_page           (GtkNotebook *notebook,
                                                 gint page_num);
    void        gtk_notebook_next_page          (GtkNotebook *notebook);
    void        gtk_notebook_prev_page          (GtkNotebook *notebook);
    void        gtk_notebook_reorder_child      (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 gint position);
    void        gtk_notebook_set_tab_pos        (GtkNotebook *notebook,
                                                 GtkPositionType pos);
    void        gtk_notebook_set_show_tabs      (GtkNotebook *notebook,
                                                 gboolean show_tabs);
    void        gtk_notebook_set_show_border    (GtkNotebook *notebook,
                                                 gboolean show_border);
    void        gtk_notebook_set_scrollable     (GtkNotebook *notebook,
                                                 gboolean scrollable);
    void        gtk_notebook_set_tab_border     (GtkNotebook *notebook,
                                                 guint border_width);
    void        gtk_notebook_popup_enable       (GtkNotebook *notebook);
    void        gtk_notebook_popup_disable      (GtkNotebook *notebook);
    gint        gtk_notebook_get_current_page   (GtkNotebook *notebook);
    GtkWidget*  gtk_notebook_get_menu_label     (GtkNotebook *notebook,
                                                 GtkWidget *child);
    GtkWidget*  gtk_notebook_get_nth_page       (GtkNotebook *notebook,
                                                 gint page_num);
    GtkWidget*  gtk_notebook_get_tab_label      (GtkNotebook *notebook,
                                                 GtkWidget *child);
    void        gtk_notebook_query_tab_label_packing
                                                (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 gboolean *expand,
                                                 gboolean *fill,
                                                 GtkPackType *pack_type);
    void        gtk_notebook_set_homogeneous_tabs
                                                (GtkNotebook *notebook,
                                                 gboolean homogeneous);
    void        gtk_notebook_set_menu_label     (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *menu_label);
    void        gtk_notebook_set_menu_label_text
                                                (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 const gchar *menu_text);
    void        gtk_notebook_set_tab_hborder    (GtkNotebook *notebook,
                                                 guint tab_hborder);
    void        gtk_notebook_set_tab_label      (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label);
    void        gtk_notebook_set_tab_label_packing
                                                (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 gboolean expand,
                                                 gboolean fill,
                                                 GtkPackType pack_type);
    void        gtk_notebook_set_tab_label_text (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 const gchar *tab_text);
    void        gtk_notebook_set_tab_vborder    (GtkNotebook *notebook,
                                                 guint tab_vborder);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkNotebook

## Properties

      "page"                 gint                 : Read / Write
      "tab-pos"              GtkPositionType      : Read / Write
      "tab-border"           guint                : Write
      "tab-hborder"          guint                : Read / Write
      "tab-vborder"          guint                : Read / Write
      "show-tabs"            gboolean             : Read / Write
      "show-border"          gboolean             : Read / Write
      "scrollable"           gboolean             : Read / Write
      "enable-popup"         gboolean             : Read / Write

## Signal Prototypes

    "switch-page"
                void        user_function      (GtkNotebook *notebook,
                                                GtkNotebookPage *page,
                                                gint page_num,
                                                gpointer user_data);

## Description

The GtkNotebook widget is a GtkContainer whose children are pages that can be accessed through bookmarks. The pages are displayed all at the same place.

## Details

### struct GtkNotebook

    struct GtkNotebook;

### GTK_NOTEBOOK_PAGE()

    #define GTK_NOTEBOOK_PAGE(_glist_)         ((GtkNotebookPage *)((GList *)(_glist_))->data)

Extracts the contents of the current element of GList `_glist_` as a GtkNotebookPage.

`_glist_` : |

### struct GtkNotebookPage

    struct GtkNotebookPage
    {
      GtkWidget *child;
      GtkWidget *tab_label;
      GtkWidget *menu_label;

      guint default_menu : 1;
      guint default_tab  : 1;
      guint expand       : 1;
      guint fill         : 1;
      guint pack         : 1;

      GtkRequisition requisition;
      GtkAllocation allocation;
    };

The GtkNotebookPage structure is used to store the pages of a notebook. It is not an object.

GtkWidget *`child` | the contents of the page
GtkWidget *`tab_label` | the label shown in the bookmark
GtkWidget *`menu_label` | the label shown in the popup menu
guint `default_menu` : 1 |
guint `default_tab` : 1 |
guint `expand` : 1 |
guint `fill` : 1 |
guint `pack` : 1 |
GtkRequisition `requisition` |
GtkAllocation `allocation` |

### gtk_notebook_new ()

    GtkWidget*  gtk_notebook_new                (void);

Creates a new GtkNotebook widget

Returns : | the newly created G=GtkNotebook

### gtk_notebook_append_page ()

    void        gtk_notebook_append_page        (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label);

Appends to `notebook` a page whose content is `child`, and whose bookmark is `tab_label`.

`notebook` : | the notebook widget
`child` : | the content of the new page
`tab_label` : | the bookmark for the page

### gtk_notebook_append_page_menu ()

    void        gtk_notebook_append_page_menu   (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 GtkWidget *menu_label);

Appends to `notebook` a page whose content is `child`, whose bookmark is `tab_label`, and whose menu label is `menu_label`.

`notebook` : | the notebook widget
`child` : | the content of the new page
`tab_label` : | the bookmark of the page
`menu_label` : | the menu label of the page

### gtk_notebook_prepend_page ()

    void        gtk_notebook_prepend_page       (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label);

Prepends to `notebook` a page whose content is `child`, whose bookmark is `tab_label`, and whose menu label is `menu_label`.

`notebook` : | the notebook widget
`child` : | the content of the new page
`tab_label` : | the bookmark of the page

### gtk_notebook_prepend_page_menu ()

    void        gtk_notebook_prepend_page_menu  (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 GtkWidget *menu_label);

Appends to `notebook` a page whose content is `child`, whose bookmark is `tab_label`, and whose menu label is `menu_label`.

`notebook` : | the notebook widget
`child` : | the content of the new page
`tab_label` : | the bookmark of the page
`menu_label` : | the menu label of the page

### gtk_notebook_insert_page ()

    void        gtk_notebook_insert_page        (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 gint position);

Inserts in `notebook` a new page whose content is `child`, and whose bookmark is `tab_label`. The page is inserted just before the page number `position`, starting with 0. If `position` is out of bounds, it is assumed to be the current number of pages.

`notebook` : | the notebook widget
`child` : | the content of the new page
`tab_label` : | the bookmark of the page
`position` : | the position to insert the page

### gtk_notebook_insert_page_menu ()

    void        gtk_notebook_insert_page_menu   (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label,
                                                 GtkWidget *menu_label,
                                                 gint position);

Inserts in `notebook` a new page whose content is `child`, whose bookmark is `tab_label`, and whose menu label is `menu_label`. The page is inserted just before the page number `position`, starting with 0. If `position` is out of bounds, it is assumed to be the current number of pages.

`notebook` : | the notebook widget
`child` : | the content of the new page
`tab_label` : | the bookmark of the page
`menu_label` : | the menu label of the page
`position` : | the position to insert the page

### gtk_notebook_remove_page ()

    void        gtk_notebook_remove_page        (GtkNotebook *notebook,
                                                 gint page_num);

Removes the page `page_num` form `notebook`. Pages are numbered starting at zero. Negative values stand for the last page; too large values are ignored.

`notebook` : | the notebook widget
`page_num` : | the page number

### gtk_notebook_current_page

    #define	gtk_notebook_current_page               gtk_notebook_get_current_page

Compatibility macro; in gtkcompat.h.

### gtk_notebook_page_num ()

    gint        gtk_notebook_page_num           (GtkNotebook *notebook,
                                                 GtkWidget *child);

Returns the page number of `child` in `notebook`.

`notebook` : | the notebook widget
`child` : | the child
Returns : | the page number, or -1 if `child` is not in `notebook`

### gtk_notebook_set_page ()

    void        gtk_notebook_set_page           (GtkNotebook *notebook,
                                                 gint page_num);

Switches to the page number `page_num`. Negative values stand for the last page; too large values are ignored.

`notebook` : | the notebook widget
`page_num` : | the page number

### gtk_notebook_next_page ()

    void        gtk_notebook_next_page          (GtkNotebook *notebook);

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

`notebook` : | the notebook widget.

### gtk_notebook_prev_page ()

    void        gtk_notebook_prev_page          (GtkNotebook *notebook);

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

`notebook` : | the notebook widget

### gtk_notebook_reorder_child ()

    void        gtk_notebook_reorder_child      (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 gint position);

Moves the page `child`, so that it appears in position `position`. Out of bounds `position` will be clamped.

`notebook` : | the notebook widget
`child` : | the child to deplace
`position` : | the new position

### gtk_notebook_set_tab_pos ()

    void        gtk_notebook_set_tab_pos        (GtkNotebook *notebook,
                                                 GtkPositionType pos);

Sets the position of the bookmarks.

`notebook` : | the notebook widget
`pos` : | the position

### gtk_notebook_set_show_tabs ()

    void        gtk_notebook_set_show_tabs      (GtkNotebook *notebook,
                                                 gboolean show_tabs);

Sets whether to show the bookmarks or not.

`notebook` : | the notebook widget
`show_tabs` : | a boolean value

### gtk_notebook_set_show_border ()

    void        gtk_notebook_set_show_border    (GtkNotebook *notebook,
                                                 gboolean show_border);

Sets whether to show the border of the notebook or not. Bookmarks are in the border.

`notebook` : | the notebook widget
`show_border` : | a boolean value

### gtk_notebook_set_scrollable ()

    void        gtk_notebook_set_scrollable     (GtkNotebook *notebook,
                                                 gboolean scrollable);

Sets whether the bookmarks area may be scrollable or not if there are too many bookmarks to fit in the allocated area.

`notebook` : | the notebook widget
`scrollable` : | a boolean value

### gtk_notebook_set_tab_border ()

    void        gtk_notebook_set_tab_border     (GtkNotebook *notebook,
                                                 guint border_width);

Sets whether there should be a border around the bookmarks or not.

`notebook` : | the notebook widget
`border_width` : | a boolean value

### gtk_notebook_popup_enable ()

    void        gtk_notebook_popup_enable       (GtkNotebook *notebook);

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` : | the notebook widget

### gtk_notebook_popup_disable ()

    void        gtk_notebook_popup_disable      (GtkNotebook *notebook);

Disables the popup menu

`notebook` : | the notebook widget

### gtk_notebook_get_current_page ()

    gint        gtk_notebook_get_current_page   (GtkNotebook *notebook);

Returns the page number of the current page.

`notebook` : | the notebook widget
Returns : | the page number

### gtk_notebook_get_menu_label ()

    GtkWidget*  gtk_notebook_get_menu_label     (GtkNotebook *notebook,
                                                 GtkWidget *child);

Returns the menu label of the page `child`. NULL is returned if `child` is not in `notebook` or NULL if it has the default menu label.

`notebook` : | the notebook widget
`child` : | the page
Returns : | the menu label

### gtk_notebook_get_nth_page ()

    GtkWidget*  gtk_notebook_get_nth_page       (GtkNotebook *notebook,
                                                 gint page_num);

Returns the content of the page number `page_num`, or NULL if `page_num` is out of bounds.

`notebook` : | the notebook widget
`page_num` : | the page number
Returns : | the content of the page

### gtk_notebook_get_tab_label ()

    GtkWidget*  gtk_notebook_get_tab_label      (GtkNotebook *notebook,
                                                 GtkWidget *child);

Returns the menu tab of the page `child`. NULL is returned if `child` is not in `notebook` or NULL if it has the default tab label.

`notebook` : | the notebook widget
`child` : | the page
Returns : | the tab label

### gtk_notebook_query_tab_label_packing ()

    void        gtk_notebook_query_tab_label_packing
                                                (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 gboolean *expand,
                                                 gboolean *fill,
                                                 GtkPackType *pack_type);

Looks for the packing attributes of the bookmarks of `child`.

`notebook` : | the notebook widget
`child` : | the page
`expand` : | a pointer to return the expand value (or NULL)
`fill` : | a pointer to return the fill value (or NULL)
`pack_type` : | a pointer to return the pack_type (or NULL)

### gtk_notebook_set_homogeneous_tabs ()

    void        gtk_notebook_set_homogeneous_tabs
                                                (GtkNotebook *notebook,
                                                 gboolean homogeneous);

Sets whether the tabs must have all the same size or not.

`notebook` : | the notebook widget
`homogeneous` : | a boolean value

### gtk_notebook_set_menu_label ()

    void        gtk_notebook_set_menu_label     (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *menu_label);

Changes the menu label of `child`. Nothing happens if `child` is not in `notebook`.

`notebook` : | the notebook widget
`child` : | the page
`menu_label` : | the menu label, or NULL for default

### gtk_notebook_set_menu_label_text ()

    void        gtk_notebook_set_menu_label_text
                                                (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 const gchar *menu_text);

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

`notebook` : | the notebook widget
`child` : | the page
`menu_text` : | the label text

### gtk_notebook_set_tab_hborder ()

    void        gtk_notebook_set_tab_hborder    (GtkNotebook *notebook,
                                                 guint tab_hborder);

Sets whether the tabs should have a horizontal border.

`notebook` : | the notebook widget
`tab_hborder` : | a boolean value

### gtk_notebook_set_tab_label ()

    void        gtk_notebook_set_tab_label      (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 GtkWidget *tab_label);

Changes the bookmark label of `child`. Nothing happens if `child` is not in `notebook`.

`notebook` : | the notebook widget
`child` : | the page
`tab_label` : | the bookmark label, or NULL for default

### gtk_notebook_set_tab_label_packing ()

    void        gtk_notebook_set_tab_label_packing
                                                (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 gboolean expand,
                                                 gboolean fill,
                                                 GtkPackType pack_type);

Sets the packing parameters for the bookmark of `child`. See GtkBoxPackStart for the exact meanings.

`notebook` : | the notebook widget
`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

### gtk_notebook_set_tab_label_text ()

    void        gtk_notebook_set_tab_label_text (GtkNotebook *notebook,
                                                 GtkWidget *child,
                                                 const gchar *tab_text);

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

`notebook` : | the notebook widget
`child` : | the page
`tab_text` : | the label text

### gtk_notebook_set_tab_vborder ()

    void        gtk_notebook_set_tab_vborder    (GtkNotebook *notebook,
                                                 guint tab_vborder);

Sets whether the tabs should have a vertical border.

`notebook` : | the notebook widget
`tab_vborder` : | a boolean value

## Properties

"`page`" (gint : Read / Write)

  The current page

"`tab-pos`" (GtkPositionType : Read / Write)

"`tab-border`" (guint : Write)

"`tab-hborder`" (guint : Read / Write)

"`tab-vborder`" (guint : Read / Write)

"`show-tabs`" (gboolean : Read / Write)

"`show-border`" (gboolean : Read / Write)

"`scrollable`" (gboolean : Read / Write)

  Whether the bookmarks should be scrollable or not

"`enable-popup`" (gboolean : Read / Write)

## Signals

### The "switch-page" signal

    void        user_function                  (GtkNotebook *notebook,
                                                GtkNotebookPage *page,
                                                gint page_num,
                                                gpointer user_data);

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

`notebook` : | the object which received the signal.
`page` : | the new current page
`page_num` : | the index of the page
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkContainer

  For functions that apply to every GtkContainer (like GtkList).

<<< Previous Page | Home | Up | Next Page >>>
GtkMisc | GtkObject