Multi-Window & Window Management

Perry supports creating multiple native windows and controlling their appearance and behavior. Every snippet below is excerpted from docs/examples/ui/multi_window/snippets.ts — CI compiles and runs it on every PR.

Creating Windows

Window(title, width, height) returns a window handle. Call .setBody() to set its content and .show() to display it:

const settings = Window("Settings", 500, 400)
settings.setBody(VStack(16, [
    Text("Settings panel"),
]))
settings.show()

Window Instance Methods

const win = Window("My Window", 600, 400)

win.setBody(Text("Hello"))   // Set the root widget
win.show()                    // Show the window
win.hide()                    // Hide without destroying
win.setSize(800, 600)         // Resize dynamically
win.onFocusLost(() => {       // Callback when the window loses focus
    win.hide()
})
win.close()                   // Close and destroy

App Window Properties

The main App({}) config object accepts the same window properties for building launcher-style, overlay, or utility apps:

App({
    title: "QuickLaunch",
    width: 600,
    height: 80,
    body: VStack(8, [
        Text("Search..."),
        Button("Open Settings", () => settings.show()),
    ]),
})

App additionally accepts the optional fields frameless, level, transparent, vibrancy, activationPolicy, and icon. They map to the following native primitives:

frameless: true

Removes the window title bar and frame, creating a borderless window.

level: "floating" | "statusBar" | "modal" | "normal"

Controls the window’s z-order level relative to other windows.

transparent: true

Makes the window background transparent, allowing the desktop to show through non-opaque regions of your UI.

vibrancy: string

Applies a native translucent material to the window background. On macOS this uses the system vibrancy effect; on Windows it uses Mica/Acrylic.

macOS materials: "sidebar", "titlebar", "selection", "menu", "popover", "headerView", "sheet", "windowBackground", "hudWindow", "fullScreenUI", "tooltip", "contentBackground", "underWindowBackground", "underPageBackground"

activationPolicy: "regular" | "accessory" | "background"

Controls whether the app appears in the dock/taskbar.

Platform Notes

On mobile platforms, “windows” are presented as modal views or dialogs since mobile apps typically use a single-window model.

Next Steps

• Events — Keyboard shortcuts
• Dialogs — Modal dialogs and sheets
• Menus — Menu bar and toolbar
• UI Overview — Full UI system overview