Struct WINDOWS

pub struct WINDOWS;

Windows service.

Provider

This service is provided by the WindowManager.

Implementations

impl WINDOWS

pub fn exit_on_last_close(&self) -> ArcVar<bool>

Defines if app process exit should be requested when the last window closes. This is true by default.

This setting does not consider headless windows and is fully ignored in headless apps.

Note that if APP.exit is requested directly the windows service will cancel it, request close for all headed and headless windows, and if all windows close request app exit again, independent of this setting.

pub fn default_render_mode(&self) -> ArcVar<RenderMode>

Defines the render mode of windows opened by this service.

Note that this setting only affects windows opened after it is changed, also the view-process may select a different render mode if it cannot support the requested mode.

pub fn parallel(&self) -> ArcVar<ParallelWin>

Defines what window operations can run in parallel, between windows.

Note that this config is for parallel execution between windows, see the parallel property for parallel execution within windows and widgets.

See ParallelWin for the options.

pub fn open<F: Future<Output = WindowRoot> + Send + 'static>( &self, new_window: impl IntoFuture<IntoFuture = F>, ) -> ResponseVar<WindowId>

Requests a new window.

The new_window future runs in an UiTask inside the new WINDOW context.

Returns a response variable that will update once when the window is opened, note that while the WINDOW is available in the new_window argument already, the window is only available in this service after the returned variable updates. Also note that the window might not be fully loaded yet.

An update cycle is processed between the end of new_window and the window init, this means that you can use the context WINDOW to set variables that will be read on init with the new value.

pub fn open_id<F: Future<Output = WindowRoot> + Send + 'static>( &self, window_id: impl Into<WindowId>, new_window: impl IntoFuture<IntoFuture = F>, ) -> ResponseVar<WindowId>

Requests a new window with pre-defined ID.

Panics

If the window_id is already assigned to an open or opening window.

pub fn open_headless<F: Future<Output = WindowRoot> + Send + 'static>( &self, new_window: impl IntoFuture<IntoFuture = F>, with_renderer: bool, ) -> ResponseVar<WindowId>

Requests a new headless window.

Headless windows don’t show on screen, but if with_renderer is true they will still render frames.

Note that in a headless app the open method also creates headless windows, this method creates headless windows even in a headed app.

pub fn open_headless_id<F: Future<Output = WindowRoot> + Send + 'static>( &self, window_id: impl Into<WindowId>, new_window: impl IntoFuture<IntoFuture = F>, with_renderer: bool, ) -> ResponseVar<WindowId>

Requests a new headless window with pre-defined ID.

Panics

If the window_id is already assigned to an open or opening window.

pub fn loading_handle( &self, window_id: impl Into<WindowId>, deadline: impl Into<Deadline>, ) -> Option<WindowLoadingHandle>

Gets a handle that stops the window from loading while the handle is alive.

A window is only opened in the view-process after it is loaded, without any loading handles the window is considered loaded after the first layout pass. Nodes in the window can request a loading handle to delay the view opening to after all async resources it requires are loaded.

Note that a window is only loaded after all handles are dropped or expired, you should set a reasonable deadline,
it is best to partially render a window after a short time than not show anything.

Returns None if the window has already loaded or is not found.

pub fn close( &self, window_id: impl Into<WindowId>, ) -> Result<ResponseVar<CloseWindowResult>, WindowNotFound>

Starts closing a window, the operation can be canceled by listeners of WINDOW_CLOSE_REQUESTED_EVENT. If the window has children they are closed together.

Returns a response var that will update once with the result of the operation.

Returns an error if the window_id is not one of the open windows or is only an open request.

pub fn close_together( &self, windows: impl IntoIterator<Item = WindowId>, ) -> Result<ResponseVar<CloseWindowResult>, WindowNotFound>

Starts closing multiple windows together, the operation can be canceled by listeners of WINDOW_CLOSE_REQUESTED_EVENT. If canceled none of the windows are closed. Children of each window are also selected the close together.

Returns a response var that will update once with the result of the operation. Returns Cancel if windows is empty.

Returns an error if any of the IDs is not one of the open windows or is only an open request.

pub fn close_all(&self) -> ResponseVar<CloseWindowResult>

Starts closing all open windows together, the operation can be canceled by listeners of WINDOW_CLOSE_REQUESTED_EVENT. If canceled none of the windows are closed.

Returns a response var that will update once with the result of the operation. Returns Cancel if no window is open.

pub fn mode( &self, window_id: impl Into<WindowId>, ) -> Result<WindowMode, WindowNotFound>

Get the window mode.

This value indicates if the window is headless or not.

Returns an error if the window_id is not one of the open windows or is only an open request.

pub fn widget_tree( &self, window_id: impl Into<WindowId>, ) -> Result<WidgetInfoTree, WindowNotFound>

Returns a shared reference to the latest widget tree info for the window.

Returns an error if the window_id is not one of the open windows or is only an open request.

pub fn widget_info(&self, widget_id: impl Into<WidgetId>) -> Option<WidgetInfo>

Search for the widget info in all windows.

pub fn frame_image( &self, window_id: impl Into<WindowId>, mask: Option<ImageMaskMode>, ) -> ImageVar

Generate an image from the current rendered frame of the window.

The image is not loaded at the moment of return, it will update when it is loaded.

If the window is not found the error is reported in the image error.

pub fn frame_image_rect( &self, window_id: impl Into<WindowId>, rect: PxRect, mask: Option<ImageMaskMode>, ) -> ImageVar

Generate an image from a rectangular selection of the current rendered frame of the window.

The image is not loaded at the moment of return, it will update when it is loaded.

If the window is not found the error is reported in the image error.

pub fn vars( &self, window_id: impl Into<WindowId>, ) -> Result<WindowVars, WindowNotFound>

Returns a shared reference the variables that control the window.

Returns an error if the window_id is not one of the open windows or is only an open request.

pub fn is_focused( &self, window_id: impl Into<WindowId>, ) -> Result<bool, WindowNotFound>

Gets if the window is focused in the operating system.

Returns an error if the window_id is not one of the open windows, returns false if the window_id is one of the open requests.

pub fn widget_trees(&self) -> Vec<WidgetInfoTree>

Returns shared references to the widget trees of each open window.

pub fn focused_window_id(&self) -> Option<WindowId>

Gets the id of the window that is focused in the operating system.

pub fn focused_info(&self) -> Option<WidgetInfoTree>

Returns a shared reference to the focused window’s info.

pub fn is_open(&self, window_id: impl Into<WindowId>) -> bool

Returns true if the window is open.

pub fn is_opening(&self, window_id: impl Into<WindowId>) -> bool

Returns true if the window_id is associated with a pending window open request or open task.

Window open requests start polling after each update.

pub fn is_loading(&self, window_id: impl Into<WindowId>) -> bool

Returns true if the window is not open or has pending loading handles.

pub fn is_loaded(&self, window_id: impl Into<WindowId>) -> bool

Returns true if the window is open and has no pending loading handles.

pub fn wait_loaded( &self, window_id: impl Into<WindowId>, wait_event: bool, ) -> impl Future<Output = bool> + Send + Sync + 'static

Wait until the window is loaded or closed.

If wait_event is true also awaits for the WINDOW_LOAD_EVENT to finish notifying.

Returns true if the window iis open and has no pending loading handles.

pub fn focus( &self, window_id: impl Into<WindowId>, ) -> Result<(), WindowNotFound>

Request operating system focus for the window.

The window will be made active and steal keyboard focus from the current focused window.

Prefer using the FOCUS service and advanced FocusRequest configs instead of using this method directly, they integrate with the in app widget focus and internally still use this method.

If the window_id is only associated with an open request it is modified to focus the window on open. If more than one focus request is made in the same update cycle only the last request is processed.

pub fn focus_or_open( &self, window_id: impl Into<WindowId>, open: impl Future<Output = WindowRoot> + Send + 'static, ) -> Option<ResponseVar<WindowId>>

Focus a window if it is open or opening, otherwise opens it focused.

pub fn bring_to_top( &self, window_id: impl Into<WindowId>, ) -> Result<(), WindowNotFound>

Move the window to the front of the operating system Z stack.

Note that the window is not focused, the focus operation also moves the window to the front.

pub fn register_root_extender<E>( &self, extender: impl FnMut(WindowRootExtenderArgs) -> E + Send + 'static, )

where E: UiNode,

Register the closure extender to be called with the root of every new window starting on the next update.

The closure returns the new root node that will be passed to any other root extender until the actual final root node is created.

This is an advanced API that enables app wide features, like themes, to inject context in every new window. The extender is called in the context of the window, after the window creation future has completed.

Note that the root node passed to the extender is the child node of the WindowRoot widget, not the widget itself. The extended root will be wrapped in the root widget node, that is, the final root widget will be root(extender_nodes(CONTEXT(EVENT(..)))), so extension nodes should operate as CONTEXT properties.

pub fn system_chrome(&self) -> ReadOnlyArcVar<ChromeConfig>

Variable that tracks the OS window manager configuration for the window chrome.

The chrome (also known as window decorations) defines the title bar, window buttons and window border. Some window managers don’t provide a native chrome, you can use this config with the WindowVars::chrome setting in a register_root_extender to provide a custom fallback chrome.

pub fn register_open_nested_handler( &self, handler: impl FnMut(&mut OpenNestedHandlerArgs) + Send + 'static, )

Register the closure handler to be called for every new window starting on the next update.

The closure can use the args to inspect the new window context and optionally convert the request to a NestedWindowNode. Nested windows can be manipulated using the WINDOWS API just like other windows, but are layout and rendered inside another window.

This is primarily an adapter for mobile platforms that only support one real window, it accelerates cross platform support from projects originally desktop only. Note that this API is not recommended for implementing features such as window docking or tabbing, you probably need to model tabs as objects that can outlive their host windows and use ArcNode to transfer the content between host windows.

pub fn nest_parent( &self, maybe_nested: impl Into<WindowId>, ) -> Option<(WindowId, WidgetId)>

Gets the parent actual window and widget that hosts maybe_nested if it is open and nested.

pub fn view_extensions_init( &self, window_id: impl Into<WindowId>, extension_id: ApiExtensionId, request: ApiExtensionPayload, ) -> Result<(), WindowNotFound>

Add a view-process extension payload to the window request for the view-process.

This will only work if called on the first UiNode::init and at most the first UiNode::layout of the window.

The payload is dropped after it is send, this method must be called again on VIEW_PROCESS_INITED_EVENT to reinitialize the extensions after view-process respawn.

pub fn view_window_extension_raw( &self, window_id: impl Into<WindowId>, extension_id: ApiExtensionId, request: ApiExtensionPayload, ) -> Result<ApiExtensionPayload, ViewExtensionError>

Call a view-process headed window extension with custom encoded payload.

Note that unlike most service methods this calls happens immediately.

pub fn view_window_extension<I, O>( &self, window_id: impl Into<WindowId>, extension_id: ApiExtensionId, request: &I, ) -> Result<O, ViewExtensionError>

where I: Serialize, O: DeserializeOwned,

Call a headed window extension with serialized payload.

Note that unlike most service methods this call happens immediately.

pub fn view_render_extension_raw( &self, window_id: impl Into<WindowId>, extension_id: ApiExtensionId, request: ApiExtensionPayload, ) -> Result<ApiExtensionPayload, ViewExtensionError>

Call a view-process render extension with custom encoded payload for the renderer associated with the window.

Note that unlike most service methods this call happens immediately.

pub fn view_render_extension<I, O>( &self, window_id: impl Into<WindowId>, extension_id: ApiExtensionId, request: &I, ) -> Result<O, ViewExtensionError>

where I: Serialize, O: DeserializeOwned,

Call a render extension with serialized payload for the renderer associated with the window.

Note that unlike most service methods this call happens immediately.

impl WINDOWS

Native dialogs.

pub fn native_message_dialog( &self, window_id: WindowId, dialog: MsgDialog, ) -> ResponseVar<MsgDialogResponse>

Show a native message dialog for the window.

The dialog can be modal in the view-process, in the app-process it is always async, the response var will update once when the user responds to the dialog.

Consider using the DIALOG service instead of the method directly.

pub fn native_file_dialog( &self, window_id: WindowId, dialog: FileDialog, ) -> ResponseVar<FileDialogResponse>

Show a native file dialog for the window.

The dialog can be modal in the view-process, in the app-process it is always async, the response var will update once when the user responds to the dialog.

Consider using the DIALOG service instead of the method directly.