Conditions
A condition is a small expression that decides whether something is shown. You can attach one to:
- A
contententry, to pick which surface is active. - An
option, to show or hide a control in the panel. - a
choiceinside aselect, to show or hide one dropdown entry.
Conditions are evaluated live. When the inputs change, the result is recomputed and the affected content or controls update.
The context
A condition reads from a context object using $ as the root. Two branches are available:
$.options
The current values of the bundle's options, keyed by option key. For example, $.options.mode is the value of the option whose key is mode.
$.app
The current app state:
| Path | Type | Meaning |
|---|---|---|
$.app.activeProcess | string or null | The foreground app's executable name in lowercase, or null on the desktop. |
$.app.fullscreen | boolean | True when the foreground app is fullscreen. |
$.app.displayId | string | The display the overlay is on. |
$.app.desktop | boolean | True when no application window is visible, that is, only the desktop is showing. |
$.app.desktop is useful for overlays that should only appear on the desktop:
{ "name": "main", "entrypoint": "index.html", "type": "overlay",
"condition": "$.app.desktop == true" }Operators
| Operator | Works on |
|---|---|
==, != | strings, booleans, numbers |
<, >, <=, >= | numbers |
&&, || | combine expressions |
| parentheses | grouping |
A bare boolean value also works on its own, for example $.options.glow.
Examples
Show a surface only in one mode:
"condition": "$.options.mode == 'wave'"Show an option only when a toggle is on:
"condition": "$.options.pro == true"Combine conditions:
"condition": "$.options.mode != 'off' && $.app.fullscreen == true"Numeric comparison:
"condition": "$.options.gain > 0"How each place uses the result
content: the app picks the first entry whose condition is true. If none match, the overlay is hidden.option: when false, the control is not drawn in the panel.choice: when false, that entry is left out of the dropdown.
Reading the same state at runtime
The $.app values mirror what you can read in code through DesktopOverlaysAPI.app (with the sdk.app permission). So you can use a condition to switch surfaces and also read the live app state inside a surface. See the app section of the API reference.