GtkStack

GtkStack — A stacking container

Functions

gboolean	gtk_stack_page_get_visible ()
void	gtk_stack_page_set_visible ()
const char *	gtk_stack_page_get_title ()
void	gtk_stack_page_set_title ()
const char *	gtk_stack_page_get_name ()
void	gtk_stack_page_set_name ()
gboolean	gtk_stack_page_get_needs_attention ()
void	gtk_stack_page_set_needs_attention ()
gboolean	gtk_stack_page_get_use_underline ()
void	gtk_stack_page_set_use_underline ()
const char *	gtk_stack_page_get_icon_name ()
void	gtk_stack_page_set_icon_name ()
GtkWidget *	gtk_stack_page_get_child ()
GtkWidget *	gtk_stack_new ()
GtkStackPage *	gtk_stack_add_child ()
GtkStackPage *	gtk_stack_add_named ()
GtkStackPage *	gtk_stack_add_titled ()
void	gtk_stack_remove ()
GtkWidget *	gtk_stack_get_child_by_name ()
GtkStackPage *	gtk_stack_get_page ()
GtkSelectionModel *	gtk_stack_get_pages ()
void	gtk_stack_set_visible_child ()
GtkWidget *	gtk_stack_get_visible_child ()
void	gtk_stack_set_visible_child_name ()
const char *	gtk_stack_get_visible_child_name ()
void	gtk_stack_set_visible_child_full ()
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

GtkWidget *	child	Read / Write / Construct Only
char *	icon-name	Read / Write
char *	name	Read / Write / Construct Only
gboolean	needs-attention	Read / Write
char *	title	Read / Write
gboolean	use-underline	Read / Write
gboolean	visible	Read / Write
gboolean	hhomogeneous	Read / Write
gboolean	interpolate-size	Read / Write
GtkSelectionModel *	pages	Read
guint	transition-duration	Read / Write
gboolean	transition-running	Read
GtkStackTransitionType	transition-type	Read / Write
gboolean	vhomogeneous	Read / Write
GtkWidget *	visible-child	Read / Write
char *	visible-child-name	Read / Write

Types and Values

	GtkStackPage
	GtkStack
enum	GtkStackTransitionType

Object Hierarchy

    GObject
    ├── GInitiallyUnowned
    │   ╰── GtkWidget
    │       ╰── GtkStack
    ╰── GtkStackPage

Implemented Interfaces

GtkStackPage implements GtkAccessible.

GtkStack implements GtkAccessible, GtkBuildable and GtkConstraintTarget.

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.

GtkStack maintains a GtkStackPage object for each added child, which holds additional per-child properties. You obtain the GtkStackPage for a child with gtk_stack_get_page().

GtkStack as GtkBuildable

To set child-specific properties in a .ui file, create GtkStackPage objects explicitly, and set the child widget as a property on it:

<object class="GtkStack" id="stack">
  <child>
    <object class="GtkStackPage">
      <property name="name">page1</property>
      <property name="title">In the beginning…</property>
      <property name="child">
        <object class="GtkLabel">
          <property name="label">It was dark</property>
        </object>
      </property>
    </object>
  </child>

CSS nodes

GtkStack has a single CSS node named stack.

Accessibility

GtkStack uses the GTK_ACCESSIBLE_ROLE_TAB_PANEL for the stack pages, which are the accessible parent objects of the child widgets.

Functions

gtk_stack_page_get_visible ()

gboolean
gtk_stack_page_get_visible (GtkStackPage *self);

Returns whether page is visible in its GtkStack. This is independent from the “visible” value of its GtkWidget.

Parameters

self

a GtkStackPage

Returns

TRUE if page is visible

gtk_stack_page_set_visible ()

void
gtk_stack_page_set_visible (GtkStackPage *self,
                            gboolean visible);

Sets the new value of the “visible” property to visible .

Parameters

self	a GtkStackPage
visible	The new property value

gtk_stack_page_get_title ()

const char *
gtk_stack_page_get_title (GtkStackPage *self);

Returns the current value of the “title” property.

Parameters

self

a GtkStackPage

Returns

The value of the “title” property. See gtk_stack_page_set_title() for details on how to set a new value.

[nullable]

gtk_stack_page_set_title ()

void
gtk_stack_page_set_title (GtkStackPage *self,
                          const char *setting);

Sets the new value of the “title” property. See also gtk_stack_page_get_title()

Parameters

self	a GtkStackPage
setting	the new value to set.	[transfer none]

gtk_stack_page_get_name ()

const char *
gtk_stack_page_get_name (GtkStackPage *self);

Returns the current value of the “name” property.

Parameters

self

a GtkStackPage

Returns

The value of the “name” property. See gtk_stack_page_set_name() for details on how to set a new value.

[nullable]

gtk_stack_page_set_name ()

void
gtk_stack_page_set_name (GtkStackPage *self,
                         const char *setting);

Sets the new value of the “name” property. See also gtk_stack_page_get_name()

Parameters

self	a GtkStackPage
setting	the new value to set.	[transfer none]

gtk_stack_page_get_needs_attention ()

gboolean
gtk_stack_page_get_needs_attention (GtkStackPage *self);

Returns the current value of the “needs-attention” property.

Parameters

self

a GtkStackPage

Returns

The value of the “needs-attention” property. See gtk_stack_page_set_needs_attention() for details on how to set a new value.

gtk_stack_page_set_needs_attention ()

void
gtk_stack_page_set_needs_attention (GtkStackPage *self,
                                    gboolean setting);

Sets the new value of the “needs-attention” property. See also gtk_stack_page_get_needs_attention()

Parameters

self	a GtkStackPage
setting	the new value to set

gtk_stack_page_get_use_underline ()

gboolean
gtk_stack_page_get_use_underline (GtkStackPage *self);

Returns the current value of the “use-underline” property.

Parameters

self

a GtkStackPage

Returns

The value of the “use-underline” property. See gtk_stack_page_set_use_underline() for details on how to set a new value.

gtk_stack_page_set_use_underline ()

void
gtk_stack_page_set_use_underline (GtkStackPage *self,
                                  gboolean setting);

Sets the new value of the “use-underline” property. See also gtk_stack_page_get_use_underline()

Parameters

self	a GtkStackPage
setting	the new value to set

gtk_stack_page_get_icon_name ()

const char *
gtk_stack_page_get_icon_name (GtkStackPage *self);

Returns the current value of the “icon-name” property.

Parameters

self

a GtkStackPage

Returns

The value of the “icon-name” property. See gtk_stack_page_set_icon_name() for details on how to set a new value.

[nullable]

gtk_stack_page_set_icon_name ()

void
gtk_stack_page_set_icon_name (GtkStackPage *self,
                              const char *setting);

Sets the new value of the “icon-name” property. See also gtk_stack_page_get_icon_name()

Parameters

self	a GtkStackPage
setting	the new value to set.	[transfer none]

gtk_stack_page_get_child ()

GtkWidget *
gtk_stack_page_get_child (GtkStackPage *self);

Returns the stack child to which self belongs.

Parameters

self

a GtkStackPage

Returns

the child to which self belongs.

[transfer none]

gtk_stack_new ()

GtkWidget *
gtk_stack_new (void);

Creates a new GtkStack container.

Returns

a new GtkStack

gtk_stack_add_child ()

GtkStackPage *
gtk_stack_add_child (GtkStack *stack,
                     GtkWidget *child);

Adds a child to stack .

Parameters

stack	a GtkStack
child	the widget to add

Returns

the GtkStackPage for child .

[transfer none]

gtk_stack_add_named ()

GtkStackPage *
gtk_stack_add_named (GtkStack *stack,
                     GtkWidget *child,
                     const char *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` or `NULL`.	[nullable]

Returns

the GtkStackPage for child .

[transfer none]

gtk_stack_add_titled ()

GtkStackPage *
gtk_stack_add_titled (GtkStack *stack,
                      GtkWidget *child,
                      const char *name,
                      const char *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` .	[nullable]
title	a human-readable title for `child`

Returns

the GtkStackPage for child .

[transfer none]

gtk_stack_remove ()

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

Removes a child widget from stack .

Parameters

stack	a GtkStack
child	the child to remove

gtk_stack_get_child_by_name ()

GtkWidget *
gtk_stack_get_child_by_name (GtkStack *stack,
                             const char *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]

gtk_stack_get_page ()

GtkStackPage *
gtk_stack_get_page (GtkStack *stack,
                    GtkWidget *child);

Returns the GtkStackPage object for child .

Parameters

stack	a GtkStack
child	a child of `stack`

Returns

the GtkStackPage for child .

[transfer none]

gtk_stack_get_pages ()

GtkSelectionModel *
gtk_stack_get_pages (GtkStack *stack);

Returns a GListModel that contains the pages of the stack, and can be used to keep an up-to-date view. The model also implements GtkSelectionModel and can be used to track and modify the visible page.

Parameters

stack

a GtkStack

Returns

a GtkSelectionModel for the stack's children.

[transfer full]

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`

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]

gtk_stack_set_visible_child_name ()

void
gtk_stack_set_visible_child_name (GtkStack *stack,
                                  const char *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

gtk_stack_get_visible_child_name ()

const char *
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]

gtk_stack_set_visible_child_full ()

void
gtk_stack_set_visible_child_full (GtkStack *stack,
                                  const char *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

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

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.

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

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.

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

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

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

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

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.

gtk_stack_get_interpolate_size ()

gboolean
gtk_stack_get_interpolate_size (GtkStack *stack);

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

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

Types and Values

GtkStackPage

typedef struct _GtkStackPage GtkStackPage;

GtkStack

typedef struct _GtkStack 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
GTK_STACK_TRANSITION_TYPE_OVER_DOWN	Cover the old page by sliding down
GTK_STACK_TRANSITION_TYPE_OVER_LEFT	Cover the old page by sliding to the left
GTK_STACK_TRANSITION_TYPE_OVER_RIGHT	Cover the old page by sliding to the right
GTK_STACK_TRANSITION_TYPE_UNDER_UP	Uncover the new page by sliding up
GTK_STACK_TRANSITION_TYPE_UNDER_DOWN	Uncover the new page by sliding down
GTK_STACK_TRANSITION_TYPE_UNDER_LEFT	Uncover the new page by sliding to the left
GTK_STACK_TRANSITION_TYPE_UNDER_RIGHT	Uncover the new page by sliding to the right
GTK_STACK_TRANSITION_TYPE_OVER_UP_DOWN	Cover the old page sliding up or uncover the new page sliding down, according to order
GTK_STACK_TRANSITION_TYPE_OVER_DOWN_UP	Cover the old page sliding down or uncover the new page sliding up, according to order
GTK_STACK_TRANSITION_TYPE_OVER_LEFT_RIGHT	Cover the old page sliding left or uncover the new page sliding right, according to order
GTK_STACK_TRANSITION_TYPE_OVER_RIGHT_LEFT	Cover the old page sliding right or uncover the new page sliding left, according to order
GTK_STACK_TRANSITION_TYPE_ROTATE_LEFT	Pretend the pages are sides of a cube and rotate that cube to the left
GTK_STACK_TRANSITION_TYPE_ROTATE_RIGHT	Pretend the pages are sides of a cube and rotate that cube to the right
GTK_STACK_TRANSITION_TYPE_ROTATE_LEFT_RIGHT	Pretend the pages are sides of a cube and rotate that cube to the left or right according to the children order

Property Details

The `“child”` property

  “child”                    GtkWidget *

The child of the page.

Owner: GtkStackPage

Flags: Read / Write / Construct Only

The `“icon-name”` property

  “icon-name”                char *

The icon name of the child page.

Owner: GtkStackPage

Flags: Read / Write

Default value: NULL

The `“name”` property

  “name”                     char *

The name of the child page.

Owner: GtkStackPage

Flags: Read / Write / Construct Only

Default value: NULL

The `“needs-attention”` property

  “needs-attention”          gboolean

Sets a flag specifying whether the page 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.

Owner: GtkStackPage

Flags: Read / Write

Default value: FALSE

The `“title”` property

  “title”                    char *

The title of the child page.

Owner: GtkStackPage

Flags: Read / Write

Default value: NULL

The `“use-underline”` property

  “use-underline”            gboolean

If set, an underline in the title indicates the next character should be used for the mnemonic accelerator key.

Owner: GtkStackPage

Flags: Read / Write

Default value: FALSE

The `“visible”` property

  “visible”                  gboolean

Whether this page is visible.

Owner: GtkStackPage

Flags: Read / Write

Default value: TRUE

The `“hhomogeneous”` property

  “hhomogeneous”             gboolean

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

Owner: GtkStack

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.

Owner: GtkStack

Flags: Read / Write

Default value: FALSE

The `“pages”` property

  “pages”                    GtkSelectionModel *

A selection model with the stacks pages.

Owner: GtkStack

Flags: Read

The `“transition-duration”` property

  “transition-duration”      guint

The animation duration, in milliseconds.

Owner: GtkStack

Flags: Read / Write

Default value: 200

The `“transition-running”` property

  “transition-running”       gboolean

Whether or not the transition is currently running.

Owner: GtkStack

Flags: Read

Default value: FALSE

The `“transition-type”` property

  “transition-type”          GtkStackTransitionType

The type of animation used to transition.

Owner: GtkStack

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.

Owner: GtkStack

Flags: Read / Write

Default value: TRUE

The `“visible-child”` property

  “visible-child”            GtkWidget *

The widget currently visible in the stack.

Owner: GtkStack

Flags: Read / Write

The `“visible-child-name”` property

  “visible-child-name”       char *

The name of the widget currently visible in the stack.

Owner: GtkStack

Flags: Read / Write

Default value: NULL