A layout is loaded using the {layout} action, optionally with a #reset# option. When loading a layout, it sets the "custom layout" checkbox and replaces any layout reference previously present in the editor. If there is any issue with the loaded layout, troubleshoot it the same way as when loading it in the editor (see Custom layout troubleshooting).

The #reset# option will reset any script variables that reference objects within the layout. Please see "Resetting layout properties" below.

To work with a layout from a script, you need to understand the basic principles of how script variables are mapped to layout objects and properties.

Each object in a layout has a "key" property that contains the name of the object, e.g., "l_toptext_full_width". If a script variable is created with the same name (@l_toptext_full_width), the layout object can be controlled using that script variable.

The built-in layouts have object names that start with "l_", which makes the corresponding script variables local to that dial. Technically, it's possible to create layout objects for global variables (without the "l_" prefix), but I can't see any real use for it. When creating your custom layout, I recommend using the "l_" prefix to keep script variables local to the dial.

Each property of an object can be referenced in the script using a dotted syntax. For example, to set the "enabled" property for the "l_toptext_full_width" object, use the variable "@l_toptext_full_width.enabled". The same syntax is used to set layout properties as for other variables: {@l_toptext_full_width.enabled:true}.

You can use the "main" variable to set the content (i.e., the "value" property) for an object, e.g., {@l_toptext_full_width:Hello World}. You can use this if the content is the ONLY thing you access for the object; if you also access other properties, I recommend using the direct path to the value property instead: {@l_toptext_full_width.value:Hello World}.

This image shows examples of how script variables are mapped to layout properties.

As shown in the image, the dotted extensions in the variable names correspond to the target layout property name. Additional comments:

• The "key", "type", and "rect" properties define the object and are read-only. They cannot be used in the script.
• The font property has two components: size and weight. These components can be used separately as ".fontsize" {@l_toptext_full_width.fontsize:12} and ".fontweight" {@l_toptext_full_width.fontweight:300}. The full font property can be used as ".font" with two values {@l_toptext_full_width.font:12,300}. 
• The main variable and the ".value" variable both access the same layout property. Avoid using both versions in the same script, as this causes confusion about which variable to use. 

The Elgato SDK documentation describes the available object types and their properties. Four different object types are used: text, pixmap (image), bar (without a triangle indicator), and gbar (with a triangle indicator).

When creating a layout file, it is important to define the data type (string, number or boolean) for each property correctly according to the Elgato specification, but when scripting, this is not the case. The layout controller keeps track of the data types and creates final configuration items that are correct. Examples:

{@l_toptext_full_width.enable:true} => true is handled as a boolean

{@l_toptext_full_width.value:true} => true is handled as a string

Many layout properties have defined data sets that must be used. The "alignment" property for text objects must, for example, be "center", "left", or "right". It is important to use only data that is valid for each layout property.

Color properties can utilize both color names and hexadecimal color values. Hexadecimal color values are typically prefixed with #, such as #A3FF76, but when used in the script, they must be prefixed with double #, that is, ##A3FF76. The double ## indicates to the script engine that these characters signify a color code rather than a mathematical expression. When sending the color code to the Stream Deck software, a single # will be used.

"enabled" controls the visibility of an object. true=visible, false=hidden.

"zOrder" is used to layer items within a layout and must be between 0 and 700. Objects with a higher zOrder will be positioned above those with a lower zOrder. The zOrder can be changed by the script, but be careful not to place two objects on the same level, as this can lead to the layout being rejected if the objects overlap. I recommend always using different zOrder values for each object to prevent such issues.

The "range" property (for bars) is set the same way as described in the Elgato documentation, using a hyphen: {@l_mybar.range:0-100}.

Properties with decimals (such as "opacity") should be expressed using a decimal point, no matter the character typically used in your country.

When preparing a dial screen update, the plugin always configures layout properties based on the settings specified in the editor. Once all plugin settings are finalized, the plugin checks for script layout variables. If any are found, they take precedence over the plugin settings for each property, meaning that script settings always have priority. 

It is important to note that setting a layout script variable is a consistent setting, rather than a one-time action. If you, for example, execute the command

[(press){@l_toptext_full_width.value:Hello World}],

the dial text will change to "Hello World" when you press the dial, and it will remain "Hello World" until it is changed (since the variable will keep its value until it is changed), and the same applies to all properties.

For text objects, the plugin automatically adjusts the font size to fit the text within the available space on a single line. Unfortunately, the Stream Deck software does not support multi-line text objects..

You can override the font size and weight calculated by the plugin in three different ways:

1.  Use the {_variablename_.font:_size_,_weight_} action. The plugin calculation is ignored, and the size and weight defined in the script action are used.
2.  Use the {_variablename_.fontsize:_size_} action. The plugin ignores its own font size calculation and uses the size specified in the script action, while the calculated font weight is applied. The plugin may switch between normal and bold text depending on font and background colors to improve readability. Sometimes, it might be helpful to keep the calculated weight even when you want to set a fixed font size.
3. Use the {_variablename_.fontweight:_weight_} action. The plugin ignores its own font weight calculation and uses the weight specified in the script action, while the calculated font size is applied. This can be helpful if you explicitly want to make text bold (or normal) while still allowing the plugin to determine the appropriate font size. 

If a script layout variable should no longer be used, it can be reset using the #reset# option.

A "reset" means two things: the script variable is deleted (i.e., completely removed, not merely emptied), and the corresponding layout property is reverted to the value defined in the layout file, if there is one. If the layout property is not defined in the layout file, the last set value will remain for the layout property (or the value set by the default plugin calculations, if any).

There are three levels of reset:

1. {@l_toptext_full_width.value:#reset#} Resetting a dotted variable will only reset that variable and its related layout property.
2. {@l_toptext_full_width:#reset#} Resetting a main variable will reset the main variable, all associated dotted variables, and all corresponding layout properties.
3. {layout:_path_,#reset#} Resetting when loading a layout will clear all main variables mapping to objects in the new layout, along with all associated dotted variables. Utilizing reset during the layout loading process ensures it loads initially as defined in the layout file, free from any residual variables from a previous use of the layout.