pub enum Effect {
Show 45 variants
Redraw(AppWindowId),
Window(WindowRequest),
Command {
window: Option<AppWindowId>,
command: CommandId,
},
QuitApp,
ShowAboutPanel,
HideApp,
HideOtherApps,
UnhideAllApps,
SetMenuBar {
window: Option<AppWindowId>,
menu_bar: MenuBar,
},
ClipboardWriteText {
window: AppWindowId,
token: ClipboardToken,
text: String,
},
ClipboardReadText {
window: AppWindowId,
token: ClipboardToken,
},
PrimarySelectionSetText {
text: String,
},
PrimarySelectionGetText {
window: AppWindowId,
token: ClipboardToken,
},
ExternalDropReadAll {
window: AppWindowId,
token: ExternalDropToken,
},
ExternalDropReadAllWithLimits {
window: AppWindowId,
token: ExternalDropToken,
limits: ExternalDropReadLimits,
},
ExternalDropRelease {
token: ExternalDropToken,
},
OpenUrl {
url: String,
target: Option<String>,
rel: Option<String>,
},
ShareSheetShow {
window: AppWindowId,
token: ShareSheetToken,
items: Vec<ShareItem>,
},
FileDialogOpen {
window: AppWindowId,
options: FileDialogOptions,
},
FileDialogReadAll {
window: AppWindowId,
token: FileDialogToken,
},
FileDialogReadAllWithLimits {
window: AppWindowId,
token: FileDialogToken,
limits: ExternalDropReadLimits,
},
FileDialogRelease {
token: FileDialogToken,
},
IncomingOpenReadAll {
window: AppWindowId,
token: IncomingOpenToken,
},
IncomingOpenReadAllWithLimits {
window: AppWindowId,
token: IncomingOpenToken,
limits: ExternalDropReadLimits,
},
IncomingOpenRelease {
token: IncomingOpenToken,
},
DiagIncomingOpenInject {
window: AppWindowId,
items: Vec<DiagIncomingOpenItem>,
},
DiagInjectEvent {
window: AppWindowId,
event: Event,
},
DiagClipboardForceUnavailable {
window: AppWindowId,
enabled: bool,
},
TextAddFontAssets {
requests: Vec<AssetRequest>,
},
TextRescanSystemFonts,
ViewportInput(ViewportInputEvent),
Dock(DockOp),
ImeAllow {
window: AppWindowId,
enabled: bool,
},
ImeRequestVirtualKeyboard {
window: AppWindowId,
visible: bool,
},
ImeSetCursorArea {
window: AppWindowId,
rect: Rect,
},
WindowMetricsSetInsets {
window: AppWindowId,
safe_area_insets: Option<Option<Edges>>,
occlusion_insets: Option<Option<Edges>>,
},
CursorSetIcon {
window: AppWindowId,
icon: CursorIcon,
},
ImageRegisterRgba8 {
window: AppWindowId,
token: ImageUploadToken,
width: u32,
height: u32,
bytes: Vec<u8>,
color_info: ImageColorInfo,
alpha_mode: AlphaMode,
},
ImageUpdateRgba8 {
window: Option<AppWindowId>,
token: ImageUpdateToken,
image: ImageId,
stream_generation: u64,
width: u32,
height: u32,
update_rect_px: Option<RectPx>,
bytes_per_row: u32,
bytes: Vec<u8>,
color_info: ImageColorInfo,
alpha_mode: AlphaMode,
},
ImageUpdateNv12 {Show 13 fields
window: Option<AppWindowId>,
token: ImageUpdateToken,
image: ImageId,
stream_generation: u64,
width: u32,
height: u32,
update_rect_px: Option<RectPx>,
y_bytes_per_row: u32,
y_plane: Vec<u8>,
uv_bytes_per_row: u32,
uv_plane: Vec<u8>,
color_info: ImageColorInfo,
alpha_mode: AlphaMode,
},
ImageUpdateI420 {Show 15 fields
window: Option<AppWindowId>,
token: ImageUpdateToken,
image: ImageId,
stream_generation: u64,
width: u32,
height: u32,
update_rect_px: Option<RectPx>,
y_bytes_per_row: u32,
y_plane: Vec<u8>,
u_bytes_per_row: u32,
u_plane: Vec<u8>,
v_bytes_per_row: u32,
v_plane: Vec<u8>,
color_info: ImageColorInfo,
alpha_mode: AlphaMode,
},
ImageUnregister {
image: ImageId,
},
RequestAnimationFrame(AppWindowId),
SetTimer {
window: Option<AppWindowId>,
token: TimerToken,
after: Duration,
repeat: Option<Duration>,
},
CancelTimer {
token: TimerToken,
},
}Expand description
Effects emitted by the portable runtime surface.
Effects are collected by the host (e.g. fret-app::App) and are expected to be handled by a
runner/backend integration layer (native or web).
§Completion events (runner contract)
Many effects represent an asynchronous request to the platform and are completed later by a
corresponding fret_core::Event. Runners/backends should treat these as best-effort.
Common mappings:
ClipboardReadText { token, .. }→fret_core::Event::ClipboardReadText { token, .. }orfret_core::Event::ClipboardReadFailed { token, .. }PrimarySelectionGetText { token, .. }→fret_core::Event::PrimarySelectionText { token, .. }orfret_core::Event::PrimarySelectionTextUnavailable { token, .. }ShareSheetShow { token, .. }→fret_core::Event::ShareSheetCompleted { token, .. }FileDialogOpen { .. }→fret_core::Event::FileDialogSelection(..)orfret_core::Event::FileDialogCanceledFileDialogReadAll { token, .. }→fret_core::Event::FileDialogData(..)IncomingOpenReadAll { token, .. }→fret_core::Event::IncomingOpenData(..)orfret_core::Event::IncomingOpenUnavailable { token, .. }SetTimer { token, .. }→fret_core::Event::Timer { token }ImageRegister* { token, .. }→fret_core::Event::ImageRegistered { token, .. }orfret_core::Event::ImageRegisterFailed { token, .. }ImageUpdate* { token, .. }→ optionallyfret_core::Event::ImageUpdateApplied { token, .. }orfret_core::Event::ImageUpdateDropped { token, .. }when the runner supports these acks (capability-gated to avoid flooding the event loop).
Variants§
Redraw(AppWindowId)
Request a window redraw (one-shot).
This is the lowest-level redraw primitive. Higher-level UI code typically calls
App::request_redraw (or Cx::request_redraw / Cx::request_frame), which eventually
results in this effect being handled by the runner/backend.
Semantics:
- This is a one-shot request and may be coalesced by the runner or platform compositor.
- This does not imply continuous frame progression. If you need to keep repainting
without input events (animations, progressive rendering), use
Effect::RequestAnimationFrameand re-issue it each frame while active.
Window(WindowRequest)
Command
QuitApp
Request the application to quit (native runners may exit their event loop).
Web runners may ignore this request.
ShowAboutPanel
Show the standard native “About” panel when available.
Platform mapping:
- macOS:
NSApplication orderFrontStandardAboutPanel: - Other platforms: runners may ignore this request.
HideApp
Hide the application (macOS: NSApplication hide:).
Other platforms may ignore this request.
HideOtherApps
Hide all other applications (macOS: NSApplication hideOtherApplications:).
Other platforms may ignore this request.
UnhideAllApps
Unhide all applications (macOS: NSApplication unhideAllApplications:).
Other platforms may ignore this request.
SetMenuBar
Set the application/window menu bar (native runners may map this to an OS menubar).
Notes:
- This is a platform integration seam; web runners may ignore it.
- The menu model is data-only (
MenuBar) and is typically derived from command metadata (ADR 0023).
ClipboardWriteText
Requests writing platform clipboard text (best-effort).
ClipboardReadText
Requests reading platform clipboard text (best-effort).
Runners/backends should eventually complete this request by emitting a corresponding event
carrying token (see ClipboardToken contract in fret-core).
PrimarySelectionSetText
Set Linux primary selection text (copy-on-select).
This is intentionally separate from ClipboardWriteText so selecting text does not
overwrite the explicit clipboard used by Ctrl+C / edit.copy.
PrimarySelectionGetText
Read Linux primary selection text (middle-click paste).
ExternalDropReadAll
ExternalDropReadAllWithLimits
ExternalDropRelease
Fields
token: ExternalDropTokenOpenUrl
Requests opening a URL using the platform’s default handler (best-effort).
Callers should ensure the URL is safe/expected. Component-layer helpers may apply
additional policies (e.g. rel="noreferrer").
Show the platform-native share sheet (best-effort).
FileDialogOpen
Opens a platform-native file dialog (best-effort).
Runners/backends typically respond by delivering one of:
fret_core::Event::FileDialogSelection(token + names), followed byEffect::FileDialogReadAllto obtain bytes, orfret_core::Event::FileDialogCanceledif the user cancels.
FileDialogReadAll
Requests reading all selected file bytes for a previously opened file dialog.
FileDialogReadAllWithLimits
FileDialogRelease
Releases runner-owned resources associated with a file dialog token (best-effort).
Fields
token: FileDialogTokenIncomingOpenReadAll
Read all data associated with an incoming-open token (best-effort).
IncomingOpenReadAllWithLimits
IncomingOpenRelease
Releases runner-owned resources associated with an incoming-open token (best-effort).
Fields
token: IncomingOpenTokenDiagIncomingOpenInject
Diagnostics-only “incoming open” injection (best-effort).
This simulates mobile-style share-target / open-in flows in CI by injecting an
Event::IncomingOpenRequest carrying tokenized items.
Runners SHOULD:
- allocate an
IncomingOpenToken, - enqueue/deliver
Event::IncomingOpenRequest { token, items }, - and retain the injected payload behind the token so subsequent reads can succeed.
Notes:
- This is intended for diagnostics/scripts only; real incoming-open requests originate from the OS.
- Payload bytes are diagnostic fixtures; they are not intended to model platform handles.
DiagInjectEvent
Diagnostics-only synthetic event injection (best-effort).
This lets tooling deliver an already-constructed runtime event to a specific window even when that window is not the one currently producing render callbacks.
Diagnostics-only clipboard override to simulate mobile privacy/user-activation denial paths.
Notes:
- Runners SHOULD treat this as a best-effort toggle and default to
enabled=false. - When enabled, clipboard reads (
ClipboardReadText,PrimarySelectionGetText) SHOULD complete as unavailable rather than attempting platform access. - Clipboard writes (
ClipboardWriteText) SHOULD complete with a failed outcome rather than attempting platform access.
TextAddFontAssets
Resolve logical font assets through the shared runtime asset resolver and add the resulting bytes to the renderer text system.
This is the runtime font-loading lane for callers that want resolver overrides, diagnostics, and packaged mounts to participate before byte injection.
The runner/backend is responsible for resolving each request, applying any successful results to the renderer, and triggering any required invalidation/redraw.
Fields
requests: Vec<AssetRequest>TextRescanSystemFonts
Request a best-effort rescan of system-installed fonts (native-only).
Web/WASM runners should ignore this effect, as they cannot access system font databases.
Semantics:
- This is an explicit, user-initiated refresh hook (ADR 0258).
- Runners should re-enumerate the font catalog and republish
FontCatalogMetadataif changes are observed. - Runners should also bump renderer text invalidation keys (e.g.
TextFontStackKey) so cached shaping/rasterization results cannot be reused after a rescan attempt.
ViewportInput(ViewportInputEvent)
Dock(DockOp)
ImeAllow
ImeRequestVirtualKeyboard
Best-effort request to show/hide the platform virtual keyboard.
Notes:
- This does not replace
Effect::ImeAllow, which remains the source of truth for whether the focused widget is a text input. - Some platforms (notably Android) may require this request to be issued within a user-activation turn (direct input event handling), otherwise it may be ignored.
ImeSetCursorArea
WindowMetricsSetInsets
Override window insets in WindowMetricsService (safe area / occlusion).
This is primarily used by diagnostics/scripted repros to simulate keyboard occlusion on platforms where the real OS insets are not available in CI.
Semantics:
Nonemeans “no change”.Some(None)clears the insets but still marks them as “known”.Some(Some(v))sets the insets tov.
Fields
window: AppWindowIdCursorSetIcon
ImageRegisterRgba8
ImageUpdateRgba8
ImageUpdateNv12
ImageUpdateI420
ImageUnregister
RequestAnimationFrame(AppWindowId)
Request the next animation frame for a window.
Use this for frame-driven updates (animations, progressive rendering) where the UI must keep repainting even if there are no new input events.
This is a one-shot request. Runners/backends should schedule a redraw and keep advancing the frame counter while these requests are being issued.
Platform mapping:
- Web backends typically map this to
requestAnimationFrame. - Desktop backends typically translate this into a “redraw on the next event-loop turn” request (and may coalesce multiple requests).
SetTimer
Requests a timer callback to be delivered as fret_core::Event::Timer (best-effort).
CancelTimer
Cancels a previously requested timer (best-effort).
Fields
token: TimerToken