Multi-Window & Window Management

Perry supports creating multiple native windows and controlling their appearance and behavior.

Creating Windows

import { App, Window, Text, Button, VStack } from "perry/ui";

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

App({
  title: "My App",
  width: 800,
  height: 600,
  body: VStack(16, [
    Text("Main Window"),
    Button("Open Settings", () => win.show()),
  ]),
});

Window(title, width, height) creates a new native window. Call .setBody() to set its content and .show() to display it.

Window Instance Methods

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

win.setBody(widget);     // Set the root widget
win.show();              // Show the window
win.hide();              // Hide without destroying
win.closeWindow();       // Close and destroy
win.onFocusLost(() => {  // Called when window loses focus
  win.hide();
});

App Window Properties

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

import { App, Text, VStack } from "perry/ui";

App({
  title: "QuickLaunch",
  width: 600,
  height: 80,
  frameless: true,
  level: "floating",
  transparent: true,
  vibrancy: "sidebar",
  activationPolicy: "accessory",
  body: VStack(8, [
    Text("Search..."),
  ]),
});

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.

Standalone Window Functions

Window management is also available as standalone functions for use with window handles:

import { Window, windowHide, windowSetSize, onWindowFocusLost } from "perry/ui";

const win = Window("Panel", 400, 300);

// Hide/show
windowHide(win);

// Resize dynamically
windowSetSize(win, 600, computedHeight);

// React to focus loss
onWindowFocusLost(win, () => {
  windowHide(win);
});

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 — Global hotkeys and keyboard shortcuts
• Dialogs — Modal dialogs and sheets
• Menus — Menu bar and toolbar
• UI Overview — Full UI system overview