Struct WindowConfig 

pub struct WindowConfig {

    pub title: String,
    pub string_id: Option<String>,
    pub app_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 minimizable: Option<bool>,
    pub maximizable: Option<bool>,
    pub activate_from_env: bool,
    pub icon: Option<WindowIcon>,
    pub modal: Option<ModalConfig>,
    pub root_builder: Option<RootBuilder>,
    pub post_root_builder: Option<PostRootBuilder>,
    pub on_close_requested: Option<CloseGuard>,
    pub can_close: Option<Prop<bool>>,
    pub on_close_blocked: Option<CloseBlockedCallback>,
    pub on_removed: Option<WindowRemovedCallback>,
}

Configuration for creating a new window.

Fields

title: String

string_id: Option<String>

app_id: Option<String>

The application id the desktop matches this window against, on the platforms that have one.

Set it to the basename of the installed desktop entry, without the .desktop suffix, and matching the reverse-DNS convention that entry already follows: "eu.example.MyApp".

Wayland: this becomes the toplevel’s xdg_toplevel.set_app_id. A toplevel that sends none cannot be tied to its desktop entry at all, so the shell shows the window as a separate unnamed entry carrying the generic fallback icon, however many icons the application installed. StartupWMClass in the desktop entry does not rescue it: a Wayland compositor has no WM_CLASS to put there, and GNOME reads that key for X11 windows only. Portals attribute notifications by the same id.

X11: it becomes WM_CLASS. Without it winit falls back to the executable’s own name, which is right often enough that the Wayland half of this gap goes unnoticed on an X11 session.

Windows and macOS: ignored. Neither identifies a window this way.

None by default, which leaves winit’s own behaviour untouched.

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

minimizable: Option<bool>

Whether the title bar offers a minimise button; None leaves it to the kind of window. Ignored for a modal window. See minimizable.

maximizable: Option<bool>

Whether the title bar offers a maximise button; None leaves it to the kind of window. See maximizable.

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<RootBuilder>

post_root_builder: Option<PostRootBuilder>

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<CloseGuard>

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 blocked: vetoed, or deferred to on_close_blocked when that is set. See WindowConfig::can_close.

on_close_blocked: Option<CloseBlockedCallback>

Optional hook run when the can_close signal blocks a close: it presents the confirmation UI and answers the close’s CloseDecision. See WindowConfig::on_close_blocked.

on_removed: Option<WindowRemovedCallback>

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() -> Self

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>) -> Self

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

pub fn app_id(self, app_id: impl Into<String>) -> Self

The application id the desktop matches this window against. See app_id for what each platform does with it, and why a Wayland session shows the wrong icon without it.

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

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) -> Self

Restored on-screen position in logical pixels: the top-left corner of the window’s frame, its title bar included, on every platform, as WindowState::position and the saved geometry hold it. None lets the window manager pick.

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

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) -> Self

Upper bound on the floating size.

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

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>) -> Self

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) -> Self

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

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

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) -> Self

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) -> Self

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) -> Self

Keep this window above all others regardless of focus.

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

Keep this window out of the taskbar. Useful for tool palettes and secondary overlays.

Honoured on Windows and X11, when the window is created. Wayland has no protocol open to every client for it, so the compositor decides. On macOS, where the Dock lists applications, the window is kept out of the Window menu and the Dock icon’s menu, the lists of windows a user switches between, as AppKit’s panels are; keeping the application itself out of the Dock is its activation policy, not this setting.

On Windows a window with no taskbar button is also left out of Alt+Tab, so once minimised the user has no way to bring it back. Give such a window no minimise button (minimizable(false)), or hide it and offer a way to show it again, such as a tray menu.

pub fn minimizable(self, minimizable: bool) -> Self

Offer a minimise button in the window’s title bar, or not. An ordinary window has one unless refused.

A modal window never has one, whatever this says (a debug build warns when it says true): a dialog is minimised and restored with the window it blocks, as Windows does with an owned window and macOS with a child window, and a dialog minimised alone would leave that window refusing input with nothing on screen to say why.

Applied when the window is created: on Windows and macOS through the window’s own title bar, and in a title bar the application draws itself (DecorationsMode::CustomChrome), whose TitleBar (teksilo-widgets) leaves the button out. The title bar an X11 window manager or a Wayland compositor draws is theirs: on X11 a modal window is a transient dialog, which window managers usually draw without a minimise button.

pub fn maximizable(self, maximizable: bool) -> Self

Offer a maximise button in the window’s title bar, or not; on macOS the zoom button. By default an ordinary window has one and a modal one does not, unless it asks. Where it applies is as for minimizable.

pub fn is_minimizable(&self) -> bool

Whether the title bar offers a minimise button: never for a modal window, otherwise as set with minimizable, by default yes.

pub fn is_maximizable(&self) -> bool

Whether the title bar offers a maximise button: as set with maximizable, otherwise unless the window is modal.

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

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) -> Self

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) -> Self

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.

The parent is the dialog’s owner. It refuses input while the dialog is open (a click or the focus there brings the dialog forward), and its close button does nothing but bring the dialog forward. The dialog stays in front of it, has no taskbar entry and no minimise button of its own (minimizable is ignored), and is minimised, restored and closed with it (its own close guard is not asked then). On Wayland, where winit gives a window no parent, the compositor treats it as a window of its own, and it is not minimised or restored with its owner: no protocol tells the application of either.

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

Make this window modal using a caller-built ModalConfig. Use this form when you need to specify an explicit focus_target. The window belongs to config.parent as modal_to describes.

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

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<RootBuilder>

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, ) -> Self

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<PostRootBuilder>

Take the post-root builder out of the config.

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

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), and when a guarded quit (EventContext::quit) asks it.

The guard runs with a real EventContext for this window’s tree, and answers with a CloseResponse: Close lets the close proceed, Veto refuses it (and abandons a quit that asked), and Defer answers later through a CloseDecision. Asking the user is a deferred answer:

WindowConfig::new()
    .on_close_requested(move |ctx| {
        if !has_unsaved_changes() {
            return CloseResponse::Close;
        }
        let decision = CloseDecision::new();
        let answer = decision.clone();
        ctx.present_message_box(
            MessageBox::question(lit!("Save before closing?"))
                .buttons(MessageBoxButtons::SaveDiscardCancel)
                .on_result(move |result, _ctx| match result.button {
                    StandardButton::Save => { save(); answer.proceed(); }
                    StandardButton::Discard => answer.proceed(),
                    _ => answer.cancel(),
                }),
        );
        CloseResponse::Defer(decision)
    });

proceed closes the window without asking the guard again, and a quit waiting on it goes on; cancel leaves it open and abandons such a quit. The guard is not consulted for a forced close (close_window_forced, close_window_by_id), a forced quit, or framework-internal teardown (modal cleanup, the final-window shutdown drain).

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

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 blocked. With no on_close_blocked the close is vetoed, which is final: a quit that asks the window is abandoned. With one, the close defers (CloseResponse::Defer) and the callback answers it, so a confirmation can let the close, and a quit waiting on it, go on.

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<'_>, CloseDecision) + 'static, ) -> Self

Hook run when the can_close signal blocks a close attempt, whether it came from the user or from a quit. Runs with this window’s EventContext and a CloseDecision for the close: present the confirmation, then answer with proceed (the window closes without its guard being asked again, and a quit goes on) or cancel (the window stays, and a guarded quit is abandoned; a quit that leaves no time to ask closes the window whatever the answer, and a forced one does not run this). The decision is Send and cloneable, so a dialog’s result callback can hold it; one dropped unanswered cancels, and a debug build says so. A callback that only wants to say why calls cancel at once.

Setting it turns the block from a veto into a CloseResponse::Defer; without it the block is a final CloseResponse::Veto. No-op unless a can_close signal is also set.

pub fn take_close_guard(&mut self) -> Option<CloseGuard>

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<CloseBlockedCallback>

Take the on_close_blocked callback out of the config.

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

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<WindowRemovedCallback>

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

Formats the value using the given formatter.

impl Default for WindowConfig

fn default() -> Self

Returns the “default value” for a type.