: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 type of the None singleton.











Signals
-------

.. rst-class:: interim-class

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

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

      The type of the None singleton.







      :param widget: the child widget to position