Struct App 

pub struct App { /* private fields */ }

Contains the state of the full application, and passed as a reference to a variety of callbacks. Other Context derefs to this type. You need a reference to an App to access the state of a Entity.

Implementations

impl App

pub fn shutdown(&mut self)

Quit the application gracefully. Handlers registered with Context::on_app_quit will be given 100ms to complete before exiting.

pub fn keyboard_layout(&self) -> &dyn PlatformKeyboardLayout

Get the id of the current keyboard layout

pub fn keyboard_mapper(&self) -> &Rc<dyn PlatformKeyboardMapper>

Get the current keyboard mapper.

pub fn on_keyboard_layout_change<F>(&self, callback: F) -> Subscription

where F: 'static + FnMut(&mut App),

Invokes a handler when the current keyboard layout changes

pub fn quit(&self)

Gracefully quit the application via the platform’s standard routine.

pub fn refresh_windows(&mut self)

Schedules all windows in the application to be redrawn. This can be called multiple times in an update cycle and still result in a single redraw.

pub fn observe<W>( &mut self, entity: &Entity<W>, on_notify: impl FnMut(Entity<W>, &mut App) + 'static, ) -> Subscription

where W: 'static,

Arrange a callback to be invoked when the given entity calls notify on its respective context.

pub fn subscribe<T, Event>( &mut self, entity: &Entity<T>, on_event: impl FnMut(Entity<T>, &Event, &mut App) + 'static, ) -> Subscription

where T: 'static + EventEmitter<Event>, Event: 'static,

Arrange for the given callback to be invoked whenever the given entity emits an event of a given type. The callback is provided a handle to the emitting entity and a reference to the emitted event.

pub fn windows(&self) -> Vec<AnyWindowHandle>

Returns handles to all open windows in the application. Each handle could be downcast to a handle typed for the root view of that window. To find all windows of a given type, you could filter on

pub fn window_stack(&self) -> Option<Vec<AnyWindowHandle>>

Returns the window handles ordered by their appearance on screen, front to back.

The first window in the returned list is the active/topmost window of the application.

This method returns None if the platform doesn’t implement the method yet.

pub fn active_window(&self) -> Option<AnyWindowHandle>

Returns a handle to the window that is currently focused at the platform level, if one exists.

pub fn open_window<V: 'static + Render>( &mut self, options: WindowOptions, build_root_view: impl FnOnce(&mut Window, &mut App) -> Entity<V>, ) -> Result<WindowHandle<V>>

Opens a new window with the given option and the root view returned by the given function. The function is invoked with a Window, which can be used to interact with window-specific functionality.

pub fn activate(&self, ignoring_other_apps: bool)

Instructs the platform to activate the application by bringing it to the foreground.

pub fn hide(&self)

Hide the application at the platform level.

pub fn hide_other_apps(&self)

Hide other applications at the platform level.

pub fn unhide_other_apps(&self)

Unhide other applications at the platform level.

pub fn displays(&self) -> Vec<Rc<dyn PlatformDisplay>>

Returns the list of currently active displays.

pub fn primary_display(&self) -> Option<Rc<dyn PlatformDisplay>>

Returns the primary display that will be used for new windows.

pub fn is_screen_capture_supported(&self) -> bool

Returns whether screen_capture_sources may work.

pub fn screen_capture_sources( &self, ) -> Receiver<Result<Vec<Rc<dyn ScreenCaptureSource>>>>

Returns a list of available screen capture sources.

pub fn find_display(&self, id: DisplayId) -> Option<Rc<dyn PlatformDisplay>>

Returns the display with the given ID, if one exists.

pub fn window_appearance(&self) -> WindowAppearance

Returns the appearance of the application’s windows.

pub fn write_to_primary(&self, item: ClipboardItem)

Writes data to the primary selection buffer. Only available on Linux.

pub fn write_to_clipboard(&self, item: ClipboardItem)

Writes data to the platform clipboard.

pub fn read_from_primary(&self) -> Option<ClipboardItem>

Reads data from the primary selection buffer. Only available on Linux.

pub fn read_from_clipboard(&self) -> Option<ClipboardItem>

Reads data from the platform clipboard.

pub fn write_credentials( &self, url: &str, username: &str, password: &[u8], ) -> Task<Result<()>>

Writes credentials to the platform keychain.

pub fn read_credentials( &self, url: &str, ) -> Task<Result<Option<(String, Vec<u8>)>>>

Reads credentials from the platform keychain.

pub fn delete_credentials(&self, url: &str) -> Task<Result<()>>

Deletes credentials from the platform keychain.

pub fn open_url(&self, url: &str)

Directs the platform’s default browser to open the given URL.

pub fn register_url_scheme(&self, scheme: &str) -> Task<Result<()>>

Registers the given URL scheme (e.g. zed for zed:// urls) to be opened by the current app.

On some platforms (e.g. macOS) you may be able to register URL schemes as part of app distribution, but this method exists to let you register schemes at runtime.

pub fn app_path(&self) -> Result<PathBuf>

Returns the full pathname of the current app bundle.

Returns an error if the app is not being run from a bundle.

pub fn compositor_name(&self) -> &'static str

On Linux, returns the name of the compositor in use.

Returns an empty string on other platforms.

pub fn path_for_auxiliary_executable(&self, name: &str) -> Result<PathBuf>

Returns the file URL of the executable with the specified name in the application bundle

pub fn prompt_for_paths( &self, options: PathPromptOptions, ) -> Receiver<Result<Option<Vec<PathBuf>>>>

Displays a platform modal for selecting paths.

When one or more paths are selected, they’ll be relayed asynchronously via the returned oneshot channel. If cancelled, a None will be relayed instead. May return an error on Linux if the file picker couldn’t be opened.

pub fn prompt_for_new_path( &self, directory: &Path, suggested_name: Option<&str>, ) -> Receiver<Result<Option<PathBuf>>>

Displays a platform modal for selecting a new path where a file can be saved.

The provided directory will be used to set the initial location. When a path is selected, it is relayed asynchronously via the returned oneshot channel. If cancelled, a None will be relayed instead. May return an error on Linux if the file picker couldn’t be opened.

pub fn reveal_path(&self, path: &Path)

Reveals the specified path at the platform level, such as in Finder on macOS.

pub fn open_with_system(&self, path: &Path)

Opens the specified path with the system’s default application.

pub fn should_auto_hide_scrollbars(&self) -> bool

Returns whether the user has configured scrollbars to auto-hide at the platform level.

pub fn restart(&mut self)

Restarts the application.

pub fn set_restart_path(&mut self, path: PathBuf)

Sets the path to use when restarting the application.

pub fn http_client(&self) -> Arc<dyn HttpClient>

Returns the HTTP client for the application.

pub fn set_http_client(&mut self, new_client: Arc<dyn HttpClient>)

Sets the HTTP client for the application.

pub fn set_quit_mode(&mut self, mode: QuitMode)

Configures when the application should automatically quit. By default, QuitMode::Default is used.

pub fn svg_renderer(&self) -> SvgRenderer

Returns the SVG renderer used by the application.

pub fn to_async(&self) -> AsyncApp

Creates an AsyncApp, which can be cloned and has a static lifetime so it can be held across await points.

pub fn background_executor(&self) -> &BackgroundExecutor

Obtains a reference to the executor, which can be used to spawn futures.

pub fn foreground_executor(&self) -> &ForegroundExecutor

Obtains a reference to the executor, which can be used to spawn futures.

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

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

Spawns the future returned by the given function on the main thread. The closure will be invoked with AsyncApp, which allows the application state to be accessed across await points.

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

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

Spawns the future returned by the given function on the main thread with the given priority. The closure will be invoked with AsyncApp, which allows the application state to be accessed across await points.

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

Schedules the given function to be run at the end of the current effect cycle, allowing entities that are currently on the stack to be returned to the app.

pub fn asset_source(&self) -> &Arc<dyn AssetSource>

Accessor for the application’s asset source, which is provided when constructing the App.

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

Accessor for the text system.

pub fn has_global<G: Global>(&self) -> bool

Check whether a global of the given type has been assigned.

pub fn global<G: Global>(&self) -> &G

Access the global of the given type. Panics if a global for that type has not been assigned.

pub fn try_global<G: Global>(&self) -> Option<&G>

Access the global of the given type if a value has been assigned.

pub fn global_mut<G: Global>(&mut self) -> &mut G

Access the global of the given type mutably. Panics if a global for that type has not been assigned.

pub fn default_global<G: Global + Default>(&mut self) -> &mut G

Access the global of the given type mutably. A default value is assigned if a global of this type has not yet been assigned.

pub fn set_global<G: Global>(&mut self, global: G)

Sets the value of the global of the given type.

pub fn remove_global<G: Global>(&mut self) -> G

Remove the global of the given type from the app context. Does not notify global observers.

pub fn observe_global<G: Global>( &mut self, f: impl FnMut(&mut Self) + 'static, ) -> Subscription

Register a callback to be invoked when a global of the given type is updated.

pub fn observe_new<T: 'static>( &self, on_new: impl 'static + Fn(&mut T, Option<&mut Window>, &mut Context<'_, T>), ) -> Subscription

Arrange for the given function to be invoked whenever a view of the specified type is created. The function will be passed a mutable reference to the view along with an appropriate context.

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

where T: 'static,

Observe the release of a entity. The callback is invoked after the entity has no more strong references but before it has been dropped.

pub fn observe_release_in<T>( &self, handle: &Entity<T>, window: &Window, on_release: impl FnOnce(&mut T, &mut Window, &mut App) + 'static, ) -> Subscription

where T: 'static,

Observe the release of a entity. The callback is invoked after the entity has no more strong references but before it has been dropped.

pub fn observe_keystrokes( &mut self, f: impl FnMut(&KeystrokeEvent, &mut Window, &mut App) + 'static, ) -> Subscription

Register a callback to be invoked when a keystroke is received by the application in any window. Note that this fires after all other action and event mechanisms have resolved and that this API will not be invoked if the event’s propagation is stopped.

pub fn intercept_keystrokes( &mut self, f: impl FnMut(&KeystrokeEvent, &mut Window, &mut App) + 'static, ) -> Subscription

Register a callback to be invoked when a keystroke is received by the application in any window. Note that this fires before all other action and event mechanisms have resolved unlike App::observe_keystrokes which fires after. This means that cx.stop_propagation calls within interceptors will prevent action dispatch

pub fn bind_keys(&mut self, bindings: impl IntoIterator<Item = KeyBinding>)

Register key bindings.

pub fn clear_key_bindings(&mut self)

Clear all key bindings in the app.

pub fn key_bindings(&self) -> Rc<RefCell<Keymap>>

Get all key bindings in the app.

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

Register a global handler for actions invoked via the keyboard. These handlers are run at the end of the bubble phase for actions, and so will only be invoked if there are no other handlers or if they called cx.propagate().

pub fn stop_propagation(&mut self)

Event handlers propagate events by default. Call this method to stop dispatching to event handlers with a lower z-index (mouse) or higher in the tree (keyboard). This is the opposite of Self::propagate. It’s also possible to cancel a call to Self::propagate by calling this method before effects are flushed.

pub fn propagate(&mut self)

Action handlers stop propagation by default during the bubble phase of action dispatch dispatching to action handlers higher in the element tree. This is the opposite of Self::stop_propagation. It’s also possible to cancel a call to Self::stop_propagation by calling this method before effects are flushed.

pub fn build_action( &self, name: &str, data: Option<Value>, ) -> Result<Box<dyn Action>, ActionBuildError>

Build an action from some arbitrary data, typically a keymap entry.

pub fn all_action_names(&self) -> &[&'static str]

Get all action names that have been registered. Note that registration only allows for actions to be built dynamically, and is unrelated to binding actions in the element tree.

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

Returns key bindings that invoke the given action on the currently focused element, without checking context. Bindings are returned in the order they were added. For display, the last binding should take precedence.

pub fn action_schemas( &self, generator: &mut SchemaGenerator, ) -> Vec<(&'static str, Option<Schema>)>

Get all non-internal actions that have been registered, along with their schemas.

pub fn deprecated_actions_to_preferred_actions( &self, ) -> &HashMap<&'static str, &'static str>

Get a map from a deprecated action name to the canonical name.

pub fn action_deprecation_messages( &self, ) -> &HashMap<&'static str, &'static str>

Get a map from an action name to the deprecation messages.

pub fn action_documentation(&self) -> &HashMap<&'static str, &'static str>

Get a map from an action name to the documentation.

pub fn on_app_quit<Fut>( &self, on_quit: impl FnMut(&mut App) -> Fut + 'static, ) -> Subscription

where Fut: 'static + Future<Output = ()>,

Register a callback to be invoked when the application is about to quit. It is not possible to cancel the quit event at this point.

pub fn on_app_restart( &self, on_restart: impl 'static + FnMut(&mut App), ) -> Subscription

Register a callback to be invoked when the application is about to restart.

These callbacks are called before any on_app_quit callbacks.

pub fn on_window_closed( &self, on_closed: impl FnMut(&mut App) + 'static, ) -> Subscription

Register a callback to be invoked when a window is closed The window is no longer accessible at the point this callback is invoked.

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

Checks if the given action is bound in the current context, as defined by the app’s current focus, the bindings in the element tree, and any global action listeners.

pub fn set_menus(&self, menus: Vec<Menu>)

Sets the menu bar for this application. This will replace any existing menu bar.

pub fn get_menus(&self) -> Option<Vec<OwnedMenu>>

Gets the menu bar for this application.

pub fn set_dock_menu(&self, menus: Vec<MenuItem>)

Sets the right click menu for the app icon in the dock

pub fn perform_dock_menu_action(&self, action: usize)

Performs the action associated with the given dock menu item, only used on Windows for now.

pub fn add_recent_document(&self, path: &Path)

Adds given path to the bottom of the list of recent paths for the application. The list is usually shown on the application icon’s context menu in the dock, and allows to open the recent files via that context menu. If the path is already in the list, it will be moved to the bottom of the list.

pub fn update_jump_list( &self, menus: Vec<MenuItem>, entries: Vec<SmallVec<[PathBuf; 2]>>, ) -> Vec<SmallVec<[PathBuf; 2]>>

Updates the jump list with the updated list of recent paths for the application, only used on Windows for now. Note that this also sets the dock menu on Windows.

pub fn dispatch_action(&mut self, action: &dyn Action)

Dispatch an action to the currently active window or global action handler See crate::Action for more information on how actions work

pub fn has_active_drag(&self) -> bool

Is there currently something being dragged?

pub fn active_drag_cursor_style(&self) -> Option<CursorStyle>

Gets the cursor style of the currently active drag operation.

pub fn stop_active_drag(&mut self, window: &mut Window) -> bool

Stops active drag and clears any related effects.

pub fn set_active_drag_cursor_style( &mut self, cursor_style: CursorStyle, window: &mut Window, ) -> bool

Sets the cursor style for the currently active drag operation.

pub fn set_prompt_builder( &mut self, renderer: impl Fn(PromptLevel, &str, Option<&str>, &[PromptButton], PromptHandle, &mut Window, &mut App) -> RenderablePromptHandle + 'static, )

Set the prompt renderer for GPUI. This will replace the default or platform specific prompts with this custom implementation.

pub fn reset_prompt_builder(&mut self)

Reset the prompt builder to the default implementation.

pub fn remove_asset<A: Asset>(&mut self, source: &A::Source)

Remove an asset from GPUI’s cache

pub fn fetch_asset<A: Asset>( &mut self, source: &A::Source, ) -> (Shared<Task<A::Output>>, bool)

Asynchronously load an asset, if the asset hasn’t finished loading this will return None.

Note that the multiple calls to this method will only result in one Asset::load call at a time, and the results of this call will be cached

pub fn focus_handle(&self) -> FocusHandle

Obtain a new FocusHandle, which allows you to track and manipulate the keyboard focus for elements rendered within this window.

pub fn notify(&mut self, entity_id: EntityId)

Tell GPUI that an entity has changed and observers of it should be notified.

pub fn get_name(&self) -> Option<&'static str>

Returns the name for this App.

pub fn can_select_mixed_files_and_dirs(&self) -> bool

Returns true if the platform file picker supports selecting a mix of files and directories.

pub fn drop_image( &mut self, image: Arc<RenderImage>, current_window: Option<&mut Window>, )

Removes an image from the sprite atlas on all windows.

If the current window is being updated, it will be removed from App.windows, you can use current_window to specify the current window. This is a no-op if the image is not in the sprite atlas.

pub fn set_inspector_renderer(&mut self, f: InspectorRenderer)

Sets the renderer for the inspector.

pub fn register_inspector_element<T: 'static, R: IntoElement>( &mut self, f: impl 'static + Fn(InspectorElementId, &T, &mut Window, &mut App) -> R, )

Registers a renderer specific to an inspector state.

pub fn init_colors(&mut self)

Initializes gpui’s default colors for the application.

These colors can be accessed through cx.default_colors().

Trait Implementations

impl AppContext for App

fn new<T: 'static>( &mut self, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Builds an entity that is owned by the application.

The given function will be invoked with a Context and must return an object representing the entity. An Entity handle will be returned, which can be used to access the entity in a context.

fn update_entity<T: 'static, R>( &mut self, handle: &Entity<T>, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> R

Updates the entity referenced by the given handle. The function is passed a mutable reference to the entity along with a Context for the entity.

type Result<T> = T

The result type for this context, used for async contexts that can’t hold a direct reference to the application context.

fn reserve_entity<T: 'static>(&mut self) -> Self::Result<Reservation<T>>

Reserve a slot for a entity to be inserted later. The returned Reservation allows you to obtain the EntityId for the future entity.

fn insert_entity<T: 'static>( &mut self, reservation: Reservation<T>, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Self::Result<Entity<T>>

Insert a new entity in the app context based on a Reservation previously obtained from reserve_entity.

fn as_mut<'a, T>(&'a mut self, handle: &Entity<T>) -> GpuiBorrow<'a, T>

where T: 'static,

Update a entity in the app context.

fn read_entity<T, R>( &self, handle: &Entity<T>, read: impl FnOnce(&T, &App) -> R, ) -> Self::Result<R>

where T: 'static,

Read a entity from the app context.

fn update_window<T, F>( &mut self, handle: AnyWindowHandle, update: F, ) -> Result<T>

where F: FnOnce(AnyView, &mut Window, &mut App) -> T,

Update a window for the given handle.

fn read_window<T, R>( &self, window: &WindowHandle<T>, read: impl FnOnce(Entity<T>, &App) -> R, ) -> Result<R>

where T: 'static,

Read a window off of the application context.

fn background_spawn<R>( &self, future: impl Future<Output = R> + Send + 'static, ) -> Task<R>

where R: Send + 'static,

Spawn a future on a background thread

fn read_global<G, R>( &self, callback: impl FnOnce(&G, &App) -> R, ) -> Self::Result<R>

where G: Global,

Read a global from this app context

impl<T> Borrow<App> for Context<'_, T>

fn borrow(&self) -> &App

Immutably borrows from an owned value.

impl<T> BorrowMut<App> for Context<'_, T>

fn borrow_mut(&mut self) -> &mut App

Mutably borrows from an owned value.

impl DefaultColors for App

fn default_colors(&self) -> &Arc<Colors>

Returns the default Colors