:right-sidebar: True

Stack
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Stack(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



``GtkStack`` 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, a separate widget
such as :obj:`~gi.repository.Gtk.StackSwitcher` or :obj:`~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.Stack.set_transition_type`.
These animations respect the :obj:`~gi.repository.Gtk.Settings.props.gtk_enable_animations`
setting.

``GtkStack`` maintains a :obj:`~gi.repository.Gtk.StackPage` object for each added
child, which holds additional per-child properties. You
obtain the ``GtkStackPage`` for a child with :obj:`~gi.repository.Gtk.Stack.get_page`
and you can obtain a ``GtkSelectionModel`` containing all the pages
with :obj:`~gi.repository.Gtk.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:


.. code-block::
   :dedent:

     <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 :const:`~gi.repository.Gtk.AccessibleRole.TAB_PANEL` for the stack
pages, which are the accessible parent objects of the child widgets.



Constructors
------------

.. rst-class:: interim-class

.. class:: Stack
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkStack``.














Methods
-------

.. rst-class:: interim-class

.. class:: Stack
   :no-index:


   .. method:: add_child(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.StackPage

      Adds a child to ``stack``.







      :param child: the widget to add





   .. method:: add_named(child: ~gi.repository.Gtk.Widget, name: str | None = None) -> ~gi.repository.Gtk.StackPage

      Adds a child to ``stack``.

      The child is identified by the ``name``.







      :param child: the widget to add


      :param name: the name for ``child``





   .. method:: add_titled(child: ~gi.repository.Gtk.Widget, name: str | None, title: str) -> ~gi.repository.Gtk.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.







      :param child: the widget to add


      :param name: the name for ``child``


      :param title: a human-readable title for ``child``





   .. method:: get_child_by_name(name: str) -> ~gi.repository.Gtk.Widget | None

      Finds the child with the name given as the argument.

      Returns :const:`None` if there is no child with this name.







      :param name: the name of the child to find





   .. method:: get_hhomogeneous() -> bool

      Gets whether ``stack`` is horizontally homogeneous.










   .. method:: get_interpolate_size() -> bool

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










   .. method:: get_page(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.StackPage

      Returns the ``GtkStackPage`` object for ``child``.







      :param child: a child of ``stack``





   .. method:: get_pages() -> ~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.SelectionModel` and can be used to track
      and modify the visible page.










   .. method:: get_transition_duration() -> int

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










   .. method:: get_transition_running() -> bool

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










   .. method:: get_transition_type() -> ~gi.repository.Gtk.StackTransitionType

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










   .. method:: get_vhomogeneous() -> bool

      Gets whether ``stack`` is vertically homogeneous.










   .. method:: get_visible_child() -> ~gi.repository.Gtk.Widget | None

      Gets the currently visible child of ``stack``.

      Returns :const:`None` if there are no visible children.










   .. method:: get_visible_child_name() -> str | None

      Returns the name of the currently visible child of ``stack``.

      Returns :const:`None` if there is no visible child.










   .. method:: remove(child: ~gi.repository.Gtk.Widget) -> None

      Removes a child widget from ``stack``.







      :param child: the child to remove





   .. method:: set_hhomogeneous(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.







      :param hhomogeneous: :const:`True` to make ``stack`` horizontally homogeneous





   .. method:: set_interpolate_size(interpolate_size: bool) -> None

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

      If the :obj:`~gi.repository.Gtk.Stack.props.interpolate_size` property is set
      to :const:`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.







      :param interpolate_size: the new value





   .. method:: set_transition_duration(duration: int) -> None

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







      :param duration: the new duration, in milliseconds





   .. method:: set_transition_type(transition: ~gi.repository.Gtk.StackTransitionType) -> 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.







      :param transition: the new transition type





   .. method:: set_vhomogeneous(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.







      :param vhomogeneous: :const:`True` to make ``stack`` vertically homogeneous





   .. method:: set_visible_child(child: ~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.Widget.show`) in order to become the visible
      child of ``stack``.







      :param child: a child of ``stack``





   .. method:: set_visible_child_full(name: str, transition: ~gi.repository.Gtk.StackTransitionType) -> None

      Makes the child with the given name visible.

      Note that the child widget has to be visible itself
      (see :obj:`~gi.repository.Gtk.Widget.show`) in order to become the visible
      child of ``stack``.







      :param name: the name of the child to make visible


      :param transition: the transition type to use





   .. method:: set_visible_child_name(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 :obj:`~gi.repository.Gtk.Widget.show`) in order to become the visible
      child of ``stack``.







      :param name: the name of the child to make visible









Properties
----------

.. rst-class:: interim-class

.. class:: Stack
   :no-index:
   

   .. attribute:: props.hhomogeneous
      :type: bool

      :const:`True` if the stack allocates the same width for all children.







   .. attribute:: props.interpolate_size
      :type: bool

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







   .. attribute:: props.pages
      :type: ~gi.repository.Gtk.SelectionModel

      A selection model with the stack pages.







   .. attribute:: props.transition_duration
      :type: int

      The animation duration, in milliseconds.







   .. attribute:: props.transition_running
      :type: bool

      Whether or not the transition is currently running.







   .. attribute:: props.transition_type
      :type: ~gi.repository.Gtk.StackTransitionType

      The type of animation used to transition.







   .. attribute:: props.vhomogeneous
      :type: bool

      :const:`True` if the stack allocates the same height for all children.







   .. attribute:: props.visible_child
      :type: ~gi.repository.Gtk.Widget

      The widget currently visible in the stack.







   .. attribute:: props.visible_child_name
      :type: str

      The name of the widget currently visible in the stack.