Trait Api 

pub trait Api {
    // Required methods
    fn init(&mut self, vp_gen: ViewProcessGen, is_respawn: bool, headless: bool);
    fn exit(&mut self);
    fn set_device_events_filter(&mut self, filter: DeviceEventsFilter);
    fn open_window(&mut self, request: WindowRequest);
    fn open_headless(&mut self, request: HeadlessRequest);
    fn close(&mut self, id: WindowId);
    fn set_title(&mut self, id: WindowId, title: Txt);
    fn set_visible(&mut self, id: WindowId, visible: bool);
    fn set_always_on_top(&mut self, id: WindowId, always_on_top: bool);
    fn set_movable(&mut self, id: WindowId, movable: bool);
    fn set_resizable(&mut self, id: WindowId, resizable: bool);
    fn set_taskbar_visible(&mut self, id: WindowId, visible: bool);
    fn bring_to_top(&mut self, id: WindowId);
    fn set_state(&mut self, id: WindowId, state: WindowStateAll);
    fn set_headless_size(
        &mut self,
        id: WindowId,
        size: DipSize,
        scale_factor: Factor,
    );
    fn set_icon(&mut self, id: WindowId, icon: Option<ImageId>);
    fn set_cursor(&mut self, id: WindowId, cursor: Option<CursorIcon>);
    fn set_cursor_image(&mut self, id: WindowId, cursor: Option<CursorImage>);
    fn set_focus_indicator(
        &mut self,
        id: WindowId,
        indicator: Option<FocusIndicator>,
    );
    fn set_enabled_buttons(&mut self, id: WindowId, buttons: WindowButton);
    fn focus(&mut self, id: WindowId) -> FocusResult;
    fn drag_move(&mut self, id: WindowId);
    fn drag_resize(&mut self, id: WindowId, direction: ResizeDirection);
    fn open_title_bar_context_menu(&mut self, id: WindowId, position: DipPoint);
    fn add_image(&mut self, request: ImageRequest<IpcBytes>) -> ImageId;
    fn add_image_pro(
        &mut self,
        request: ImageRequest<IpcReceiver<IpcBytes>>,
    ) -> ImageId;
    fn forget_image(&mut self, id: ImageId);
    fn use_image(&mut self, id: WindowId, image_id: ImageId) -> ImageTextureId;
    fn update_image_use(
        &mut self,
        id: WindowId,
        texture_id: ImageTextureId,
        image_id: ImageId,
        dirty_rect: Option<PxRect>,
    ) -> bool;
    fn delete_image_use(&mut self, id: WindowId, texture_id: ImageTextureId);
    fn encode_image(&mut self, request: ImageEncodeRequest) -> ImageEncodeId;
    fn add_audio(&mut self, request: AudioRequest<IpcBytes>) -> AudioId;
    fn add_audio_pro(
        &mut self,
        request: AudioRequest<IpcReceiver<IpcBytes>>,
    ) -> AudioId;
    fn forget_audio(&mut self, id: AudioId);
    fn open_audio_output(&mut self, request: AudioOutputRequest);
    fn update_audio_output(&mut self, request: AudioOutputUpdateRequest);
    fn close_audio_output(&mut self, id: AudioOutputId);
    fn cue_audio(&mut self, request: AudioPlayRequest) -> AudioPlayId;
    fn encode_audio(&mut self, request: AudioEncodeRequest) -> AudioEncodeId;
    fn add_font_face(
        &mut self,
        id: WindowId,
        bytes: IpcFontBytes,
        index: u32,
    ) -> FontFaceId;
    fn delete_font_face(&mut self, id: WindowId, font_face_id: FontFaceId);
    fn add_font(
        &mut self,
        id: WindowId,
        font_face_id: FontFaceId,
        glyph_size: Px,
        options: FontOptions,
        variations: Vec<(FontVariationName, f32)>,
    ) -> FontId;
    fn delete_font(&mut self, id: WindowId, font_id: FontId);
    fn set_capture_mode(&mut self, id: WindowId, enable: bool);
    fn frame_image(
        &mut self,
        id: WindowId,
        mask: Option<ImageMaskMode>,
    ) -> ImageId;
    fn frame_image_rect(
        &mut self,
        id: WindowId,
        rect: PxRect,
        mask: Option<ImageMaskMode>,
    ) -> ImageId;
    fn set_video_mode(&mut self, id: WindowId, mode: VideoMode);
    fn render(&mut self, id: WindowId, frame: FrameRequest);
    fn render_update(&mut self, id: WindowId, frame: FrameUpdateRequest);
    fn access_update(&mut self, id: WindowId, update: AccessTreeUpdate);
    fn message_dialog(&mut self, id: WindowId, dialog: MsgDialog) -> DialogId;
    fn file_dialog(&mut self, id: WindowId, dialog: FileDialog) -> DialogId;
    fn notification_dialog(&mut self, notification: Notification) -> DialogId;
    fn update_notification(&mut self, id: DialogId, notification: Notification);
    fn read_clipboard(
        &mut self,
        data_types: Vec<ClipboardType>,
        first: bool,
    ) -> Result<Vec<ClipboardData>, ClipboardError>;
    fn write_clipboard(
        &mut self,
        data: Vec<ClipboardData>,
    ) -> Result<usize, ClipboardError>;
    fn start_drag_drop(
        &mut self,
        id: WindowId,
        data: Vec<DragDropData>,
        allowed_effects: DragDropEffect,
    ) -> Result<DragDropId, DragDropError>;
    fn cancel_drag_drop(&mut self, id: WindowId, drag_id: DragDropId);
    fn drag_dropped(
        &mut self,
        id: WindowId,
        drop_id: DragDropId,
        applied: DragDropEffect,
    );
    fn set_ime_area(&mut self, id: WindowId, area: Option<DipRect>);
    fn set_system_shutdown_warn(&mut self, id: WindowId, reason: Txt);
    fn set_app_menu(&mut self, menu: AppMenu);
    fn set_tray_icon(&mut self, indicator: TrayIcon);
    fn third_party_licenses(&mut self) -> Vec<LicenseUsed>;
    fn app_extension(
        &mut self,
        extension_id: ApiExtensionId,
        extension_request: ApiExtensionPayload,
    ) -> ApiExtensionPayload;
    fn window_extension(
        &mut self,
        id: WindowId,
        extension_id: ApiExtensionId,
        extension_request: ApiExtensionPayload,
    ) -> ApiExtensionPayload;
    fn render_extension(
        &mut self,
        id: WindowId,
        extension_id: ApiExtensionId,
        extension_request: ApiExtensionPayload,
    ) -> ApiExtensionPayload;
    fn ping(&mut self, count: u16) -> u16;

    // Provided method
    fn respond(&mut self, request: Request) -> Response { ... }
}

The view-process API.

Required Methods

fn init(&mut self, vp_gen: ViewProcessGen, is_respawn: bool, headless: bool)

Called once on init.

Sends an Event::Inited once the view is completely connected, the event details what API features are implemented by the view-process.

Other methods may only be called after this event.

fn exit(&mut self)

Called once after exit, if running in a managed external process it will be killed after this call.

fn set_device_events_filter(&mut self, filter: DeviceEventsFilter)

Enable/disable global device events.

This filter affects device events not targeted at windows, such as mouse move outside windows or key presses when the app has no focused window.

fn open_window(&mut self, request: WindowRequest)

Open a window.

Sends an Event::WindowOpened once the window, context and renderer have finished initializing or a Event::WindowOrHeadlessOpenError if it failed.

fn open_headless(&mut self, request: HeadlessRequest)

Open a headless surface.

This is a real renderer but not connected to any window, you can requests pixels to get the rendered frames.

Sends an Event::HeadlessOpened once the context and renderer have finished initializing or a Event::WindowOrHeadlessOpenError if it failed.

fn close(&mut self, id: WindowId)

Close the window or headless surface.

All documents associated with the window or surface are also closed.

fn set_title(&mut self, id: WindowId, title: Txt)

Set window title.

fn set_visible(&mut self, id: WindowId, visible: bool)

Set window visible.

fn set_always_on_top(&mut self, id: WindowId, always_on_top: bool)

Set if the window is “top-most”.

fn set_movable(&mut self, id: WindowId, movable: bool)

Set if the user can drag-move the window when it is in Normal mode.

fn set_resizable(&mut self, id: WindowId, resizable: bool)

Set if the user can resize the window when it is in Normal mode.

fn set_taskbar_visible(&mut self, id: WindowId, visible: bool)

Set the window taskbar icon visibility.

fn bring_to_top(&mut self, id: WindowId)

Bring the window to the Z top, without focusing it.

fn set_state(&mut self, id: WindowId, state: WindowStateAll)

Set the window state, position, size.

fn set_headless_size( &mut self, id: WindowId, size: DipSize, scale_factor: Factor, )

Set the headless surface or document area size (viewport size).

fn set_icon(&mut self, id: WindowId, icon: Option<ImageId>)

Set the window icon, the icon image must be loaded.

fn set_cursor(&mut self, id: WindowId, cursor: Option<CursorIcon>)

Set the window cursor icon and visibility.

fn set_cursor_image(&mut self, id: WindowId, cursor: Option<CursorImage>)

Set the window cursor to a custom image.

Falls back to cursor icon if not supported or if set to None.

fn set_focus_indicator( &mut self, id: WindowId, indicator: Option<FocusIndicator>, )

Sets the user attention request indicator, the indicator is cleared when the window is focused or if canceled by setting to None.

fn set_enabled_buttons(&mut self, id: WindowId, buttons: WindowButton)

Set enabled window chrome buttons.

fn focus(&mut self, id: WindowId) -> FocusResult

Brings the window to the front and sets input focus.

Sends an Event::FocusChanged if the window is focused, the request can be ignored by the window manager, or if the window is not visible, minimized or already focused.

This request can steal focus from other apps disrupting the user, be careful with it.

fn drag_move(&mut self, id: WindowId)

Moves the window with the left mouse button until the button is released.

There’s no guarantee that this will work unless the left mouse button was pressed immediately before this function is called.

fn drag_resize(&mut self, id: WindowId, direction: ResizeDirection)

Resizes the window with the left mouse button until the button is released.

There’s no guarantee that this will work unless the left mouse button was pressed immediately before this function is called.

fn open_title_bar_context_menu(&mut self, id: WindowId, position: DipPoint)

Open the system title bar context menu.

fn add_image(&mut self, request: ImageRequest<IpcBytes>) -> ImageId

Cache an image resource.

The image is decoded asynchronously, the events Event::ImageMetadataDecoded, Event::ImageDecoded or Event::ImageDecodeError will be send when the image is ready for use or failed.

The ImageRequest::data handle must contain the full image data already, it will be dropped after the image finishes decoding.

Images are shared between renderers, to use an image in a window you must first call use_image this will register the image data with the renderer.

fn add_image_pro( &mut self, request: ImageRequest<IpcReceiver<IpcBytes>>, ) -> ImageId

Cache an image from data that has not fully loaded.

If the view-process implementation supports progressive decoding it will start decoding the image as more data is received, otherwise it will collect all data first and then add_image. Each ImageRequest::data` package is the continuation of the previous call, send an empty package to indicate finish.

The events Event::ImageMetadataDecoded, Event::ImageDecoded or Event::ImageDecodeError will be send while decoding.

fn forget_image(&mut self, id: ImageId)

Remove an image from cache.

Note that if the image is in use in a renderer it will remain in memory until delete_image_use is called or the renderer is deinited by closing the window.

fn use_image(&mut self, id: WindowId, image_id: ImageId) -> ImageTextureId

Add an image resource to the window renderer.

Returns the new image texture ID. If the image_id is not loaded returns the INVALID texture ID.

fn update_image_use( &mut self, id: WindowId, texture_id: ImageTextureId, image_id: ImageId, dirty_rect: Option<PxRect>, ) -> bool

Replace the image resource in the window renderer.

The new image_id must represent an image with same dimensions and format as the previous. If the image cannot be updated an error is logged and false is returned.

The dirty_rect can be set to optimize texture upload to the GPU, if not set the entire image region updates.

The ImageTextureId will be associated with the new ImageId.

fn delete_image_use(&mut self, id: WindowId, texture_id: ImageTextureId)

Delete the image resource in the window renderer.

fn encode_image(&mut self, request: ImageEncodeRequest) -> ImageEncodeId

Encode the image.

Returns immediately. The encoded data will be send as the event Event::ImageEncoded or Event::ImageEncodeError. The returned ID identifies this request.

fn add_audio(&mut self, request: AudioRequest<IpcBytes>) -> AudioId

Cache an audio resource.

The entire audio source is already loaded in the request, it may be fully decode or decoded on demand depending on the request the returned ID can be played as soon as it starts decoding.

The events Event::AudioMetadataDecoded, Event::AudioDecoded and Event::AudioDecodeError will be send while decoding.

fn add_audio_pro( &mut self, request: AudioRequest<IpcReceiver<IpcBytes>>, ) -> AudioId

Cache an streaming audio resource.

The audio is decoded as bytes are buffered in. The returned ID can be played as soon as it starts decoding.

The events Event::AudioMetadataDecoded, Event::AudioDecoded and Event::AudioDecodeError will be send while decoding.

fn forget_audio(&mut self, id: AudioId)

Remove an audio from cache.

Note that if the audio playing it will continue until the end or it is stopped.

fn open_audio_output(&mut self, request: AudioOutputRequest)

Create a playback stream.

Opens a connection with the audio device if there are no other streams connected to it.

fn update_audio_output(&mut self, request: AudioOutputUpdateRequest)

Update configuration of an existing playback stream.

fn close_audio_output(&mut self, id: AudioOutputId)

Stop and drop a playback stream.

Note that even if this is the last connection to the device the underlying system connection may remain open as some systems expect this resource to exist for the lifetime of the process.

fn cue_audio(&mut self, request: AudioPlayRequest) -> AudioPlayId

Play or enqueue audio.

fn encode_audio(&mut self, request: AudioEncodeRequest) -> AudioEncodeId

Encode the audio.

fn add_font_face( &mut self, id: WindowId, bytes: IpcFontBytes, index: u32, ) -> FontFaceId

Add a raw font resource to the window renderer.

Returns the new font key.

fn delete_font_face(&mut self, id: WindowId, font_face_id: FontFaceId)

Delete the font resource in the window renderer.

fn add_font( &mut self, id: WindowId, font_face_id: FontFaceId, glyph_size: Px, options: FontOptions, variations: Vec<(FontVariationName, f32)>, ) -> FontId

Add a sized font to the window renderer.

Returns the new fond ID.

fn delete_font(&mut self, id: WindowId, font_id: FontId)

Delete a font instance.

fn set_capture_mode(&mut self, id: WindowId, enable: bool)

Sets if the headed window is in capture-mode. If true the resources used to capture a screenshot may be kept in memory to be reused in the next screenshot capture.

Note that capture must still be requested in each frame request.

fn frame_image(&mut self, id: WindowId, mask: Option<ImageMaskMode>) -> ImageId

Create a new image resource from the current rendered frame.

If mask is set captures an A8 mask, otherwise captures a full BGRA8 image.

Returns immediately, an Event::ImageDecoded will be send when the image is ready.

Returns ImageId::INVALID if the window is not found.

fn frame_image_rect( &mut self, id: WindowId, rect: PxRect, mask: Option<ImageMaskMode>, ) -> ImageId

Create a new image from a selection of the current rendered frame.

If mask is set captures an A8 mask, otherwise captures a full BGRA8 image.

Returns immediately, an Event::ImageDecoded will be send when the image is ready.

Returns ImageId::INVALID if the window is not found.

fn set_video_mode(&mut self, id: WindowId, mode: VideoMode)

Set the video mode used when the window is in exclusive fullscreen.

fn render(&mut self, id: WindowId, frame: FrameRequest)

Render a new frame.

fn render_update(&mut self, id: WindowId, frame: FrameUpdateRequest)

Update the current frame and re-render it.

fn access_update(&mut self, id: WindowId, update: AccessTreeUpdate)

Update the window’s accessibility info tree.

fn message_dialog(&mut self, id: WindowId, dialog: MsgDialog) -> DialogId

Shows a native message dialog for the window.

Returns an ID that identifies the response event.

fn file_dialog(&mut self, id: WindowId, dialog: FileDialog) -> DialogId

Shows a native file/folder picker for the window.

Returns the ID that identifies the response event.

fn notification_dialog(&mut self, notification: Notification) -> DialogId

Register a native notification, either a popup or an entry in the system notifications list.

Returns an ID that identifies the response event.

fn update_notification(&mut self, id: DialogId, notification: Notification)

Update the notification content.

fn read_clipboard( &mut self, data_types: Vec<ClipboardType>, first: bool, ) -> Result<Vec<ClipboardData>, ClipboardError>

Get the clipboard content that matches the data_types.

If first is true tries to read all data types requested and returns the first ok. If is false returns all requested data types ok.

fn write_clipboard( &mut self, data: Vec<ClipboardData>, ) -> Result<usize, ClipboardError>

Set the clipboard content.

Returns the count of data types that where set, if at least one data is supported by the implementation the operation is considered a success. If the implementation only support a single data entry the first compatible entry is written.

fn start_drag_drop( &mut self, id: WindowId, data: Vec<DragDropData>, allowed_effects: DragDropEffect, ) -> Result<DragDropId, DragDropError>

Start a drag and drop operation, if the window is pressed.

fn cancel_drag_drop(&mut self, id: WindowId, drag_id: DragDropId)

Cancel a drag and drop operation.

fn drag_dropped( &mut self, id: WindowId, drop_id: DragDropId, applied: DragDropEffect, )

Notify the drag source of what effect was applied for a received drag&drop.

fn set_ime_area(&mut self, id: WindowId, area: Option<DipRect>)

Enable or disable IME by setting a cursor area.

In mobile platforms also shows the software keyboard for Some(_) and hides it for None.

fn set_system_shutdown_warn(&mut self, id: WindowId, reason: Txt)

Attempt to set a system wide shutdown warning associated with the window.

Operating systems that support this show the reason in a warning for the user, it must be a short text that identifies the critical operation that cannot be cancelled.

Note that there is no guarantee that the view-process or operating system will actually set a block, there is no error result because operating systems can silently ignore block requests at any moment, even after an initial successful block.

Set to an empty text to remove the warning.

fn set_app_menu(&mut self, menu: AppMenu)

Set the custom menu items for the system application menu.

The application menu is shown outside the app windows, usually at the top of the main screen in macOS and Gnome desktops.

Set to empty to remove the menu.

fn set_tray_icon(&mut self, indicator: TrayIcon)

Set the tray icon indicator for the app.

This is a small status indicator icon displayed near the notifications area.

fn third_party_licenses(&mut self) -> Vec<LicenseUsed>

Licenses that may be required to be displayed in the app about screen.

This is specially important for prebuilt view users, as the tools that scrap licenses may not find the prebuilt dependencies.

fn app_extension( &mut self, extension_id: ApiExtensionId, extension_request: ApiExtensionPayload, ) -> ApiExtensionPayload

Call the API extension.

The extension_id is the index of an extension in the extensions list provided by the view-process on init. The extension_request is any data required by the extension.

Returns the extension response or ApiExtensionPayload::unknown_extension if the extension_id is not on the list, or ApiExtensionPayload::invalid_request if the extension_request is not in a format expected by the extension.

fn window_extension( &mut self, id: WindowId, extension_id: ApiExtensionId, extension_request: ApiExtensionPayload, ) -> ApiExtensionPayload

Call the API extension.

This is similar to Api::app_extension, but is targeting the instance of an extension associated with the id window or headless surface.

fn render_extension( &mut self, id: WindowId, extension_id: ApiExtensionId, extension_request: ApiExtensionPayload, ) -> ApiExtensionPayload

Call the API extension.

This is similar to Api::app_extension, but is targeting the instance of an extension associated with the id renderer.

fn ping(&mut self, count: u16) -> u16

Returns the count and notifies Event::Pong after ensuring the view-process is responsive.

The app-process and view-process automatically monitor message frequency to detect when the paired process is stuck. View-process implementers must only ensure the response event goes through its main loop to get an accurate read of if it is stuck.

Provided Methods

fn respond(&mut self, request: Request) -> Response

Already implemented, matches a request, calls the corresponding method and packages the response.

Implementors