GTK+ 3 Reference Manual: GtkStack

## GtkStack GtkStack — A stacking container |

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkStack;
    GtkWidget *         gtk_stack_new                       (void);
    void                gtk_stack_add_named                 (GtkStack *stack,
                                                             GtkWidget *child,
                                                             const gchar *name);
    void                gtk_stack_add_titled                (GtkStack *stack,
                                                             GtkWidget *child,
                                                             const gchar *name,
                                                             const gchar *title);
    void                gtk_stack_set_visible_child         (GtkStack *stack,
                                                             GtkWidget *child);
    GtkWidget *         gtk_stack_get_visible_child         (GtkStack *stack);
    void                gtk_stack_set_visible_child_name    (GtkStack *stack,
                                                             const gchar *name);
    const gchar *       gtk_stack_get_visible_child_name    (GtkStack *stack);
    void                gtk_stack_set_visible_child_full    (GtkStack *stack,
                                                             const gchar *name,
                                                             GtkStackTransitionType transition);
    void                gtk_stack_set_homogeneous           (GtkStack *stack,
                                                             gboolean homogeneous);
    gboolean            gtk_stack_get_homogeneous           (GtkStack *stack);
    void                gtk_stack_set_transition_duration   (GtkStack *stack,
                                                             guint duration);
    guint               gtk_stack_get_transition_duration   (GtkStack *stack);
    enum                GtkStackTransitionType;
    void                gtk_stack_set_transition_type       (GtkStack *stack,
                                                             GtkStackTransitionType transition);
    GtkStackTransitionType gtk_stack_get_transition_type    (GtkStack *stack);
    gboolean            gtk_stack_get_transition_running    (GtkStack *stack);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkStack

## Implemented Interfaces

GtkStack implements AtkImplementorIface and GtkBuildable.

## Properties

      "homogeneous"              gboolean              : Read / Write / Construct
      "transition-duration"      guint                 : Read / Write / Construct
      "transition-running"       gboolean              : Read
      "transition-type"          GtkStackTransitionType  : Read / Write / Construct
      "visible-child"            GtkWidget*            : Read / Write
      "visible-child-name"       gchar*                : Read / Write

## Child Properties

      "icon-name"                gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "needs-attention"          gboolean              : Read / Write
      "position"                 gint                  : Read / Write
      "title"                    gchar*                : Read / Write

## Description

The GtkStack widget is a container which only shows one of its children at a time. In contrast to GtkNotebook, GtkStack does not provide a means for users to change the visible child. Instead, the GtkStackSwitcher widget can be used with GtkStack to provide this functionality.

Transitions between pages can be animated as slides or fades. This can be controlled with `gtk_stack_set_transition_type()`. These animations respect the "gtk-enable-animations" setting.

The GtkStack widget was added in GTK+ 3.10.

## Details

### struct GtkStack

    struct GtkStack;

### gtk_stack_new ()

    GtkWidget *         gtk_stack_new                       (void);

Creates a new GtkStack container.

Returns : | a new GtkStack

Since 3.10

### gtk_stack_add_named ()

    void                gtk_stack_add_named                 (GtkStack *stack,
                                                             GtkWidget *child,
                                                             const gchar *name);

Adds a child to `stack`. The child is identified by the `name`.

`stack` : | a GtkStack
`child` : | the widget to add
`name` : | the name for `child`

Since 3.10

### gtk_stack_add_titled ()

    void                gtk_stack_add_titled                (GtkStack *stack,
                                                             GtkWidget *child,
                                                             const gchar *name,
                                                             const gchar *title);

Adds a child to `stack`. The child is identified by the `name`. The `title` will be used by GtkStackSwitcher to represent `child` in a tab bar, so it should be short.

`stack` : | a GtkStack
`child` : | the widget to add
`name` : | the name for `child`
`title` : | a human-readable title for `child`

Since 3.10

### gtk_stack_set_visible_child ()

    void                gtk_stack_set_visible_child         (GtkStack *stack,
                                                             GtkWidget *child);

Makes `child` the visible child of `stack`.

If `child` is different from the currently visible child, the transition between the two will be animated with the current transition type of `stack`.

`stack` : | a GtkStack
`child` : | a child of `stack`

Since 3.10

### gtk_stack_get_visible_child ()

    GtkWidget *         gtk_stack_get_visible_child         (GtkStack *stack);

Gets the currently visible child of `stack`, or `NULL` if there are no visible children.

`stack` : | a GtkStack
Returns : | the visible child of the GtkStack. [transfer none]

Since 3.10

### gtk_stack_set_visible_child_name ()

    void                gtk_stack_set_visible_child_name    (GtkStack *stack,
                                                             const gchar *name);

Makes the child with the given name visible.

If `child` is different from the currently visible child, the transition between the two will be animated with the current transition type of `stack`.

`stack` : | a GtkStack
`name` : | the name of the child to make visible

Since 3.10

### gtk_stack_get_visible_child_name ()

    const gchar *       gtk_stack_get_visible_child_name    (GtkStack *stack);

Returns the name of the currently visible child of `stack`, or `NULL` if there is no visible child.

`stack` : | a GtkStack
Returns : | the name of the visible child of the GtkStack. [transfer none]

Since 3.10

### gtk_stack_set_visible_child_full ()

    void                gtk_stack_set_visible_child_full    (GtkStack *stack,
                                                             const gchar *name,
                                                             GtkStackTransitionType transition);

Makes the child with the given name visible.

`stack` : | a GtkStack
`name` : | the name of the child to make visible
`transition` : | the transition type to use

Since 3.10

### gtk_stack_set_homogeneous ()

    void                gtk_stack_set_homogeneous           (GtkStack *stack,
                                                             gboolean homogeneous);

Sets the GtkStack to be homogeneous or not. If it is homogeneous, the GtkStack will request the same size for all its children. If it isn't, the stack may change size when a different child becomes visible.

`stack` : | a GtkStack
`homogeneous` : | `TRUE` to make `stack` homogeneous

Since 3.10

### gtk_stack_get_homogeneous ()

    gboolean            gtk_stack_get_homogeneous           (GtkStack *stack);

Gets whether `stack` is homogeneous. See `gtk_stack_set_homogeneous()`.

`stack` : | a GtkStack
Returns : | whether `stack` is homogeneous.

Since 3.10

### gtk_stack_set_transition_duration ()

    void                gtk_stack_set_transition_duration   (GtkStack *stack,
                                                             guint duration);

Sets the duration that transitions between pages in `stack` will take.

`stack` : | a GtkStack
`duration` : | the new duration, in milliseconds

Since 3.10

### gtk_stack_get_transition_duration ()

    guint               gtk_stack_get_transition_duration   (GtkStack *stack);

Returns the amount of time (in milliseconds) that transitions between pages in `stack` will take.

`stack` : | a GtkStack
Returns : | the transition duration

Since 3.10

### enum GtkStackTransitionType

    typedef enum {
      GTK_STACK_TRANSITION_TYPE_NONE,
      GTK_STACK_TRANSITION_TYPE_CROSSFADE,
      GTK_STACK_TRANSITION_TYPE_SLIDE_RIGHT,
      GTK_STACK_TRANSITION_TYPE_SLIDE_LEFT,
      GTK_STACK_TRANSITION_TYPE_SLIDE_UP,
      GTK_STACK_TRANSITION_TYPE_SLIDE_DOWN,
      GTK_STACK_TRANSITION_TYPE_SLIDE_LEFT_RIGHT,
      GTK_STACK_TRANSITION_TYPE_SLIDE_UP_DOWN,
      GTK_STACK_TRANSITION_TYPE_OVER_UP,
      GTK_STACK_TRANSITION_TYPE_OVER_DOWN,
      GTK_STACK_TRANSITION_TYPE_OVER_LEFT,
      GTK_STACK_TRANSITION_TYPE_OVER_RIGHT,
      GTK_STACK_TRANSITION_TYPE_UNDER_UP,
      GTK_STACK_TRANSITION_TYPE_UNDER_DOWN,
      GTK_STACK_TRANSITION_TYPE_UNDER_LEFT,
      GTK_STACK_TRANSITION_TYPE_UNDER_RIGHT,
      GTK_STACK_TRANSITION_TYPE_OVER_UP_DOWN
    } GtkStackTransitionType;

These enumeration values describe the possible transitions between pages in a GtkStack widget.

New values may be added to this enumeration over time.

`GTK_STACK_TRANSITION_TYPE_NONE` | No transition
`GTK_STACK_TRANSITION_TYPE_CROSSFADE` | A cross-fade
`GTK_STACK_TRANSITION_TYPE_SLIDE_RIGHT` | Slide from left to right
`GTK_STACK_TRANSITION_TYPE_SLIDE_LEFT` | Slide from right to left
`GTK_STACK_TRANSITION_TYPE_SLIDE_UP` | Slide from bottom up
`GTK_STACK_TRANSITION_TYPE_SLIDE_DOWN` | Slide from top down
`GTK_STACK_TRANSITION_TYPE_SLIDE_LEFT_RIGHT` | Slide from left or right according to the children order
`GTK_STACK_TRANSITION_TYPE_SLIDE_UP_DOWN` | Slide from top down or bottom up according to the order
`GTK_STACK_TRANSITION_TYPE_OVER_UP` | Cover the old page by sliding up. Since 3.12
`GTK_STACK_TRANSITION_TYPE_OVER_DOWN` | Cover the old page by sliding down. Since: 3.12
`GTK_STACK_TRANSITION_TYPE_OVER_LEFT` | Cover the old page by sliding to the left. Since: 3.12
`GTK_STACK_TRANSITION_TYPE_OVER_RIGHT` | Cover the old page by sliding to the right. Since: 3.12
`GTK_STACK_TRANSITION_TYPE_UNDER_UP` | Uncover the new page by sliding up. Since 3.12
`GTK_STACK_TRANSITION_TYPE_UNDER_DOWN` | Uncover the new page by sliding down. Since: 3.12
`GTK_STACK_TRANSITION_TYPE_UNDER_LEFT` | Uncover the new page by sliding to the left. Since: 3.12
`GTK_STACK_TRANSITION_TYPE_UNDER_RIGHT` | Uncover the new page by sliding to the right. Since: 3.12
`GTK_STACK_TRANSITION_TYPE_OVER_UP_DOWN` | Cover the old page or uncover the new page, according to order. Since: 3.12

### gtk_stack_set_transition_type ()

    void                gtk_stack_set_transition_type       (GtkStack *stack,
                                                             GtkStackTransitionType transition);

Sets the type of animation that will be used for transitions between pages in `stack`. Available types include various kinds of fades and slides.

The transition type can be changed without problems at runtime, so it is possible to change the animation based on the page that is about to become current.

`stack` : | a GtkStack
`transition` : | the new transition type

Since 3.10

### gtk_stack_get_transition_type ()

    GtkStackTransitionType gtk_stack_get_transition_type    (GtkStack *stack);

Gets the type of animation that will be used for transitions between pages in `stack`.

`stack` : | a GtkStack
Returns : | the current transition type of `stack`

Since 3.10

### gtk_stack_get_transition_running ()

    gboolean            gtk_stack_get_transition_running    (GtkStack *stack);

Returns whether the `stack` is currently in a transition from one page to another.

`stack` : | a GtkStack
Returns : | `TRUE` if the transition is currently running, `FALSE` otherwise.

Since 3.12

## Property Details

### The `"homogeneous"` property

      "homogeneous"              gboolean              : Read / Write / Construct

Homogeneous sizing.

Default value: TRUE

### The `"transition-duration"` property

      "transition-duration"      guint                 : Read / Write / Construct

The animation duration, in milliseconds.

Default value: 200

### The `"transition-running"` property

      "transition-running"       gboolean              : Read

Whether or not the transition is currently running.

Default value: FALSE

### The `"transition-type"` property

      "transition-type"          GtkStackTransitionType  : Read / Write / Construct

The type of animation used to transition.

Default value: GTK_STACK_TRANSITION_TYPE_NONE

### The `"visible-child"` property

      "visible-child"            GtkWidget*            : Read / Write

The widget currently visible in the stack.

### The `"visible-child-name"` property

      "visible-child-name"       gchar*                : Read / Write

The name of the widget currently visible in the stack.

Default value: NULL

## Child Property Details

### The `"icon-name"` child property

      "icon-name"                gchar*                : Read / Write

The icon name of the child page.

Default value: NULL

### The `"name"` child property

      "name"                     gchar*                : Read / Write

The name of the child page.

Default value: NULL

### The `"needs-attention"` child property

      "needs-attention"          gboolean              : Read / Write

Sets a flag specifying whether the child requires the user attention. This is used by the GtkStackSwitcher to change the appearance of the corresponding button when a page needs attention and it is not the current one.

Default value: FALSE

Since 3.12

### The `"position"` child property

      "position"                 gint                  : Read / Write

The index of the child in the parent.

Allowed values: >= -1

Default value: 0

### The `"title"` child property

      "title"                    gchar*                : Read / Write

The title of the child page.

Default value: NULL

## See Also

GtkNotebook, GtkStackSwitcher