Types¶

The documentation will likely contain typehints to various types used internally in the code. Any types that are relevant when writing a configuration file will be noted here, as well as a couple of hints that may be useful when writing custom functions.

Direct types mean they are an alias for more complex types, like the PSSMdimension indicating DimensionStrings can be used, for example. class types mean they can be configured further.

A quick refresher on how Python types relate to YAML syntax:

dict:
    value1: 1
    value2: hi
list:
    quick_list: [1, 2, 3]
    long_list:
        - 1
        - 2
        - 3
tuple: same as list

For the default values of element properties, you will often see these denoted via {} for a dict, and [] or () for a list.

Shorthand Types¶

These types are used as shorthands to quickly note the use of a certain variable.

ColorType¶: alias of str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]

This type indicates a value expect a valid color. This means it can be anything that inkBoard considers a valid color value, and can thus also be a self defined shorthand, for example.

Denotes durations are accepted. Either a float or integer, which is the direct value in seconds, or a duration string.

PSSMdimension¶: alias of str | int | float

Any kind of acceptable dimension, meaning either an integer or float (which translates directly to the number of pixels), or a dimensional string

PSSMarea¶: alias of tuple[tuple[x, y], tuple[w, h]]

The format in which pssm defines element areas.

PSSMLayout¶: alias of list[list[PSSMdimension | tuple[Element, PSSMdimension]]]

The internal representation of a layout in the base Layout element. Generally not required unless using the Layout element.

PSSMLayoutString¶: alias of LayoutString

Indicates a layoutstring can be used. For example, a tile_layout. See the Tile tutorial.

DurationType¶: alias of duration

Used for properties that describe durations. A DurationType can be passed as a float (i.e. 1.5), int (i.e. 2) or a duration string i.e. (2min). Unless stated otherwise, float and int values are equivalent to the amount of seconds.

RotationValues¶: alias of Literal[‘UR’, ‘CW’, ‘UD’, ‘CCW’]

Type hint for rotation values that can be set via strings. Mainly useful for devices where a screen rotation can be set. Allowed values and their corresponding value in degrees are:

UR : 0°
CW : 90°
UD : 180°
CCW : 270°

BadgeLocationType¶: alias of Literal[‘UR’, ‘LR’, ‘UL’, ‘LL’]

Shorthand values for placing badges. Currently only in use for Icon elements.

UR : Upper Right
LR : Lower Right
UL : Upper Left
LL : Lower Left

Configuration Types¶

These types usually mean an attribute requires some more configuration when used in the YAML configuration, like aditional keys.

class ElementActionType¶

action: ElementActionFunction | str: The function to call. Either a string mapping to a shorthand, or a direct function. Depending on the shorthand action, additional keys may be required.

data: dict[str, Any]: Fixed keyword values to pass to the function

map: dict[str, Any]: Keywords whos value will be passed as the value of the corresponding attribute of the element

The action types in YAML syntax:

my_action:
    action: my-action
    data:
        value: 1

my_shorthand_action: my-action

element_action:
    action: my-action
    data:
        value: 1
    map:
        value_2: attribute

Advanced Types¶

These are types you may not run into directly, especially when just using YAML. However they are useful when writing custom functions or elements and the like.

class ElementActionFunction¶

__call__(element: Element, any: Any, **kwargs) → Any

Type hint for how an element’s action is called.

The element and any parameters are passed as positional arguments.

Parameters:

element (Element) – The element from which the function was called
Any (Any) – Any additional data corresponding to the action. For interaction actions that is an InteractEvent, for others it may be a string.

class InteractEvent¶

This event is passed to functions when dispatched from a screen interaction.

action: str: Type of interaction function that was registered. I.e. ‘tap’, ‘hold’ or ‘hold_release’

x: int: x coordinate of the interaction

y: int: y coordinate of the interaction

Decorators¶

Some decorators are included which can make the creation of custom functions and elements more convenient. They can be imported from PythonScreenStackManager.pssm.util.