Skip to content

Commit

Permalink
rewrite of button definition in progress, added now features
Browse files Browse the repository at this point in the history
  • Loading branch information
@devleaks
devleaks committed Oct 31, 2024
1 parent bb5b7bc commit 9d538ab
Show file tree
Hide file tree
Showing 4 changed files with 124 additions and 24 deletions.
49 changes: 34 additions & 15 deletions docs/Button.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,39 @@ A *button* is the general term for a key, knob, rotary encoder, slider cursor, o

For a given deck, all buttons that are available and/or displayed at a moment in time are on the same *Page*, the collection of buttons currently usable on that deck. Hence, in the definition of a page, there is a mandatory `buttons` attributes that lists all buttons on that page.

In that list, each button is defined by a list of attributes that will determine what it does and how it appears on the deck. The list of attributes that define a button is called a Button Definition.
In that list, each button is defined by a list of attributes that will determine what it does and how it appears on the deck. The list of attributes that define a button is called a *Button Definition*.

# Button Definition

The *Button Definition* is a list of parameters that describe what the button will do when it is manipulated and how it will be represented on the deck if the deck can some how represent the state of that button.

Button definition can be very simple and straightforward, but definitions can also be complex and refined.

Here is an example of a very simple definition of a button to toggle the map display in X-Plane.

```
index: 0
type: push
command: sim/map/toggle_map_display
icon: map
```

The definition of a button is always structured in 4 distinct sections:

1. What the button is (and where it is on the deck)
2. What it does (when the button is pressed on the deck)
3. What it displays (on the deck)
4. Where does it get the value it displays from.

The following sections address these.

![[button-anatomy.png]]

Resulting button:

![[button.png|200]]

The following Sections describe button definition attributes that are common to all buttons, what ever they do and represent.
The following Sections describe the four button definition sections in detail.

The button *Activation* page describes attributes specific to *what a button will trigger or do* when used.

Expand All @@ -24,19 +44,18 @@ The button *Representation* page describes attributes specific to the *feedback*

(In the picture above, this refer to the blue part of the definition.)

| Attribute | Definition |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index` | **Mandatory**. There is no default value.<br><br>Each «Button» on a deck is designated by its [[Button Index]].<br><br>On a given Page, the Index of a button must be unique on that Page since it addresses a very precise key, knob or slider on the deck.<br><br>Depending on the model of deck, buttons have [[Button Index]].<br><br>On a simple deck with a number of similar keys, the index of a button is its ordering number: 0, 1, 2... until the number of keys is reached. On a more complex deck, with button and knobs, knobs may be indexed with name like knob0, knob1, knob2... until the number of knobs is reached.<br> |
| `name` | Optional. A button can be named.<br><br>The name of a button on a page must be unique. If more than one button have the same name, an error is reported and the definition of the button is ignored.<br><br>If no name is provided, a unique, long, technical name is created from deck name, page name, and index. |
| `type` | **Mandatory**.<br><br>The type of a button defines what the button will do and how it will be used.<br><br>The [[Button Activation]] describe button-type specific attributes. In other words, depending on the value of the type attribute, other button defining attributes will be expected.<br><br>For example, if the value of a button type is `page` to change a page on a deck, it is expected to find the attribute named `page` which contains the name of the page to switch to when pressed. |
| `label` | The label of a button is a short reminder of what the button does. The text of the label is laid over the button image if any. The labelling of a button uses the following attributes:<br><br>Note: The Button *Label* should not be confused with Button Text. The Label exist for all buttons, and is displayed according to its attributes if the underlying button is capable. The text of the label is defined as a button attribute and is static (cannot be changed dynamically).<br><br>The Button *Text* is a text that is part of the Button representation. |
| `label-color` | See [[Resources#Colors]]. |
| `label-font` | See [[Resources#Fonts]]. |
| `label-size` | In pixels. Internally, Cockpitdecks uses 256 × 256 pixel images. |
| `label-position` | The position of the label is a 2 letter code:<br><br>1. l, c, or r for left, center, or right-justified on the image (horizontal alignment),<br>2. t, m, or b, for top, middle, or bottom of the image (vertical alignment). |
| `options` | Regularly, buttons have additional parameters.<br><br>The button options parameter is a string of comma separated options. An option is either a simple string or word, or a name=value string.<br><br>Options are, by nature, not indispensable to the button’s activation or rendering but rather add to it to alter behaviour or appearance. |
| `view` | The view attribute is a Command that is executed after the activation. |
| `view-if` | The view-if formula is evaluated before the view is executed. If present, the view will only be executed if view-if evaluates to True. |
| Attribute | Definition |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index` | **Mandatory**. There is no default value.<br><br>Each «Button» on a deck is designated by its [[Button Index]]. So the index designate a very precise button on the deck.<br>On a simple deck with a number of similar keys, the index of a button is its ordering number: 0, 1, 2... until the number of keys is reached. On a more complex deck, with button and knobs, knobs may be indexed with name like knob0, knob1, knob2... |
| `name` | Optional. A button can be named to ease its identification.<br><br>The name of a button on a page must be unique. If more than one button have the same name, an error is reported and the definition of the button is ignored.<br><br>If no name is provided, a unique, long, technical name is created from deck name, page name, and index. |
| `type` | **Mandatory**.<br><br>The type of a button defines what the button will do and how it will be used.<br><br>The [[Button Activation]] describe button-type specific attributes. In other words, depending on the value of the type attribute, other button defining attributes will be expected.<br><br>For example, if the value of a button type is `page` to change a page on a deck, it is expected to find the attribute named `page` which contains the name of the page to switch to when pressed. |
| `label` | The label of a button is a short reminder of what the button does. The text of the label is laid over the button image if any. The labelling of a button uses the following attributes:<br><br>Note: The Button *Label* should not be confused with Button Text. The Label exist for all buttons, and is displayed according to its attributes if the underlying button is capable. The text of the label is defined as a button attribute and is static (cannot be changed dynamically).<br><br>The Button *Text* is a text that is part of the Button representation. |
| `label-color` | See [[Resources#Colors]]. |
| `label-font` | See [[Resources#Fonts]]. |
| `label-size` | In pixels. Internally, Cockpitdecks uses 256 × 256 pixel images. |
| `label-position` | The position of the label is a 2 letter code:<br><br>1. l, c, or r for left, center, or right-justified on the image (horizontal alignment),<br>2. t, m, or b, for top, middle, or bottom of the image (vertical alignment). |
| `options` | Regularly, buttons have additional parameters.<br><br>The button options parameter is a string of comma separated options. An option is either a simple string or word, or a name=value string.<br><br>Options are, by nature, not indispensable to the button’s activation or rendering but rather add to it to alter behaviour or appearance. |
| `view` | The view attribute is an additional optional instruction that is executed *after* the activation. The idea behind it is to first perform the action and then change the simulator view to focus on an area of interest and the activation has completed. |

# Button Value

Expand Down
65 changes: 65 additions & 0 deletions docs/Button/Button Activation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,71 @@ Second, if the activation produces a value, it is written to the `set-dataref` o

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 to 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*.

## Simple Command String

```
command: sim/map/show_current
```

## 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.

## 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*.

# No Activation

`type: none`
Expand Down
Loading

0 comments on commit 9d538ab

Please sign in to comment.