Struct zng_view_api::Controller

pub struct Controller { /* private fields */ }

View Process controller, used in the App Process.

Exit

The View Process is killed when the controller is dropped, if the app is running in same process mode then the current process exits with code 0 on drop.

Implementations

impl Controller

pub fn start<F>( view_process_exe: PathBuf, view_process_env: HashMap<Txt, Txt>, device_events: bool, headless: bool, on_event: F, ) -> Self

where F: FnMut(Event) + Send + 'static,

Start with a custom view process.

The view_process_exe must be an executable that starts a view server. Note that the VERSION of this crate must match in both executables.

The view_process_env can be set to any env var needed to start the view-process. Note that if view_process_exe is the current executable this most likely need set zng_env::PROCESS_MAIN.

The on_event closure is called in another thread every time the app receives an event.

Tests

The current_exe cannot be used in tests, you should set an external view-process executable. Unfortunately there is no way to check if start was called in a test so we cannot provide an error message for this. If the test is hanging in debug builds or has a timeout error in release builds this is probably the reason.

pub fn online(&self) -> bool

View-process is connected and ready to respond.

pub fn generation(&self) -> ViewProcessGen

View-process generation.

pub fn headless(&self) -> bool

If is running in headless mode.

pub fn device_events(&self) -> bool

If device events are enabled.

pub fn same_process(&self) -> bool

If is running both view and app in the same process.

pub fn handle_inited(&mut self, gen: ViewProcessGen)

Handle an Event::Inited.

Set the online flag to true.

pub fn handle_suspended(&mut self)

Handle an Event::Suspended.

Set the online flat to false.

pub fn handle_disconnect(&mut self, gen: ViewProcessGen)

Handle an Event::Disconnected.

The gen parameter is the generation provided by the event. It is used to determinate if the disconnect has not been handled already.

Tries to cleanup the old view-process and start a new one, if all is successful an Event::Inited is send.

The old view-process exit code and std output is logged using the vp_respawn target.

Exits the current process with code 1 if the view-process was killed by the user. In Windows this is if the view-process exit code is 1. In Unix if it was killed by SIGKILL, SIGSTOP, SIGINT.

Panics

If the last five respawns happened all within 500ms of the previous respawn.

If the an error happens three times when trying to spawn the new view-process.

If another disconnect happens during the view-process startup dialog.

pub fn respawn(&mut self)

Reopen the view-process, causing another Event::Inited.

This is similar to handle_disconnect but the current process does not exit depending on the view-process exit code.

impl Controller

pub fn open_window( &mut self, request: WindowRequest, ) -> Result<(), ViewProcessOffline>

Open a window.

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

pub fn open_headless( &mut self, request: HeadlessRequest, ) -> Result<(), ViewProcessOffline>

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.

pub fn close(&mut self, id: WindowId) -> Result<(), ViewProcessOffline>

Close the window or headless surface.

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

pub fn set_title( &mut self, id: WindowId, title: Txt, ) -> Result<(), ViewProcessOffline>

Set window title.

pub fn set_visible( &mut self, id: WindowId, visible: bool, ) -> Result<(), ViewProcessOffline>

Set window visible.

pub fn set_always_on_top( &mut self, id: WindowId, always_on_top: bool, ) -> Result<(), ViewProcessOffline>

Set if the window is “top-most”.

pub fn set_movable( &mut self, id: WindowId, movable: bool, ) -> Result<(), ViewProcessOffline>

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

pub fn set_resizable( &mut self, id: WindowId, resizable: bool, ) -> Result<(), ViewProcessOffline>

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

pub fn set_taskbar_visible( &mut self, id: WindowId, visible: bool, ) -> Result<(), ViewProcessOffline>

Set the window taskbar icon visibility.

pub fn bring_to_top(&mut self, id: WindowId) -> Result<(), ViewProcessOffline>

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

pub fn set_state( &mut self, id: WindowId, state: WindowStateAll, ) -> Result<(), ViewProcessOffline>

Set the window state, position, size.

pub fn set_headless_size( &mut self, id: WindowId, size: DipSize, scale_factor: Factor, ) -> Result<(), ViewProcessOffline>

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

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

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

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

Set the window cursor icon and visibility.

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

Set the window cursor to a custom image.

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

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

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

pub fn set_enabled_buttons( &mut self, id: WindowId, buttons: WindowButton, ) -> Result<(), ViewProcessOffline>

Set enabled window chrome buttons.

pub fn focus(&mut self, id: WindowId) -> Result<FocusResult, ViewProcessOffline>

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.

pub fn drag_move(&mut self, id: WindowId) -> Result<(), ViewProcessOffline>

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.

pub fn drag_resize( &mut self, id: WindowId, direction: ResizeDirection, ) -> Result<(), ViewProcessOffline>

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.

pub fn open_title_bar_context_menu( &mut self, id: WindowId, position: DipPoint, ) -> Result<(), ViewProcessOffline>

Open the system title bar context menu.

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

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.

pub fn add_image_pro( &mut self, request: ImageRequest<IpcBytesReceiver>, ) -> Result<ImageId, ViewProcessOffline>

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.

pub fn forget_image(&mut self, id: ImageId) -> Result<(), ViewProcessOffline>

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.

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

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.

pub fn update_image_use( &mut self, id: WindowId, texture_id: ImageTextureId, image_id: ImageId, ) -> Result<(), ViewProcessOffline>

Replace the image resource in the window renderer.

The ImageTextureId will be associated with the new ImageId.

pub fn delete_image_use( &mut self, id: WindowId, texture_id: ImageTextureId, ) -> Result<(), ViewProcessOffline>

Delete the image resource in the window renderer.

pub fn image_decoders(&mut self) -> Result<Vec<Txt>, ViewProcessOffline>

Returns a list of image decoders supported by this implementation.

Each string is the lower-case file extension.

pub fn image_encoders(&mut self) -> Result<Vec<Txt>, ViewProcessOffline>

Returns a list of image encoders supported by this implementation.

Each string is the lower-case file extension.

pub fn encode_image( &mut self, id: ImageId, format: Txt, ) -> Result<(), ViewProcessOffline>

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.

pub fn add_font_face( &mut self, id: WindowId, bytes: IpcBytes, index: u32, ) -> Result<FontFaceId, ViewProcessOffline>

Add a raw font resource to the window renderer.

Returns the new font key.

pub fn delete_font_face( &mut self, id: WindowId, font_face_id: FontFaceId, ) -> Result<(), ViewProcessOffline>

Delete the font resource in the window renderer.

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

Add a sized font to the window renderer.

Returns the new fond ID.

pub fn delete_font( &mut self, id: WindowId, font_id: FontId, ) -> Result<(), ViewProcessOffline>

Delete a font instance.

pub fn set_capture_mode( &mut self, id: WindowId, enable: bool, ) -> Result<(), ViewProcessOffline>

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.

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

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.

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

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.

pub fn set_video_mode( &mut self, id: WindowId, mode: VideoMode, ) -> Result<(), ViewProcessOffline>

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

pub fn render( &mut self, id: WindowId, frame: FrameRequest, ) -> Result<(), ViewProcessOffline>

Render a new frame.

pub fn render_update( &mut self, id: WindowId, frame: FrameUpdateRequest, ) -> Result<(), ViewProcessOffline>

Update the current frame and re-render it.

pub fn access_update( &mut self, id: WindowId, update: AccessTreeUpdate, ) -> Result<(), ViewProcessOffline>

Update the window’s accessibility info tree.

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

Shows a native message dialog for the window.

Returns an ID that identifies the response event.

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

Shows a native file/folder picker for the window.

Returns the ID that identifies the response event.

pub fn read_clipboard( &mut self, data_type: ClipboardType, ) -> Result<Result<ClipboardData, ClipboardError>, ViewProcessOffline>

Get the clipboard content that matches the data_type.

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

Set the clipboard content.

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

Enable or disable IME by setting a cursor area.

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

pub fn set_system_shutdown_warn( &mut self, id: WindowId, reason: Txt, ) -> Result<(), ViewProcessOffline>

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.

pub fn third_party_licenses( &mut self, ) -> Result<Vec<LicenseUsed>, ViewProcessOffline>

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.

pub fn app_extension( &mut self, extension_id: ApiExtensionId, extension_request: ApiExtensionPayload, ) -> Result<ApiExtensionPayload, ViewProcessOffline>

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.

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

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.

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

Call the API extension.

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

Trait Implementations

impl Drop for Controller

fn drop(&mut self)

Kills the View Process, unless it is running in the same process.