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.
Size and title bar
Section titled “Size and title bar”- 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 devsession that runs a single app (an app project without--desktop), the app fills the host window, andsizesets 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. Withoutsizethe host window takes most of the screen (90% of its width and 85% of its height, at most 1440 × 900). acdev dev --headlesshas no host window, andsizeis not applied: the screen is 1440 × 900 (1280 × 800 inacdev test) and the app fills it, so the page is 1440 × 868. To see the app in a window of its ownsize, run it in a desktop:acdev dev --desktop ./my-desktop, or--desktop dopameonce that desktop is installed (see acdev dev).- The title bar drawn by the system is not part of the page's document:
innerHeight,100vh, andresizeevents only cover the content area. To drop the title bar, set"frame": falsein the config, draw your own, and usesetGrabHintto tell the system where the window can be dragged. - The title comes from
document.titleorwindow.setTitle(), whichever was set last (a<title>in the page replaces a title set before the document loaded); if neither is set,labelis used. - Declare the colour schemes your page supports, as in a browser:
color-scheme: light darkon the root (:root { color-scheme: light dark }) or<meta name="color-scheme" content="light dark">when it follows the system withprefers-color-scheme,darkwhen it is always dark. The system draws a dark title bar only for pages that namedark; a page that declares nothing is taken as light only and gets a light title bar even in a dark theme. Thehtmltemplate follows the system and declareslight dark. An app run on its own (anacdev devof the app,acdev test) gets a dark title bar while the page is dark: a page that names onlydarkalways, a page that nameslight darkwhileprefers-color-schemeisdark(the system's scheme, oremulate({ colorScheme })in a test). As in browsers, the root'scolor-schemecounts before the meta: an app with its own light / dark switch setscolor-scheme: darkorlighton the root, and the title bar follows it.
acde:window
Section titled “acde:window”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 globalwindow, 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 |
Window state
Section titled “Window state”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. Afixedwindow can only be minimized, and apinnedone cannot change state. A window whoseminimizableisfalsecannot be minimized:requestState('minimized')changes nothing, andminimize()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
stateevent (orself.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 devsession the app already fills the host window, and state requests may change nothing (headless on macOS,minimized,filledandfullscreenall leave the statenormal, and no event arrives). Try states in a desktop session. - The standard Fullscreen API (
element.requestFullscreen()) is not supported; it rejects withNotSupportedError.
Events
Section titled “Events”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 devof 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 itsonSelect. An item withoutonSelectis shown disabled.acdev inspectlists the menus first (menuitem "File" [collapsed] [w1.m1], and the items of the open one,w1.m1.2),acdev act w1.m1.2 clickopens the menu and chooses the item, and in a testgetByRole('menuitem', { name: 'New' })finds them. With"frame": falsethere 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.
A second window of your app
Section titled “A second window of your app”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 akindthat the app lists in its ownrequests;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
notesinopen, the call is rejected with 403forbidden(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.
Browser APIs
Section titled “Browser APIs”| 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 |
Module entry
Section titled “Module entry”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 appMemory and hangs
Section titled “Memory and hangs”- 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.