Trait Api

pub trait Api {
    // Required methods
    fn init(
        &mut self,
        gen: ViewProcessGen,
        is_respawn: bool,
        device_events: bool,
        headless: bool,
    );
    fn exit(&mut self);
    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<IpcBytesReceiver>,
    ) -> 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,
    );
    fn delete_image_use(&mut self, id: WindowId, texture_id: ImageTextureId);
    fn image_decoders(&mut self) -> Vec<Txt>;
    fn image_encoders(&mut self) -> Vec<Txt>;
    fn encode_image(&mut self, id: ImageId, format: Txt);
    fn add_font_face(
        &mut self,
        id: WindowId,
        bytes: IpcBytes,
        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 read_clipboard(
        &mut self,
        data_type: ClipboardType,
    ) -> Result<ClipboardData, ClipboardError>;
    fn write_clipboard(
        &mut self,
        data: ClipboardData,
    ) -> Result<(), 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 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;

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

The view-process API.

Required Methods

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

Called once on init.

Sends an Event::Inited once the view is completely online. 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 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::ImageMetadataLoaded, Event::ImageLoaded or Event::ImageLoadError 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<IpcBytesReceiver>) -> 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::ImageMetadataLoaded, Event::ImageLoaded or Event::ImageLoadError 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 image ID.

fn update_image_use( &mut self, id: WindowId, texture_id: ImageTextureId, image_id: ImageId, )

Replace the image resource in the window renderer.

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 image_decoders(&mut self) -> Vec<Txt>

Returns a list of image decoders supported by this implementation.

Each string is the lower-case file extension.

fn image_encoders(&mut self) -> Vec<Txt>

Returns a list of image encoders supported by this implementation.

Each string is the lower-case file extension.

fn encode_image(&mut self, id: ImageId, format: Txt)

Encode the image into the format.

The format must be one of the values returned by image_encoders.

Returns immediately. The encoded data will be send as the event Event::ImageEncoded or Event::ImageEncodeError.

fn add_font_face( &mut self, id: WindowId, bytes: IpcBytes, 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 if an Event::FrameImageReady will be send when the image is ready. Returns 0 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 if an Event::FrameImageReady will be send when the image is ready. Returns 0 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 read_clipboard( &mut self, data_type: ClipboardType, ) -> Result<ClipboardData, ClipboardError>

Get the clipboard content that matches the data_type.

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

Set the clipboard content.

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 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.

Provided Methods

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

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

Implementors