In the definition of the button, the type attribute determine what the button will do.

For a given button on a deck, the action that the button will be able to carry over is limited to a set of valid types. A push button is not capable of rotations of an encoder.

On the other hand, a button that can be pressed can offer different types of usage: simple press, long, continuous press, emulation of rotation switch… all this can be activated from a button with a simple press capability.

When interaction occurs on a button on a deck, Cockpitdecks creates a typed Event, and passes it for activation.

Each activation is designed to handle one or more Events types. For example a EncoderPush activation is capable of handling both PressEvent and EncoderEvent. What is does with those event is left to the activation.

This file list all activations that are currently available in Cockpitdecks. For each activation, we present its name or keyword by which it must be referred to, the attributes it expects to work properly, the type of events it expects, and internal state values it produces and maintains.

Activation Steps

Each activation always goes through 3 steps.

First, the event is handled completely. Most of the time, the root class of activations is activated first, for global handling and checks. Then the activation itself is performed. The activation returns a boolean flag to indicate that it completed successfully.

Second, if the activation produces a value, it is written to the set-dataref of the button, if any. This operation can be considered like an second instruction that is performed provided that the button instructed to write the value to the dataref pointed by set-dataref.

Third, and finally, if the button activation contains a view command, it is executed. The purpose of the view command if to alter the view in the cockpit, may be to focus on a particular area of the dashboard to control the effect of the activation.

Command, Commands, and «Macro Instruction»

When specifying attributes for an activation command and commands attributes can be requested. A command is a single command, commands is a list of individual commands, often, the number of commands in the list matters and match the Activation requirements.

A command can be:

a single string naming the command to execute, or
a single command block, with a condition and or a delay, or
a Macro Instruction, that can contain one or more command blocks.

Single Command String

    command: sim/map/show_current

Command to Change Variable

    set-dataref: AirbusFBW/DUBrightness[0]

While it does not appear as a command, the above instruction is actually a command to set the value pointed by the set-dataref variable to the value of the button.

Single Command Block

A Command Block is a series of attributes that specify a command to execute and some optional behavior.

	command:
	  - set-dataref: sim/value/to/set
	    condition: ${sim/position/altitude} 5000 >
	    delay: 5

The group of attributes set-dataref, condition, delay is a command block. It is one instruction (set-dataref), a condition to satisfy before executing the instruction, and a delay to wait after the condition is satisfied before executing the command.

The condition is evaluated each time one of its parameter changes.

Command Block Attributes

Command

There are currently two attributes that can be used to specify a command to execute:

command
set-dataref

Either one can be used but not both. (If both are specified, a warning is issued and the command is ignored.)

Condition

A condition is a formula that specify, when evaluated, if the command can be executed. The condition is evaluated each time one of its constituting simulator value changes.

Delay

The delay is a value in seconds that specifies how long after the command receives its instruction to execute it actually perform the task. This allows to pause between commands rather than submitting them all simultaneously to the target. The delay starts when the previous command is submitted for execution.

Multiple Command Blocks: Macro Instruction

    command:
      - command: AirbusFBW/MCDU1Menu
      - command: AirbusFBW/MCDU1LSK6L
        delay: 1
      - command: AirbusFBW/MCDU1LSK6R
        delay: 1
      - command: AirbusFBW/MCDU1LSK1R
        delay: 1

In the above example, the single command consists of a series of 4 command blocks. In this case, the single command is called a Macro Instruction.

Since delay starts after the previous command is started, the command AirbusFBW/MCDU1LSK1R will be executed 1 second after AirbusFBW/MCDU1LSK6R command is started, 3 seconds after command AirbusFBW/MCDU1Menu is started.

No Activation

type: none

Button with no activation are button used for display purpose only.

Events

Any event can be handed over to the No Activation, since it will not be used.

State Values

State Variable	Value
`activation_count`	Number of time button was activated
`last_activated`	Time stamp of last activation
`initial_value`	Initial value in configuration (if any)
`current_value`	Button current value
`previous_value`	Button previous value before change
`guarded`	Whether button has a guard on top of it
`managed`	Whether button has managed mode (specific to some cockpits, which means there are alternate display values)

Activation Value

Among the above State Value that an Activation returns, there always is a special state value named the activation value. The activation value can be accessed by requesting the activation_value attribute in the state values.

This value is just a value among the existing state values that gets highlighted because it is the most sensible value used by the activation.

For exemple, the activation value for the On/Off activation is the current state of the activation, either On or Off.

In the following descriptions, the activation value is highlighted for each activation.

For No Activation activation, the activation value is equal to the activation count. This is also the "default" activation value, if nothing more precise is returned, the activation value is the number of activation of that button.

The activation value comes to play when the button needs to determine its value. It first look for a formula, then a single dataref, and if there is no formula and no single dataref, the activation value is used.

Page

type: page

When the button is pressed, a deck will load a page of buttons.

Attributes

Attribute	Definition
`page`	Mandatory. Name of the page to load. The page must be in the Layout of the target deck.
`remote_deck`	Optional. If present, will load the page on the target deck.

Events

PushEvent and PressEvent can trigger the Page activation.

State Values

Attribute	Definition
`page`	page that is currently displayed

Theme

type: theme

When the button is pressed, the main theme will be changed.

Attributes

Attribute	Definition
`theme`	Mandatory. Name of theme.

Events

PushEvent and PressEvent can trigger the Page activation.

Push

type: push

Push button.

Attributes

Attribute	Definition
`command`	Mandatory. X-Plane command that is executed each time the button is pressed.

Note

Command is a mandatory parameter but if no command is necessary a command placeholder value can be used. Command placeholder value are any of the following string:
none, noop, no-operation, no-command, do-nothing
They all are ignored and do not trigger any activity in X-Plane.

Events

PushEvent. Please note that PushEvent consists of 2 distinct events, a pressed event (PushEvent with pressed = True), and a release event (PushEvent with pressed = False), when the button is pressed or released respectively.

Options

Option	Definition
`auto-repeat`	Auto repeat command at specified pace while the button remains pressed. `auto-repeat` option accepts a couple of optional values: - `delay`: Time (in second) after which the auto-repeat starts, default to 1 second. - `speed`: Time (in second) between 2 executions of the command.

	options: auto-repeat=3/0.5,dot

Auto-repeat will start 3 second after the button was pressed, the command will auto-repeat every 0.5 seconds, twice per second. (dot option also set for other purpose.)

BeginEndPress

type: begin-end-command

Push button that will carry the command as long as the button will remain pressed.

Long press command should not be confused with auto-repeat commands. A BeginEndPress command in one command that is executed once as long as the button remain pressed. An auto-repeat command is the same command that is executed several times at regular interval (typically once every 0.2 seconds, 5 times per second) as long as the button is pressed.

Note

The BeginEndPress command requires installation of a XPPYthon3 plugin in X-Plane to circumvent a few X-Plane UDP limitations.

Events

PushEvent

Only PushEvent can be used to trigger BeginEndPress Activation since both press and release events are necessary to estimate the timing between both events.

Attributes

Attribute	Definition
`command`	Mandatory. X-Plane command that is executed each time the button is pressed.

X-Plane will issue a beginCommand when the button is pressed and a endCommand when released.

Note

Please note that the use of longpress command needs the addition of a little plugin to circumvent X-Plane UDP limitations when used through UDP.

OnOff

type: onoff

Push button.

Events

PushEvent, PressEvent, LongPressEvent

Attributes

Attribute	Definition
`commands`	Optional pair of X-Plane commands that are executed alternatively. Two commands must be supplied, but the same command can be provided twice.
`set-dataref`	Optional dataref to set On(=1) or Off (=0). Either attribute can be set or both. In the latter case, the command is first executed and then the dataref is set.

State Values

Attribute	Definition
`on`	current state On or Off

Activation Value

The activation value for On/Off activation is the current status, either On or Off.

UpDown

type: updown

Cycle Up and Down button.

Attributes

Attribute	Definition
`commands`	X-Plane commands that are executed when pushes increase value, and when pushes descrease value.
`stops=3`	Number of stop values. For example: Stops=3 will give 0-1-2-1-0 cycles, with 3 stops 0, 1, and 2.
`initial-value`	If an initial value is supplied, it's sign indicated how the value will evolve. For example, if the initial value is 1, the next value will be 2 (go up). If the initial value is -1, the initial value will be set to 1, but the next value will be zero (go down).
`set-dataref`	Optional dataref to set the value of the current stop. Very much like On/Off activation either `commands` or `set-dataref` can be supplied or both.

The number of supplied commands may vary.

If no command is supplied, it is assumed that there is a set-dataref instruction. In this case, the activation runs inside the [0, #stops[ interval and writes the current value to the dataref.

If two commands are supplied, they are assumed to be commands to go up and go down when cycling between the values.

If the number of commands is equal to the number of stops, and if there are more than 3 stops, then the activation runs inside the [0, #stops[ interval and executes the command corresponding to the current value.

Activation Value

The activation value for UpDown activation is the current value.

State Values

Attribute	Definition
`stops`	Number of stops
`go_up`	True will increase at next push; False will decrease
`stop`	Current value

ShortOrLongpress

Short or long press has two commands, one that is executed when the button is pressed for less than long-time seconds, and one when it is pressed more than long-time seconds.

type: short-or-longpress

Attributes

Attribute	Definition
`commands`	Two commands, the first one is called on short press.
`long-time`	Time to press the button to activate second command. Default to 2 seconds.

Encoder

Type: encoder

An Encoder is a rotating knob or dial with steps. Steps are often materialised by a little sound or a slight resistance in the rotation.

Attributes

Attribute	Definition
`commands`	An Encoder has two commands, one that is executed for each step while turning clockwise, and one for each step when turning counter-clockwise.

State Values

State	Definition
`rotation_clockwise`	number of times/clicks the encoder was turned clockwise.
`rotation_counterclockwise`	same.

Activation Value

The activation value for Encoder activation is the current rotation value, i.e. number of rotation clockwise minus number of rotation counter-clockwise, negative values means there are more counter clockwise turns.

EncoderPush

type: encoder-push

An EncoderPush is the combination of an Encoder and a push button.

Attributes

Attribute	Definition
`commands`	An EncoderPush has 3 commands: 1. First command gets executed when it is pushed 2. Second command gets executed when encoder is turned clockwise 3. Third command gets executed when encoder is turned counterclockwise

State Values

State	Definition
`turns`	Number of turns, positive is clockwise
`cw`	number of times/clicks the encoder was turned clockwise.
`ccw`	same, counter clockwise.

Activation Value

Same as Encoder activation.

EncoderOnOff

type: encoder-push

An EncoderOnOff is the combination of an Encoder and an OnOff button.

Attributes

Attribute	Definition
`commands`	An EncoderPush has 4 commands: 1. First command gets executed when it is OFF, to turn it ON 2. Second command gets executed when it is ON, to turn it OFF 3. Third command gets executed when encoder is turned clockwise 4. Fourth command gets executed when encoder is turned counterclockwise

Options

Attribute Definition

dual With option dual, the activation uses two more commands.

1. First command gets executed when it is OFF, to turn it ON
2. Second command gets executed when it is ON, to turn it OFF
3. Third command gets executed when encoder is turned clockwise and ON
4. Fourth command gets executed when encoder is turned counterclockwise and ON
5. Third command gets executed when encoder is turned clockwise and OFF
6. Fourth command gets executed when encoder is turned counterclockwise and OFF.

State Values

State	Definition
`cw`	number of times/clicks the encoder was turned clockwise.
`ccw`	same.
`on`	Is currently On or Off

Activation Value

Same as Encoder activation.

EncoderLongPush

A combination of pushing and turning.

Attributes

Attribute	Definition
`commands`	An EncoderLongPush has 4 commands: 1. First command gets executed when encoder is turned clockwise 2. Second command gets executed when encoder is turned counterclockwise 3. Third command gets executed when encoder is first pushed, then turned clockwise 4. Fourth command gets executed when encoder is first pushed, then turned counterclockwise

State Values

State	Definition
`cw`	number of times/clicks the encoder was turned clockwise.
`ccw`	same.

Activation Value

Same as Encoder activation.

EncoderValue

type: encoder-push

An EncoderValue is an Encoder that increases or decrease an internal value each time it is rotated clockwise or counterclockwise. The value can be written to an X-Plane dataref or used for other pruposes.

Attributes

Attribute	Definition
`initial-value`	Initial value. Default to 0.
`step`	Amount of value increase or decrease.
`stepxl`	Alternate value for step increase or decrease. If the encoder is capable of push action, the push action will switch between the `step` and `stepxl` values.
`min`	Minimal value.
`max`	Maximal value.
`formula`	Optional. Formula to transform the `${state:button-value}` before it is sent to the dataref.
`set-dataref`	Optional dataref to set to the value of the computed value. The value is sent right away, after each encoder activation.

State Values

State	Definition
`cw`	number of times/clicks the encoder was turned clockwise.
`ccw`	same.
`value`	Current raw value

Activation Value

The activation value of the EncoderValue activation is the computed value of the encoder.

Slider

type: slider

A Slider is a one dimensional cursor that produces a continuous value within a range. The value can be written to an X-Plane dataref, directly, or after a computation.

Attributes

Attribute	Definition
`set-dataref`	Optional. Dataref to write the value to, if present.
`formula`	Optional. Formula to transform the `${state:button-value}` (value produced by the slider) before it is sent to the dataref.

State Values

State	Definition
`value`	Current raw value

Activation Value

The activation value of the Slider activation is the value of the slider.

Swipe

type: swipe

A Swipe is a 2 dimensional movement of a finger on a surface. The event produced consists of the start and end positions of the finger relative to the surface (x, y) and timing information (time stamp).

(Currently not used.)

The Swipe event has no attribute.

State Values

The event of a swipe is complex. The entire event is available as last_event.

The event has the following structure:

ts_start: 123.456
ts_end: 135.246
pos_start: (23, 48)
pos_end: (78, 42)

State Values

State	Definition
`start_x`	Start of swipe position laterally
`start_y`	Start of swipe position vertically
`start_ts`	Timestamp of start of swipe, in microseconds
`end_x`	End of swipe position laterally
`end_y`	End of swipe position vertically
`end_ts`	Timestamp of end of swipe, in microseconds

From the above values, with some tolerence, it is possible to determine whether the finger moved on the surface or not (swipe or touch), and to determine the duration of the contact with the surface.

Button Activations for Developers

Reload, Stop, or Inspect are special activations for developer.

These activations are normally not used during regular operations.

New Activations

It always is possible to create new activations by extending Cockpitdecks.