Struct WindowConfig 

pub struct WindowConfig {

    pub title: String,
    pub string_id: Option<String>,
    pub size: (u32, u32),
    pub position: Option<(i32, i32)>,
    pub min_size: Option<(u32, u32)>,
    pub max_size: Option<(u32, u32)>,
    pub restore_geometry: bool,
    pub initial_placement: WindowPlacement,
    pub decorations: DecorationsMode,
    pub resizable: bool,
    pub size_to_content: SizeToContent,
    pub always_on_top: bool,
    pub skip_taskbar: bool,
    pub activate_from_env: bool,
    pub icon: Option<WindowIcon>,
    pub modal: Option<ModalConfig>,
    pub root_builder: Option<Box<dyn FnOnce(&mut WidgetTree, WindowState) -> WidgetId>>,
    pub post_root_builder: Option<Box<dyn FnOnce(&mut WidgetTree, WidgetId) -> WidgetId>>,
    pub on_close_requested: Option<Rc<dyn Fn(&mut EventContext<'_>) -> CloseResponse>>,
    pub can_close: Option<Prop<bool>>,
    pub on_close_blocked: Option<Rc<dyn Fn(&mut EventContext<'_>)>>,
    pub on_removed: Option<Rc<dyn Fn(&WindowRemovedEvent)>>,
}

Configuration for creating a new window.

Fields

title: String

string_id: Option<String>

size: (u32, u32)

position: Option<(i32, i32)>

min_size: Option<(u32, u32)>

max_size: Option<(u32, u32)>

restore_geometry: bool

Whether this window’s geometry is restored from the persisted window state at creation. Default true.

Persisting and restoring are usually the same decision, so string_id normally governs both. They come apart in one common case: a multi-window (or multi-process) app where every window shares one geometry slot. Restoring the saved geometry into every window would stack them exactly on top of each other; you want the first window to land where the user left it, and any window opened alongside it to be placed by the OS (which cascades). But you still want every window to save its geometry, so whichever the user moved or closed last is what reopens next time — the behaviour of Word, Firefox and most document apps.

Set false for those later windows: they still persist under their string_id, they simply don’t read the saved value back. With position left None, the window manager picks the spot.

initial_placement: WindowPlacement

decorations: DecorationsMode

resizable: bool

size_to_content: SizeToContent

Whether the OS window resizes itself to fit its content’s intrinsic size. See SizeToContent. Default SizeToContent::Off.

always_on_top: bool

skip_taskbar: bool

activate_from_env: bool

When set, this window consumes an xdg_activation_v1 startup token from the environment at creation so it comes up focused on Wayland (the launching process set it via set_child_activation_env). No effect off Wayland/X11.

icon: Option<WindowIcon>

modal: Option<ModalConfig>

root_builder: Option<Box<dyn FnOnce(&mut WidgetTree, WindowState) -> WidgetId>>

post_root_builder: Option<Box<dyn FnOnce(&mut WidgetTree, WidgetId) -> WidgetId>>

Optional post-root wrapper. When set, the framework calls it after root_builder and uses the returned id as the window’s effective root. See PostRootBuilder.

on_close_requested: Option<Rc<dyn Fn(&mut EventContext<'_>) -> CloseResponse>>

Optional close guard. Consulted before this window closes in response to a user gesture; returning CloseResponse::Veto cancels the close. See WindowConfig::on_close_requested.

can_close: Option<Prop<bool>>

Optional reactive “may this window close?” signal. Sugar over on_close_requested: when present and false, a close attempt is vetoed and on_close_blocked fires (if set). See WindowConfig::can_close.

on_close_blocked: Option<Rc<dyn Fn(&mut EventContext<'_>)>>

Optional notification fired when the can_close signal blocks a close — the hook that presents the confirmation UI. See WindowConfig::on_close_blocked.

on_removed: Option<Rc<dyn Fn(&WindowRemovedEvent)>>

Optional teardown hook, fired once this window has been fully removed from the window manager. See WindowConfig::on_removed.

Implementations

impl WindowConfig

pub fn new() -> WindowConfig

Start a config with sensible defaults.

Defaults: title "Teksilo", size 800x600, WindowPlacement::Floating, DecorationsMode::Native, resizable, no parent, no id, no root builder.

pub fn title(self, title: impl Into<String>) -> WindowConfig

User-visible title. Also becomes the initial value of WindowState::title.

pub fn size(self, width: u32, height: u32) -> WindowConfig

Restored size in logical pixels. This is the size the window returns to when leaving Maximized or Fullscreen, and the current size when placement is Floating.

pub fn position(self, x: i32, y: i32) -> WindowConfig

Restored on-screen position in logical pixels. None lets the window manager pick.

pub fn min_size(self, width: u32, height: u32) -> WindowConfig

Lower bound on the floating size. The OS prevents the user from resizing the window below this.

pub fn max_size(self, width: u32, height: u32) -> WindowConfig

Upper bound on the floating size.

pub fn restore_geometry(self, restore: bool) -> WindowConfig

Whether to restore this window’s persisted geometry at creation (default true). See WindowConfig::restore_geometry.

Pass false for a window that should still save its geometry but be placed by the OS rather than reopened at the remembered spot — the second and later windows of an app whose windows share one geometry slot, which would otherwise all land exactly on top of each other.

pub fn id(self, id: impl Into<String>) -> WindowConfig

Stable string identifier for later lookup via EventContext::find_window. Optional — omit for “open a fresh window every time.”

pub fn initial_placement(self, placement: WindowPlacement) -> WindowConfig

Initial placement. Defaults to Floating; pass WindowPlacement::Fullscreen / Maximized to start in that state.

pub fn decorations(self, mode: DecorationsMode) -> WindowConfig

Chrome mode. Native draws OS decorations; CustomChrome constructs a PlatformTitleBarHost (on X11, falls back to Native when the window manager lacks _NET_WM_MOVERESIZE); None is borderless.

pub fn resizable(self, resizable: bool) -> WindowConfig

Whether the user can resize the window interactively. Also affects whether maximize gestures are accepted on some platforms.

pub fn size_to_content(self, mode: SizeToContent) -> WindowConfig

Make this window resize itself to fit its content’s intrinsic size. See SizeToContent. The configured size / min_size act as a floor. Used for native modal dialogs (e.g. MessageBox) so the OS window grows when the content does — matching the in-tree overlay path.

Do NOT also call .resizable(false): winit encodes non-resizable as equal min/max size hints (notably on X11), which would clamp away the programmatic growth this relies on.

pub fn always_on_top(self, on_top: bool) -> WindowConfig

Keep this window above all others regardless of focus.

pub fn skip_taskbar(self, skip: bool) -> WindowConfig

Hide this window from the taskbar / dock. Useful for tool palettes and secondary overlays.

pub fn activate_from_env(self, on: bool) -> WindowConfig

Consume an xdg_activation_v1 startup token from the environment at creation so this window comes up focused on Wayland. Set on the initial window of a process spawned by another instance’s “open in new window”.

pub fn icon(self, icon: WindowIcon) -> WindowConfig

Set the window’s icon from a raw RGBA8 buffer. The icon is used by the taskbar / dock and the window’s title bar on platforms where it applies.

Invalid buffers (rgba.len() != width * height * 4) are logged and dropped at creation time — the window still opens, just with the platform default icon.

pub fn modal_to(self, parent: TeksiloWindowId) -> WindowConfig

Make this window modal to the given parent, with no explicit focus target. Prefer this over constructing ModalConfig yourself when you already have the parent id handy.

pub fn modal(self, config: ModalConfig) -> WindowConfig

Make this window modal using a caller-built ModalConfig. Use this form when you need to specify an explicit focus_target.

pub fn root( self, builder: impl FnOnce(&mut WidgetTree, WindowState) -> WidgetId + 'static, ) -> WindowConfig

Root-widget builder. Called once during window creation with the new window’s WidgetTree and a cloned WindowState so widgets can bind against window-level signals.

pub fn take_root_builder( &mut self, ) -> Option<Box<dyn FnOnce(&mut WidgetTree, WindowState) -> WidgetId>>

Take the root builder out of the config, leaving None in its place. Consumed by the window manager exactly once during create_window.

pub fn post_root( self, builder: impl FnOnce(&mut WidgetTree, WidgetId) -> WidgetId + 'static, ) -> WindowConfig

Attach a per-window post-root hook. Runs after the user’s root_builder returns; receives the user’s root id and may return either the same id or a wrapper’s id. The framework uses the returned id as the window’s effective root.

Typically used by the debug inspector. Apps that want to install a default wrapper across all windows should use the app-level mechanism instead of setting this per-config.

pub fn take_post_root_builder( &mut self, ) -> Option<Box<dyn FnOnce(&mut WidgetTree, WidgetId) -> WidgetId>>

Take the post-root builder out of the config.

pub fn on_close_requested( self, guard: impl Fn(&mut EventContext<'_>) -> CloseResponse + 'static, ) -> WindowConfig

Install a close guard consulted before this window closes in response to a user gesture — the OS close button / Alt+F4 / Cmd+W, a custom-chrome close button, or EventContext::close_window.

The guard runs with a real EventContext for this window’s tree. Return CloseResponse::Close to let the close proceed, or CloseResponse::Veto to cancel it. The canonical pattern is veto-then-reissue:

WindowConfig::new()
    .on_close_requested(move |ctx| {
        if has_unsaved_changes() {
            ctx.show_message_box(/* "Save before closing?" */);
            CloseResponse::Veto
        } else {
            CloseResponse::Close
        }
    });

// …and from the confirmation dialog's "Discard & Close" button:
ctx.close_window_forced();

close_window_forced bypasses the guard, so the second close actually goes through. The guard is not consulted for framework-internal teardown (modal cleanup, the final-window shutdown drain).

pub fn can_close(self, may_close: impl Into<Prop<bool>>) -> WindowConfig

Reactive sugar over on_close_requested: bind a Signal<bool> that answers “may this window close right now?”. While the signal reads false, every user-initiated close attempt is vetoed and on_close_blocked (if set) fires so the app can surface a confirmation.

can_close is evaluated before the on_close_requested guard: a false signal short-circuits to a veto; a true signal (or no signal) falls through to the guard, then to closing.

pub fn on_close_blocked( self, on_blocked: impl Fn(&mut EventContext<'_>) + 'static, ) -> WindowConfig

Notification fired when the can_close signal blocks a close attempt. Runs with this window’s EventContext; use it to open the confirmation dialog / modal that, on confirm, calls close_window_forced. No-op unless a can_close signal is also set.

pub fn take_close_guard( &mut self, ) -> Option<Rc<dyn Fn(&mut EventContext<'_>) -> CloseResponse>>

Take the close guard out of the config. Consumed by the window manager once during create_window, which stores it on the managed window for the window’s lifetime.

pub fn take_can_close(&mut self) -> Option<Prop<bool>>

Take the can_close prop out of the config.

pub fn take_close_blocked( &mut self, ) -> Option<Rc<dyn Fn(&mut EventContext<'_>)>>

Take the on_close_blocked callback out of the config.

pub fn on_removed( self, hook: impl Fn(&WindowRemovedEvent) + 'static, ) -> WindowConfig

Register a teardown hook for this window: an Fn, not FnOnce or FnMut, because a shared closure (Rc-cloned config, or a closure built once and attached to several windows opened for the same document) may run once per window it’s attached to.

Fires exactly once, no matter which of the two ways this window closes:

• a guarded close (EventContext::close_window / the OS close button / Alt+F4 / Cmd+W), once can_close / on_close_requested let it through;
• a forced close (EventContext::close_window_forced / EventContext::close_window_by_id), which bypasses the guard entirely;

because the window manager funnels both through the same, single teardown routine.

Runs after the window is gone: its tree has been dropped, its platform window destroyed, and every framework-internal registration for it (native menu, drag-and-drop target, pending async completions, …) purged. This is the deliberate choice — it is what lets WindowRemovedEvent::remaining_windows already exclude the window being removed, so a handler that wants to know “was this the last window [for my Work]” gets an unambiguous answer rather than having to remember to subtract one. The trade-off is that the callback cannot reach into the removed window’s own widget tree — by the time it runs, there isn’t one. If a hook needs to read tree state before it’s torn down, that has to happen earlier, in on_close_requested or on_close_blocked.

The intended use is releasing whatever an app keeps keyed by a window’s TeksiloWindowId — a shared-document refcount, an entry in the app’s own “windows open for this Work” map — so that bookkeeping is decremented exactly when the framework agrees the window is really gone, instead of a hand-maintained registry that only ever grows.

pub fn take_on_removed(&mut self) -> Option<Rc<dyn Fn(&WindowRemovedEvent)>>

Take the on_removed teardown hook out of the config.

pub fn is_modal(&self) -> bool

pub fn modal_parent(&self) -> Option<TeksiloWindowId>

pub fn modal_focus_target(&self) -> Option<WidgetId>

Trait Implementations

impl Debug for WindowConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for WindowConfig

fn default() -> WindowConfig

Returns the “default value” for a type.