inset-embedder

A host connects Inset's framework to one platform: it runs the loop, delivers input, and puts frames on screen. Inset has no engine, so the host also does the engine's part.

How an embedder is built

Every embedder takes the same shape, whatever its system; the winit embedder (crates/inset-embedder-winit) is the worked example.

• The main loop talks. One type hears every event of the system and every request of the app, and only it calls the client or asks the system for something. Its reactions live in files by concern: windows, frames, input, quitting.
• Helpers decide. Each concern, such as a view's text input, the pointer or the quit being asked, is a plain type that takes an event and answers what follows from it. The main loop delivers the answer, so the rule lives in one place and is tested without a window.
• Shared facts have one owner. What both the main loop and Platform need, such as the views, the appearance and the app's handlers, lives in one state that both hold and reach only through its named operations. The main loop changes it; Platform answers the app from it and sends the rest to the loop as requests.
• A system's extras are listed once. What a system adds beyond the windowing library is a list of small traits, one per concern, each with the answer of a system that lacks it: nothing, or None. A system fills in only what it has.
• Missing is None, all the way to the app. A capability an app may ask for is an Option on Platform, None where the system lacks it, never a call that silently does nothing. An ability several systems have goes into this interface; one only a single system has stays the embedder's own, behind a method named for that system, such as WinitPlatform::macos.

App and loop

Starting

• the host's own run, whose start closure takes a PlatformRef and returns the EmbedderClient; Platform::target_platform
• Call the start closure once, at launch, as soon as the views the platform gives then are in Platform::views, whether or not they have their windows yet, and keep the client it returns. A view with no window has no size, as Flutter's implicit view has empty metrics until its window reports them. A desktop gives none.

Waking

• Dispatcher::wake_at, wake_now
• Wake the framework at its timer, and as soon as possible after wake_now, from any thread.

Background work

• Dispatcher::dispatch
• Run dispatched work on the system's thread pool or the host's own threads, and on the web as a later task of the browser's loop.

Quitting

• EmbedderClient::request_app_exit, AppExitReply, AppExit::quit
• Ask the app at every request the system makes, a second one while the first is being decided included, quit when its reply is exit, and quit at once when it calls quit. Act on both on a turn of the loop, never inside the call that answered.

Lifecycle states

• EmbedderClient::app_lifecycle_state_changed, Platform::initial_lifecycle_state
• At each notice from the system, report the state the app is now in, and let the framework fill in the states between.

Links, files and back

• EmbedderClient::pop_route, Platform::default_route_name, file_opening, FileOpening::set_open_files_handler; a reopen is the host's own
• Keep what a launch hands over until the app listens, and do the system's own back when pop_route answers false.

Windows and views

Views

• View, View::initial_data, Platform::views, EmbedderClient::view_added, view_removed
• List every view the app has, given or asked for, update Platform::views before each view_added and view_removed, report with them only the views that come and go after launch, and release a view's native window as soon as the window closes. Hand on what an embedder attached to a view it gives as its initial data.

Surfaces

• none: a view's surface is the host's own; EmbedderClient::frame
• Give every view a surface whenever the system gives them and ask for a frame to draw on them, take every surface when the system takes them, and keep the app and its views throughout.

Views the app asks for

• Platform::request_view, View::request_id, View::window, HostWindow, EmbedderClient::view_close_requested, view_request_failed
• Make a window for each request on a turn of the loop, add its view carrying the request's id and initial data, or report the failure, and give each WindowConfig option the system's nearest equivalent. Refuse requests where the platform gives the app its views. Report the user's request to close a view and close nothing until the app does.

Size and scale

• ViewMetrics::physical_size, device_pixel_ratio, EmbedderClient::view_metrics_changed
• Give every size and position in physical pixels from the view's top-left corner, and update View::metrics before calling view_metrics_changed.

Padding and insets

• ViewMetrics::view_padding, view_insets, padding
• Report what the system may cover as view_padding, what the keyboard hides as view_insets, and padding as max(0, view_padding - view_insets) on each side.

Screens

• Platform::screens, Screens::screens, pointer_location
• Give every position in the coordinates of a window's frame, from the main screen's top-left corner, the main screen first.

Displays

• none yet
• Follow the system's notices as displays change and windows move between them, because a window's display sets its scale and its vsync.

Visibility

• EmbedderClient::app_lifecycle_state_changed, Surface::next_vsync
• A window nobody can see draws nothing, and draws again as soon as any part shows.

Focus

• Platform::request_view_focus_change, EmbedderClient::view_focus_changed
• Serve a focus request on a later turn of the loop, and report each native focus change with the system's direction, or Undefined.

Frames

Frames

• Platform::request_frame → EmbedderClient::frame
• Draw one frame per vsync while the framework asks for one; a resize draws its frame at once.

Vsync

• Surface::next_vsync, VsyncObserver::vsync
• Take vsync from each display, or from a timer at its rate where the system gives none, so each visible window keeps ticking while others are hidden.

Presenting

• View::present
• Keep the last scene, and present it again as soon as the system can take it after a refused frame.

Resizing

• EmbedderClient::view_metrics_changed, then EmbedderClient::frame
• Draw the new size's frame inside the system's resize callback, so the size and the picture reach the screen in one transaction.

Native surfaces

• Platform::compositor, Compositor::open_surface, Surface::present, Scene::surfaces
• Place a scene's surfaces beneath its picture in the same native transaction, and run each buffer's released once the compositor is done with it.

Input

Mouse

• EmbedderClient::pointer_data_packet
• Complete the data as Flutter's engine does: Add before a device's first event, a new pointer_identifier for each press, deltas from the last position, and Remove once it leaves with its buttons up.

Scrolling and trackpad gestures

• PointerSignalKind::Scroll, Scale, ScrollInertiaCancel, PointerChange::PanZoomStart, PanZoomUpdate, PanZoomEnd
• Send fingers on a trackpad as one pan-zoom with its pan, scale and rotation, and leave momentum to the framework.

Touch and stylus

• PointerDeviceKind::Touch, Stylus, InvertedStylus, View::gesture_settings
• Make each finger its own device, with its Add in the packet of its down and its Remove in the packet of its up or cancel.

Keyboard

• KeyData::physical, logical, synthesized
• Repeats and releases carry the logical key their press had, and the presses and releases the system lost arrive synthesized.

Key order

• EmbedderClient::key_data and its answer
• A composing input method gets each key first, then the framework, and a key the framework declines goes on to text input and the system.

Text input

• TextInputHost, EmbedderClient::text_input_*
• Input methods can read and change the text around the caret, so composing, dead keys and accents work.

Cursor

• Platform::mouse_cursor, MouseCursor::activate_system_cursor
• Show the last cursor asked for over the view the pointer is on, and set it again each time the system resets it.

Drag and drop

• EmbedderClient::drop_data
• Send one DropData per phase, with all its files in that one report, and the position where the system gives one.

System services

Clipboard

• Platform::clipboard, Clipboard::set_text, text, has_strings
• Start each write inside the call, and answer each read once the text arrives, with nothing where the host cannot reach the clipboard.

Menus and text services

• PopupMenus, SystemContextMenu, TextServices, EmbedderClient::system_context_menu_hidden, custom_context_menu_action; none yet for the menu bar
• Perform the system context menu's built-in items in the host, and report its custom items and its closing to the client.

Dialogs

• none yet
• Start each dialog with the system's non-blocking call and answer through a future, so the host's loop keeps running.

Appearance and locale

• Platform::platform_brightness, locales, set_application_locale, EmbedderClient::platform_brightness_changed, locales_changed
• Update what Platform answers before calling its change hook, and list the locales most preferred first.

Fonts and images

• Platform::font_source, open_image_codec, import_pixels, EmbedderClient::system_fonts_changed
• Call system_fonts_changed after registering faces that arrive late, and answer every decode, off the main thread, with its frames or an error.

System chrome and haptics

• Platform::system_chrome, haptics
• Style the system bars on the thread that owns the window, which on Android is the Java main thread.

Restoration

• Platform::restoration, Restoration::get, put
• Keep the last map put hands over until the system asks for it, and answer get with what the system gave back at launch.

Accessibility

• none yet
• A host adds accessibility when the framework does.

Dock, taskbar and notifications

• none yet
• Give the app the identity the system knows it by, a bundle on macOS and an AppUserModelID on Windows, before it reaches the Dock, the taskbar or notifications.

Robustness

Threads

• Dispatcher, Compositor, Surface and VsyncObserver, the parts other threads may call
• Call the client only on the main thread, and reach each native window on the thread that owns it.

Re-entrancy

• Platform, View, HostWindow and each capability
• Whatever a framework call or a system callback needs of the loop or the client becomes a request, served in order on a later turn.

Nested loops

• PopupMenus::show
• Wakes and vsyncs keep coming while the system runs a nested loop, such as a popup menu, a modal dialog or a live resize.

Panics

• none yet
• A panic in a platform callback aborts after printing its message, and background work drops its own panic.

References

Paths start at each repository's root.

• Flutter: engine/src/flutter/shell/platform/, with darwin/macos, darwin/ios, android, windows, linux and the embedder API in embedder; the web's is engine/src/flutter/lib/web_ui/.
• gpui: Zed's crates/gpui_macos, crates/gpui_windows, crates/gpui_linux and crates/gpui_web.
• Chromium: macOS in components/remote_cocoa/, ui/base/cocoa/ and ui/display/mac/; Windows in ui/views/win/, ui/base/win/ and ui/display/win/.
• winit: src/platform_impl/, one folder per system.