Struct PopupOptions 

pub struct PopupOptions {
    pub parent: AnyWindowHandle,
    pub anchor_rect: Bounds<Pixels>,
    pub anchor: PopupAnchor,
    pub gravity: PopupGravity,
    pub constraint_adjustment: PopupConstraintAdjustment,
    pub offset: Point<Pixels>,
    pub grab: bool,
}

Describes where a native popup goes, relative to a rectangle on its parent window.

Use a popup for menus, comboboxes, context menus and tooltips that should be able to leave the parent window’s bounds. Use an in-window element for everything else. Pass the popup to WindowKind::AnchoredPopup in WindowOptions::kind.

The popup is placed relative to anchor_rect rather than at an absolute screen position. The platform resolves the final position. That works on Wayland, where the compositor places windows, and on platforms with absolute coordinates.

The popup’s size comes from window_bounds in WindowOptions. Wayland uses only the size, not the origin. All coordinates are in logical pixels.

Native popups are available on Wayland only. On macOS, Windows, X11 and the web, opening one returns a PopupNotSupportedError and you can draw the same content in the window instead.

Pass the parent window and anchor rectangle to PopupOptions::new, then chain setters to configure placement and input grabbing.

Examples

use gpui::popup::{PopupAnchor, PopupGravity, PopupOptions};
// A dropdown below a button whose bounds are `anchor_rect`.
let anchor_rect = Bounds::new(point(px(10.), px(20.)), size(px(80.), px(24.)));
let options = PopupOptions::new(parent, anchor_rect)
    .anchor(PopupAnchor::BottomLeft)
    .gravity(PopupGravity::BottomRight)
    .grab(true);

assert_eq!(options.anchor, PopupAnchor::BottomLeft);
assert_eq!(options.gravity, PopupGravity::BottomRight);
assert!(options.grab);

Fields

parent: AnyWindowHandle

The window the popup is anchored to.

anchor_rect: Bounds<Pixels>

The rectangle the popup is positioned relative to, in the parent window’s coordinate space (the same space element bounds are in). For example, a dropdown menu uses the bounds of the button that opened it.

anchor: PopupAnchor

Which point of Self::anchor_rect the popup is anchored to.

gravity: PopupGravity

The direction in which the popup extends away from the anchor point. A dropdown that drops below its button anchors to PopupAnchor::BottomLeft with a gravity of PopupGravity::BottomRight so it grows down and to the right.

constraint_adjustment: PopupConstraintAdjustment

How the platform may adjust the popup if the requested placement would put it off-screen.

offset: Point<Pixels>

An additional offset applied to the popup after anchoring.

grab: bool

Whether the popup should take an explicit input grab.

Grabbing popups behave like menus: they take keyboard focus and are dismissed when the user clicks outside of them or presses a dismissing key. Use it for menus and comboboxes, not for tooltips or other passive popups.

On Wayland, the grab uses the serial of the most recent mouse or key press, so open a grabbing popup in response to a press. If the window hasn’t received a press yet, the popup opens without a grab.

Automatic dismissal only covers input aimed at other applications. A click elsewhere in your own application still reaches it as usual, so closing the popup in that case is up to you. Nested grabbing popups must be closed in the reverse order they were opened.

Implementations

impl PopupOptions

pub fn parent(self, value: impl Into<AnyWindowHandle>) -> Self

Sets the parent field of this struct.

pub fn anchor_rect(self, value: impl Into<Bounds<Pixels>>) -> Self

Sets the anchor_rect field of this struct.

pub fn anchor(self, value: impl Into<PopupAnchor>) -> Self

Sets the anchor field of this struct.

pub fn gravity(self, value: impl Into<PopupGravity>) -> Self

Sets the gravity field of this struct.

pub fn constraint_adjustment( self, value: impl Into<PopupConstraintAdjustment>, ) -> Self

Sets the constraint_adjustment field of this struct.

pub fn offset(self, value: impl Into<Point<Pixels>>) -> Self

Sets the offset field of this struct.

pub fn grab(self, value: impl Into<bool>) -> Self

Sets the grab field of this struct.

impl PopupOptions

pub fn new( parent: impl Into<AnyWindowHandle>, anchor_rect: Bounds<Pixels>, ) -> Self

Creates popup options for a parent window and anchor rectangle.

Defaults to centered placement, zero offset, no constraint adjustments, and no input grab.

Trait Implementations

impl Clone for PopupOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PopupOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for PopupOptions

impl FluentBuilder for PopupOptions

fn map<U>(self, f: impl FnOnce(Self) -> U) -> U

where Self: Sized,

Passes self to f, and returns the result. Use it to continue a chain with a closure.

fn when(self, condition: bool, then: impl FnOnce(Self) -> Self) -> Self

where Self: Sized,

Calls then with self if condition is true. Otherwise returns self unchanged.

fn when_else( self, condition: bool, then: impl FnOnce(Self) -> Self, else_fn: impl FnOnce(Self) -> Self, ) -> Self

where Self: Sized,

Calls then with self if condition is true, and else_fn with self otherwise.

fn when_some<T>( self, option: Option<T>, then: impl FnOnce(Self, T) -> Self, ) -> Self

where Self: Sized,

Calls then with self and the value inside option if the option is Some. Returns self unchanged for None.

fn when_none<T>( self, option: &Option<T>, then: impl FnOnce(Self) -> Self, ) -> Self

where Self: Sized,

Calls then with self if option is None. The option is taken by reference, so you can still use it afterward.

impl PartialEq for PopupOptions

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PopupOptions