:right-sidebar: True

Overlay
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Overlay(**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`



``GtkOverlay`` is a container which contains a single main child, on top
of which it can place “overlay” widgets.


.. image:: https://docs.gtk.org/gtk4/overlay.png


The position of each overlay widget is determined by its
:obj:`~gi.repository.Gtk.Widget.props.halign` and :obj:`~gi.repository.Gtk.Widget.props.valign`
properties. E.g. a widget with both alignments set to :const:`~gi.repository.Gtk.Align.START`
will be placed at the top left corner of the ``GtkOverlay`` container,
whereas an overlay with halign set to :const:`~gi.repository.Gtk.Align.CENTER` and valign set
to :const:`~gi.repository.Gtk.Align.END` will be placed a the bottom edge of the ``GtkOverlay``,
horizontally centered. The position can be adjusted by setting the margin
properties of the child to non-zero values.

More complicated placement of overlays is possible by connecting
to the :obj:`~gi.repository.Gtk.Overlay.signals.get_child_position` signal.

An overlay’s minimum and natural sizes are those of its main child.
The sizes of overlay children are not considered when measuring these
preferred sizes.

GtkOverlay as GtkBuildable
--------------------------

The ``GtkOverlay`` implementation of the ``GtkBuildable`` interface
supports placing a child as an overlay by specifying “overlay” as
the “type” attribute of a ``<child>`` element.

CSS nodes
---------

``GtkOverlay`` has a single CSS node with the name “overlay”. Overlay children
whose alignments cause them to be positioned at an edge get the style classes
“.left”, “.right”, “.top”, and/or “.bottom” according to their position.



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

.. rst-class:: interim-class

.. class:: Overlay
   :no-index:


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

      Creates a new ``GtkOverlay``.














Methods
-------

.. rst-class:: interim-class

.. class:: Overlay
   :no-index:


   .. method:: add_overlay(widget: ~gi.repository.Gtk.Widget) -> None

      Adds ``widget`` to ``overlay``.

      The widget will be stacked on top of the main widget
      added with :obj:`~gi.repository.Gtk.Overlay.set_child`.

      The position at which ``widget`` is placed is determined
      from its :obj:`~gi.repository.Gtk.Widget.props.halign` and
      :obj:`~gi.repository.Gtk.Widget.props.valign` properties.







      :param widget: a ``GtkWidget`` to be added to the container





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

      Gets the child widget of ``overlay``.










   .. method:: get_clip_overlay(widget: ~gi.repository.Gtk.Widget) -> bool

      Gets whether ``widget`` should be clipped within the parent.







      :param widget: an overlay child of ``GtkOverlay``





   .. method:: get_measure_overlay(widget: ~gi.repository.Gtk.Widget) -> bool

      Gets whether ``widget``'s size is included in the measurement of
      ``overlay``.







      :param widget: an overlay child of ``GtkOverlay``





   .. method:: remove_overlay(widget: ~gi.repository.Gtk.Widget) -> None

      Removes an overlay that was added with :func:`~gi.repository.Gtk.Overlay.add_overlay`.







      :param widget: a ``GtkWidget`` to be removed





   .. method:: set_child(child: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the child widget of ``overlay``.







      :param child: the child widget





   .. method:: set_clip_overlay(widget: ~gi.repository.Gtk.Widget, clip_overlay: bool) -> None

      Sets whether ``widget`` should be clipped within the parent.







      :param widget: an overlay child of ``GtkOverlay``


      :param clip_overlay: whether the child should be clipped





   .. method:: set_measure_overlay(widget: ~gi.repository.Gtk.Widget, measure: bool) -> None

      Sets whether ``widget`` is included in the measured size of ``overlay``.

      The overlay will request the size of the largest child that has
      this property set to :const:`True`. Children who are not included may
      be drawn outside of ``overlay``'s allocation if they are too large.







      :param widget: an overlay child of ``GtkOverlay``


      :param measure: whether the child should be measured









Properties
----------

.. rst-class:: interim-class

.. class:: Overlay
   :no-index:
   

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

      The main child widget.











Signals
-------

.. rst-class:: interim-class

.. class:: Overlay.signals
   :no-index:
   

   .. method:: get_child_position(widget: ~gi.repository.Gtk.Widget) -> tuple[bool, ~gi.repository.Gdk.Rectangle]

      Emitted to determine the position and size of any overlay
      child widgets.

      A handler for this signal should fill ``allocation`` with
      the desired position and size for ``widget``, relative to
      the 'main' child of ``overlay``.

      The default handler for this signal uses the ``widget``'s
      halign and valign properties to determine the position
      and gives the widget its natural size (except that an
      alignment of :const:`~gi.repository.Gtk.Align.FILL` will cause the overlay to
      be full-width/height). If the main child is a
      ``GtkScrolledWindow``, the overlays are placed relative
      to its contents.







      :param widget: the child widget to position