Trait StatefulInteractiveElement 

pub trait StatefulInteractiveElement: InteractiveElement {
    // Provided methods
    fn role(self, role: Role) -> Self { ... }
    fn accessibility_id(self, id: impl Into<SharedString>) -> Self { ... }
    fn aria_label(self, label: impl Into<SharedString>) -> Self { ... }
    fn aria_description(self, description: impl Into<SharedString>) -> Self { ... }
    fn aria_keyshortcuts(self, keyshortcuts: impl Into<SharedString>) -> Self { ... }
    fn aria_hidden(self) -> Self { ... }
    fn aria_active_descendant(self) -> Self { ... }
    fn a11y_synthetic_children(
        self,
        f: impl FnOnce(&mut A11ySubtreeBuilder<'_>) + 'static,
    ) -> Self { ... }
    fn aria_selected(self, selected: bool) -> Self { ... }
    fn aria_expanded(self, expanded: bool) -> Self { ... }
    fn aria_toggled(self, toggled: Toggled) -> Self { ... }
    fn aria_disabled(self, disabled: bool) -> Self { ... }
    fn aria_numeric_value(self, value: f64) -> Self { ... }
    fn aria_numeric_value_step(self, step: f64) -> Self { ... }
    fn aria_value(self, value: impl Into<SharedString>) -> Self { ... }
    fn aria_placeholder(self, placeholder: impl Into<SharedString>) -> Self { ... }
    fn aria_min_numeric_value(self, value: f64) -> Self { ... }
    fn aria_max_numeric_value(self, value: f64) -> Self { ... }
    fn aria_orientation(self, orientation: Orientation) -> Self { ... }
    fn aria_level(self, level: usize) -> Self { ... }
    fn aria_position_in_set(self, position: usize) -> Self { ... }
    fn aria_size_of_set(self, size: usize) -> Self { ... }
    fn aria_row_index(self, index: usize) -> Self { ... }
    fn aria_column_index(self, index: usize) -> Self { ... }
    fn aria_row_count(self, count: usize) -> Self { ... }
    fn aria_column_count(self, count: usize) -> Self { ... }
    fn aria_modal(self, modal: bool) -> Self { ... }
    fn aria_live(self, live: Live) -> Self { ... }
    fn aria_live_atomic(self, atomic: bool) -> Self { ... }
    fn on_a11y_action(
        self,
        action: Action,
        listener: impl FnMut(Option<&ActionData>, &mut Window, &mut App) + 'static,
    ) -> Self { ... }
    fn focusable(self) -> Self { ... }
    fn overflow_scroll(self) -> Self { ... }
    fn overflow_x_scroll(self) -> Self { ... }
    fn overflow_y_scroll(self) -> Self { ... }
    fn restrict_scroll_to_axis(self) -> Self { ... }
    fn track_scroll(self, scroll_handle: &ScrollHandle) -> Self { ... }
    fn anchor_scroll(self, scroll_anchor: Option<ScrollAnchor>) -> Self { ... }
    fn active(self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self
       where Self: Sized { ... }
    fn group_active(
        self,
        group_name: impl Into<SharedString>,
        f: impl FnOnce(StyleRefinement) -> StyleRefinement,
    ) -> Self
       where Self: Sized { ... }
    fn on_click(
        self,
        listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static,
    ) -> Self
       where Self: Sized { ... }
    fn on_aux_click(
        self,
        listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static,
    ) -> Self
       where Self: Sized { ... }
    fn on_drag<T, W>(
        self,
        value: T,
        constructor: impl Fn(&T, Point<Pixels>, &mut Window, &mut App) -> Entity<W> + 'static,
    ) -> Self
       where Self: Sized,
             T: 'static,
             W: 'static + Render { ... }
    fn on_drag_alt<F>(self, listener: F) -> Self
       where Self: Sized,
             F: 'static + Fn(Point<Pixels>, Option<CursorStyle>, &mut Window, &mut App) -> AnyDrag { ... }
    fn external_drag_payload<T>(
        self,
        resolver: impl Fn(&T, &mut Window, &mut App) -> Option<ExternalDragPayload> + 'static,
    ) -> Self
       where Self: Sized,
             T: 'static { ... }
    fn on_hover(
        self,
        listener: impl Fn(&bool, &mut Window, &mut App) + 'static,
    ) -> Self
       where Self: Sized { ... }
    fn hover_listener_mode(self, mode: HoverListenerMode) -> Self
       where Self: Sized { ... }
    fn on_hover_region<R: PartialEq + 'static>(
        self,
        project: impl Fn(Point<Pixels>, Bounds<Pixels>) -> Option<R> + 'static,
        listener: impl Fn(&Option<R>, &mut Window, &mut App) + 'static,
    ) -> Self
       where Self: Sized { ... }
    fn tooltip(
        self,
        build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static,
    ) -> Self
       where Self: Sized { ... }
    fn hoverable_tooltip(
        self,
        build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static,
    ) -> Self
       where Self: Sized { ... }
    fn tooltip_show_delay(self, delay: Duration) -> Self
       where Self: Sized { ... }
    fn on_prepaint(
        self,
        listener: impl Fn(&InteractivityPrepaint, &mut Window, &mut App) + 'static,
    ) -> Self
       where Self: Sized { ... }
}

An element with an id, which can also be clicked, scrolled, dragged, given a tooltip, and read by accessibility tools.

The methods here keep state between frames: they need the element to have an ElementId, so call id first. The result of id is a Stateful element, which implements this trait. Accessibility methods are here too, because accessibility nodes are matched across frames by id.

See the elements concept for why stateful elements need ids.

Provided Methods

fn role(self, role: Role) -> Self

Sets the accessibility role of this element, such as a button or a list.

Screen readers use the role to describe the element and decide what it can do. Use the role that matches the element’s behavior. accesskit::Role::GenericContainer is ignored, so use it only for layout. See the accessibility guide for an overview.

Panics

Panics in debug builds if role is accesskit::Role::GenericContainer.

fn accessibility_id(self, id: impl Into<SharedString>) -> Self

Sets the identifier that accessibility clients use to find this element.

Unlike the ElementId, this value is visible outside the process. Automation tools read it through UIA AutomationId on Windows, AXIdentifier on macOS, and AT-SPI AccessibleId where the adapter supports it. Keep it stable across runs and unique within its tree. It does not affect rendering or input.

fn aria_label(self, label: impl Into<SharedString>) -> Self

Sets the accessible name of this element, which screen readers announce when focus reaches it.

Use it when the element has no visible text, such as an icon button. The label names the element; use aria_description for extra information.

fn aria_description(self, description: impl Into<SharedString>) -> Self

Sets the accessible description of this element, announced after its name, role and value.

Use it for supplementary information, such as a hint or a settings subtitle. The aria_label names the element, and the description adds to it.

fn aria_keyshortcuts(self, keyshortcuts: impl Into<SharedString>) -> Self

Sets the keyboard shortcut that assistive technology announces for this element.

The value is passed to AccessKit as the keyboard shortcut. It does not bind any keys: use a KeyBinding for that. Use the same shortcut your keymap uses so that the two match.

fn aria_hidden(self) -> Self

Hides this element and its descendants from assistive technology.

Rendering, focus and input do not change. Don’t hide an element that can receive focus or that contains focusable descendants, because a screen reader user would then reach a control it cannot see.

fn aria_active_descendant(self) -> Self

Reports this element as the focused node in the accessibility tree, while a focused ancestor is present.

Use it for composite widgets, such as a menu or listbox, that keep keyboard focus on a container while one child is selected. Set it on the selected child, so that assistive technology announces the child. The element needs a role and an id to produce an accessibility node. If no ancestor holds focus, the setting is ignored, so it is safe to set on the selected child at all times.

fn a11y_synthetic_children( self, f: impl FnOnce(&mut A11ySubtreeBuilder<'_>) + 'static, ) -> Self

Adds accessibility nodes that don’t correspond to any element, as children of this element.

Use it for content that has no elements of its own, such as the runs of text in an editor. GPUI calls f after prepaint, with a builder for the subtree. The element must have an id and either a role or to be aria_hidden. See Element::a11y_synthetic_children for details.

fn aria_selected(self, selected: bool) -> Self

Sets whether this element is selected, such as an item in a list or a tab.

fn aria_expanded(self, expanded: bool) -> Self

Sets whether this element is expanded, such as a disclosure triangle or a tree node.

fn aria_toggled(self, toggled: Toggled) -> Self

Sets the toggled state of this element, such as a checkbox that is on, off or mixed.

fn aria_disabled(self, disabled: bool) -> Self

Sets whether this element is disabled, so that it rejects input.

Use it for a disabled control or a group of controls. It maps to AccessKit’s Disabled flag, which tells assistive technology that the element is unavailable.

fn aria_numeric_value(self, value: f64) -> Self

Sets the current numeric value of this element, such as the position of a slider.

fn aria_numeric_value_step(self, step: f64) -> Self

Sets the amount by which the numeric value changes per step, such as when a spin button is incremented.

fn aria_value(self, value: impl Into<SharedString>) -> Self

Sets the text value of this element, such as the contents of a simple text input.

fn aria_placeholder(self, placeholder: impl Into<SharedString>) -> Self

Sets the placeholder that assistive technology reads when a text input is empty.

fn aria_min_numeric_value(self, value: f64) -> Self

Sets the smallest numeric value this element can take.

fn aria_max_numeric_value(self, value: f64) -> Self

Sets the largest numeric value this element can take.

fn aria_orientation(self, orientation: Orientation) -> Self

Sets whether this element is laid out horizontally or vertically, such as a scrollbar or a splitter.

fn aria_level(self, level: usize) -> Self

Sets the heading level of this element, where 1 is the top level.

fn aria_position_in_set(self, position: usize) -> Self

Sets the one-based position of this element within its set, such as the third item of five in a list.

Use it with aria_size_of_set so that assistive technology can announce “3 of 5”.

fn aria_size_of_set(self, size: usize) -> Self

Sets the number of items in the set this element belongs to.

fn aria_row_index(self, index: usize) -> Self

Sets the one-based row index of this element within its table or grid.

fn aria_column_index(self, index: usize) -> Self

Sets the one-based column index of this element within its table or grid.

fn aria_row_count(self, count: usize) -> Self

Sets the number of rows in the table or grid that contains this element.

fn aria_column_count(self, count: usize) -> Self

Sets the number of columns in the table or grid that contains this element.

fn aria_modal(self, modal: bool) -> Self

Marks this element, typically a dialog, as modal.

While it is open, assistive technology treats the rest of the window as inert. It maps to AccessKit’s Modal flag.

fn aria_live(self, live: Live) -> Self

Sets how urgently assistive technology announces changes to this element, as an ARIA live region.

See accesskit::Live for the options. Set it on the element whose content changes.

fn aria_live_atomic(self, atomic: bool) -> Self

Sets whether a change to this live region is announced as a whole, instead of only the changed part.

It is meaningful only with aria_live.

fn on_a11y_action( self, action: Action, listener: impl FnMut(Option<&ActionData>, &mut Window, &mut App) + 'static, ) -> Self

Runs listener when assistive technology requests action on this element.

The listener receives the action data the client sent, if any, along with the window and the app. Use it to let a screen reader press a button or change a value. See the accessibility guide for an overview.

fn focusable(self) -> Self

Makes this element focusable, without giving it a focus handle of your own.

GPUI creates a focus handle for the element and keeps it while the element is rendered. Use track_focus when you need to focus the element from your code.

fn overflow_scroll(self) -> Self

Makes this element scroll on both axes when its content overflows.

It sets overflow_x and overflow_y to scroll. Scrolling needs an id, which turns the element into a Stateful element, so that the scroll offset is kept between frames.

fn overflow_x_scroll(self) -> Self

Makes this element scroll horizontally when its content overflows.

Scrolling needs an id, which turns the element into a Stateful element.

fn overflow_y_scroll(self) -> Self

Makes this element scroll vertically when its content overflows.

Scrolling needs an id, which turns the element into a Stateful element.

Example

let list = div()
    .id("list")
    .overflow_y_scroll()
    .children((0..100).map(|index| div().child(format!("Row {index}"))));

fn restrict_scroll_to_axis(self) -> Self

Restricts a scroll gesture to the axis it started on, so that a vertical swipe doesn’t also scroll sideways.

See Style::restrict_scroll_to_axis for details.

fn track_scroll(self, scroll_handle: &ScrollHandle) -> Self

Records this element’s scroll state in scroll_handle, so that you can read and change the scroll position.

Use the same handle across renders. Read the offset with ScrollHandle::offset and move to an item with ScrollHandle::scroll_to_item.

fn anchor_scroll(self, scroll_anchor: Option<ScrollAnchor>) -> Self

Connects this element to a ScrollAnchor, so that the anchor can scroll the parent to this element.

Use it when the element is not a direct child of the scrolling parent.

fn active(self, f: impl FnOnce(StyleRefinement) -> StyleRefinement) -> Self

where Self: Sized,

Applies f’s style while the mouse button is held down on this element.

The style applies after a press that started on the element and until the button is released. It does not apply after keyboard input.

fn group_active( self, group_name: impl Into<SharedString>, f: impl FnOnce(StyleRefinement) -> StyleRefinement, ) -> Self

where Self: Sized,

Applies f’s style while the mouse button is held down on any member of group_name.

Set the group with group on the parent.

fn on_click( self, listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static, ) -> Self

where Self: Sized,

Runs listener when this element is clicked, or activated from the keyboard.

A mouse click fires when the left button is pressed and released over the element, with no drag in between. A keyboard click fires when Enter or Space is pressed and released while the element is focused, with no other key pressed in between. The listener receives a ClickEvent that says which kind of click it was.

Clicks need an id, so call id first. Keyboard clicks also need the element to be focusable, through track_focus or focusable.

Example

let button = div()
    .id("save")
    .on_click(|event, _window, _cx| {
        if event.is_keyboard() {
            // Activated with Enter or Space.
        }
    });

fn on_aux_click( self, listener: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static, ) -> Self

where Self: Sized,

Runs listener for clicks with a button other than the left one, such as the middle button.

Like on_click, this needs an id.

fn on_drag<T, W>( self, value: T, constructor: impl Fn(&T, Point<Pixels>, &mut Window, &mut App) -> Entity<W> + 'static, ) -> Self

where Self: Sized, T: 'static, W: 'static + Render,

Starts a drag of value when the left button is pressed on this element and the pointer moves.

A drag starts when the pointer has moved more than 2 pixels from the press, and it is cancelled if the button is released first. The constructor runs at the start of the drag. It receives the value and the offset of the cursor from the element’s origin, and returns the view that is drawn under the pointer.

Use on_drop on another element to receive the value. Use on_drag_move to follow the pointer during the drag.

Example

#[derive(Clone)]
struct Card(&'static str);

struct Chip(&'static str);

impl Render for Chip {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().px_2().bg(rgb(0xdbeafe)).child(self.0)
    }
}

fn card(label: &'static str) -> impl IntoElement {
    div()
        .id(label)
        .on_drag(Card(label), |card, _offset, _window, cx| {
            cx.new(|_| Chip(card.0))
        })
}

fn on_drag_alt<F>(self, listener: F) -> Self

where Self: Sized, F: 'static + Fn(Point<Pixels>, Option<CursorStyle>, &mut Window, &mut App) -> AnyDrag,

Sets the function that starts a drag from this element.

The function receives the cursor offset and the cursor style, and returns an AnyDrag. Use on_drag unless you need to build the AnyDrag yourself, for example to provide a different cursor style.

fn external_drag_payload<T>( self, resolver: impl Fn(&T, &mut Window, &mut App) -> Option<ExternalDragPayload> + 'static, ) -> Self

where Self: Sized, T: 'static,

Registers a resolver for the data to offer the platform when a drag from this element leaves the window.

The resolver runs at most once per drag, when the pointer leaves the window. Call it after on_drag, and use the same dragged type T.

Panics

Panics in debug builds if called before on_drag. If called twice on the same element, it panics in debug builds when a drag starts.

fn on_hover( self, listener: impl Fn(&bool, &mut Window, &mut App) + 'static, ) -> Self

where Self: Sized,

Runs listener with true when the pointer enters this element and false when it leaves.

The listener does not run while a drag is in progress. Transitions caused by layout changes under a stationary pointer also run it.

After keyboard input, hover stays off until the pointer moves, a button is pressed or the screen is touched. Set HoverListenerMode::InputModalityIndependent with Self::hover_listener_mode to keep tracking it.

fn hover_listener_mode(self, mode: HoverListenerMode) -> Self

where Self: Sized,

Sets how Self::on_hover responds to key presses while the mouse is stationary. This affects only the hover listener, not hover styles or tooltips. The fluent API equivalent to Interactivity::hover_listener_mode.

fn on_hover_region<R: PartialEq + 'static>( self, project: impl Fn(Point<Pixels>, Bounds<Pixels>) -> Option<R> + 'static, listener: impl Fn(&Option<R>, &mut Window, &mut App) + 'static, ) -> Self

where Self: Sized,

Calls the listener when a typed pointer projection changes.

fn tooltip( self, build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static, ) -> Self

where Self: Sized,

Shows a tooltip built by build_tooltip while the pointer rests over this element.

The tooltip appears after the show delay, which is 500 milliseconds by default. It hides when the pointer leaves the element, so the user cannot move onto it. It is not shown while a button is pressed on the element or after keyboard input. A long press on a touch screen also shows it. Use hoverable_tooltip for a tooltip that stays open. Tooltips need an id.

Example

struct Hint;

impl Render for Hint {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child("Save the document")
    }
}

fn save_button() -> impl IntoElement {
    div()
        .id("save")
        .tooltip(|_window, cx| cx.new(|_| Hint).into())
}

fn hoverable_tooltip( self, build_tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static, ) -> Self

where Self: Sized,

Shows a tooltip built by build_tooltip while the pointer rests over this element, and keeps it open while the pointer is over the tooltip.

This is the same as tooltip except that the user can move into the tooltip, for example to select text or press a button in it.

fn tooltip_show_delay(self, delay: Duration) -> Self

where Self: Sized,

Sets how long the pointer must rest over this element before its tooltip appears.

The default is 500 milliseconds. A long press on a touch screen shows the tooltip as soon as it’s recognized.

fn on_prepaint( self, listener: impl Fn(&InteractivityPrepaint, &mut Window, &mut App) + 'static, ) -> Self

where Self: Sized,

Runs listener during prepaint, once the element’s bounds and content size are known.

The listener is consumed each frame, so register it again on every render.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl StatefulInteractiveElement for Img

impl<E> StatefulInteractiveElement for Stateful<E>

where Self: InteractiveElement,