GtkStack: GTK+ 3 Reference Manual

## GtkStack GtkStack — A stacking container |

## Functions

GtkWidget * | gtk_stack_new ()
void | gtk_stack_add_named ()
void | gtk_stack_add_titled ()
GtkWidget * | gtk_stack_get_child_by_name ()
void | gtk_stack_set_visible_child ()
GtkWidget * | gtk_stack_get_visible_child ()
void | gtk_stack_set_visible_child_name ()
const gchar * | gtk_stack_get_visible_child_name ()
void | gtk_stack_set_visible_child_full ()
void | gtk_stack_set_homogeneous ()
gboolean | gtk_stack_get_homogeneous ()
void | gtk_stack_set_hhomogeneous ()
gboolean | gtk_stack_get_hhomogeneous ()
void | gtk_stack_set_vhomogeneous ()
gboolean | gtk_stack_get_vhomogeneous ()
void | gtk_stack_set_transition_duration ()
guint | gtk_stack_get_transition_duration ()
void | gtk_stack_set_transition_type ()
GtkStackTransitionType | gtk_stack_get_transition_type ()
gboolean | gtk_stack_get_transition_running ()
gboolean | gtk_stack_get_interpolate_size ()
void | gtk_stack_set_interpolate_size ()

## Properties

gboolean | hhomogeneous | Read / Write
gboolean | homogeneous | Read / Write
gboolean | interpolate-size | Read / Write
guint | transition-duration | Read / Write
gboolean | transition-running | Read
GtkStackTransitionType | transition-type | Read / Write
gboolean | vhomogeneous | Read / Write
GtkWidget * | visible-child | Read / Write
gchar * | visible-child-name | Read / Write

## Child Properties

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

## Types and Values

struct | GtkStack
enum | GtkStackTransitionType

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkStack

## Implemented Interfaces

GtkStack implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtk.h>

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

### CSS nodes

GtkStack has a single CSS node named stack.

## Functions

### 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` .

#### Parameters

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.

#### Parameters

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_get_child_by_name ()

    GtkWidget *
    gtk_stack_get_child_by_name (GtkStack *stack,
                                 const gchar *name);

Finds the child of the GtkStack with the name given as the argument. Returns `NULL` if there is no child with this name.

#### Parameters

stack | a GtkStack |
name | the name of the child to find |

#### Returns

the requested child of the GtkStack.

[transfer none][nullable]

Since: 3.12

### 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` .

Note that the `child` widget has to be visible itself (see `gtk_widget_show()`) in order to become the visible child of `stack` .

#### Parameters

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.

#### Parameters

stack | a GtkStack |

#### Returns

the visible child of the GtkStack.

[transfer none][nullable]

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

Note that the child widget has to be visible itself (see `gtk_widget_show()`) in order to become the visible child of `stack` .

#### Parameters

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.

#### Parameters

stack | a GtkStack |

#### Returns

the name of the visible child of the GtkStack.

[transfer none][nullable]

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.

Note that the child widget has to be visible itself (see `gtk_widget_show()`) in order to become the visible child of `stack` .

#### Parameters

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.

Since 3.16, homogeneity can be controlled separately for horizontal and vertical size, with the “hhomogeneous” and “vhomogeneous”.

#### Parameters

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()`.

#### Parameters

stack | a GtkStack |

#### Returns

whether `stack` is homogeneous.

Since: 3.10

### gtk_stack_set_hhomogeneous ()

    void
    gtk_stack_set_hhomogeneous (GtkStack *stack,
                                gboolean hhomogeneous);

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

#### Parameters

stack | a GtkStack |
hhomogeneous | `TRUE` to make `stack` horizontally homogeneous |

Since: 3.16

### gtk_stack_get_hhomogeneous ()

    gboolean
    gtk_stack_get_hhomogeneous (GtkStack *stack);

Gets whether `stack` is horizontally homogeneous. See `gtk_stack_set_hhomogeneous()`.

#### Parameters

stack | a GtkStack |

#### Returns

whether `stack` is horizontally homogeneous.

Since: 3.16

### gtk_stack_set_vhomogeneous ()

    void
    gtk_stack_set_vhomogeneous (GtkStack *stack,
                                gboolean vhomogeneous);

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

#### Parameters

stack | a GtkStack |
vhomogeneous | `TRUE` to make `stack` vertically homogeneous |

Since: 3.16

### gtk_stack_get_vhomogeneous ()

    gboolean
    gtk_stack_get_vhomogeneous (GtkStack *stack);

Gets whether `stack` is vertically homogeneous. See `gtk_stack_set_vhomogeneous()`.

#### Parameters

stack | a GtkStack |

#### Returns

whether `stack` is vertically homogeneous.

Since: 3.16

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

#### Parameters

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.

#### Parameters

stack | a GtkStack |

#### Returns

the transition duration

Since: 3.10

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

#### Parameters

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

#### Parameters

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.

#### Parameters

stack | a GtkStack |

#### Returns

`TRUE` if the transition is currently running, `FALSE` otherwise.

Since: 3.12

### gtk_stack_get_interpolate_size ()

    gboolean
    gtk_stack_get_interpolate_size (GtkStack *stack);

Returns wether the GtkStack is set up to interpolate between the sizes of children on page switch.

#### Parameters

stack | A GtkStack |

#### Returns

`TRUE` if child sizes are interpolated

Since: 3.18

### gtk_stack_set_interpolate_size ()

    void
    gtk_stack_set_interpolate_size (GtkStack *stack,
                                    gboolean interpolate_size);

Sets whether or not `stack` will interpolate its size when changing the visible child. If the “interpolate-size” property is set to `TRUE`, `stack` will interpolate its size between the current one and the one it'll take after changing the visible child, according to the set transition duration.

#### Parameters

stack | A GtkStack |
interpolate_size | the new value |

Since: 3.18

## Types and Values

### struct GtkStack

    struct GtkStack;

### enum GtkStackTransitionType

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

New values may be added to this enumeration over time.

#### Members

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 sliding up or uncover the new page sliding down, according to order. Since: 3.12 |
GTK_STACK_TRANSITION_TYPE_OVER_DOWN_UP | Cover the old page sliding down or uncover the new page sliding up, according to order. Since: 3.14 |
GTK_STACK_TRANSITION_TYPE_OVER_LEFT_RIGHT | Cover the old page sliding left or uncover the new page sliding right, according to order. Since: 3.14 |
GTK_STACK_TRANSITION_TYPE_OVER_RIGHT_LEFT | Cover the old page sliding right or uncover the new page sliding left, according to order. Since: 3.14 |

## Property Details

### The `“hhomogeneous”` property

      “hhomogeneous”             gboolean

`TRUE` if the stack allocates the same width for all children.

Flags: Read / Write

Default value: TRUE

Since: 3.16

### The `“homogeneous”` property

      “homogeneous”              gboolean

Homogeneous sizing.

Flags: Read / Write

Default value: TRUE

### The `“interpolate-size”` property

      “interpolate-size”         gboolean

Whether or not the size should smoothly change when changing between differently sized children.

Flags: Read / Write

Default value: FALSE

### The `“transition-duration”` property

      “transition-duration”      guint

The animation duration, in milliseconds.

Flags: Read / Write

Default value: 200

### The `“transition-running”` property

      “transition-running”       gboolean

Whether or not the transition is currently running.

Flags: Read

Default value: FALSE

### The `“transition-type”` property

      “transition-type”          GtkStackTransitionType

The type of animation used to transition.

Flags: Read / Write

Default value: GTK_STACK_TRANSITION_TYPE_NONE

### The `“vhomogeneous”` property

      “vhomogeneous”             gboolean

`TRUE` if the stack allocates the same height for all children.

Flags: Read / Write

Default value: TRUE

Since: 3.16

### The `“visible-child”` property

      “visible-child”            GtkWidget *

The widget currently visible in the stack.

Flags: Read / Write

### The `“visible-child-name”` property

      “visible-child-name”       gchar *

The name of the widget currently visible in the stack.

Flags: Read / Write

Default value: NULL

## Child Property Details

### The `“icon-name”` child property

      “icon-name”                gchar *

The icon name of the child page.

Flags: Read / Write

Default value: NULL

### The `“name”` child property

      “name”                     gchar *

The name of the child page.

Flags: Read / Write

Default value: NULL

### The `“needs-attention”` child property

      “needs-attention”          gboolean

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.

Flags: Read / Write

Default value: FALSE

Since: 3.12

### The `“position”` child property

      “position”                 gint

The index of the child in the parent.

Flags: Read / Write

Allowed values: >= -1

Default value: 0

### The `“title”` child property

      “title”                    gchar *

The title of the child page.

Flags: Read / Write

Default value: NULL

## See Also

GtkNotebook, GtkStackSwitcher