Struct Interactivity 

pub struct Interactivity {
    pub element_id: Option<ElementId>,
    pub active: Option<bool>,
    pub hovered: Option<bool>,
    pub base_style: Box<StyleRefinement>,
    /* private fields */
}

The interactivity state of an element: its listeners, styles, focus and scroll state.

Div and Stateful keep one of these. Use it directly when you build your own element and want the same mouse, keyboard, drag and styling behavior as div. See the elements concept and the custom drawing guide.

Fields

element_id: Option<ElementId>

The element’s id, if it has one. Elements that keep state between frames need an id.

active: Option<bool>

Whether the mouse button is pressed on this element, as of its most recent prepaint.

This is None until the element has been prepainted with a state that tracks presses, such as an on_click listener or an active style.

hovered: Option<bool>

Whether the pointer is over this element, as of its most recent paint.

This is None if the element did not get a hitbox during prepaint.

base_style: Box<StyleRefinement>

The base style of the element, before any modifications are applied by focus, active, etc.

Implementations

impl Interactivity

pub fn new() -> Interactivity

Create an Interactivity, capturing the caller location in debug mode.

pub fn source_location(&self) -> Option<&'static Location<'static>>

Returns where this Interactivity was created, if the caller location was recorded.

The location is recorded in debug builds and with the inspector feature, and is None otherwise. The inspector uses it to point at the code that created an element.

pub fn on_mouse_down( &mut self, button: MouseButton, listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static, )

Runs listener when button is pressed over this element.

The listener runs in the bubble phase, and only if the pointer is over the element’s hitbox. This is the imperative equivalent of InteractiveElement::on_mouse_down. Prefer the fluent method when you are building an element in a single chain.

pub fn capture_any_mouse_down( &mut self, listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static, )

Runs listener for a press of any button over this element, during the capture phase.

Use it to see a press before the element on top handles it. The listener runs only while the pointer is over the element. This is the imperative equivalent of InteractiveElement::capture_any_mouse_down.

pub fn on_any_mouse_down( &mut self, listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static, )

Runs listener for a press of any button over this element, during the bubble phase.

This is the imperative equivalent of InteractiveElement::on_any_mouse_down.

pub fn on_mouse_pressure( &mut self, listener: impl Fn(&MousePressureEvent, &mut Window, &mut App) + 'static, )

Runs listener for pressure changes over this element, during the bubble phase.

Pressure events come from force-sensitive trackpads, which report them only on macOS today. The listener runs only while the pointer is over the element. This is the imperative equivalent of InteractiveElement::on_mouse_pressure.

pub fn capture_mouse_pressure( &mut self, listener: impl Fn(&MousePressureEvent, &mut Window, &mut App) + 'static, )

Runs listener for pressure changes over this element, during the capture phase.

The listener runs only while the pointer is over the element. This is the imperative equivalent of InteractiveElement::capture_mouse_pressure.

pub fn on_mouse_up( &mut self, button: MouseButton, listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static, )

Runs listener when button is released over this element, during the bubble phase.

The listener runs only while the pointer is over the element. This is the imperative equivalent of InteractiveElement::on_mouse_up.

pub fn capture_any_mouse_up( &mut self, listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static, )

Runs listener for a release of any button over this element, during the capture phase.

The listener runs only while the pointer is over the element. This is the imperative equivalent of InteractiveElement::capture_any_mouse_up.

pub fn on_any_mouse_up( &mut self, listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static, )

Runs listener for a release of any button over this element, during the bubble phase.

The listener runs only while the pointer is over the element.

pub fn on_mouse_down_out( &mut self, listener: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static, )

Runs listener for a press of any button outside this element, during the capture phase.

The listener does not run while a window prompt is open. Use it to close a popover when the user clicks elsewhere. This is the imperative equivalent of InteractiveElement::on_mouse_down_out.

pub fn on_mouse_down_all( &mut self, listener: impl Fn(&MouseDownEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static, )

Runs listener for every mouse press, in both phases, whether or not the pointer is over the element.

The listener receives the phase, the element’s hitbox, and the event. Check the phase yourself. This is the imperative equivalent of InteractiveElement::on_mouse_down_all.

pub fn on_mouse_up_out( &mut self, button: MouseButton, listener: impl Fn(&MouseUpEvent, &mut Window, &mut App) + 'static, )

Runs listener when button is released outside this element, during the capture phase.

The listener runs only if the pointer is not over the element’s hitbox at the time of the release. This is the imperative equivalent of InteractiveElement::on_mouse_up_out.

pub fn on_mouse_up_all( &mut self, listener: impl Fn(&MouseUpEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static, )

Runs listener for every mouse release, in both phases, whether or not the pointer is over the element.

The listener receives the phase, the element’s hitbox, and the event. Check the phase yourself. This is the imperative equivalent of InteractiveElement::on_mouse_up_all.

pub fn on_mouse_move( &mut self, listener: impl Fn(&MouseMoveEvent, &mut Window, &mut App) + 'static, )

Runs listener when the pointer moves over this element, during the bubble phase.

The listener runs only while the pointer is over the element’s hitbox. This is the imperative equivalent of InteractiveElement::on_mouse_move.

pub fn on_mouse_move_all( &mut self, listener: impl Fn(&MouseMoveEvent, DispatchPhase, &Hitbox, &mut Window, &mut App) + 'static, )

Runs listener for every mouse move, whether or not the pointer is over the element.

The listener receives the phase, the element’s hitbox, and the event. Use it to track the pointer while a drag is in progress outside the element. This is the imperative equivalent of InteractiveElement::on_mouse_move_all.

pub fn on_mouse_exit( &mut self, listener: impl Fn(&MouseExitEvent, &mut Window, &mut App) + 'static, )

Runs listener when the pointer leaves the window while it is over this element.

This is the imperative equivalent of InteractiveElement::on_mouse_exit.

pub fn on_file_drop_exit( &mut self, listener: impl Fn(&FileDropEvent, &mut Window, &mut App) + 'static, )

Bind the given callback to FileDropEvent::Exited when a platform file drag leaves this element’s window while the element is hovered.

This is a window-local exit event, not notification that the platform drag session ended. The imperative API equivalent to InteractiveElement::on_file_drop_exit.

See Context::listener to get access to a view’s state from this callback.

pub fn on_drag_move<T>( &mut self, listener: impl Fn(&DragMoveEvent<T>, &mut Window, &mut App) + 'static, )

where T: 'static,

Runs listener for pointer moves during a drag of type T, in the capture phase.

The listener runs for every move while a drag of type T is active, including moves outside this element. This is the imperative equivalent of InteractiveElement::on_drag_move.

pub fn on_scroll_wheel( &mut self, listener: impl Fn(&ScrollWheelEvent, &mut Window, &mut App) + 'static, )

Runs listener for scroll wheel events at the pointer, during the bubble phase.

The innermost element runs first. The event continues to ancestors unless a listener calls App::stop_propagation, and elements behind an occlude hitbox don’t receive it. This is the imperative equivalent of InteractiveElement::on_scroll_wheel.

pub fn on_pinch( &mut self, listener: impl Fn(&PinchEvent, &mut Window, &mut App) + 'static, )

Runs listener for pinch gestures over this element, during the bubble phase.

The listener runs only while the pointer is over the element’s hitbox. This is the imperative equivalent of InteractiveElement::on_pinch.

pub fn capture_pinch( &mut self, listener: impl Fn(&PinchEvent, &mut Window, &mut App) + 'static, )

Runs listener for pinch gestures during the capture phase, whether or not the pointer is over the element.

This is the imperative equivalent of InteractiveElement::capture_pinch.

pub fn capture_action<A: Action>( &mut self, listener: impl Fn(&A, &mut Window, &mut App) + 'static, )

Runs listener when an action of type A is dispatched to this element, during the capture phase.

The capture phase runs before the bubble phase. If the listener does not call App::stop_propagation, dispatch continues to the bubble handlers. This is the imperative equivalent of InteractiveElement::capture_action.

pub fn on_action<A: Action>( &mut self, listener: impl Fn(&A, &mut Window, &mut App) + 'static, )

Runs listener when an action of type A is dispatched along the focus path, during the bubble phase.

Dispatch reaches this element when it is on the focus path. The listener receives the action and can stop propagation or call App::propagate. This is the imperative equivalent of InteractiveElement::on_action.

Example

use gpui::{actions, div, prelude::*, Context, Window};

actions!(counter_example, [Increment]);

struct Counter {
    count: usize,
}

impl Render for Counter {
    fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div().on_action(cx.listener(|counter: &mut Counter, _: &Increment, _window, cx| {
            counter.count += 1;
            cx.notify();
        }))
    }
}

pub fn on_boxed_action( &mut self, action: &dyn Action, listener: impl Fn(&dyn Action, &mut Window, &mut App) + 'static, )

Runs listener when an action of the same type as action is dispatched, during the bubble phase.

Use this when the action type is only known at runtime, such as when a component accepts actions from its caller. The listener receives the action value passed here, not the dispatched action, so only its type is used for matching. This is the imperative equivalent of InteractiveElement::on_boxed_action.

pub fn on_key_down( &mut self, listener: impl Fn(&KeyDownEvent, &mut Window, &mut App) + 'static, )

Runs listener for key presses, during the bubble phase.

The listener runs only if no action bound to the keystroke handled it. The element must be on the focus path. This is the imperative equivalent of InteractiveElement::on_key_down.

pub fn capture_key_down( &mut self, listener: impl Fn(&KeyDownEvent, &mut Window, &mut App) + 'static, )

Runs listener for key presses during the capture phase. Like on_key_down, it runs only if no action bound to the keystroke handled it.

This is the imperative equivalent of InteractiveElement::capture_key_down.

pub fn on_key_up( &mut self, listener: impl Fn(&KeyUpEvent, &mut Window, &mut App) + 'static, )

Runs listener for key releases, during the bubble phase.

This is the imperative equivalent of InteractiveElement::on_key_up.

pub fn capture_key_up( &mut self, listener: impl Fn(&KeyUpEvent, &mut Window, &mut App) + 'static, )

Runs listener for key releases during the capture phase.

This is the imperative equivalent of InteractiveElement::capture_key_up.

pub fn on_modifiers_changed( &mut self, listener: impl Fn(&ModifiersChangedEvent, &mut Window, &mut App) + 'static, )

Runs listener when the set of pressed modifier keys changes.

The event is delivered along the focus path, from the focused element upward. This is the imperative equivalent of InteractiveElement::on_modifiers_changed.

pub fn on_drop<T: 'static>( &mut self, listener: impl Fn(&T, &mut Window, &mut App) + 'static, )

Runs listener when a drag of type T is released over this element.

The drop runs whether or not the drag started on this element. Use InteractiveElement::can_drop or a DropListener to refuse drops. This is the imperative equivalent of InteractiveElement::on_drop.

pub fn on_drop_alt<T: 'static>(&mut self, listener: DropListener<T>)

Attaches a DropListener that handles drags of type T over this element.

This is the imperative equivalent of InteractiveElement::on_drop_alt.

pub fn can_drop( &mut self, predicate: impl Fn(&dyn Any, &mut Window, &mut App) -> bool + 'static, )

Sets a predicate that decides whether this element accepts the value being dragged.

The predicate runs only while the pointer is over the element, and it receives the dragged value. This is the imperative equivalent of InteractiveElement::can_drop.

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

where Self: Sized,

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

A mouse click fires when the left button is pressed and released over the element without the pointer moving far enough to start a drag. A keyboard click fires when Enter or Space is pressed and released while the element is focused and no other key is pressed in between. The listener receives a ClickEvent. This is the imperative equivalent of StatefulInteractiveElement::on_click. It requires an element id.

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

where Self: Sized,

Runs listener for clicks with a button other than the left one.

This is the imperative equivalent of StatefulInteractiveElement::on_aux_click. It requires an element id.

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

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.

The constructor runs when the drag starts. It receives the value and the cursor offset from the element’s origin, and returns the view that is drawn under the pointer. Any dragged value must be 'static. This is the imperative equivalent of StatefulInteractiveElement::on_drag.

pub fn on_drag_alt<F>(&mut self, listener: F)

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 Interactivity::on_drag unless you need to build the AnyDrag yourself. This is the imperative equivalent of StatefulInteractiveElement::on_drag_alt.

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

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 for each drag, when the pointer leaves the window. It must be called after Interactivity::on_drag and with the same dragged type T. This is the imperative equivalent of StatefulInteractiveElement::external_drag_payload.

Panics

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

pub fn on_drag_over_any( &mut self, predicate: impl Fn(StyleRefinement, &dyn Any, &mut Window, &mut App) -> StyleRefinement + 'static, )

Sets a style function that applies while a dragged value is over this element.

The style applies only if this element has a drop listener for the dragged type. Use DropListener::on_drag_over when the style depends on the dragged type. This is the imperative equivalent of InteractiveElement::on_drag_over_any.

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

where Self: Sized,

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

Transitions caused by layout changes under a stationary pointer also run the listener. The listener does not run while a drag is in progress. This is the imperative equivalent of StatefulInteractiveElement::on_hover.

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.

pub fn cursor_with( &mut self, resolver: impl Fn(Point<Pixels>, Bounds<Pixels>) -> Option<CursorStyle> + 'static, )

where Self: Sized,

Resolves this element’s cursor from pointer position and bounds. Return None to defer to another cursor request.

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

where Self: Sized,

Calls listener when the projected pointer value changes. The projection receives window coordinates and element bounds; return None outside active regions. Layout changes and occlusion are observed independently of event propagation. Keep listener order stable across renders.

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

where Self: Sized,

Sets a function that builds a tooltip view shown while the pointer rests over this element.

The tooltip is hidden as soon as the pointer leaves the element, so the user cannot move onto it. Use Interactivity::hoverable_tooltip for a tooltip that stays open. A long press on a touch screen also shows it. This is the imperative equivalent of StatefulInteractiveElement::tooltip.

Panics

Panics in debug builds if a tooltip is already set on this element.

pub fn hover_listener_mode(&mut self, mode: HoverListenerMode)

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 imperative API equivalent to StatefulInteractiveElement::hover_listener_mode.

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

where Self: Sized,

Sets a function that builds a tooltip view that stays open while the pointer is over it.

This is the same as Interactivity::tooltip, except the pointer can move into the tooltip without closing it. This is the imperative equivalent of StatefulInteractiveElement::hoverable_tooltip.

Panics

Panics in debug builds if a tooltip is already set on this element.

pub fn tooltip_show_delay(&mut self, delay: Duration)

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. This is the imperative equivalent of StatefulInteractiveElement::tooltip_show_delay.

pub fn occlude_mouse(&mut self)

Stops the mouse from reaching elements behind this element.

Use Interactivity::block_mouse_except_scroll for most cases, because it still lets scroll events reach the elements behind. This is the imperative equivalent of InteractiveElement::occlude.

pub fn window_control_area(&mut self, area: WindowControlArea)

Marks this element’s bounds as a window control area, such as a title bar button.

The platform uses area to decide what clicks and drags here do, such as moving or closing the window. This is the imperative equivalent of InteractiveElement::window_control_area.

pub fn block_mouse_except_scroll(&mut self)

Stops mouse interactions from reaching elements behind this element, but lets scroll events through.

This is the imperative equivalent of InteractiveElement::block_mouse_except_scroll.

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

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. This is the imperative equivalent of StatefulInteractiveElement::on_prepaint.

impl Interactivity

pub fn set_scroll_offset( &self, global_id: Option<&GlobalElementId>, window: &mut Window, point: Point<Pixels>, )

Sets the scroll offset of the element, for use during layout.

Does nothing unless the element’s style has overflow set to scroll on an axis. Call it from request_layout, before the children are laid out.

impl Interactivity

pub fn request_layout( &mut self, global_id: Option<&GlobalElementId>, _inspector_id: Option<&InspectorElementId>, window: &mut Window, cx: &mut App, f: impl FnOnce(Style, &mut Window, &mut App) -> LayoutId, ) -> LayoutId

Lays out this element using its configured styles.

f receives the computed Style and returns the LayoutId for the element. Call it from an element’s request_layout to apply the element’s listeners, styles and state to its layout.

pub fn prepaint<R>( &mut self, global_id: Option<&GlobalElementId>, _inspector_id: Option<&InspectorElementId>, bounds: Bounds<Pixels>, content_size: Size<Pixels>, window: &mut Window, cx: &mut App, f: impl FnOnce(&Style, Point<Pixels>, Option<Hitbox>, &mut Window, &mut App) -> R, ) -> R

Commits the bounds of this element, computes its final style and hitbox, and then runs f.

f receives the computed style, the scroll offset, and the element’s hitbox if one was inserted. Prepaint listeners registered with Interactivity::on_prepaint run before f.

pub fn paint( &mut self, global_id: Option<&GlobalElementId>, _inspector_id: Option<&InspectorElementId>, bounds: Bounds<Pixels>, hitbox: Option<&Hitbox>, window: &mut Window, cx: &mut App, f: impl FnOnce(&Style, &mut Window, &mut App), )

Paints this element’s background, borders and shadows, and registers its listeners with the window.

f runs the painting of the element’s contents, and receives the final style. Call it from an element’s paint method, with the hitbox returned from prepaint.

pub fn compute_style( &self, global_id: Option<&GlobalElementId>, hitbox: Option<&Hitbox>, window: &mut Window, cx: &mut App, ) -> Style

Computes the visual style of this element for its current state.

The result includes the base style, plus any focus, hover, active and drag-over styles that apply at the moment.

pub fn write_a11y_info(&self, node: &mut Node)

Writes this element’s accessibility metadata and actions to an AccessKit node.

A custom element that composes an Interactivity calls this from its Element::write_a11y_info so the fluent accessibility properties land on its own node.

Trait Implementations

impl Default for Interactivity

fn default() -> Self

Returns the “default value” for a type.