Launch Options

When the app launches content, it provides the read-only DesktopEngine.launchOptions before index.js runs:

const options = DesktopEngine.launchOptions || {};
options.windowType;   // 'widget' (on the desktop) or 'overlay' (above windows), for new DesktopEngine.Window({ type })
options.width;        // the widget's width in points, for the size picked
options.height;
options.position;     // { x, y }: where the user last dragged it, or the default position the app worked out
options.display;      // { id, name, frame, visibleFrame, scale }
options.displays;     // every display instead, when a wallpaper spans them, see Wallpapers
options.parameters;   // the values of the options
options.locale;       // the user's preferred language, e.g. 'en-US'
options.permissions;  // the permissions the user allowed, e.g. ['audio', 'network']; denied ones aren't there
options.screenSaver;  // { preview } when running as the screen saver, absent otherwise

Coordinates are the ones of DesktopEngine.Window styles: the origin at the top left of the main display, y pointing down. See LaunchOptions for all the fields.

• parameters are the values of the options, see When options change.
• See Permissions for permissions, Spanning all displays for displays and Screen saver for screenSaver.
• While developing, desktopengine dev --size / --level / --display / --span / --param / --position stand in for them, see Command Line.

When options change

When the user changes an option, the app restarts the content with the new values. Listen to parameterschange of DesktopEngine.system and it keeps running instead: apply the new values yourself, keeping everything else as it is, such as the time left on a timer or where a pet is walking.

const system = DesktopEngine.system;
let accent = DesktopEngine.launchOptions.parameters?.accent ?? '#0A84FF';
system.onparameterschange = (event) => {
  accent = event.parameters.accent ?? '#0A84FF';
  draw();
};

• Set the listener when the content starts: the app looks for one each time the user changes an option.
• event.parameters has every value, event.changed the keys that changed; DesktopEngine.launchOptions.parameters has the new values too.
• Dragging a slider fires it several times a second: redraw right away, but leave heavy work, such as rebuilding a scene, until the values stop changing.

Talking to the app

win.onmove = (payload) => postMessage('host', { type: 'move', x: payload.x, y: payload.y });
postMessage('host', { type: 'close' }); // removes itself from the desktop

The app remembers the position move reports and passes it back in options.position next time.

Appearance

DesktopEngine.system.appearance is the system's current appearance, 'light' or 'dark'. appearancechange fires when the user switches it in System Settings (or Auto switches it by the time of day):

const system = DesktopEngine.system;
let dark = system.appearance === 'dark';
system.onappearancechange = (event) => {
  dark = event.appearance === 'dark';
  draw();
};

An Appearance option should offer auto (following the system) as its default, see the widget and wallpaper templates. Wallpapers draw every frame anyway: read appearance each frame and fade to its colors, no event needed.