Trait Platform 

pub trait Platform: 'static {
    // Required methods
    fn background_executor(&self) -> BackgroundExecutor;
    fn foreground_executor(&self) -> ForegroundExecutor;
    fn text_system(&self) -> Arc<dyn PlatformTextSystem> ;
    fn run(&self, on_finish_launching: Box<dyn FnOnce() + 'static>);
    fn quit(&self);
    fn restart(&self, binary_path: Option<PathBuf>, arguments: Vec<OsString>);
    fn activate(&self, ignoring_other_apps: bool);
    fn hide(&self);
    fn hide_other_apps(&self);
    fn unhide_other_apps(&self);
    fn displays(&self) -> Vec<Rc<dyn PlatformDisplay>>;
    fn primary_display(&self) -> Option<Rc<dyn PlatformDisplay>>;
    fn on_displays_changed(&self, callback: Box<dyn FnMut()>);
    fn active_window(&self) -> Option<AnyWindowHandle>;
    fn open_window(
        &self,
        handle: AnyWindowHandle,
        options: WindowParams,
    ) -> Result<Box<dyn PlatformWindow>>;
    fn window_appearance(&self) -> WindowAppearance;
    fn open_url(&self, url: &str);
    fn on_open_urls(&self, callback: Box<dyn FnMut(Vec<String>)>);
    fn register_url_scheme(&self, url: &str) -> Task<Result<()>> ;
    fn prompt_for_paths(
        &self,
        options: PathPromptOptions,
    ) -> Receiver<Result<Option<Vec<PathBuf>>>> ;
    fn prompt_for_new_path(
        &self,
        directory: &Path,
        suggested_name: Option<&str>,
    ) -> Receiver<Result<Option<PathBuf>>> ;
    fn can_select_mixed_files_and_dirs(&self) -> bool;
    fn reveal_path(&self, path: &Path);
    fn open_with_system(&self, path: &Path);
    fn on_quit(&self, callback: Box<dyn FnMut() -> bool>);
    fn on_reopen(&self, callback: Box<dyn FnMut()>);
    fn on_system_sleep(&self, callback: Box<dyn FnMut()>);
    fn on_system_wake(&self, callback: Box<dyn FnMut()>);
    fn set_menus(&self, menus: Vec<Menu>, keymap: &Keymap);
    fn set_dock_menu(&self, menu: Vec<MenuItem>, keymap: &Keymap);
    fn on_app_menu_action(&self, callback: Box<dyn FnMut(&dyn Action)>);
    fn on_will_open_app_menu(&self, callback: Box<dyn FnMut()>);
    fn on_validate_app_menu_command(
        &self,
        callback: Box<dyn FnMut(&dyn Action) -> bool>,
    );
    fn thermal_state(&self) -> ThermalState;
    fn on_thermal_state_change(&self, callback: Box<dyn FnMut()>);
    fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>> ;
    fn app_path(&self) -> Result<PathBuf>;
    fn path_for_auxiliary_executable(&self, name: &str) -> Result<PathBuf>;
    fn set_cursor_style(&self, style: CursorStyle);
    fn hide_cursor_until_mouse_moves(&self);
    fn is_cursor_visible(&self) -> bool;
    fn should_auto_hide_scrollbars(&self) -> bool;
    fn read_from_clipboard(&self) -> Option<ClipboardItem>;
    fn write_to_clipboard(&self, item: ClipboardItem);
    fn read_from_primary(&self) -> Option<ClipboardItem>;
    fn write_to_primary(&self, item: ClipboardItem);
    fn write_credentials(
        &self,
        url: &str,
        username: &str,
        password: &[u8],
    ) -> Task<Result<()>> ;
    fn read_credentials(
        &self,
        url: &str,
    ) -> Task<Result<Option<(String, Vec<u8>)>>> ;
    fn delete_credentials(&self, url: &str) -> Task<Result<()>> ;
    fn keyboard_layout(&self) -> Box<dyn PlatformKeyboardLayout>;
    fn keyboard_mapper(&self) -> Rc<dyn PlatformKeyboardMapper>;
    fn on_keyboard_layout_change(&self, callback: Box<dyn FnMut()>);

    // Provided methods
    fn set_initial_windowing(&self, _request: WindowingRequest) { ... }
    fn request_windowing(&self, _request: WindowingRequest) -> Task<Result<()>>  { ... }
    fn set_activation_policy(&self, _policy: ActivationPolicy) { ... }
    fn window_stack(&self) -> Option<Vec<AnyWindowHandle>> { ... }
    fn is_screen_capture_supported(&self) -> bool { ... }
    fn screen_capture_sources(
        &self,
    ) -> Receiver<Result<Vec<Rc<dyn ScreenCaptureSource>>>>  { ... }
    fn set_window_appearance(&self, _appearance: Option<WindowAppearance>) { ... }
    fn button_layout(&self) -> Option<WindowButtonLayout> { ... }
    fn on_app_lifecycle(&self, _callback: Box<dyn FnMut(AppLifecyclePhase)>) { ... }
    fn on_memory_warning(&self, _callback: Box<dyn FnMut()>) { ... }
    fn gestures(&self) -> Option<Rc<dyn PlatformGestures>> { ... }
    fn get_menus(&self) -> Option<Vec<OwnedMenu>> { ... }
    fn perform_dock_menu_action(&self, _action: usize) { ... }
    fn add_recent_document(&self, _path: &Path) { ... }
    fn update_jump_list(
        &self,
        _menus: Vec<MenuItem>,
        _entries: Vec<SmallVec<[PathBuf; 2]>>,
    ) -> Task<Vec<SmallVec<[PathBuf; 2]>>>  { ... }
    fn set_app_identity(&self, identifier: &str, name: &str) { ... }
    fn show_system_notification(&self, notification: SystemNotification) { ... }
    fn dismiss_system_notification(&self, tag: &str) { ... }
    fn on_system_notification_response(
        &self,
        callback: Box<dyn FnMut(SystemNotificationResponse)>,
    ) { ... }
    fn compositor_name(&self) -> &'static str { ... }
    fn graphical_environment(&self) -> Option<GraphicalEnvironment> { ... }
    fn read_from_clipboard_async(
        &self,
    ) -> Task<Result<Option<ClipboardItem>, ClipboardReadError>>  { ... }
    fn set_gpu_requirements(&self, _requirements: Box<dyn Any>) { ... }
    fn set_keyring_label(&self, _label: SharedString) { ... }
    fn supports_haptic_feedback(&self) -> bool { ... }
    fn play_haptic_feedback(&self, _style: HapticFeedbackStyle) { ... }
}

The operating system or browser that GPUI runs on, as seen by the App.

Each backend crate implements this trait once: gpui_macos, gpui_windows, gpui_linux and gpui_web. Application code doesn’t call most of these methods directly. It calls the App methods that wrap them. Use this trait to implement a new backend, or to reach a platform service that App doesn’t expose.

Methods without a default body are required. Methods with a default body are optional platform services: the default supplies the behavior for a backend that does not provide the service. The platforms table lists the backends that override each default.

Required Methods

fn background_executor(&self) -> BackgroundExecutor

Returns the executor for work that runs off the main thread.

fn foreground_executor(&self) -> ForegroundExecutor

Returns the executor that runs tasks on the main thread, the thread that owns windows.

fn text_system(&self) -> Arc<dyn PlatformTextSystem>

Returns the platform’s text system, which shapes and rasterizes glyphs.

fn run(&self, on_finish_launching: Box<dyn FnOnce() + 'static>)

Starts the event loop and calls on_finish_launching once the application is ready.

This method blocks until the application exits. Create windows inside on_finish_launching.

fn quit(&self)

Asks the application to quit.

On macOS the request is processed asynchronously, so the event loop keeps running briefly. The web backend only logs a warning, because a page can’t quit itself.

fn restart(&self, binary_path: Option<PathBuf>, arguments: Vec<OsString>)

Restarts the application by launching a new process and quitting this one.

binary_path defaults to the current executable when None, and arguments are passed to the new process. The web backend does nothing.

fn activate(&self, ignoring_other_apps: bool)

Brings the application to the front.

When ignoring_other_apps is true, the application takes focus even if another application is active. The web backend ignores the call.

fn hide(&self)

Hides all of the application’s windows. macOS hides them. Windows does nothing, and Linux logs a message and ignores the call.

fn hide_other_apps(&self)

Hides all other running applications. macOS does this. Linux and the web do nothing. Windows panics, because its implementation is unimplemented!().

fn unhide_other_apps(&self)

Shows the applications hidden by Platform::hide_other_apps. macOS does this. Linux and the web do nothing.

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

Returns every display currently connected, in no particular order.

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

Returns the display that new windows open on by default, or None if there is none.

fn on_displays_changed(&self, callback: Box<dyn FnMut()>)

Registers the callback invoked when displays may have been added or removed, or a display’s properties may have changed. GPUI rereads Self::displays to find out what changed, so calls may be spurious. The callback runs on the main thread outside of any window update.

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

Returns the handle of the window that currently has focus, if any.

fn open_window( &self, handle: AnyWindowHandle, options: WindowParams, ) -> Result<Box<dyn PlatformWindow>>

Creates a native window for handle with the given options.

App::open_window calls this. The returned PlatformWindow represents the native window. Errors are returned for unsupported options, such as a second window on the web.

fn window_appearance(&self) -> WindowAppearance

Returns the appearance of the application’s windows.

fn open_url(&self, url: &str)

Opens url in the default handler for its scheme, such as the browser for https.

fn on_open_urls(&self, callback: Box<dyn FnMut(Vec<String>)>)

Registers the callback that receives URLs the operating system asks this application to open.

Registering replaces any earlier callback. The web backend stores the callback but never calls it.

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

Registers this application as the handler for url’s scheme, such as myapp://.

The task resolves once registration finishes. The web backend resolves it at once and does nothing.

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

Shows a file or folder picker and resolves to the chosen paths.

The receiver yields Ok(None) when the user cancels. The options control whether files, directories or several items can be picked. The web backend doesn’t support this, so the receiver resolves to an error.

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

Shows a save dialog in directory and resolves to the chosen path.

suggested_name pre-fills the file name. The receiver yields Ok(None) when the user cancels. The web backend doesn’t support this.

fn can_select_mixed_files_and_dirs(&self) -> bool

Returns whether a single file picker can select both files and directories.

Only macOS returns true. Other platforms return false and need separate pickers for files and directories.

fn reveal_path(&self, path: &Path)

Shows path selected in the file manager, such as Finder or Explorer.

fn open_with_system(&self, path: &Path)

Opens path with the application the system associates with its file type.

fn on_quit(&self, callback: Box<dyn FnMut() -> bool>)

Registers the callback the platform runs when the application is asked to quit.

The callback returns true when shutdown has completed, and false when it couldn’t shut down synchronously. macOS calls it while terminating and ignores the return value.

fn on_reopen(&self, callback: Box<dyn FnMut()>)

Registers the callback run when the user activates the running application again, such as clicking its Dock icon on macOS.

fn on_system_sleep(&self, callback: Box<dyn FnMut()>)

Registers the callback invoked when the system is about to sleep.

fn on_system_wake(&self, callback: Box<dyn FnMut()>)

Registers the callback run after the system wakes from sleep.

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

Replaces the application menu with menus, and uses keymap to show each item’s shortcut.

Windows stores the menus but doesn’t draw them. Linux and the web don’t show a menu bar.

fn set_dock_menu(&self, menu: Vec<MenuItem>, keymap: &Keymap)

Sets the menu shown when the user right-clicks the app’s Dock icon (macOS) or taskbar entry (Windows, as a jump list).

fn on_app_menu_action(&self, callback: Box<dyn FnMut(&dyn Action)>)

Registers the callback that receives actions chosen from the application menu.

fn on_will_open_app_menu(&self, callback: Box<dyn FnMut()>)

Registers the callback run just before a menu opens, so the app can update its menu items.

fn on_validate_app_menu_command( &self, callback: Box<dyn FnMut(&dyn Action) -> bool>, )

Registers the callback that decides whether a menu item is enabled. Return true to enable the action.

fn thermal_state(&self) -> ThermalState

Returns the device’s current thermal state. See ThermalState.

fn on_thermal_state_change(&self, callback: Box<dyn FnMut()>)

Registers the callback run when Platform::thermal_state changes. Read the new state from the platform inside the callback.

fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>>

Requests that the operating system keep the device awake while the returned guard lives.

The reason explains the activity to the platform and may be shown in system UI. Dropping the ActivityGuard releases the request. The task resolves with the guard or an error if the platform cannot create the activity request.

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

Returns the path of the running application’s executable.

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

Returns the path of a helper executable named name that ships alongside the application.

fn set_cursor_style(&self, style: CursorStyle)

Shows the mouse cursor style over this application’s windows.

fn hide_cursor_until_mouse_moves(&self)

Hides the mouse cursor until the user moves the mouse over one of this application’s windows.

fn is_cursor_visible(&self) -> bool

Returns whether the mouse cursor is currently visible.

fn should_auto_hide_scrollbars(&self) -> bool

Returns true when scrollbars should hide until the user scrolls. macOS follows the overlay-scroller setting, Windows and Linux read their UI settings, and the web returns true.

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

Returns the clipboard’s contents synchronously, or None if it’s empty.

The web backend can’t read the clipboard synchronously and always returns None. Use Platform::read_from_clipboard_async there.

fn write_to_clipboard(&self, item: ClipboardItem)

Replaces the clipboard’s contents with item.

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

Returns the contents of the X11 or Wayland primary selection, the text selected with the mouse.

fn write_to_primary(&self, item: ClipboardItem)

Sets the primary selection to item. The selection is the text highlighted with the mouse, pasted with middle-click.

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

Stores username and password for url in the system credential store.

The task resolves once the credentials are saved. Use Platform::read_credentials to read them back.

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

Reads the username and password stored for url, resolving to None if there are none.

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

Deletes the credentials stored for url.

fn keyboard_layout(&self) -> Box<dyn PlatformKeyboardLayout>

Returns the current keyboard layout.

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

Returns the mapper that converts key codes to the characters the current layout produces.

fn on_keyboard_layout_change(&self, callback: Box<dyn FnMut()>)

Registers the callback run when the keyboard layout changes.

Provided Methods

fn set_initial_windowing(&self, _request: WindowingRequest)

Sets the windowing mode the platform starts in. Called before run. See Application::with_windowing.

fn request_windowing(&self, _request: WindowingRequest) -> Task<Result<()>>

Requests a switch between headless and windowed modes while the application is running.

The returned task resolves when the platform has applied the change. Platforms that do not support switching return an error from the default implementation.

fn set_activation_policy(&self, _policy: ActivationPolicy)

Sets the initial or current activation policy. Has no effect outside macOS.

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

Returns the open windows from front to back, or None if the platform doesn’t track stacking order.

Implemented on macOS and Linux. The default returns None.

fn is_screen_capture_supported(&self) -> bool

Returns true if this platform can capture the screen.

Returns true on macOS 12.3 or later and on Windows. Other platforms return false.

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

Lists the displays and windows that can be captured.

The result arrives on the returned channel once enumeration finishes. The default sends an error, so backends must override it to list sources.

fn set_window_appearance(&self, _appearance: Option<WindowAppearance>)

Overrides the appearance (light/dark) applied to the app’s windows, independent of the OS-wide setting. Pass None to clear the override and follow the system again. The override is reflected by Platform::window_appearance.

Only macOS implements this, by setting NSApplication.appearance. This keeps the native window chrome matching a dark app theme when the system is light, or the reverse. Other platforms ignore the call.

fn button_layout(&self) -> Option<WindowButtonLayout>

Returns the order of window control buttons, or None if the platform doesn’t use the layout. Only Linux returns a value. macOS, Windows and the web return None.

fn on_app_lifecycle(&self, _callback: Box<dyn FnMut(AppLifecyclePhase)>)

Registers a callback invoked whenever the application’s lifecycle phase changes. See AppLifecyclePhase for the phase vocabulary and its mapping onto iOS and Android.

Desktop platforms never invoke this.

fn on_memory_warning(&self, _callback: Box<dyn FnMut()>)

Registers a callback invoked when the OS signals memory pressure (iOS didReceiveMemoryWarning, Android onTrimMemory).

Desktop platforms never invoke this.

fn gestures(&self) -> Option<Rc<dyn PlatformGestures>>

Returns the platform’s gesture recognizers, or None to use GPUI’s portable ones. See PlatformGestures.

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

Returns the menus last set with Platform::set_menus, or None if the platform doesn’t keep them.

fn perform_dock_menu_action(&self, _action: usize)

Runs the dock menu item at index _action. Windows implements this.

fn add_recent_document(&self, _path: &Path)

Adds path to the system’s recent documents list. Only macOS implements this.

fn update_jump_list( &self, _menus: Vec<MenuItem>, _entries: Vec<SmallVec<[PathBuf; 2]>>, ) -> Task<Vec<SmallVec<[PathBuf; 2]>>>

Updates the Windows jump list with _menus and the recent-file _entries, and returns the entries that were kept.

Other backends return an empty list.

fn set_app_identity(&self, identifier: &str, name: &str)

Sets the application’s identifier and user-visible name.

Windows sets identifier as the AppUserModelID, unless the process already has package identity. Linux stores name. macOS and the web ignore both values.

Call it once early in startup, before opening windows or posting notifications.

fn show_system_notification(&self, notification: SystemNotification)

Posts notification to the operating system’s notification center.

Posting a notification whose SystemNotification::tag matches an earlier one replaces that notification where the platform supports it. No-op on platforms without notification support, or when delivery is unavailable (e.g. authorization was denied).

fn dismiss_system_notification(&self, tag: &str)

Removes the delivered or pending notification with this tag.

Best-effort: some platforms cannot retract a notification once shown, in which case it ages out of the notification center on its own.

fn on_system_notification_response( &self, callback: Box<dyn FnMut(SystemNotificationResponse)>, )

Registers the callback invoked when the user activates a system notification, either by clicking its body or one of its action buttons.

Implementations must invoke the callback on the main thread.

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

Returns the name of the display server or compositor, such as "Wayland", "X11" or "Headless".

Returns an empty string by default.

fn graphical_environment(&self) -> Option<GraphicalEnvironment>

The environment of the display server a platform that can switch windowing modes is connected to. See App::graphical_environment.

fn read_from_clipboard_async( &self, ) -> Task<Result<Option<ClipboardItem>, ClipboardReadError>>

Reads the clipboard, resolving once its contents are available.

Most platforms read synchronously and return a ready task. A platform with inherently asynchronous or permission-gated access, such as the browser’s Async Clipboard API, overrides this method. On those platforms, Platform::read_from_clipboard cannot return the contents; callers that can await should use this method.

fn set_gpu_requirements(&self, _requirements: Box<dyn Any>)

Registers extra GPU device requirements, such as features and limits, before the first window is opened.

The value must be a gpui_wgpu::WgpuDeviceRequirements. macOS and Linux use it. Other backends ignore it.

fn set_keyring_label(&self, _label: SharedString)

Sets the label applied to credentials stored in the system keyring. Only Linux/FreeBSD use this label.

fn supports_haptic_feedback(&self) -> bool

Returns true if Platform::play_haptic_feedback has an effect on this platform.

Only macOS returns true, for trackpads with Force Touch.

fn play_haptic_feedback(&self, _style: HapticFeedbackStyle)

Plays haptic feedback of the given style.

No-op on platforms that don’t support haptic feedback.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors