Gtk.Overlay¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

Places “overlay” widgets on top of a single main child.

The position of each overlay widget is determined by its Widget.halign and Widget.valign properties. E.g. a widget with both alignments set to Align.START will be placed at the top left corner of the GtkOverlay container, whereas an overlay with halign set to Align.CENTER and valign set to 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 Overlay.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¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new GtkOverlay.

Methods¶

add_overlay¶

def add_overlay(self, widget: Widget) -> None

Adds widget to overlay.

The widget will be stacked on top of the main widget added with Overlay.set_child.

The position at which widget is placed is determined from its Widget.halign and Widget.valign properties.

Parameters:

widget — a GtkWidget to be added to the container

get_child¶

def get_child(self) -> Widget | None

Gets the child widget of overlay.

get_clip_overlay¶

def get_clip_overlay(self, widget: Widget) -> bool

Gets whether widget should be clipped within the parent.

Parameters:

widget — an overlay child of GtkOverlay

get_measure_overlay¶

def get_measure_overlay(self, widget: Widget) -> bool

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

Parameters:

widget — an overlay child of GtkOverlay

remove_overlay¶

def remove_overlay(self, widget: Widget) -> None

Removes an overlay that was added with Overlay.add_overlay.

Parameters:

widget — a GtkWidget to be removed

set_child¶

def set_child(self, child: Widget | None = ...) -> None

Sets the child widget of overlay.

Parameters:

child — the child widget

set_clip_overlay¶

def set_clip_overlay(self, widget: Widget, clip_overlay: bool) -> None

Sets whether widget should be clipped within the parent.

Parameters:

widget — an overlay child of GtkOverlay
clip_overlay — whether the child should be clipped

set_measure_overlay¶

def set_measure_overlay(self, widget: 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 True. Children who are not included may be drawn outside of overlay's allocation if they are too large.

Parameters:

widget — an overlay child of GtkOverlay
measure — whether the child should be measured

Properties¶

child¶

child: Widget  # read/write

The main child widget.

Signals¶

get-child-position¶

def on_get_child_position(self, widget: Widget) -> bool: ...

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 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.