Struct WindowVars

pub struct WindowVars(/* private fields */);

Variables that configure the opening or open window.

You can get the vars for any window using WINDOWS.vars.

You can get the vars for the current context window using WINDOW.vars.

Implementations

impl WindowVars

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

Defines if the window chrome is visible.

The window chrome is the non-client area of the window, usually a border with resize handles and a title bar.

The default value is true.

Note that if the WINDOWS.system_chrome reports the windowing system prefers a custom chrome and does not provide one the system chrome is not requested, even if this is true. Window widget implementers can use this to detect when a fallback chrome must be provided.

pub fn icon(&self) -> ArcVar<WindowIcon>

Window icon.

See WindowIcon for details.

The default value is WindowIcon::Default.

You can retrieve the custom icon image using actual_icon.

pub fn actual_icon(&self) -> ReadOnlyArcVar<Option<Img>>

Window icon image.

This is None if icon is WindowIcon::Default, otherwise it is an Img reference clone.

pub fn cursor(&self) -> ArcVar<CursorSource>

Window cursor icon and visibility.

See CursorSource for details.

The default is CursorIcon::Default.

pub fn actual_cursor_img(&self) -> ReadOnlyArcVar<Option<(Img, PxPoint)>>

Window custom cursor image.

This is None if cursor is not set to a custom image, otherwise it is an Img reference clone with computed hotspot PxPoint.

pub fn title(&self) -> ArcVar<Txt>

Window title text.

The default value is "".

pub fn state(&self) -> ArcVar<WindowState>

Window screen state.

Minimized, maximized or fullscreen. See WindowState for details.

The default value is WindowState::Normal.

pub fn monitor(&self) -> ArcVar<MonitorQuery>

Window monitor.

The query selects the monitor to which the position and size is relative to.

It evaluate once when the window opens and then once every time the variable updates. You can track what the current monitor is by using actual_monitor.

Behavior After Open

If this variable is changed after the window has opened, and the new query produces a different monitor from the actual_monitor and the window is visible; then the window is moved to the new monitor:

• Maximized: The window is maximized in the new monitor.
• Normal: The window is centered in the new monitor, keeping the same size, unless the position and size where set in the same update, in that case these values are used.
• Minimized/Hidden: The window restore position and size are defined like Normal.

pub fn video_mode(&self) -> ArcVar<VideoMode>

Video mode for exclusive fullscreen.

pub fn actual_monitor(&self) -> ReadOnlyArcVar<Option<MonitorId>>

Current monitor hosting the window.

This is None only if the window has not opened yet (before first render) or if no monitors where found in the operating system or if the window is headless without renderer.

pub fn video_modes(&self) -> BoxedVar<Vec<VideoMode>>

Available video modes in the current monitor.

pub fn scale_factor(&self) -> ReadOnlyArcVar<Factor>

Current scale factor of the current monitor hosting the window.

pub fn actual_position(&self) -> ReadOnlyArcVar<DipPoint>

Window actual position on the monitor.

This is a read-only variable that tracks the computed position of the window, it updates every time the window moves.

The initial value is (0, 0), it starts updating once the window opens. The point is relative to the origin of the monitor.

pub fn global_position(&self) -> ReadOnlyArcVar<PxPoint>

Window actual position on the virtual screen that encompasses all monitors.

This is a read-only variable that tracks the computed position of the window, it updates every time the window moves.

The initial value is (0, 0), it starts updating once the window opens.

pub fn restore_state(&self) -> ReadOnlyArcVar<WindowState>

Window restore state.

The restore state that the window must be set to be restored, if the current state is Maximized, Fullscreen or Exclusive the restore state is Normal, if the current state is Minimized the restore state is the previous state.

When the restore state is Normal the restore_rect defines the window position and size.

pub fn restore_rect(&self) -> ReadOnlyArcVar<DipRect>

Window restore position and size when restoring to Normal.

The restore rectangle is the window position and size when its state is Normal, when the state is not Normal this variable tracks the last normal position and size, it will be the window actual_position and actual_size again when the state is set back to Normal.

This is a read-only variable, to programmatically set it assign the position and size variables. The initial value is (30, 30).at(800, 600), it starts updating when the window opens.

Note that to restore the window you only need to set state to restore_state, if the restore state is Normal this position and size will be applied automatically.

pub fn position(&self) -> ArcVar<Point>

Window top-left offset on the monitor when the window is Normal.

Relative values are computed in relation to the monitor size, updating every time the position or monitor variable updates.

When the user moves the window this value is considered stale, when it updates it overwrites the window position again, note that the window is only moved if it is in the Normal state, otherwise only the restore_rect updates.

When the window is moved by the user this variable does not update back, to track the current position of the window use actual_position, to track the restore position use restore_rect.

The Length::Default value causes the OS to select a value.

pub fn actual_size(&self) -> ReadOnlyArcVar<DipSize>

Window actual size on the screen.

This is a read-only variable that tracks the computed size of the window, it updates every time the window resizes.

The initial value is (0, 0), it starts updating when the window opens.

pub fn actual_size_px(&self) -> BoxedVar<PxSize>

Window actual_size, converted to pixels given the scale_factor.

pub fn safe_padding(&self) -> ReadOnlyArcVar<DipSideOffsets>

Padding that must be applied to the window content so that it stays clear of screen obstructions such as a camera notch cutout.

Note that the unsafe area must still be rendered as it may be partially visible, just don’t place nay interactive or important content outside of this padding.

pub fn size(&self) -> ArcVar<Size>

Window width and height on the screen when the window is Normal.

Relative values are computed in relation to the monitor size, updating every time the size or monitor variable updates.

When the user resizes the window this value is considered stale, when it updates it overwrites the window size again, note that the window is only resized if it is in the Normal state, otherwise only the restore_rect updates.

When the window is resized this variable is not updated back, to track the current window size use actual_size, to track the restore size use restore_rect.

The default value is (800, 600).

pub fn auto_size(&self) -> ArcVar<AutoSize>

Defines if and how the window size is controlled by the content layout.

When enabled overwrites size, but is still coerced by min_size and max_size. Auto-size is disabled if the user manually resizes.

The default value is AutoSize::DISABLED.

pub fn auto_size_origin(&self) -> ArcVar<Point>

The point in the window content that does not move when the window is resized by auto_size.

When the window size increases it grows to the right-bottom, the top-left corner does not move because the origin of windows it at the top-left and the position did not change, this variables overwrites this origin for auto_size size changes, the window position is adjusted so that it is the center of the resize.

Note this only applies to resizes, the initial auto-size when the window opens is positioned according to the StartPosition value.

The default value is Point::top_left.

pub fn min_size(&self) -> ArcVar<Size>

Minimal window width and height constraint on the size.

Relative values are computed in relation to the monitor size, updating every time the size or monitor variable updates.

Note that the OS can also define a minimum size that supersedes this variable.

The default value is (192, 48).

pub fn max_size(&self) -> ArcVar<Size>

Maximal window width and height constraint on the size.

Relative values are computed in relation to the monitor size, updating every time the size or monitor variable updates.

Note that the OS can also define a maximum size that supersedes this variable.

The default value is (100.pct(), 100.pct())

pub fn font_size(&self) -> ArcVar<Length>

Root font size.

This is the font size in all widget branches that do not override the font size. The rem unit is relative to this value.

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

Defines if the user can resize the window using the window frame.

Note that even if disabled the window can still be resized from other sources.

The default value is true.

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

Defines if the user can move the window using the window frame.

Note that even if disabled the window can still be moved from other sources.

The default value is true.

pub fn enabled_buttons(&self) -> ArcVar<WindowButton>

Defines the enabled state of the window chrome buttons.

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

Defines if the window should always stay on top of other windows.

Note this only applies to other windows that are not also “always-on-top”.

The default value is false.

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

Defines if the window is visible on the screen and in the task-bar.

This variable is observed only after the first frame render, before that the window is always not visible.

The default value is true.

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

Defines if the window is visible in the task-bar.

The default value is true.

pub fn parent(&self) -> ArcVar<Option<WindowId>>

Defines the parent window.

If a parent is set this behavior applies:

• If the parent is minimized, this window is also minimized.
• If the parent window is maximized, this window is restored.
• This window is always on-top of the parent window.
• If the parent window is closed, this window is also closed.
• If modal is set, the parent window cannot be focused while this window is open.
• If a color_scheme is not set, the fallback is the parent’s actual scheme.
• If an accent_color is not set, the fallback is the parent’s actual accent.

The default value is None.

Validation

The parent window cannot have a parent, if it has, that parent ID is used instead. The parent window must exist. This window (child) cannot have children, it also can’t set itself as the parent.

If any of these conditions are not met, an error is logged and the parent var is restored to the previous value.

pub fn nest_parent(&self) -> ReadOnlyArcVar<Option<WidgetId>>

Gets the widget in parent that hosts the window, if it is nesting.

Nesting windows are presented as an widget, similar to an “iframe”.

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

Defines the parent connection.

Value is ignored if parent is not set. When this is true the parent window cannot be focused while this window is open.

The default value is false.

pub fn children(&self) -> ReadOnlyArcVar<IdSet<WindowId>>

Window children.

This is a set of other windows that have this window as a parent.

pub fn color_scheme(&self) -> ArcVar<Option<ColorScheme>>

Override the preferred color scheme.

If set to None the system preference is used, see actual_color_scheme.

pub fn actual_color_scheme(&self) -> ReadOnlyArcVar<ColorScheme>

Actual color scheme to use.

This is the system preference, or color_scheme if it is set.

pub fn accent_color(&self) -> ArcVar<Option<LightDark>>

Override the preferred accent color.

If set to None the system preference is used, see actual_accent_color.

pub fn actual_accent_color(&self) -> ReadOnlyArcVar<LightDark>

Actual accent color to use.

This is the system preference, or color_scheme if it is set.

The window widget also sets ACCENT_COLOR_VAR to this variable.

pub fn is_open(&self) -> ReadOnlyArcVar<bool>

If the window is open.

This is a read-only variable, it starts set to true and will update only once, when the window finishes opening.

Note that a window is only actually opened in the view-process after it is_loaded.

pub fn is_loaded(&self) -> ReadOnlyArcVar<bool>

If the window has finished loading.

This is a read-only variable, it starts set to false and will update only once, after the first window layout and when all loading handles to the window are released.

A window is only opened in the view-process once it is loaded, see WINDOWS.loading_handle for more details.

pub fn focus_indicator(&self) -> ArcVar<Option<FocusIndicator>>

Defines the active user attention required indicator.

This is usually a visual indication on the taskbar icon that prompts the user to focus on the window, it is automatically changed to None once the window receives focus or you can set it to None to cancel the indicator.

Prefer using the FOCUS service and advanced FocusRequest configs instead of setting this variable directly.

pub fn frame_capture_mode(&self) -> ArcVar<FrameCaptureMode>

Defines if and how the frame pixels are captured for the next rendered frames.

If set to Next the value will change to Sporadic after the next frame is rendered.

Note that setting this to Next does not cause a frame request. Use WIDGET.render_update for that.

pub fn render_mode(&self) -> ReadOnlyArcVar<RenderMode>

Window actual render mode.

The initial value is the default_render_mode, it can update after the window is created, when the view-process actually creates the backend window and after a view-process respawn.

pub fn access_enabled(&self) -> ReadOnlyArcVar<AccessEnabled>

If an accessibility service has requested info from this window.

You can enable this in the app-process using enable_access, the view-process can also enable it on the first request for accessibility info by an external tool.

This variable does not update to fully disabled after first enable, but the VIEW bit can disable and re-enable.

pub fn system_shutdown_warn(&self) -> ArcVar<Txt>

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

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

Set to an empty text to remove the warning.

Note that this does not stop the window from closing or the app from exiting normally, you must handle window close requests and show some feedback to the user, the view-process will send a window close request when a system shutdown attempt is detected.

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.

Current Limitations

The current zng::view_process or zng-view only implements this feature on Windows and it will only work properly under these conditions:

• It must be running in run_same_process mode. Windows kills all other processes, so in a run with init the app-process will be lost. Note that this also mean that the crash handler and worker processes are also killed.
• Must be built with #![windows_subsystem = "windows"] and must be running from the Windows Explorer (desktop).

Trait Implementations

impl Clone for WindowVars

fn clone(&self) -> WindowVars

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq for WindowVars

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for WindowVars