standard control¶

The below properties are enabled on the base ZControl class which all other control types descend from. Unless otherwise specified, they behave the same way for all control types.

yaml schema¶

These are options you can set on each control via its yaml definition. Some options will not be available in every context.

type: string
color: string, int, ZColor
includes: list[string]
buttons: dict[ZControl]
gestures: dict[dict]
pad_group: string
vars: dict
repeat: boolean=false
externally_managed_light: boolean=false
template: string, list[string], null
props: dict[any]
threhshold: int=30

type¶

string='standard'

Changing this property from the default standard will create a specialised ZControl. Allowed value is the name of any installed control classes.

color¶

string | int | dict

The base color of the control. See color reference.

string Any named color.

int The MIDI value to send to this control.

dict See color reference,

includes¶

list[string]

Only available on named control group definitions.

See template reference.

pad_group¶

dict[ZControl]

Only available on matrix control group definitions.

See template reference.

controls¶

list[ZControl] | dict[ZControl]

Used in a group control definition to override properties on one or more ZControls in the group. Accepts a list for a group of matrix controls or a dict for a group of named controls.

gestures¶

dict[dict[command]]

See command reference.

vars¶

dict[dict[string]]

See template reference.

repeat¶

boolean=false

Repeatedly trigger this control's pressed gesture (with modifiers) while it is held.

externally_managed_light¶

boolean=false

Suppress most color change events that fire on this control, preventing colors set manually via the API from being overwritten.

template¶

string | list[string] | null

The template(s) to apply to this control. See template reference.

string Apply a single template.

list[string] Apply each template consecutively. Properties that conflict will be overwritten from left to right.

null Apply no template, including the __global__ template.

props¶

dict[string | int]

Any arbitrary data. Can be referenced from within template strings.

threshold¶

int=30

Override the global velocity threshold, which by default is 30. Triggers under this threshold will be ignored.

properties¶

These are values attached to controls that can be referenced from within template strings.

position properties¶

index¶

Returns the zero-indexed position of a matrix control within its containing section. Returns 0 for non-matrix controls, or the control's group_index if it belongs to a group.

Index¶

with a capital I

Returns index + 1.

group_index¶

Returns the zero-indexed position of a control within its containing group.

group_Index¶

with a capital I

Returns group_index + 1.

location properties¶

Only available on matrix controls.

x, x_flip¶

Returns the zero-indexed column of the control (x) or its mirrored position (x_flip), relative to its containing section.

y, y_flip¶

Returns the zero-indexed row of the control (y) or its mirrored position (y_flip), relative to its containing section.

global_x, global_x_flip¶

Returns the zero-indexed column of the control (global_x) or its mirrored position (global_x_flip), relative to the entire matrix.

global_y, global_y_flip¶

Returns the zero-indexed row of the control (global_y) or its mirrored position (global_y_flip), relative to the entire matrix.

velocity properties¶

The following properties are based on the last velocity at which a control was struck. This value will not reset to 0 when the control is released.

vel¶

Returns the last velocity as an integer (between 0-127).

velp¶

Returns the last velocity as a percentage (string).

velps¶

Returns the last velocity as a percentage, but scaled according to the control's threshold.

E.g., if a control has a threshold of 30, a press with a velocity of 30 will return 0%.