Struct Window 

pub struct Window { /* private fields */ }

The state of one platform window: its focus, input, bounds, frame and drawing.

You get a &mut Window in Render::render, in event listeners such as StatefulInteractiveElement::on_click, and in WindowHandle::update. Methods group by the job they do:

• Focus and keyboard: Window::focus, Window::focused, Window::focus_next, Window::dispatch_keystroke.
• Size and display: Window::bounds, Window::viewport_size, Window::scale_factor, Window::rem_size, Window::appearance.
• Mouse and hover: Window::mouse_position, Window::insert_hitbox, Window::on_mouse_event.
• Painting (during paint only): Window::paint_quad, Window::paint_path, Window::paint_svg, Window::paint_image, and the other paint_* methods.
• Layout (during request layout only): Window::request_layout.
• Per-element state: Window::use_state, Window::use_keyed_state.
• Scheduling a frame: Window::refresh, Window::on_next_frame, Window::request_animation_frame.

Examples

window.update(|_, window, cx| {
    let handle = cx.focus_handle();
    window.focus(&handle, cx);
    assert!(window.focused(cx).is_some());
});

Phases

Several methods may only be called during one phase of a frame. The phase names below match the frame:

• Request layout and prepaint are separate phases. Render::render runs during request layout for its view, so render may call methods marked “request layout or prepaint” but not paint methods.
• Paint runs after prepaint. Only paint methods, and the listener registration methods, are valid here.

Calling a method in the wrong phase panics in debug builds. Release builds don’t check, so keep to the phase the method’s docs name.

See the frame for the full sequence, and the windows guide.

Implementations

impl Window

pub fn visibility(&self) -> WindowVisibility

Whether the platform is presenting this window’s frames (see WindowVisibility).

pub fn is_visible(&self) -> bool

Whether frames drawn for this window will be shown.

This is not the window’s shown/hidden state: a shown window that is fully behind another window, minimized, or on a sleeping display is not visible here.

pub fn observe_window_visibility( &self, callback: impl FnMut(WindowVisibility, &mut Window, &mut App) + 'static, ) -> Subscription

Registers a callback to be invoked when the window’s visibility changes.

pub fn observe_window_appearance( &self, callback: impl FnMut(&mut Window, &mut App) + 'static, ) -> Subscription

Calls callback when the system switches between light and dark appearance.

The callback runs during the next update after the change, not inside the platform callback. Keep the returned Subscription alive for as long as you want to be notified; dropping it unsubscribes. See Window::appearance to read the current value.

pub fn observe_button_layout_changed( &self, callback: impl FnMut(&mut Window, &mut App) + 'static, ) -> Subscription

Calls callback when the platform’s window button layout changes.

The button layout decides which window controls appear in a custom title bar, and which side they are on. Keep the returned Subscription alive while you need the callback; dropping it unsubscribes.

pub fn replace_root<E>( &mut self, cx: &mut App, build_view: impl FnOnce(&mut Window, &mut Context<'_, E>) -> E, ) -> Entity<E>

where E: 'static + Render,

Replaces the window’s root view with a new view built by build_view.

The window stops referring to the old root and redraws with the new one. The old view is freed once no other Entity handles to it remain. The returned entity is the new root.

pub fn root<E>(&self) -> Option<Option<Entity<E>>>

where E: 'static + Render,

Returns the window’s root view as an Entity<E>.

The result has two layers of Option. The outer None means the window has no root view. The inner None means the root is not of type E.

Examples

window.update(|_, window, _| {
    assert!(matches!(window.root::<Root>(), Some(Some(_))));
});

pub fn window_handle(&self) -> AnyWindowHandle

Returns an AnyWindowHandle for this window, which can be stored and used later.

pub fn refresh(&mut self)

Redraws the whole window on the next frame, without notifying any entity.

Use it when something outside your entities changes what the window shows, such as a system setting or the contents of a global that views don’t observe. Calling it during a draw does nothing, because the window is already drawing. Prefer Context::notify when an entity changed.

Examples

window.update(|_, window, _| window.refresh());

pub fn remove_window(&mut self)

Closes this window when the current update finishes.

The window isn’t removed in the middle of the update, so you can keep using the Window until the update returns.

pub fn focused(&self, cx: &App) -> Option<FocusHandle>

Returns the FocusHandle of the focused element, or None if nothing has focus.

Returns None if the focused element’s handles have all been dropped.

pub fn focus_lost_restore_target(&self, cx: &App) -> Option<FocusHandle>

While focus-lost listeners are being dispatched, returns the closest ancestor of the previously focused element that can still receive focus, making it a suitable target for focus restoration. Returns None at all other times, or when no such ancestor exists.

pub fn focus(&mut self, handle: &FocusHandle, cx: &mut App)

Moves focus to the element that handle belongs to.

Focus changes right away, and the next frame renders the new focus. Focusing the element that already has focus does nothing. Does nothing after Window::disable_focus. Pending keystrokes are cleared.

Examples

window.update(|_, window, cx| {
    let handle = cx.focus_handle();
    window.focus(&handle, cx);
    assert_eq!(window.focused(cx), Some(handle));
});

pub fn blur(&mut self, cx: &mut App)

Removes focus from every element in the window.

Focus can be given again afterward with Window::focus. Pending keystrokes are cleared. Does nothing if focus is disabled.

pub fn disable_focus(&mut self, cx: &mut App)

Removes focus from the window and stops any element in it from receiving focus.

Later calls to Window::focus, Window::focus_next and Window::focus_prev do nothing. Use it when the window is being torn down or is only for display.

pub fn focus_next(&mut self, cx: &mut App)

Moves focus to the next tab stop in tab order, wrapping at the end.

Tab stops are the focusable elements whose FocusHandle::tab_stop is true, read from the last rendered frame. If nothing has focus, this moves to the first tab stop. Does nothing if focus is disabled or there are no tab stops.

GPUI doesn’t bind Tab to this method. Bind a key to it with App::bind_keys and an action handler, as in the focus guide.

pub fn focus_prev(&mut self, cx: &mut App)

Moves focus to the previous tab stop in tab order, wrapping at the start.

This is the reverse of Window::focus_next, with the same rules for tab stops and disabled focus.

pub fn text_system(&self) -> &Arc<WindowTextSystem>

Returns the text system that shapes and rasterizes text for this window.

pub fn text_style(&self) -> TextStyle

Returns the text style in effect, built from the refinements active in Window::with_text_style.

pub fn resolved_direction(&self) -> ResolvedDirection

Returns the resolved direction of the current measured or prepainted layout node.

Custom elements can use this when direction changes intrinsic measurement or a detached sublayout created during prepaint.

pub fn is_maximized(&self) -> bool

Returns whether the platform reports this window as maximized.

On some platforms, such as Windows, a maximized window is not the same as a window whose bounds match the display’s size.

pub fn request_decorations(&self, decorations: WindowDecorations)

Requests client-side or server-side window decorations from the platform.

The request applies on Wayland.

pub fn set_exclusive_zone(&self, zone: Pixels)

Set the exclusive zone for a layer-shell surface: how much screen space it reserves so other surfaces avoid occluding it (e.g. a panel reserving space). Positive values reserve that distance from the anchored edge, 0 lets the surface be moved out of others’ exclusive zones, and -1 ignores reserved space and may extend under other surfaces. (Wayland layer-shell windows only)

pub fn set_exclusive_edge(&self, edge: Anchor)

Set which anchored edge a layer-shell surface’s exclusive zone applies to. This is only needed to disambiguate a corner-anchored surface; otherwise the edge is deduced from the anchor. The edge must be a single edge the surface is anchored to, or it is ignored. (Wayland layer-shell windows only)

pub fn start_window_resize(&self, edge: ResizeEdge)

Starts an interactive resize from edge, if this window is resizable.

pub fn set_input_region(&self, region: Option<&[Bounds<Pixels>]>)

Linux (wayland) only: Set the window’s input region, the area that receives pointer and touch input. Events outside it pass through to whatever is below the window.

• Some(rects) restricts input to the union of rects, in window coordinates.
• Some(&[]) is an empty region, so the window receives no pointer or touch input.
• None resets the region to the default, so the whole window receives input again.

pub fn window_bounds(&self) -> WindowBounds

Returns the window’s bounds and state, such as windowed, maximized or fullscreen.

Save this value to reopen the window at the same place later, as WindowOptions::window_bounds expects.

pub fn inner_window_bounds(&self) -> WindowBounds

Returns the window’s bounds and state without the client-side insets that Wayland and X11 windows draw around their content.

pub fn native_window_state(&self) -> Option<Vec<u8>>

Encode the window’s native restorable state into an opaque blob. Returns None on platforms without native state restoration or if encoding fails.

pub fn restore_native_window_state(&self, state: &[u8])

Restore the window’s native state from a blob previously produced by Window::native_window_state. A no-op on platforms without native state restoration.

pub fn dispatch_action(&mut self, action: Box<dyn Action>, cx: &mut App)

Dispatches action to the focused element, after the current update finishes.

The action runs through the focus path, like an action from a keybinding. If nothing has focus, it is dispatched from the root of the window’s last rendered frame.

pub fn defer( &self, cx: &mut App, f: impl FnOnce(&mut Window, &mut App) + 'static, )

Runs f with this window after the current update finishes.

Use it to act on this window while the entities that are being updated are still borrowed. If the window has closed by then, f doesn’t run.

pub fn observe<T: 'static>( &mut self, observed: &Entity<T>, cx: &mut App, on_notify: impl FnMut(Entity<T>, &mut Window, &mut App) + 'static, ) -> Subscription

Calls on_notify each time observed is notified, with a handle to it and this window.

This is the window-aware form of Context::observe. The callback runs when the current update finishes, not during the call to Context::notify. The observation lasts as long as the returned Subscription is alive, and it ends early once observed is released.

pub fn subscribe<Emitter, Evt>( &mut self, entity: &Entity<Emitter>, cx: &mut App, on_event: impl FnMut(Entity<Emitter>, &Evt, &mut Window, &mut App) + 'static, ) -> Subscription

where Emitter: EventEmitter<Evt>, Evt: 'static,

Calls on_event each time entity emits an event of type Evt.

The callback receives a handle to the emitter, the event, and this window. It is the window-aware form of Context::subscribe. The subscription lasts as long as the returned Subscription is alive, and it ends early once entity is released. Emitter must implement EventEmitter for Evt.

pub fn observe_release<T>( &self, entity: &Entity<T>, cx: &mut App, on_release: impl FnOnce(&mut T, &mut Window, &mut App) + 'static, ) -> Subscription

where T: 'static,

Calls on_release once when entity is released, with its final state and this window.

The callback runs after the last handle to entity is dropped. Keep the returned Subscription alive until the entity is released; dropping it cancels the callback.

pub fn to_async(&self, cx: &App) -> AsyncWindowContext

Returns an AsyncWindowContext for this window, which can be held across .await points.

Use it inside a task spawned with cx.spawn when the task needs to update this window later.

pub fn on_next_frame( &self, callback: impl FnOnce(&mut Window, &mut App) + 'static, )

Runs callback once, after the next frame is drawn.

The callback runs after the frame has been prepainted and painted, so the frame on screen is already set. If the callback changes state, it draws again on a later frame. Use it to draw a frame that depends on the one before, or to keep a loop going. Window::request_animation_frame builds on this method.

Examples

let ran = Rc::new(Cell::new(false));
let flag = ran.clone();
window.update(|_, window, _| window.on_next_frame(move |_, _| flag.set(true)));
window.update(|_, window, cx| {
    window.simulate_next_frame(cx);
});
assert!(ran.get());

pub fn request_animation_frame(&self)

Draws the current view again on the next frame, even if nothing changed.

Use it for continuous drawing, such as a video or a canvas that updates every frame. Call it while rendering or painting the view that should update. It notifies that view on the next frame, and stops when you stop calling it.

Purely decorative motion, such as spinners, should use AnimationExt::with_animation, which respects App::reduce_motion. If you use this method for decorative motion instead, check App::reduce_motion first.

Panics

Panics if no view is being rendered or painted. Use Window::on_next_frame instead when you aren’t inside a view.

pub fn simulate_next_frame(&mut self, cx: &mut App) -> usize

Runs the callbacks scheduled with Window::on_next_frame and returns how many ran.

Tests have no platform frame loop, so this runs the pending callbacks in place of the next frame. Callbacks scheduled while it runs wait for the next call.

pub fn spawn<AsyncFn, R>(&self, cx: &App, f: AsyncFn) -> Task<R>

where R: 'static, AsyncFn: AsyncFnOnce(&mut AsyncWindowContext) -> R + 'static,

Spawns a future on the foreground executor, and gives it access to this window.

The closure receives an AsyncWindowContext that the future can use to update the window after .await points. The task runs on the main thread, and the returned Task cancels the work when it is dropped.

pub fn spawn_with_priority<AsyncFn, R>( &self, priority: Priority, cx: &App, f: AsyncFn, ) -> Task<R>

where R: 'static, AsyncFn: AsyncFnOnce(&mut AsyncWindowContext) -> R + 'static,

Like Window::spawn, but schedules the future at the given priority.

pub fn bounds_changed(&mut self, cx: &mut App)

Refreshes the window’s cached size, scale and display, and calls the bounds observers.

The platform calls this when the window resizes or moves between displays. It reads the new viewport size, scale factor, display and mouse position, redraws the window, and then calls each callback registered with Window::observe on the window bounds. Tests call it to simulate a resize; use TestAppWindow::simulate_resize for that.

pub fn refresh_interval(&self, cx: &App) -> Option<Duration>

The time between refreshes of the display the window is on, as of the platform’s last display change notification. Variable refresh rate displays report their maximum rate. Returns None when the platform doesn’t report it.

pub fn observe_window_display( &self, callback: impl FnMut(&mut Window, &mut App) + 'static, ) -> Subscription

Registers a callback invoked when the window moves to another display or its display’s properties change, for example its refresh interval. Self::refresh_interval already returns the new value when the callback runs.

pub fn bounds(&self) -> Bounds<Pixels>

Returns the window’s bounds in global screen coordinates, in logical pixels.

The window can span several displays, so the origin is in the same global space as the displays. Use Window::viewport_size for the size of the content area.

pub fn insets(&self) -> WindowInsets

Returns the regions of this window obscured by system UI and the keyboard.

pub fn render_to_image(&self) -> Result<RgbaImage>

Rasterizes the last rendered frame and returns its pixels as an RGBA image.

The frame isn’t shown on screen, and the window doesn’t need to be visible. Use it for visual tests. Returns an error if the platform can’t render to an image.

pub fn rendered_primitive_counts(&self) -> (usize, usize, usize, usize)

Returns how many quads, monochrome sprites, subpixel sprites and polychrome sprites the last frame contains.

The four counts are in that order. Use them in tests to check that a change painted or removed primitives, without comparing pixels.

pub fn painted_quads(&self) -> Vec<Quad>

Returns the quads in the last rendered frame, for tests that check painted output.

Quad bounds are in scaled pixels and aren’t clipped. Each quad carries the content mask it is clipped to when drawn. Quads whose bounds don’t intersect their content mask are skipped while painting, so they don’t appear here.

Examples

window.draw();
window.update(|_, window, _| assert_eq!(window.painted_quads().len(), 1));

pub fn painted_underlines(&self) -> Vec<Underline>

Returns the underlines in the most recently rendered frame’s scene.

pub fn resize(&mut self, size: Size<Pixels>)

Resizes the window’s content area to size, in logical pixels.

pub fn is_fullscreen(&self) -> bool

Returns whether the window is in fullscreen mode.

pub fn is_simple_fullscreen(&self) -> bool

Returns whether the window is in simple fullscreen, which covers the whole screen including the menu bar.

Always false on platforms other than macOS.

pub fn appearance(&self) -> WindowAppearance

Returns whether the system uses a light or dark appearance for this window.

Updated before the callbacks from Window::observe_window_appearance run.

pub fn viewport_size(&self) -> Size<Pixels>

Returns the size of the window’s content area, in logical pixels.

This excludes window decorations, so it is the size your root view lays out in.

pub fn visual_viewport_bounds(&self) -> Bounds<Pixels>

Returns the platform’s visible viewport in window-local logical pixels.

Unlike viewport_size, this can shrink or move when the keyboard opens. During drawing this is a consistent frame snapshot. Outside drawing it reflects the latest platform sample, not a synchronous geometry query.

pub fn fully_visible_bounds(&self) -> Bounds<Pixels>

Returns a conservative rectangle avoiding platform-known obscured content.

Intersects the visual viewport with the full layout area inset by system safe areas and keyboard occlusion. Unknown overlays cannot be excluded.

pub fn request_virtual_keyboard(&self)

Requests the virtual keyboard for the currently focused text input.

Call from a user gesture on platforms that require one. The platform may decline the request; this does not change focus or the layout viewport.

pub fn dismiss_virtual_keyboard(&self)

Requests dismissal of the virtual keyboard without changing GPUI focus.

pub fn is_window_active(&self) -> bool

Returns whether the operating system considers this window active.

Key input goes to the focused element only while the window is active.

pub fn is_window_hovered(&self) -> bool

Returns whether this is the window that the mouse pointer is over.

On macOS this is the same as Window::is_window_active.

pub fn zoom_window(&self)

Zooms the window using the platform’s zoom behavior.

pub fn show_window_menu(&self, position: Point<Pixels>)

Opens the platform’s title bar menu at position, in window coordinates.

Use it from a custom title bar with client-side decorations, on Wayland and X11.

pub fn start_window_move(&self)

Hands window movement to the platform’s compositor, so the window follows the pointer.

Call it from a mouse-down handler on your custom title bar, on Wayland and X11. Mouse events may not arrive while the move is in progress.

pub fn set_client_inset(&mut self, inset: Pixels)

Sets the width of the invisible shadow or border that client-side decorations draw.

Use it on Wayland and X11 when your app draws its own decorations. Read it back with Window::client_inset.

pub fn client_inset(&self) -> Option<Pixels>

Returns the inset set by Window::set_client_inset, or None if none was set.

pub fn window_decorations(&self) -> Decorations

Returns whether the window uses server-side or client-side decorations.

Client-side decorations mean your app must draw the title bar and window controls. This applies on Wayland and X11.

pub fn is_resizable(&self) -> bool

Returns whether the window was opened as resizable in WindowOptions::is_resizable.

pub fn is_minimizable(&self) -> bool

Returns whether the window was opened as minimizable in WindowOptions::is_minimizable.

pub fn window_controls(&self) -> WindowControls

Returns which window controls, such as minimize and maximize, the platform supports.

pub fn set_window_title(&mut self, title: &str)

Sets the window’s title in the platform title bar, and in accessibility trees.

pub fn set_app_id(&mut self, app_id: &str)

Sets the application identifier that the platform uses to group and match windows.

pub fn set_background_appearance( &self, background_appearance: WindowBackgroundAppearance, )

Sets the window background appearance.

pub fn set_window_edited(&mut self, edited: bool)

Mark the window as dirty at the platform level.

pub fn set_document_path(&self, path: Option<&Path>)

Set the path of the file this window represents. On macOS, this sets the window’s accessibility document property (AXDocument).

pub fn display(&self, cx: &App) -> Option<Rc<dyn PlatformDisplay>>

Determine the display on which the window is visible.

pub fn show_character_palette(&self)

Show the platform character palette.

On macOS and Windows, opens the system character or emoji picker. On Linux, opens an installed desktop picker (Plasma, IBus, GNOME Characters, or KCharSelect); these pickers may require copying and pasting the selection. Logs a warning if the platform has no available picker.

pub fn scale_factor(&self) -> f32

Returns the scale factor of the display the window is on.

A value of 2.0 means each logical pixel is two device pixels, as on a Retina display. GPUI’s coordinates are logical pixels; multiply by this value only when you need device pixels.

pub fn set_scale_factor(&mut self, scale_factor: f32)

Overrides the display scale factor, and redraws the window. Only available in tests.

pub fn rem_size(&self) -> Pixels

Returns the size of one rem, in logical pixels.

Rems are the unit of Styled lengths such as .text_size(rems(1.)), so changing the rem size scales the whole window. The value is the one set by Window::set_rem_size, or the one from the innermost Window::with_rem_size while it runs.

pub fn set_rem_size(&mut self, rem_size: impl Into<Pixels>)

Sets the size of one rem, in logical pixels, for the rest of the window’s life.

Call it when the user changes the font size. The new size is used the next time the window lays out, and it doesn’t redraw the window by itself. Use Window::with_rem_size to change it for part of an element tree.

pub fn with_global_id<R>( &mut self, element_id: ElementId, f: impl FnOnce(&GlobalElementId, &mut Self) -> R, ) -> R

Runs f with a global element id made from element_id and the ids already on the stack.

The id is valid only inside f. Element state keyed by it, such as the state behind Window::use_state, is found again on the next frame when the same path of ids is used. Most code calls Window::use_state instead.

pub fn with_id<R>( &mut self, element_id: impl Into<ElementId>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f with element_id pushed onto the element id stack, then pops it.

Ids nest, so the same id under different parents identifies different elements. InteractiveElement::id and Element implementations call this for you.

pub fn with_rem_size<F, R>( &mut self, rem_size: Option<impl Into<Pixels>>, f: F, ) -> R

where F: FnOnce(&mut Self) -> R,

Runs f with rem_size as the rem size, or with the current rem size if None.

The override applies to everything f lays out, paints or prepaints, and ends when it returns. Use it to render part of a tree at a different text scale.

Panics

Panics in debug builds if called outside request layout, prepaint, or paint.

pub fn line_height(&self) -> Pixels

Returns the line height of the current text style, in logical pixels.

pub fn pixel_snap(&self, value: Pixels) -> Pixels

Rounds a value in logical pixels to the nearest device pixel.

Use it to keep edges crisp when you draw lines or borders at fractional positions.

pub fn pixel_snap_f64(&self, value: f64) -> f64

Rounds an f64 logical value to the nearest device pixel. See Window::pixel_snap.

pub fn pixel_snap_bounds(&self, bounds: Bounds<Pixels>) -> Bounds<Pixels>

Rounds each edge of bounds to the nearest device pixel. See Window::pixel_snap.

pub fn pixel_snap_point(&self, position: Point<Pixels>) -> Point<Pixels>

Rounds each coordinate of position to the nearest device pixel. See Window::pixel_snap.

pub fn underline_bounds( &self, origin: Point<Pixels>, width: Pixels, style: &UnderlineStyle, ) -> Bounds<ScaledPixels>

Returns the snapped device-space bounds used to paint an underline.

pub fn paint_underline_with_exclusions( &mut self, origin: Point<Pixels>, width: Pixels, style: &UnderlineStyle, exclusions: &[Range<ScaledPixels>], )

Paints an underline excluding absolute device-space horizontal spans.

pub fn prevent_default(&mut self)

Marks the event being dispatched as handled, so default behavior is skipped.

Currently it stops parent elements from taking focus on a mouse down. Check the result with Window::default_prevented in later listeners.

pub fn default_prevented(&self) -> bool

Returns whether Window::prevent_default was called for the event being dispatched.

pub fn is_action_available(&self, action: &dyn Action, cx: &App) -> bool

Returns whether a listener for action is on the dispatch path from the focused element.

Use it to enable or disable menu items and buttons that trigger action. If nothing has focus, the path starts at the window’s root.

pub fn is_action_available_in( &self, action: &dyn Action, focus_handle: &FocusHandle, ) -> bool

Returns whether a listener for action is on the dispatch path from focus_handle.

This is Window::is_action_available for an element other than the focused one.

pub fn mouse_position(&self) -> Point<Pixels>

Returns the last known mouse position, in window coordinates.

The position is updated from the mouse events the window receives.

pub fn capture_pointer(&mut self, hitbox_id: HitboxId)

Captures the pointer for hitbox_id. While captured, all mouse move and mouse up events will be routed to listeners that check this hitbox’s is_hovered status, regardless of actual hit testing. This enables drag operations that continue even when the pointer moves outside the element’s bounds.

The capture is automatically released on mouse up.

pub fn release_pointer(&mut self)

Releases the pointer capture set by Window::capture_pointer, if there is one.

pub fn captured_hitbox(&self) -> Option<HitboxId>

Returns the hitbox that has captured the pointer, or None if the pointer isn’t captured.

pub fn capture_long_press<T: 'static>(&mut self, entity: &Entity<T>)

Gives entity the current long press. Only the entity that captured it receives its events.

The capture is released when the gesture ends or is cancelled, or when a replacement touch begins. A listener must also call Self::prevent_default on the started event to claim the gesture.

pub fn has_long_press_capture<T: 'static>(&self, entity: &Entity<T>) -> bool

Returns whether entity is the one that captured the current long press.

pub fn modifiers(&self) -> Modifiers

Returns the modifier keys (Shift, Control, Alt, Command and so on) held right now.

pub fn last_input_was_keyboard(&self) -> bool

Returns whether the most recent input came from the keyboard.

Focus rings and hover styles often check this, so they appear only for keyboard navigation. HitboxId::is_hovered already returns false when it is true.

pub fn last_input_was_touch(&self) -> bool

Returns whether the last input event came from a touch screen.

pub fn capslock(&self) -> Capslock

Returns the state of the Caps Lock key.

pub fn draw(&mut self, cx: &mut App) -> ArenaClearNeeded

Builds a new frame from the root view and makes it the rendered frame.

This runs the render, request-layout, prepaint and paint phases, then swaps the frame in and delivers focus-change listeners. The frame is not shown until the window presents it to the screen. The returned token must be passed to ArenaClearNeeded::clear, which frees the element arena for the next frame. GPUI calls this for every frame that needs one, so most code doesn’t call it directly.

pub fn with_text_style<F, R>( &mut self, style: Option<TextStyleRefinement>, f: F, ) -> R

where F: FnOnce(&mut Self) -> R,

Runs f with style refined onto the current text style, and restores the previous style afterward.

Text painted and measured inside f uses the refined style. Pass None to run f with the current style unchanged. Use Window::text_style to read the combined style. Call it during request layout, prepaint or paint.

pub fn set_cursor_style(&mut self, style: CursorStyle, hitbox: &Hitbox)

Sets the cursor shown while the pointer is over hitbox.

The style applies only while hitbox is hovered. Call it during paint. Set it on a hitbox you inserted during prepaint. Use Window::set_window_cursor_style to set the cursor for the whole window.

pub fn set_cursor_style_with( &mut self, hitbox: &Hitbox, resolve: impl Fn(Point<Pixels>) -> Option<CursorStyle> + 'static, )

Resolves this hitbox’s cursor from window coordinates on pointer input. Return None to use the next cursor request. Cached paints retain the resolver.

pub fn set_window_cursor_style(&mut self, style: CursorStyle)

Sets the cursor for the whole window, overriding any cursor set with Window::set_cursor_style.

Call it during paint.

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

Resolves a window-wide cursor from pointer position. Return None to defer to hitbox cursor requests.

pub fn set_tooltip(&mut self, tooltip: AnyTooltip) -> TooltipId

Shows tooltip for the upcoming frame and returns its TooltipId.

Call it during prepaint. GPUI draws the tooltip above the window’s content. Use TooltipId::is_hovered to check whether the mouse is over the tooltip.

pub fn with_content_mask<R>( &mut self, mask: Option<ContentMask<Pixels>>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f with mask intersected with the current content mask.

Painting and hit-testing inside f are clipped to the result, and the previous mask is restored when f returns. Passing None leaves the mask unchanged. Call it during prepaint or paint.

pub fn with_element_offset<R>( &mut self, offset: Point<Pixels>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f with offset added to the current element offset, then restores it.

Bounds that elements compute inside f are shifted by offset, which is how scroll containers move their children. Call it during prepaint.

pub fn with_absolute_element_offset<R>( &mut self, offset: Point<Pixels>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f with the element offset set to offset, ignoring the current offset.

Use it to place an element at a fixed position, such as a drag preview that follows the pointer. The previous offset is restored when f returns. Call it during prepaint.

pub fn transact<T, U>( &mut self, f: impl FnOnce(&mut Self) -> Result<T, U>, ) -> Result<T, U>

Runs f during prepaint, and discards its hitboxes, tooltips and other frame data if it returns Err.

Use it to prepaint children, check the result, and try again. A successful f keeps everything it registered. The autoscroll support in crate::List uses this method. Call it during prepaint.

Errors

Returns the Err value from f. Nothing from the failed attempt remains in the frame.

pub fn request_autoscroll(&mut self, bounds: Bounds<Pixels>)

Asks the scroll containers around the current element to scroll bounds into view.

Call it from Element::prepaint. Scroll containers such as crate::List read the request with Window::take_autoscroll, scroll, and prepaint their children again. Call it during prepaint.

pub fn take_autoscroll(&mut self) -> Option<Bounds<Pixels>>

Returns and clears the autoscroll request made with Window::request_autoscroll, if any.

Scroll containers call it during prepaint to implement autoscroll. Call it during prepaint.

pub fn use_asset<A: Asset>( &mut self, source: &A::Source, cx: &mut App, ) -> Option<A::Output>

Returns the loaded asset, or None while it is still loading.

The first call starts loading source. When loading finishes, the current view is notified and redrawn, and later calls return Some. Concurrent calls share one load. Call it during render or paint. See Window::get_asset for a version that doesn’t redraw the view.

pub fn get_asset<A: Asset>( &mut self, source: &A::Source, cx: &mut App, ) -> Option<A::Output>

Returns the loaded asset if it is ready, or starts loading it and returns None.

Unlike Window::use_asset, this doesn’t redraw the view when loading finishes. Use it when a later redraw from some other cause will pick up the result. Concurrent calls share one load.

pub fn element_offset(&self) -> Point<Pixels>

Returns the offset that the current element’s position is shifted by, in logical pixels.

Scroll containers set it with Window::with_element_offset. Call it during prepaint.

pub fn content_mask(&self) -> ContentMask<Pixels>

Returns the content mask in effect, which is the window’s bounds unless a parent has clipped it.

Call it during prepaint or paint. See Window::with_content_mask.

pub fn with_element_namespace<R>( &mut self, element_id: impl Into<ElementId>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f with element_id pushed onto the id path, so child ids are unique only within it.

Use it inside a custom element to give each group of children its own namespace. For example, a table can namespace each row’s cells by the row’s id.

pub fn use_keyed_state<S: 'static>( &mut self, key: impl Into<ElementId>, cx: &mut App, init: impl FnOnce(&mut Self, &mut Context<'_, S>) -> S, ) -> Entity<S>

Returns an entity that persists across frames for as long as key keeps being rendered.

The first time key is used, init creates the entity. On later frames the same entity is returned. GPUI redraws the current view whenever this entity is notified, so the view reflects changes to it. The state is dropped when the element isn’t rendered in a frame.

Use a different key for each element when several share a parent, such as list rows, and use a stable key such as a database id. Call it during Render::render, RenderOnce::render, or the drawing functions of Element. For the same state without a key, see Window::use_state.

Examples

assert_eq!(values.borrow().last(), Some(&0));
let counter = counter_slot.borrow().as_ref().unwrap().clone();
app.update(|cx| {
    counter.update(cx, |count, cx| {
        *count = 1;
        cx.notify();
    });
});
window.draw();

assert_eq!(values.borrow().last(), Some(&1));
assert!(counter_ids.borrow().iter().all(|id| *id == counter.entity_id()));

pub fn use_state<S: 'static>( &mut self, cx: &mut App, init: impl FnOnce(&mut Self, &mut Context<'_, S>) -> S, ) -> Entity<S>

Returns state that persists across frames, identified by the call site of this method.

This is Window::use_keyed_state with a key made from the caller’s source location, so each call site in your code gets its own state. Inside a loop, every iteration shares one key, so use use_keyed_state with an id for each item instead.

pub fn with_element_state<S, R>( &mut self, global_id: &GlobalElementId, f: impl FnOnce(Option<S>, &mut Self) -> (R, S), ) -> R

where S: 'static,

Passes the state stored for global_id to f, and stores the state f returns.

f receives None the first time, or after the element wasn’t rendered in the previous frame. The state is found by global_id and its type S, so each type has its own state for the same element. Call it during prepaint or paint, or during Render::render and the element drawing methods.

Panics

Panics if the state stored for global_id has a different type than S. A nested call for the same id and type doesn’t see the state that f is updating. Use Window::use_keyed_state for ordinary state that needs no type juggling.

pub fn with_optional_element_state<S, R>( &mut self, global_id: Option<&GlobalElementId>, f: impl FnOnce(Option<Option<S>>, &mut Self) -> (R, Option<S>), ) -> R

where S: 'static,

Like Window::with_element_state, but the element may not have an id.

When global_id is None, f receives None for the outer option, which means no id was provided. The inner Option is None the first time the state is used. When global_id is Some, f must return Some state; when it is None, f must return None, since there is nothing to store it under. Prefer with_element_state when the element always has an id. Call it during prepaint or paint.

pub fn use_transition<T: Lerp + Clone + PartialEq + 'static>( &mut self, cx: &mut App, motion: impl Into<Motion>, init: impl Fn(&mut Window, &mut Context<'_, TransitionState<T>>) -> T, ) -> Transition<T>

Creates a transition whose state persists across frames, identified by the call site.

Like Window::use_state, each call site gets its own state, and every iteration of a loop shares one. Use use_keyed_transition with a key for each item instead.

pub fn use_keyed_transition<T: Lerp + Clone + PartialEq + 'static>( &mut self, key: impl Into<ElementId>, cx: &mut App, motion: impl Into<Motion>, init: impl Fn(&mut Window, &mut Context<'_, TransitionState<T>>) -> T, ) -> Transition<T>

Creates a new keyed transition with persistent state.

The state for this transition is associated with the provided key and will persist across renders as long as the key remains the same. This is the recommended method for most use cases where you want smooth, continuous animations.

This method should only be called during Render::render, RenderOnce::render, or the drawing functions of Element.

pub fn with_tab_group<R>( &mut self, index: Option<isize>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f as a tab group, so tab navigation visits its focusable elements together.

Tab stops registered inside f are ordered by index relative to other groups. Pass None to run f without creating a group.

pub fn defer_draw( &mut self, element: AnyElement, absolute_offset: Point<Pixels>, priority: usize, content_mask: Option<ContentMask<Pixels>>, )

Schedules element to be drawn on top of the current tree, after the tree is painted.

The element is laid out and painted at absolute_offset in window coordinates. Deferred elements with a higher priority are drawn later, so they appear above the others. Popovers, menus and tooltips use it to escape the clipping of their parents. Pass a content_mask to clip the element during both prepaint and paint, or None for no clip.

Call it during prepaint.

Panics

Panics in debug builds if called outside prepaint. Panics if there is no active node in the dispatch tree, which happens when no element is being prepainted.

pub fn paint_layer<R>( &mut self, bounds: Bounds<Pixels>, f: impl FnOnce(&mut Self) -> R, ) -> R

Runs f inside a new layer clipped to bounds, which groups the primitives f paints.

A layer is a batch of primitives with the same draw order and no overlaps. Layers are a performance hint that lets the renderer batch the work. Painting outside bounds is clipped to the intersection of bounds and the content mask. If that intersection is empty, f runs with no layer. Call it during paint.

pub fn paint_drop_shadows( &mut self, bounds: Bounds<Pixels>, corner_radii: Corners<Pixels>, corner_smoothing: f32, shadows: &[BoxShadow], )

Paints the outer shadows in shadows behind an element of bounds and corner_radii.

Paint these before the element’s background, so the shadow sits under it. Inset shadows are skipped; paint those with Window::paint_inset_shadows after the background. Call it during paint.

pub fn paint_inset_shadows( &mut self, bounds: Bounds<Pixels>, corner_radii: Corners<Pixels>, corner_smoothing: f32, shadows: &[BoxShadow], )

Paints the inset shadows in shadows inside an element of bounds and corner_radii.

Paint these after the element’s background, so the shadow sits on top of the fill. Outer shadows are skipped; paint those with Window::paint_drop_shadows before the background. Call it during paint.

pub fn paint_backdrop_filter( &mut self, bounds: Bounds<Pixels>, corner_radii: Corners<Pixels>, corner_smoothing: f32, filters: &[Filter], )

Paint a backdrop filter into the scene for the next frame at the current z-index. The renderer blurs the content already painted behind bounds and composites the result into the rounded rectangle described by bounds and corner_radii — the CSS backdrop-filter effect (frosted glass). Typically the element then paints a translucent background quad on top so its color tints the blurred backdrop. corner_smoothing ranges from circular corners at 0.0 to maximum smoothing at 1.0.

Does nothing when filters produce no visible blur.

This method should only be called as part of the paint phase of element drawing.

pub fn with_filter_layer<R>( &mut self, bounds: Bounds<Pixels>, corner_radii: Corners<Pixels>, corner_smoothing: f32, filters: &[Filter], f: impl FnOnce(&mut Self) -> R, ) -> R

Isolate the painting performed by f into a content-filter group: the renderer renders everything f paints into an offscreen target, blurs it as a single layer, and composites the result back into the rounded rectangle described by bounds and corner_radii — the CSS filter effect (e.g. blurring an element and its children). corner_smoothing ranges from circular corners at 0.0 to maximum smoothing at 1.0.

When filters produce no visible blur this simply runs f with no offscreen indirection.

This method should only be called as part of the paint phase of element drawing.

pub fn paint_quad(&mut self, quad: PaintQuad)

Paint one or more quads into the scene for the next frame at the current stacking context. Quads are colored rectangular regions with an optional background, border, and corner radius. Use PaintQuad::new and its builder methods to construct the quad. quad.corner_smoothing ranges from circular corners at 0.0 to maximum smoothing at 1.0.

This method should only be called as part of the paint phase of element drawing.

Note that the quad.corner_radii are allowed to exceed the bounds, creating sharp corners where the circular arcs meet. This will not display well when combined with dashed borders. Use Corners::clamp_radii_for_quad_size if the radii should fit within the bounds.

pub fn paint_path(&mut self, path: Path<Pixels>, color: impl Into<Background>)

Paints path filled with color, at the current z-index.

The path’s coordinates are in logical pixels within the window, and the content mask and element opacity apply to it. Call it during paint.

pub fn paint_underline( &mut self, origin: Point<Pixels>, width: Pixels, style: &UnderlineStyle, )

Paints an underline of width starting at origin, using style.

The underline is drawn at the current z-index, and the content mask and element opacity apply to it. style.wavy draws a wave instead of a straight line. Call it during paint.

pub fn paint_strikethrough( &mut self, origin: Point<Pixels>, width: Pixels, style: &StrikethroughStyle, )

Paints a strikethrough line of width starting at origin, using style.

The line is drawn at the current z-index, and the content mask and element opacity apply to it. Call it during paint.

pub fn paint_glyph( &mut self, origin: Point<Pixels>, font_id: FontId, glyph_id: GlyphId, font_size: Pixels, color: Hsla, ) -> Result<()>

Paints a monochrome (non-emoji) glyph into the scene for the next frame at the current z-index.

The y component of the origin is the baseline of the glyph. You should generally prefer to use the ShapedLine::paint or ShapedText::paint methods in the TextSystem. This method is only useful if you need to paint a single glyph that has already been shaped.

This method should only be called as part of the paint phase of element drawing.

pub fn paint_emoji( &mut self, origin: Point<Pixels>, font_id: FontId, glyph_id: GlyphId, font_size: Pixels, ) -> Result<()>

Paints an emoji glyph into the scene for the next frame at the current z-index.

The y component of the origin is the baseline of the glyph. You should generally prefer to use the ShapedLine::paint or ShapedText::paint methods in the TextSystem. This method is only useful if you need to paint a single emoji that has already been shaped.

This method should only be called as part of the paint phase of element drawing.

pub fn paint_emoji_with_color( &mut self, origin: Point<Pixels>, font_id: FontId, glyph_id: GlyphId, font_size: Pixels, color: Hsla, ) -> Result<()>

Paints a color glyph with an application foreground for currentColor layers.

pub fn paint_svg( &mut self, bounds: Bounds<Pixels>, path: SharedString, data: Option<&[u8]>, transformation: TransformationMatrix, color: Hsla, cx: &App, ) -> Result<()>

Paints a monochrome SVG into bounds, tinted with color.

path identifies the SVG for caching. If data is Some, those bytes are the SVG; if it is None, the SVG is loaded from path through the app’s asset source. transformation rotates or flips the SVG within bounds. Returns an error if the SVG can’t be rendered. Call it during paint.

pub fn paint_image( &mut self, bounds: Bounds<Pixels>, image_bounds: Bounds<Pixels>, corner_radii: Corners<Pixels>, corner_smoothing: f32, data: Arc<RenderImage>, frame_index: usize, grayscale: bool, ) -> Result<()>

Paints data into bounds, scaled to fit image_bounds.

The visible region is bounds.intersect(&image_bounds), and corner_radii round the corners of bounds. frame_index selects a frame of an animated image, and grayscale paints the image in grayscale. Returns an error if the image can’t be uploaded to the renderer. Call it during paint.

pub fn paint_surface( &mut self, bounds: Bounds<Pixels>, source: impl Into<SurfaceSource>, )

Paints a platform surface, such as a video frame, into bounds.

source identifies the surface. The content mask applies. Call it during paint.

pub fn drop_image(&mut self, data: Arc<RenderImage>) -> Result<()>

Removes every frame of data from the renderer’s texture atlas, freeing its GPU memory.

Call it when an image is no longer needed. The image is uploaded again the next time it is painted. The Result is always Ok, and it exists so the method can be extended later.

pub fn has_image_atlas_entry(&self, data: &RenderImage) -> bool

Returns whether every frame of data is already uploaded to the texture atlas.

Use it to check whether painting data would need an upload. Images with no frames return false.

pub fn request_layout( &mut self, style: Style, children: impl IntoIterator<Item = LayoutId>, cx: &mut App, ) -> LayoutId

Adds a layout node with style and children to the frame, and returns its id.

Call it from Element::request_layout (or from a view’s render, which runs during request layout). Pass the ids of the child nodes you created, and use the returned LayoutId to read the node’s bounds later with Window::layout_bounds. Layout is computed once, after every node is requested, by the framework.

Call it during request layout or prepaint.

pub fn request_measured_layout<F>( &mut self, style: Style, measure: F, ) -> LayoutId

where F: Fn(Size<Option<Pixels>>, Size<AvailableSpace>, &mut Window, &mut App) -> Size<Pixels> + 'static,

Adds a layout node whose size comes from measure, which runs during layout.

Use it for content whose size depends on what it contains, such as text. measure receives the known dimensions (None where the size is not yet known), the available space on each axis, the window and the app, and returns the size the node should take. GPUI uses it for text measurement.

Call it during request layout or prepaint.

pub fn compute_layout( &mut self, layout_id: LayoutId, available_space: Size<AvailableSpace>, cx: &mut App, )

Computes the layout of layout_id and its descendants within available_space.

GPUI calls this for the root of each frame, before prepaint. After it runs, Window::layout_bounds returns the bounds of layout_id and of any of its descendants. Call it during prepaint.

pub fn layout_bounds(&mut self, layout_id: LayoutId) -> Bounds<Pixels>

Returns the bounds of a layout node, in window coordinates, after the element offset is applied.

GPUI passes these bounds to Element::prepaint for you, so you rarely need this method directly. It is valid during prepaint, after Window::compute_layout has run. The offset comes from Window::with_element_offset, such as a scroll position.

pub fn parent_relative_layout_bounds( &mut self, layout_id: LayoutId, ) -> Bounds<Pixels>

Returns the bounds of a layout node relative to its parent, snapped to device pixels.

Unlike Window::layout_bounds, this result doesn’t depend on where the parent is in the window, so a child keeps the same sub-pixel position while its parent moves. Text-bearing elements use it so their glyphs don’t shift as a parent scrolls. Call it during prepaint.

pub fn set_layout_direction_text( &mut self, node_id: LayoutId, text: impl Into<SharedString>, )

Supplies source text used by LayoutDirection::Auto for a custom layout node.

Built-in text elements register their content automatically. Call this during request_layout after obtaining the node’s LayoutId.

pub fn insert_hitbox( &mut self, bounds: Bounds<Pixels>, behavior: HitboxBehavior, ) -> Hitbox

Inserts a hitbox covering bounds for the frame being prepainted, and returns it.

The hitbox’s content mask is the one active now, so a hitbox inside a scroll container doesn’t receive input outside the container. Call it during prepaint. Keep the returned Hitbox for paint or for event handlers, where Hitbox::is_hovered tells you whether the pointer is over it.

Examples

struct Hovered {
    hitbox: Rc<RefCell<Option<Hitbox>>>,
}

impl Render for Hovered {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
        let slot = self.hitbox.clone();
        canvas(
            move |bounds, window, _| {
                *slot.borrow_mut() = Some(window.insert_hitbox(bounds, HitboxBehavior::Normal));
            },
            |_, _, _, _| {},
        )
        .size(px(100.))
    }
}

pub fn insert_hitbox_mut( &mut self, bounds: Bounds<Pixels>, behavior: HitboxBehavior, ) -> &mut Hitbox

Like Window::insert_hitbox, but returns a mutable reference so you can set the hitbox’s tags before the frame ends.

The reference is into this frame’s hitbox list, so it stays valid only until the next call that inserts a hitbox. Call it during prepaint.

pub fn insert_window_control_hitbox( &mut self, area: WindowControlArea, hitbox: Hitbox, )

Registers hitbox as the platform control area of a custom title bar.

The platform uses the hitbox to drag, maximize, minimize or close the window when the user interacts with it. Call it during paint, and see WindowControlArea for the areas.

pub fn set_key_context(&mut self, context: KeyContext)

Sets the key context of the current element, which key bindings match against.

A binding with a context such as "Editor" applies only when an element on the focus path has that context. Call it during paint. See InteractiveElement::key_context for the usual way to set it.

pub fn set_focus_handle(&mut self, focus_handle: &FocusHandle, _: &App)

Connects the current element to focus_handle for focus and key dispatch this frame.

If the handle is focused, the frame keeps it focused. InteractiveElement::track_focus calls this for you. Call it during prepaint.

pub fn set_view_id(&mut self, view_id: EntityId)

Sets the view that the current element belongs to, for view caching.

GPUI sets this for each view it renders, so custom elements rarely need it. It exists for elements built outside a view. The method is expected to go away. Call it during prepaint.

pub fn current_view(&self) -> EntityId

Returns the id of the view whose element is being rendered, prepainted or painted.

Use it when a callback needs to notify the view being drawn, such as the callback that Window::use_asset schedules. Call it during prepaint or paint.

Panics

Panics if no view is being rendered, such as in an event listener or outside a frame. Debug builds also panic when called outside prepaint and paint.

pub fn with_image_cache<F, R>( &mut self, image_cache: Option<AnyImageCache>, f: F, ) -> R

where F: FnOnce(&mut Self) -> R,

Runs f with image_cache active, so images painted inside f load through it.

Pass None to run f with the cache already in effect. The cache applies only while f runs.

pub fn handle_input( &mut self, focus_handle: &FocusHandle, input_handler: impl InputHandler, cx: &App, )

Registers input_handler to receive text from the platform, if focus_handle is focused.

Text input and IME composition go through this handler. It stays active until the next frame is painted, and it is ignored unless focus_handle has focus. Use ElementInputHandler to implement it for an element. Call it during paint.

pub fn notify_text_input_changed(&self, focus_handle: &FocusHandle)

Notifies native text services that the focused component’s text changed.

Text components should call this after application-driven edits, in addition to notifying GPUI to redraw. Unfocused or unregistered components are ignored.

pub fn notify_text_selection_changed(&self, focus_handle: &FocusHandle)

Notifies native text services that the focused component’s selection changed.

Text components should call this after application-driven selection changes, in addition to notifying GPUI to redraw.

pub fn on_mouse_event<Event: MouseEvent>( &mut self, listener: impl FnMut(&Event, DispatchPhase, &mut Window, &mut App) + 'static, )

Registers a listener for every mouse event of type Event, for the frame being painted.

The listener runs for each event of that type, whether or not the pointer is over an element. Event is chosen by the type of the listener’s first parameter, such as MouseDownEvent. The listener is called in both the capture and the bubble phase, and phase says which. Listeners are cleared when the next frame is painted, so register them on every paint. Most code should use the handlers on elements, such as on_mouse_down, instead. Call it during paint.

Examples

struct Root {
    clicks: Rc<Cell<usize>>,
}

impl Render for Root {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
        let clicks = self.clicks.clone();
        canvas(
            |_, _, _| {},
            move |_, _, window, _| {
                window.on_mouse_event(move |_: &MouseDownEvent, phase, _, _| {
                    if phase.bubble() {
                        clicks.set(clicks.get() + 1);
                    }
                });
            },
        )
        .size(px(100.))
    }
}

pub fn on_key_event<Event: KeyEvent>( &mut self, listener: impl Fn(&Event, DispatchPhase, &mut Window, &mut App) + 'static, )

Registers a listener for key events of type Event on the current element, for the frame being painted.

Event is chosen by the type of the listener’s first parameter, such as KeyDownEvent. Listeners are cleared when the next frame is painted, so register them on every paint. This is a low-level method. Prefer the handlers on elements, such as on_key_down, unless you need to register a listener yourself. Call it during paint.

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

Registers a listener for changes to the modifier keys, for the frame being painted.

The listener runs when Shift, Control, Alt or Command goes down or up. Like the other listeners, it is cleared when the next frame is painted. Call it during paint.

pub fn on_focus_in( &mut self, handle: &FocusHandle, cx: &mut App, listener: impl FnMut(&mut Window, &mut App) + 'static, ) -> Subscription

Calls listener when handle’s element, or one of its descendants, gains focus.

It doesn’t fire when focus moves between handle’s element and its descendants, because handle already had focus. The listener runs during the focus phase at the end of the frame. The returned Subscription keeps the listener active until it is dropped. Keep the subscription in the view that owns the element, or the listener stops firing.

pub fn on_focus_out( &mut self, handle: &FocusHandle, cx: &mut App, listener: impl FnMut(FocusOutEvent, &mut Window, &mut App) + 'static, ) -> Subscription

Calls listener when handle’s element, or one of its descendants, loses focus.

The listener gets a FocusOutEvent whose blurred field identifies the element that lost focus. The listener runs during the focus phase at the end of the frame. The returned Subscription keeps the listener active until it is dropped. Context::on_focus_out is the same for the view being rendered.

pub fn dispatch_keystroke(&mut self, keystroke: Keystroke, cx: &mut App) -> bool

Dispatches keystroke as if the user had pressed it, and returns whether it was handled.

The keystroke goes through the same path as a real key press: actions from key bindings run first, then key listeners, then the focused input handler receives its text. The return value is true if a listener stopped propagation or the input handler accepted the text. Tests use it through TestAppWindow::simulate_keystrokes. Build a keystroke with Keystroke::parse.

pub fn keystroke_text_for(&self, action: &dyn Action) -> String

Returns the keystrokes bound to action, formatted for display, such as "cmd-s".

Uses the highest-precedence binding, which is the last one added to the keymap. Returns the action’s name if it has no binding. Use it for labels on menus and tooltips.

pub fn dispatch_event( &mut self, event: PlatformInput, cx: &mut App, ) -> DispatchEventResult

Dispatches a platform input event to the window and returns how it was handled.

Mouse, keyboard and touch events are routed as described in input dispatch. The result says whether propagation continued and whether a listener called Window::prevent_default. Platforms call this for every event. Tests normally use the simulate_* methods on TestAppWindow instead.

pub fn touch_prediction_enabled(&self) -> bool

Whether recognized touch pans may use the platform’s predicted touch positions (TouchEvent::predicted_position) to compensate for input latency. Defaults to true.

pub fn set_touch_prediction_enabled(&mut self, enabled: bool)

Sets whether recognized touch pans may use the platform’s predicted touch positions. Disabling drops TouchEvent::predicted_position before gesture recognition, so pans track only raw touch positions.

pub fn mouse_hit_test(&self) -> &HitTest

Returns the hit test for the mouse position, computed from the last rendered frame.

It lists the hitboxes under the pointer, front to back, with each hitbox’s depth and tags. The result is updated when the mouse moves or the frame is redrawn.

pub fn has_pending_keystrokes(&self) -> bool

Returns whether the window is partway through a multi-keystroke binding, such as cmd-k cmd-s.

After the first keystroke of such a binding, GPUI waits for the next one. Use this to show that a sequence is pending.

pub fn pending_input(&self) -> Option<PendingInputStatus<'_>>

Returns the keystrokes typed so far that could still complete a multi-keystroke binding.

Returns None when no binding is pending. The list is cleared when the sequence completes, times out, or focus changes. Returns pending input that can still complete a multi-stroke key binding. Input left over from a previous focus can never complete one.

pub fn set_pending_input_timeout_paused<T: 'static>( &mut self, owner: &Entity<T>, paused: bool, cx: &mut App, ) -> bool

Pauses or resumes the current pending input timeout on behalf of owner.

A paused timeout resumes automatically if owner is released. Returns whether the timeout state changed. A timeout paused by one owner cannot be resumed by another.

pub fn pending_input_keystrokes(&self) -> Option<&[Keystroke]>

Returns the currently pending input keystrokes that might result in a multi-stroke key binding.

pub fn observe_global<G: Global>( &mut self, cx: &mut App, f: impl Fn(&mut Window, &mut App) + 'static, ) -> Subscription

Calls handler each time the global G is updated, for as long as the subscription is alive.

The window-aware form of App::observe_global. Keep the returned Subscription in the view that uses the global.

pub fn activate(&self)

Brings the window to the front and focuses it at the platform level.

The platform may refuse, such as when the app isn’t allowed to steal focus. If you have an activation token from the platform, use Window::activate_with_token instead.

pub fn activate_with_token(&self, token: &str) -> bool

Request focus using a token supplied by the desktop shell, such as a Wayland tray host. Show the window before calling this method.

Returns whether the platform submitted the request. The compositor may still deny focus. Returns false for empty tokens or unsupported platforms; callers can then fall back to Self::activate. Tokens must not be reused for subsequent activations.

pub fn request_attention(&self)

Asks the operating system to draw attention to this window, such as by bouncing the dock icon.

pub fn minimize_window(&self)

Minimizes the window at the platform level.

pub fn set_visible(&self, visible: bool)

Show or hide the current window at the platform level.

Call Window::activate separately when the window should also receive focus. The window manager may still focus a window when it is shown.

pub fn toggle_fullscreen(&self)

Enters fullscreen mode, or leaves it if the window is already fullscreen.

pub fn toggle_simple_fullscreen(&self)

Toggle simple (borderless) fullscreen, where the window covers the entire screen including the menu bar and, on notched displays, the area around the notch. Unlike Window::toggle_fullscreen, this does not move the window into its own Mission Control space. Only has an effect on macOS.

pub fn invalidate_character_coordinates(&self)

Tells the platform to recompute where the input method candidate window should appear.

Call it after the caret moves, so the candidate window follows the text input.

pub fn prompt<T>( &mut self, level: PromptLevel, message: &str, detail: Option<&str>, answers: &[T], cx: &mut App, ) -> Receiver<usize>

where T: Clone + Into<PromptButton>,

Shows a prompt with message, detail and one button per entry in answers.

The returned receiver yields the index of the button the user clicked. The level sets the prompt’s icon and emphasis. Unless the app has set a prompt builder, the platform’s native dialog is used. Await the receiver from a task, and don’t block on it in a listener.

pub fn has_active_prompt(&self) -> bool

Returns whether a prompt rendered by GPUI is currently active in this window.

This is only true for prompts rendered in the window (see App::set_prompt_builder), not for platform-native prompt dialogs.

pub fn context_stack(&self) -> Vec<KeyContext>

Returns the key contexts on the path from the root to the focused element, outermost first.

Key bindings match against this stack. It is empty when nothing has focus.

pub fn available_actions(&self, cx: &App) -> Vec<Box<dyn Action>>

Returns one instance of each action that a listener on the focused element’s path handles.

Use it to populate a command palette. Actions that need input to build are left out.

pub fn bindings_for_action(&self, action: &dyn Action) -> Vec<KeyBinding>

Returns the key bindings that invoke action from the focused element, in the order they were added.

For display, use the last binding, which takes precedence. See Window::highest_precedence_binding_for_action to get that one directly.

pub fn highest_precedence_binding_for_action( &self, action: &dyn Action, ) -> Option<KeyBinding>

Returns the key binding that takes precedence for action from the focused element.

This is the same as the last result of Window::bindings_for_action, without building the list.

pub fn bindings_for_action_in_context( &self, action: &dyn Action, context: KeyContext, ) -> Vec<KeyBinding>

Returns the key bindings for an action in a context.

pub fn highest_precedence_binding_for_action_in_context( &self, action: &dyn Action, context: KeyContext, ) -> Option<KeyBinding>

Returns the highest precedence key binding for an action in a context. This is more efficient than getting the last result of bindings_for_action_in_context.

pub fn bindings_for_action_in( &self, action: &dyn Action, focus_handle: &FocusHandle, ) -> Vec<KeyBinding>

Returns any bindings that would invoke an action on the given focus handle if it were focused. Bindings are returned in the order they were added. For display, the last binding should take precedence.

pub fn highest_precedence_binding_for_action_in( &self, action: &dyn Action, focus_handle: &FocusHandle, ) -> Option<KeyBinding>

Returns the highest precedence key binding that would invoke an action on the given focus handle if it were focused. This is more efficient than getting the last result of bindings_for_action_in.

pub fn possible_bindings_for_input( &self, input: &[Keystroke], ) -> Vec<KeyBinding>

Returns the bindings that could complete the sequence input, given the current key contexts.

Use it with Window::pending_input_keystrokes to show the next keys of a sequence.

pub fn listener_for<T: 'static, E>( &self, view: &Entity<T>, f: impl Fn(&mut T, &E, &mut Window, &mut Context<'_, T>) + 'static, ) -> impl Fn(&E, &mut Window, &mut App) + 'static

Wraps f as an event listener that updates the entity view, if it is still alive.

The returned closure takes an event, a window and an app, and calls f with the view, the event, the window and a Context<T>. If view has been released, the call does nothing. It works like Context::listener for code that has a window but no Context at hand.

pub fn handler_for<E: 'static, Callback: Fn(&mut E, &mut Window, &mut Context<'_, E>) + 'static>( &self, entity: &Entity<E>, f: Callback, ) -> impl Fn(&mut Window, &mut App) + 'static

Wraps f as a handler that updates entity, if it is still alive.

Like Window::listener_for, but the handler takes only a window and an app, with no event. Use it for callbacks such as on_click handlers that don’t need the event value.

pub fn on_window_should_close( &self, cx: &App, f: impl Fn(&mut Window, &mut App) -> bool + 'static, )

Registers a callback that runs when the user asks to close the window, and can cancel the close.

The callback returns true to let the window close and false to keep it open, such as when there are unsaved changes. If the window no longer exists when the request arrives, the close proceeds. Call it once per window; it sets the platform’s close handler.

pub fn on_action( &mut self, action_type: TypeId, listener: impl Fn(&dyn Any, DispatchPhase, &mut Window, &mut App) + 'static, )

Register an action listener on this node for the next frame. The type of action is determined by the first parameter of the given listener. When the next frame is rendered the listener will be cleared.

This is a fairly low-level method, so prefer using action handlers on elements unless you have a specific need to register a listener yourself.

This method should only be called as part of the paint phase of element drawing.

pub fn on_action_when( &mut self, condition: bool, action_type: TypeId, listener: impl Fn(&dyn Any, DispatchPhase, &mut Window, &mut App) + 'static, )

Registers listener for action_type on the current node, if condition is true.

Works like Window::on_action, but the listener is registered only when condition is true. The listener is cleared when the next frame is painted. Call it during paint.

pub fn gpu_specs(&self) -> Option<GpuSpecs>

Returns information about the GPU that renders this window, if the platform reports it.

Currently it returns None on macOS and Windows.

pub fn gpu_context(&self) -> Option<Box<dyn Any>>

Returns the GPU device and queue used to render this window, if the backend exposes them.

The returned box holds the backend’s device and queue, which you downcast to use. Embedders that share the device with their own rendering use this. See also Window::gpu_device_lost.

pub fn gpu_context_info(&self) -> Option<Box<dyn Any>>

Returns backend-specific GPU information for custom controls.

The returned box has the rendering backend’s own type. Downcast it with downcast_ref to read the backend’s values.

pub fn gpu_device_lost(&self) -> Option<bool>

Whether the GPU device backing this window has been lost (recovery happens on a subsequent platform draw). None when the backend cannot know. Embedders that captured the device from Self::gpu_context should stop submitting while this is Some(true) and re-acquire the device once it reads Some(false).

pub fn titlebar_double_click(&self)

Performs the platform’s title bar double-click action, such as zooming or minimizing.

This is macOS specific. Call it from a double-click handler on a custom title bar.

pub fn window_title(&self) -> String

Returns the window’s title as the platform reports it.

This is macOS specific. To set the title, use Window::set_window_title.

pub fn tabbed_windows(&self) -> Option<Vec<SystemWindowTab>>

Returns a list of all tabbed windows and their titles. This is macOS specific.

pub fn tab_bar_visible(&self) -> bool

Returns the tab bar visibility. This is macOS specific.

pub fn merge_all_windows(&self)

Merges all open windows into a single tabbed window. This is macOS specific.

pub fn move_tab_to_new_window(&self)

Moves the tab to a new containing window. This is macOS specific.

pub fn toggle_window_tab_overview(&self)

Shows or hides the window tab overview. This is macOS specific.

pub fn set_tabbing_identifier(&self, tabbing_identifier: Option<String>)

Sets the tabbing identifier for the window. This is macOS specific.

pub fn play_system_bell(&self)

Request the OS to play an alert sound. On some platforms this is associated with the window, for others it’s just a simple global function call.

pub fn is_a11y_enabled(&self) -> bool

Returns whether accessibility support is enabled for this window.

This is false when the app was created with crate::Application::new_inaccessible. Unlike Self::is_a11y_active, this does not depend on whether assistive technology is currently connected, so it can be used to gate subscriptions that are only needed for accessibility.

pub fn is_a11y_active(&self) -> bool

Returns whether accessibility features are active for this frame, i.e. whether assistive technology (such as a screen reader) is connected and an accessibility tree is being built.

Use this to skip computing data during rendering that is only observable through the accessibility tree. When accessibility is activated, a redraw is forced, so gated work is recomputed before the next tree update is sent to the platform.

See the accessibility guide for an overview.

pub fn set_a11y_forced(&mut self, forced: bool)

Build this window’s accessibility tree every frame, even with no assistive technology connected, so Self::debug_a11y_tree_json and the accessibility actions work for automation. Forces a redraw, since the tree is built during prepaint. crate::Application::new_inaccessible still wins.

pub fn debug_a11y_tree_json(&self) -> Option<String>

Debug representation of the last frame’s accessibility information.

pub fn a11y_tree(&self) -> Option<&TreeUpdate>

The accessibility tree built by the last frame, when one was built (see Self::is_a11y_active and Self::set_a11y_forced). Node ids are stable while the element identity is; bounds come from Self::a11y_node_bounds.

pub fn a11y_node_bounds(&self, node: NodeId) -> Option<Bounds<Pixels>>

Window-space bounds, in logical pixels, of a node in the last built tree.

pub fn a11y_frame_number(&self) -> u64

How many accessibility trees this window has built; zero before the first. Lets a caller tell a fresh tree from the one it already read.

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

Register a listener for an accessibility action on a specific node. The listener will be called when a screen reader requests the given action on the node identified by node_id.

See the accessibility guide for an overview.

pub fn perform_a11y_action( &mut self, target: NodeId, action: Action, data: Option<ActionData>, cx: &mut App, )

Perform an accessibility action on a node as assistive technology would: a registered Self::on_a11y_action listener first, else the built-in handling (Click synthesizes a pointer click at the node’s bounds, Focus focuses it, Blur blurs the window).

pub fn toggle_inspector(&mut self, cx: &mut App)

Turns the element inspector on or off for this window.

While on, the window shows the inspector panel, and clicking an element in picking mode selects it. Available with the inspector feature or in debug builds.

pub fn is_inspector_picking(&self, _cx: &App) -> bool

Returns whether the inspector is in picking mode, where clicks select elements instead of reaching them.

pub fn with_inspector_state<T: 'static, R>( &mut self, inspector_id: Option<&InspectorElementId>, cx: &mut App, f: impl FnOnce(&mut Option<T>, &mut Self) -> R, ) -> Option<R>

Runs f with mutable access to the inspector’s state for the element inspector_id.

The state is Some only for the element the inspector has selected. Otherwise f gets a temporary None. Element code uses it to expose its own state to the inspector.

pub fn insert_inspector_hitbox( &mut self, hitbox_id: HitboxId, inspector_id: Option<&InspectorElementId>, cx: &App, )

Records hitbox_id as belonging to inspector_id, so picking mode can select that element.

Does nothing unless the inspector is in picking mode. Call it during prepaint or paint, after inserting the hitbox.

pub fn set_modifiers(&mut self, modifiers: Modifiers)

Sets the modifier keys that the window reports, without sending an event.

Tests use it to hold a key, such as Shift, while they simulate a click.

pub fn simulate_mouse_move(&mut self, position: Point<Pixels>, cx: &mut App)

Sends a mouse move to position through normal event dispatch, which updates hover state and tooltips.

Use it in tests. It doesn’t draw the window, so call TestAppWindow::draw first if the frame you’re testing has not been drawn yet.

Trait Implementations

impl HasDisplayHandle for Window

fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError>

Get a handle to the display controller of the windowing system.

impl HasWindowHandle for Window

fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError>

Get a handle to the window.