Gdk.PopupLayout¶

record (struct)

Contains information that is necessary position a Popup relative to its parent.

The positioning requires a negotiation with the windowing system, since it depends on external constraints, such as the position of the parent surface, and the screen dimensions.

The basic ingredients are a rectangle on the parent surface, and the anchor on both that rectangle and the popup. The anchors specify a side or corner to place next to each other.

Popup anchors

For cases where placing the anchors next to each other would make the popup extend offscreen, the layout includes some hints for how to resolve this problem. The hints may suggest to flip the anchor position to the other side, or to 'slide' the popup along a side, or to resize it.

Flipping popups

Sliding popups

These hints may be combined.

Ultimatively, it is up to the windowing system to determine the position and size of the popup. You can learn about the result by calling Popup.get_position_x, Popup.get_position_y, Popup.get_rect_anchor and Popup.get_surface_anchor after the popup has been presented. This can be used to adjust the rendering. For example, GtkPopover changes its arrow position accordingly. But you have to be careful avoid changing the size of the popover, or it has to be presented again.

Constructors¶

new¶

@classmethod
def new(cls, anchor_rect: Rectangle, rect_anchor: Gravity | int, surface_anchor: Gravity | int) -> PopupLayout

Create a popup layout description.

Used together with Popup.present to describe how a popup surface should be placed and behave on-screen.

anchor_rect is relative to the top-left corner of the surface's parent. rect_anchor and surface_anchor determine anchor points on anchor_rect and surface to pin together.

The position of anchor_rect's anchor point can optionally be offset using PopupLayout.set_offset, which is equivalent to offsetting the position of surface.

Parameters:

anchor_rect — the anchor rectangle to align surface with
rect_anchor — the point on anchor_rect to align with surface's anchor point
surface_anchor — the point on surface to align with rect's anchor point

Methods¶

copy¶

def copy(self) -> PopupLayout

Makes a copy of layout.

equal¶

def equal(self, other: PopupLayout) -> bool

Check whether layout and other has identical layout properties.

Parameters:

other — another popup layout

get_anchor_hints¶

def get_anchor_hints(self) -> AnchorHints

Get the anchor hints.

get_anchor_rect¶

def get_anchor_rect(self) -> Rectangle

Get the anchor rectangle.

get_offset¶

def get_offset(self) -> tuple[int, int]

Retrieves the offset for the anchor rectangle.

get_rect_anchor¶

def get_rect_anchor(self) -> Gravity

Returns the anchor position on the anchor rectangle.

get_shadow_width¶

def get_shadow_width(self) -> tuple[int, int, int, int]

Obtains the shadow widths of this layout.

get_surface_anchor¶

def get_surface_anchor(self) -> Gravity

Returns the anchor position on the popup surface.

ref¶

def ref(self) -> PopupLayout

Increases the reference count of value.

set_anchor_hints¶

def set_anchor_hints(self, anchor_hints: AnchorHints | int) -> None

Set new anchor hints.

The set anchor_hints determines how surface will be moved if the anchor points cause it to move off-screen. For example, GDK_ANCHOR_FLIP_X will replace GDK_GRAVITY_NORTH_WEST with GDK_GRAVITY_NORTH_EAST and vice versa if surface extends beyond the left or right edges of the monitor.

Parameters:

anchor_hints — the new anchor hints

set_anchor_rect¶

def set_anchor_rect(self, anchor_rect: Rectangle) -> None

Set the anchor rectangle.

Parameters:

anchor_rect — the new anchor rectangle

set_offset¶

def set_offset(self, dx: int, dy: int) -> None

Offset the position of the anchor rectangle with the given delta.

Parameters:

dx — x delta to offset the anchor rectangle with
dy — y delta to offset the anchor rectangle with

set_rect_anchor¶

def set_rect_anchor(self, anchor: Gravity | int) -> None

Set the anchor on the anchor rectangle.

Parameters:

anchor — the new rect anchor

set_shadow_width¶

def set_shadow_width(self, left: int, right: int, top: int, bottom: int) -> None

Sets the shadow width of the popup.

The shadow width corresponds to the part of the computed surface size that would consist of the shadow margin surrounding the window, would there be any.

Parameters:

left — width of the left part of the shadow
right — width of the right part of the shadow
top — height of the top part of the shadow
bottom — height of the bottom part of the shadow

set_surface_anchor¶

def set_surface_anchor(self, anchor: Gravity | int) -> None

Set the anchor on the popup surface.

Parameters:

anchor — the new popup surface anchor

unref¶

def unref(self) -> None

Decreases the reference count of value.