Base Command Properties
An APL command is a message that can change the visual or audio presentation of the content on the screen.
Common Properties
A single command is encoded as a JSON object. All commands contain the following properties.
Property | Type | Default | Description |
---|---|---|---|
|
String |
REQUIRED |
Type of the command |
|
String |
"" |
Optional documentation for this command |
|
Integer |
0 |
Delay time in milliseconds before this command runs. Must be non-negative. Defaults to 0. |
|
Boolean |
|
If true, disable the interaction timer. |
|
String |
"" |
Specify the sequencer that should run this command. |
|
Boolean |
|
Conditional expression. If this evaluates to |
type
Specifies the particular command to run. This may be a pre-defined primitive command types or a user-defined command.
delay
The delay
value is the amount of time in milliseconds inserted before running this command. The delay
value must be a non-negative integer, which if not specified, defaults to 0. The delay
value is ignored if the when
property resolves to false
, or if the command runs from within an event handler.
screenLock
If true, the interaction timer is disabled while this command runs. When a command with screenLock=true
finishes running, the interaction timer is reset to 0.
The screenLock
applies to the entire extent of the command including
any defined delay
. For
example, the following command holds the screen lock for 30 seconds:
{
"type": "Idle",
"delay": 30000,
"screenLock": true,
}
sequencer
If specified, the sequencer
property names the sequencer that this command should run on. The sequencer selection rules are (in order):
- If the sequencer is specified, the command runs in normal mode on that sequencer.
- Else, if the command is running in fast mode, run normally in fast mode
- Else, if the command is a subcommand of a
Sequential
orParallel
command, run in normal mode on the sequencer of theSequential
orParallel
command. - Else, run the command in normal mode on the "MAIN" sequencer.
For details about the command sequencer, see Command sequencing
when
If when
is set to true
, run the command. If false
, ignore the command. Commands that are ignored also ignore the screenLock
property.
Reinflation strategy
The Reinflate command reinflates the document, which by default ends any running commands. You can change this default by defining a sequencer
for the command, and preserving that sequencer
with the preservedSequencers property on the Reinflate
command.
For any command, when the command runs on a preserved sequencer
and the Reinflate
command runs, the remaining delay
for the command is saved.
For example, assume an Idle
command has delay set to 2000 ms and 1000 ms have elapsed when a reinflate occurs. After reinflation, the Idle command continue to run for the remaining 1000 ms specified in delay
.
All commands can have a delay
. Some commands take time to run, such as AutoPage
and SpeakItem
. These commands resume after reinflation when run on a preserved sequencer. Refer to the reinflation strategy section for a command to understand how the command behaves when it is preserved during reinflation.
Related topics
Last updated: frontmatter-missing