XU XUv0.13.1
中文

UI / WIDGETS / Feedback

Popover

Show interactive content beside an anchor

Run the Xu example

The example executes in the browser using the Xu/WASM runtime.

What to try

Open preferences and apply a choice.

Usage notes

Show temporary interactive content beside an anchor. Distinguish apply from cancel; dismissing the popover should not commit an unconfirmed edit.

Create through Screen

The Screen constructor returns a node ID. Pass that ID to Screen layout, state and event APIs. It is separate from the standalone control object documented below.

Native Xu setup fragment: call configure during initialization of an existing Screen. See the complete example for window creation, event dispatch and cleanup.

#ui/widgets

fn configure(screen $&widgets.Screen) int {
    anchor := screen.button("Preferences") or >>
    screen.place(anchor,24.0,24.0,180.0,40.0) or >>
    id := screen.popover(anchor,"Preferences") or >>
    << id
}

($&Screen) popover

XuAPI
pub fn (s $&Screen) popover(anchor int,text string) int

Purpose

Create Popover in Screen and return the component node ID; throw on creation failure.

Parameters

s $&Screen
The Screen instance used by this call (exclusive borrow).
anchor int
anchor (int)
text string
text (string)

Returns

int — component node ID for place and other Screen methods.

Placement, state and events

The application owns the component. Screen.place positions nodes; Screen.set_enabled and Screen.set_visible control availability and visibility. Present again after state changes, handle or errors, and keep topology changes outside paint callbacks. ToastHost uses its own queue API.

Action · Styles · UI lifecycle and styling guide

Screen.place · Screen.set_enabled · Screen.set_visible

Standalone control object API

These types and methods support applications that manage control objects, input and painting directly. Their receiver is a control object, not a Screen node ID. For Screen usage, use the constructor above and the Screen methods in the Widgets module.

struct Popover

XuAPI
pub struct Popover {

}

Purpose

Anchored popover container attached to target element.

Public fields

This type has no public fields.

(&Popover) id

XuAPI
pub fn (p &Popover) id() int

Purpose

Return the unique integer ID of the element or control.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

int — a value of this type

(&Popover) bounds

XuAPI
pub fn (p &Popover) bounds() layout.Rect

Purpose

Return the bounding Rectangle of the control or geometry.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Popover) is_enabled

XuAPI
pub fn (p &Popover) is_enabled() bool

Purpose

Return whether the control is currently enabled.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

bool — true or false

(&Popover) is_selectable

XuAPI
pub fn (p &Popover) is_selectable() bool

Purpose

Operation on &Popover: whether it is selectable.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

bool — true or false

($&Popover) set_selectable

XuAPI
pub fn (p $&Popover) set_selectable(selectable bool)

Purpose

Operation on $&Popover: set selectable.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
selectable bool
selectable (bool)

Returns

This call does not return a value.

($&Popover) set_text

XuAPI
pub fn (p $&Popover) set_text(context &draw.Context,text &string) int

Purpose

Operation on $&Popover: set text. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
context &draw.Context
context (read-only borrow; caller keeps the original; type &draw.Context)
text &string
text (read-only borrow; caller keeps the original; type &string)

Returns

int — a value of this type

(&Popover) has_popup_open

XuAPI
pub fn (p &Popover) has_popup_open() bool

Purpose

Operation on &Popover: whether it has popup open.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

bool — true or false

(&Popover) popup_bounds

XuAPI
pub fn (p &Popover) popup_bounds() layout.Rect

Purpose

Operation on &Popover: popup bounds.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Popover) selected_text

XuAPI
pub fn (p &Popover) selected_text() string

Purpose

Operation on &Popover: selected text.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

string — result string

(&Popover) copy_selection

XuAPI
pub fn (p &Popover) copy_selection() int

Purpose

Operation on &Popover: copy selection.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

int — a value of this type

(&Popover) selection_range

XuAPI
pub fn (p &Popover) selection_range() ui.TextRange

Purpose

Operation on &Popover: selection range.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

ui.TextRange — a value of this type

(&Popover) cursor

XuAPI
pub fn (p &Popover) cursor() int

Purpose

Execute cursor on &Popover.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

int — a value of this type

($&Popover) set_viewport

XuAPI
pub fn (p $&Popover) set_viewport(viewport &layout.Rect)

Purpose

Operation on $&Popover: set viewport.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
viewport &layout.Rect
viewport (read-only borrow; caller keeps the original; type &layout.Rect)

Returns

This call does not return a value.

($&Popover) set_locale

XuAPI
pub fn (p $&Popover) set_locale(locale &Locale) int

Purpose

Operation on $&Popover: set locale. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
locale &Locale
locale (read-only borrow; caller keeps the original; type &Locale)

Returns

int — a value of this type

(&Popover) is_open

XuAPI
pub fn (p &Popover) is_open() bool

Purpose

Return whether the overlay, menu or dialog is currently open.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

bool — true or false

(&Popover) is_visible

XuAPI
pub fn (p &Popover) is_visible() bool

Purpose

Check whether the popover remains visible, including its exit transition.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

true while open or fading out, and false once fully hidden.

(&Popover) opacity

XuAPI
pub fn (p &Popover) opacity() f64

Purpose

Execute opacity on &Popover.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

f64 — a value of this type

(&Popover) needs_paint

XuAPI
pub fn (p &Popover) needs_paint() bool

Purpose

Return whether the control needs repainting; call painted after painting to clear the flag.

Parameters

p &Popover
The Popover instance used by this call (borrow).

Returns

bool — true or false

($&Popover) painted

XuAPI
pub fn (p $&Popover) painted()

Purpose

Acknowledge the painted frame and clear the dirty flag; this is not a query.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Popover) set_geometry

XuAPI
pub fn (p $&Popover) set_geometry(anchor &layout.Rect,size &layout.Size,viewport &layout.Rect) int

Purpose

Operation on $&Popover: set geometry. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
anchor &layout.Rect
anchor (read-only borrow; caller keeps the original; type &layout.Rect)
size &layout.Size
size (read-only borrow; caller keeps the original; type &layout.Size)
viewport &layout.Rect
viewport (read-only borrow; caller keeps the original; type &layout.Rect)

Returns

int — a value of this type

($&Popover) open

XuAPI
pub fn (p $&Popover) open(now time.Instant,reduced_motion bool) int

Purpose

Open the popover with its entrance animation; a disabled popover stays closed.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
now time.Instant
Current animation time.Instant; use the same time basis for opening, ticking and closing.
reduced_motion bool
Whether to reduce motion; true moves directly to the target state.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • Advance animation with tick each frame and use is_visible to decide whether painting must continue.

Error handling

  • Invalid animation parameters or state throw.

($&Popover) close

XuAPI
pub fn (p $&Popover) close(now time.Instant,reduced_motion bool) int

Purpose

Request closing with an exit animation; painting may continue briefly after logical closure.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
now time.Instant
Current animation time.Instant; use the same time basis for opening, ticking and closing.
reduced_motion bool
Whether to reduce motion; true moves directly to the target state.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • is_open() becomes false on the close request; is_visible() becomes false after the exit animation ends.

Error handling

  • Animation failures propagate.

($&Popover) set_enabled

XuAPI
pub fn (p $&Popover) set_enabled(enabled bool) int

Purpose

Operation on $&Popover: set enabled. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
enabled bool
enabled (bool)

Returns

int — a value of this type

($&Popover) tick

XuAPI
pub fn (p $&Popover) tick(now time.Instant,reduced_motion bool) bool

Purpose

Advance the fade animation to the current time and use the result to schedule repainting.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
now time.Instant
Current animation time.Instant; use the same time basis for opening, ticking and closing.
reduced_motion bool
Whether to reduce motion; true moves directly to the target state.

Returns

true when opacity changes, otherwise false.

Error handling

  • Invalid time or animation state throws.

(&Popover) next_tick

XuAPI
pub fn (p &Popover) next_tick(now time.Instant) time.Instant

Purpose

Operation on &Popover: next tick. Throws on failure; handle the error or propagate it to the caller.

Parameters

p &Popover
The Popover instance used by this call (borrow).
now time.Instant
now (time.Instant)

Returns

time.Instant — a value of this type

($&Popover) input

XuAPI
pub fn (p $&Popover) input(event &ui.InputEvent) Action

Purpose

Handle outside presses, Escape and cancellation according to the popover's dismissal settings.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
event &ui.InputEvent
Input event for the same window, canvas and generation, with coordinates in the control's canvas space.

Returns

An Action: kind identifies the action, consumed marks a handled event, request_focus requests focus, and needs_paint requests repainting.

Usage notes

  • Presses inside the anchor or panel are not outside dismissal; the caller continues dispatching interactions to panel content.

($&Popover) route

XuAPI
pub fn (p $&Popover) route(kind int,event &ui.InputEvent) Action

Purpose

Route and dispatch the input event to matching targets. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
kind int
kind tag (int)
event &ui.InputEvent
event (read-only borrow; caller keeps the original; type &ui.InputEvent)

Returns

Action — input result with kind, id, repaint and focus requests.

(&Popover) paint_styled

XuAPI
pub fn (p &Popover) paint_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Paint the popover panel background and border.

Parameters

p &Popover
The Popover instance used by this call (borrow).
frame $&draw.Frame
Current frame to receive drawing commands.
styles &Styles
Effective styles supplying colors, spacing, fonts and state appearance.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • The caller paints panel content; this call does not create, lay out or dispatch content controls.

Error handling

  • Drawing failures propagate.

($&Popover) paint_content_styled

XuAPI
pub fn (p $&Popover) paint_content_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Operation on $&Popover: paint content styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

int — a value of this type

($&Popover) paint_popup_styled

XuAPI
pub fn (p $&Popover) paint_popup_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Operation on $&Popover: paint popup styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

int — a value of this type

(&Popover) style_or

XuAPI
pub fn (p &Popover) style_or(styles &Styles) ControlStyle

Purpose

Operation on &Popover: style or.

Parameters

p &Popover
The Popover instance used by this call (borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

ControlStyle — a value of this type

($&Popover) set_style

XuAPI
pub fn (p $&Popover) set_style(style &ControlStyle) int

Purpose

Operation on $&Popover: set style. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
style &ControlStyle
style (read-only borrow; caller keeps the original; type &ControlStyle)

Returns

int — a value of this type

($&Popover) set_motion

XuAPI
pub fn (p $&Popover) set_motion(spec &MotionSpec) int

Purpose

Operation on $&Popover: set motion. Throws on failure; handle the error or propagate it to the caller.

Parameters

p $&Popover
The Popover instance used by this call (exclusive borrow).
spec &MotionSpec
spec (read-only borrow; caller keeps the original; type &MotionSpec)

Returns

int — a value of this type

($&Popover) set_placement

XuAPI
pub fn (panel $&Popover) set_placement(placement &OverlayPlacement) int

Purpose

Operation on $&Popover: set placement. Throws on failure; handle the error or propagate it to the caller.

Parameters

panel $&Popover
The Popover instance used by this call (exclusive borrow).
placement &OverlayPlacement
placement (read-only borrow; caller keeps the original; type &OverlayPlacement)

Returns

int — a value of this type

($&Popover) set_dismissal

XuAPI
pub fn (panel $&Popover) set_dismissal(outside bool,escape bool)

Purpose

Operation on $&Popover: set dismissal.

Parameters

panel $&Popover
The Popover instance used by this call (exclusive borrow).
outside bool
outside (bool)
escape bool
escape (bool)

Returns

This call does not return a value.

Complete native example

Component Workshop · Back to Widgets