Module window

Expand description

Window service, widget, events, commands and other types.

The Window! widget instantiates a window root, the windows service uses the window root as the root widget of new window.

The example below declares a window that toggles if it can close.

use zng::prelude::*;

fn app() {
    APP.defaults().run_window(async { window() });
}

fn window() -> window::WindowRoot {
    let allow_close = var(true);
    Window! {
        on_close_requested = hn!(allow_close, |args| {
            if !allow_close.get() {
                args.propagation().stop();
            }
        });

        title = "Can I Close?";
        child_align = layout::Align::CENTER;
        child = Toggle! {
            child = Text!(allow_close.map(|a| formatx!("allow close = {a:?}")));
            checked = allow_close;
        };
    }
}

The WINDOWS service can be used to open, manage and close windows. The example below opens a parent and child window.

use zng::prelude::*;

fn app() {
    APP.defaults().run(async {
        let r = WINDOWS.open(async { main_window() });
        println!("opened {}", r.wait_rsp().await);
    });
}

fn main_window() -> window::WindowRoot {
    Window! {
        title = "Main Window";
        child_align = layout::Align::CENTER;
        child = {
            let enabled = var(true);
            Button! {
                child = Text!("Open/Close Child");
                on_click = async_hn!(enabled, |_| {
                    enabled.set(false);

                    if WINDOWS.is_open("child-id") {
                        if let Ok(r) = WINDOWS.close("child-id") {
                            r.wait_done().await;
                        }
                    } else {
                        let parent = WINDOW.id();
                        WINDOWS.open_id("child-id", async move { child_window(parent) }).wait_done().await;
                    }

                    enabled.set(true);
                });
                widget::enabled;
            }
        };
    }
}

fn child_window(parent: WindowId) -> window::WindowRoot {
    Window! {
        parent;
        title = "Child Window";
        size = (200, 100);
        child = Button! {
            child = Text!("Close");
            on_click = hn!(|_| {
                let _ = WINDOW.close();
            });
        };
    }
}

§Theming

Themes are a collection of widget styles that replace the look and feel of the entire application. This can be achieved by setting contextual properties that change the style and appearance for all widgets in all windows.

The WINDOWS.register_style_fn method is a convenient entry point for applying themes. It injects a window style in all subsequent window instances. A custom theme can define a window style that sets all the contextual properties that affect the other widgets. Widgets either implement the zng::style feature or provide their own contextual properties.

Note that the theme concept is different from the accent_color and color_scheme (light/dark). Themes usually provide a more drastic change in appearance, not just changing the colors. Custom theme implementers should strongly consider incorporating these contextual color values, these values are usually provided by the operating system, derived from the user preferences.

use zng::prelude::*;

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Theme {
    Default,
    Custom,
}
impl Theme {
    pub fn window_style_fn(&self) -> zng::style::StyleFn {
        match self {
            Theme::Default => style_fn!(|_| zng::window::DefaultStyle!()),
            Theme::Custom => style_fn!(|_| themes::custom()),
        }
    }
}

mod themes {
    use zng::{prelude::*, style::StyleBuilder};

    pub fn custom() -> StyleBuilder {
        let base_color = colors::RED.with_alpha(60.pct());

        zng::window::DefaultStyle! {
            zng::button::style_fn = Style! {
                color::base_color = base_color;
            };
            zng::toggle::style_fn = Style! {
                color::base_color = base_color;
            };
            zng::toggle::check_style_fn = Style! {
                color::accent_color = colors::RED;
            };
        }
    }
}

let theme = var(Theme::Default);
WINDOWS.register_style_fn(theme.map(|t| t.window_style_fn()));

The example above provide a simple theming setup and a very basic custom theme, the theme will be applied for all subsequent window instances and will dynamically update on variable change. Usually in a full app the Theme enum would be serializable and the variable provided by the zng::config::CONFIG service. See zng::style docs for more details about styles that fully replace the appearance of a widget.

§Full API

See zng_ext_window, zng_app::window and zng_wgt_window for the full window API.

Modules§

cmd: Window commands.
inspector: Debug inspection helpers.

Structs§

AutoSize: Window auto-size config.
DefaultStyle: W Default window style.
FrameImageReadyArgs: FRAME_IMAGE_READY_EVENT args.
HeadlessMonitor: “Monitor” configuration used by windows in headless mode.
ImeArgs: Arguments for IME_EVENT.
MONITORS: Monitors service.
MonitorId: Unique identifier of a monitor screen.
MonitorInfo: All information about a monitor that MONITORS can provide.
MonitorsChangedArgs: MONITORS_CHANGED_EVENT args.
ParallelWin: Defines what window operations can run in parallel, between windows.
VideoMode: Exclusive video mode info.
WINDOW: Current context window.
WINDOWS: Windows service.
Window: W A window container.
WindowButton: Window chrome buttons.
WindowChangedArgs: WINDOW_CHANGED_EVENT args.
WindowCloseArgs: WINDOW_CLOSE_EVENT args.
WindowCloseRequestedArgs: WINDOW_CLOSE_REQUESTED_EVENT args.
WindowId: Unique identifier of an open window.
WindowLoadingHandle: Represents a handle that stops the window from loading while the handle is alive.
WindowOpenArgs: WINDOW_OPEN_EVENT args.
WindowRoot: Window root node and values.
WindowRootExtenderArgs: Arguments for WINDOWS.register_root_extender.
WindowStateAllowed: Mask of allowed WindowState states of a window.
WindowVars: Variables that configure the opening or open window.

Enums§

BlockWindowLoad: Defines if a widget load affects the parent window load.
CloseWindowResult: Response message of close and close_together.
FocusIndicator: Represents a focus request indicator.
FrameCaptureMode: Frame image capture mode in a window.
MonitorQuery: A selector that returns a MonitorInfo.
RenderMode: Render backend preference.
StartPosition: Window startup position.
WindowIcon: Window icon.
WindowMode: Mode of an open window.
WindowState: Window state.

Statics§

FRAME_IMAGE_READY_EVENT: A window frame has finished rendering.
IME_EVENT: Input Method Editor event targeting a text input widget.
MONITORS_CHANGED_EVENT: Monitors added, removed or modified event.
WINDOW_CHANGED_EVENT: Window moved, resized or other state changed.
WINDOW_CLOSE_EVENT: Window closed event.
WINDOW_CLOSE_REQUESTED_EVENT: Window close requested event.
WINDOW_LOAD_EVENT: Window finished loading and has opened in the view-process.
WINDOW_OPEN_EVENT: New window has inited.

Traits§

AppRunWindowExt: Extension trait, adds run_window to AppExtended.
HeadlessAppWindowExt: Window extension methods for HeadlessApp.
WINDOWS_Ext: Extension methods for WINDOWS.
WINDOW_Ext: Extensions methods for WINDOW contexts of windows open by WINDOWS.
WidgetInfoBuilderImeArea: IME extension methods for WidgetInfoBuilder.
WidgetInfoImeArea: IME extension methods for WidgetInfo.

Functions§

default_mobile_nested_open_handler: Default handler registered in mobile platforms.
on_frame_image_ready: P On window frame rendered.
on_ime: P On Input Method Editor event.
on_pre_frame_image_ready: P Preview on_frame_image_ready event.
on_pre_ime: P Preview on_ime event.
on_pre_window_changed: P Preview on_window_changed event.
on_pre_window_close_requested: P Preview on_window_close_requested event.
on_pre_window_exited_fullscreen: P Preview on_window_exited_fullscreen event.
on_pre_window_fullscreen: P Preview on_window_fullscreen event.
on_pre_window_load: P Preview on_window_load event.
on_pre_window_maximized: P Preview on_window_maximized event.
on_pre_window_minimized: P Preview on_window_minimized event.
on_pre_window_moved: P Preview on_window_moved event.
on_pre_window_open: P Preview on_window_open event.
on_pre_window_resized: P Preview on_window_resized event.
on_pre_window_restored: P Preview on_window_restored event.
on_pre_window_state_changed: P Preview on_window_state_changed event.
on_pre_window_unmaximized: P Preview on_window_unmaximized event.
on_pre_window_unminimized: P Preview on_window_unminimized event.
on_window_changed: P On window moved, resized or other state changed.
on_window_close_requested: P On window close requested.
on_window_exited_fullscreen: P On window state changed from WindowState::is_fullscreen.
on_window_fullscreen: P On window state changed to WindowState::is_fullscreen.
on_window_load: P On window loaded.
on_window_maximized: P On window state changed to WindowState::Maximized.
on_window_minimized: P On window state changed to WindowState::Minimized.
on_window_moved: P On window position changed.
on_window_open: P On window opened.
on_window_resized: P On window size changed.
on_window_restored: P On window state changed to WindowState::Normal.
on_window_state_changed: P On window state changed.
on_window_unmaximized: P On window state changed from WindowState::Maximized.
on_window_unminimized: P On window state changed from WindowState::Minimized.

Module window

Module window Copy item path

§Theming

§Full API

Modules§

Structs§

Enums§

Statics§

Traits§

Functions§

Module window