Gtk.Stack¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

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, a separate widget such as StackSwitcher or StackSidebar can be used with GtkStack to provide this functionality.

Transitions between pages can be animated as slides or fades. This can be controlled with Stack.set_transition_type. These animations respect the Settings.gtk-enable-animations setting.

GtkStack maintains a StackPage object for each added child, which holds additional per-child properties. You obtain the GtkStackPage for a child with Stack.get_page and you can obtain a GtkSelectionModel containing all the pages with Stack.get_pages.

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 AccessibleRole.tab_panel role for the stack pages, which are the accessible parent objects of the child widgets.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new GtkStack.

Methods¶

add_child¶

def add_child(self, child: Widget) -> StackPage

Adds a child to stack.

Parameters:

child — the widget to add

add_named¶

def add_named(self, child: Widget, name: str | None = ...) -> StackPage

Adds a child to stack.

The child is identified by the name.

Parameters:

child — the widget to add
name — the name for child

add_titled¶

def add_titled(self, child: Widget, name: str | None, title: str) -> StackPage

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:

child — the widget to add
name — the name for child
title — a human-readable title for child

get_child_by_name¶

def get_child_by_name(self, name: str) -> Widget | None

Finds the child with the name given as the argument.

Returns None if there is no child with this name.

Parameters:

name — the name of the child to find

get_hhomogeneous¶

def get_hhomogeneous(self) -> bool

Gets whether stack is horizontally homogeneous.

get_interpolate_size¶

def get_interpolate_size(self) -> bool

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

get_page¶

def get_page(self, child: Widget) -> StackPage

Returns the GtkStackPage object for child.

Parameters:

child — a child of stack

get_pages¶

def get_pages(self) -> SelectionModel

Returns a GListModel that contains the pages of the stack.

This can be used to keep an up-to-date view. The model also implements SelectionModel and can be used to track and modify the visible page.

get_transition_duration¶

def get_transition_duration(self) -> int

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

get_transition_running¶

def get_transition_running(self) -> bool

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

get_transition_type¶

def get_transition_type(self) -> StackTransitionType

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

get_vhomogeneous¶

def get_vhomogeneous(self) -> bool

Gets whether stack is vertically homogeneous.

get_visible_child¶

def get_visible_child(self) -> Widget | None

Gets the currently visible child of stack.

Returns None if there are no visible children.

get_visible_child_name¶

def get_visible_child_name(self) -> str | None

Returns the name of the currently visible child of stack.

Returns None if there is no visible child.

remove¶

def remove(self, child: Widget) -> None

Removes a child widget from stack.

Parameters:

child — the child to remove

set_hhomogeneous¶

def set_hhomogeneous(self, hhomogeneous: bool) -> None

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:

hhomogeneous — True to make stack horizontally homogeneous

set_interpolate_size¶

def set_interpolate_size(self, interpolate_size: bool) -> None

Sets whether or not stack will interpolate its size when changing the visible child.

If the Stack.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:

interpolate_size — the new value

set_transition_duration¶

def set_transition_duration(self, duration: int) -> None

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

Parameters:

duration — the new duration, in milliseconds

set_transition_type¶

def set_transition_type(self, transition: StackTransitionType | int) -> None

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:

transition — the new transition type

set_vhomogeneous¶

def set_vhomogeneous(self, vhomogeneous: bool) -> None

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:

vhomogeneous — True to make stack vertically homogeneous

set_visible_child¶

def set_visible_child(self, child: Widget) -> None

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 Widget.show) in order to become the visible child of stack.

Parameters:

child — a child of stack

set_visible_child_full¶

def set_visible_child_full(self, name: str, transition: StackTransitionType | int) -> None

Makes the child with the given name visible.

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

Parameters:

name — the name of the child to make visible
transition — the transition type to use

set_visible_child_name¶

def set_visible_child_name(self, name: str) -> None

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 Widget.show) in order to become the visible child of stack.

Parameters:

name — the name of the child to make visible

Properties¶

hhomogeneous¶

hhomogeneous: bool  # read/write

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

interpolate_size¶

interpolate_size: bool  # read/write

Whether or not the size should smoothly change during the transition.

pages¶

pages: SelectionModel  # read-only

A selection model with the stack pages.

transition_duration¶

transition_duration: int  # read/write

The animation duration, in milliseconds.

transition_running¶

transition_running: bool  # read-only

Whether or not the transition is currently running.

transition_type¶

transition_type: StackTransitionType | int  # read/write

The type of animation used to transition.

vhomogeneous¶

vhomogeneous: bool  # read/write

True if the stack allocates the same height for all children.

visible_child¶

visible_child: Widget  # read/write

The widget currently visible in the stack.

visible_child_name¶

visible_child_name: str  # read/write

The name of the widget currently visible in the stack.