Skip to content
Select theme
Select languageEnglish

Windows

Each app window is a separate web page with its own DOM and JS heap; one window crashing does not affect the others. All windows of the same app share storage such as localStorage, IndexedDB, and cookies.

  • In a desktop, a new window's content area is the configured size (800 × 600 by default) and opens centered; next time it opens where it was last closed.
  • In an acdev dev session that runs a single app (an app project without --desktop), the app fills the host window, and size sets how large that window opens: with "size": [400, 300] the host window's content area is 400 × 300. The title bar is drawn inside it, so the page is 400 × 268. Without size the host window takes most of the screen (90% of its width and 85% of its height, at most 1440 × 900).
  • acdev dev --headless has no host window, and size is not applied: the screen is 1440 × 900 (1280 × 800 in acdev test) and the app fills it, so the page is 1440 × 868. To see the app in a window of its own size, run it in a desktop: acdev dev --desktop ./my-desktop, or --desktop dopame once that desktop is installed (see acdev dev).
  • The title bar drawn by the system is not part of the page's document: innerHeight, 100vh, and resize events only cover the content area. To drop the title bar, set "frame": false in the config, draw your own, and use setGrabHint to tell the system where the window can be dragged.
  • The title comes from document.title or window.setTitle(), whichever was set last (a <title> in the page replaces a title set before the document loaded); if neither is set, label is used.
  • Declare the colour schemes your page supports, as in a browser: color-scheme: light dark on the root (:root { color-scheme: light dark }) or <meta name="color-scheme" content="light dark"> when it follows the system with prefers-color-scheme, dark when it is always dark. The system draws a dark title bar only for pages that name dark; a page that declares nothing is taken as light only and gets a light title bar even in a dark theme. The html template follows the system and declares light dark. An app run on its own (an acdev dev of the app, acdev test) gets a dark title bar while the page is dark: a page that names only dark always, a page that names light dark while prefers-color-scheme is dark (the system's scheme, or emulate({ colorScheme }) in a test). As in browsers, the root's color-scheme counts before the meta: an app with its own light / dark switch sets color-scheme: dark or light on the root, and the title bar follows it.
import { window as self } from 'acde:window'
self.setTitle('Untitled — Notes')
self.on('beforeclose', async () => {
if (!dirty) return true
return confirmDiscard() // return false to keep the window open
})

The module is named window, the same as the global window, so renaming it on import keeps things clear.

Member Does
id This window's id (a number)
setTitle(title) Sets the title
setMenus(menus) App menus (shown in the desktop's menu bar)
close() Closes the window at once; beforeclose is not asked
minimize() Minimizes the window, as requestState('minimized') does; the promise rejects with status: 409, code: 'unavailable' when the window cannot be minimized
state / requestState(state) The window's state: normal, minimized, filled (fills the work area), fullscreen; see Window state
requestMode(mode) Whether the user can move and resize the window: free (both), fixed (move only), pinned (neither)
output The screen the window is on: {width, height, scale, workArea: {x, y, width, height}} in logical pixels; workArea leaves out what the desktop's panels reserve. In a session that runs a single app the screen is the host window: with "size": [400, 300], output and its workArea are both 400 × 300
requestAttention() Requests attention (for example a bouncing Dock icon; up to the desktop)
requestActivate() Brings the window to the front and requests focus; the system may turn this into a request for attention
setGrabHint(rect, edges?) Pressing in this area makes the system move the window (no edges) or resize it (with edges)
setBackdrop(rect, effect?) Frosted glass over whatever is behind this area: {radius, blur, saturate, brightness}; null removes it
requestGrab(kind) / releaseGrab(kind) Takes exclusive pointer or keyboard input ('pointer' / 'keyboard')
shortcut(combo) / unshortcut(combo) Registers an app-level global shortcut, such as 'ctrl+shift+k'
hostControls true when the host system draws the window's minimize / maximize / close buttons, so a frameless app should hide its own
minimizable false when this window cannot be minimized. In a session that runs a single app, on macOS and headless, the app's window is such a window: it fills the host window

Full screen is a state of the window, not a mode: requestMode('fullscreen') throws a TypeError (requestMode: full screen is a window state, use requestState('fullscreen')).

self.on('state', ({ state, previous }) => {
document.body.dataset.windowState = state
})
self.requestState('fullscreen') // 'normal' | 'minimized' | 'filled' | 'fullscreen'
  • requestState() returns nothing. The system decides: when it refuses, nothing changes and no event arrives. A fixed window can only be minimized, and a pinned one cannot change state. A window whose minimizable is false cannot be minimized: requestState('minimized') changes nothing, and minimize() rejects.
  • The state also changes without the page asking: the title bar's buttons, the desktop minimizing the window, the user bringing a minimized window back. Keep the UI in step with the state event (or self.state), not with what the page last requested.
  • A minimized window that gets the focus again returns to the state it had before (fullscreen, for example).
  • In a single-app acdev dev session the app already fills the host window, and state requests may change nothing (headless on macOS, minimized, filled and fullscreen all leave the state normal, and no event arrives). Try states in a desktop session.
  • The standard Fullscreen API (element.requestFullscreen()) is not supported; it rejects with NotSupportedError.

Subscribe with on(name, handler), which returns an unsubscribe function. A name the module does not have throws a TypeError (acde:window has no nosuch event (activate, deactivate, beforeclose, request, suspend, resume, grab, grablost, state, output, hostcontrols, minimizable, shortcut)). Events are not dispatched on the global window.

Event When
activate / deactivate The window gains / loses focus
state The window's state changed, {state, previous}
output The screen or its work area changed; the handler gets the new output
beforeclose The user or the desktop wants to close the window. Return false (or resolve to false) to keep it; if there is no answer within 3 seconds, it closes
request Another app or the system asks this window to open something (see Opening apps)
shortcut A registered shortcut was pressed, {key}
grab / grablost Exclusive input was answered, {kind, granted} / taken back, {kind: 'lost', reason}
hostcontrols / minimizable hostControls / minimizable changed; the handler gets the new value
self.setMenus([
{
id: 'file',
label: 'File',
items: [
{ id: 'new', label: 'New', shortcut: 'ctrl+n', onSelect: () => newDoc() },
{ type: 'separator' },
{ id: 'close', label: 'Close', onSelect: () => self.close() },
],
},
])

Call setMenus again with the whole list to change anything (a checked mark, a disabled item). Where the menus show:

  • In a desktop, in its menu bar (the Dopame desktop shows the focused window's menus).
  • An app run on its own (an acdev dev of the app, acdev test) shows them on the title bar the system draws: the menu names after the window buttons, the window's title moved past them. A name opens its menu on a press; the arrow keys, Return and Escape work the open menu, and choosing an item runs its onSelect. An item without onSelect is shown disabled. acdev inspect lists the menus first (menuitem "File" [collapsed] [w1.m1], and the items of the open one, w1.m1.2), acdev act w1.m1.2 click opens the menu and chooses the item, and in a test getByRole('menuitem', { name: 'New' }) finds them. With "frame": false there is no title bar, so no menus either.

An item's shortcut ('ctrl+n', the same names as shortcut(), also mod, which is ⌘ on macOS and Ctrl elsewhere) is shown next to it. In a desktop it is only shown: to have the key work, register the combo with self.shortcut() as well and handle the shortcut event. An app run on its own has it bound too, while its window is focused: pressing it runs the item's onSelect, as long as the item has one and is not disabled. The page then gets no keydown for that combo (an Edit item with ctrl+c takes copy from text fields as well), and if the app also registered it with self.shortcut(), the item runs and no shortcut event comes, so it does not run twice.

An app opens another window of itself with open from acde:open, like any other app. It needs two things in its config: multiple, so that a second window is allowed, and its own id in the open capability:

{
"id": "notes",
"multiple": true,
"requests": ["edit-note"],
"capabilities": { "open": ["notes"] }
}
import { open } from 'acde:open'
import { window as self } from 'acde:window'
const { window } = await open('notes', { kind: 'edit-note', note: 'todo' })
self.on('request', (request) => {
if (request.kind === 'edit-note') load(request.note)
})
  • The new window runs the same entry; a request tells it what to show. Like any request it needs a kind that the app lists in its own requests; open('notes') with no request opens a plain window.
  • Without multiple, open('notes', …) opens nothing new: it resolves with the window that already runs, and that window gets the request.
  • Without notes in open, the call is rejected with 403 forbidden (Notes may not use open notes (not in its manifest's capabilities)), even though it is the app's own id.
  • Pass { parent: self.id } as the third argument to make the new window a child of this one (see Opening apps).
  • The windows share storage (localStorage, IndexedDB, cookies) but not memory: each is its own page.
API In acdev
window.close() Closes this window
location.reload() Reloads this window
alert() Drawn inside the window; confirm() / prompt() return false / null
External links Handed to the browser app
Downloads Saved to the Downloads folder
Notification Shown by the desktop (a system notification when there is no desktop, except on Windows, where a single app shows none; acde:capabilities reports notifications unsupported there)
visibilitychange The window is hidden / shown
screen.* The screen's logical size

entry can also be a module whose default export is a WindowApp:

import type { WindowApp } from '@dopame/acde-api'
const app: WindowApp = {
mount(element, host) {
host.setTitle('Hello')
element.textContent = 'Hello from a module'
return () => { element.textContent = '' } // unmount
},
}
export default app
  • Each window's JS heap has a limit (heapMb, 256 MB by default). Exceeding it ends only that window.
  • When a single task runs longer than 5 seconds, the desktop is told the window is "not responding" and can end it.