Picture & Icon¶

The Icon element is one of the most versatile elements, at least in terms of styling options. Badges can be added, as well as a variety of background shapes.

The Picture element is based on the same parent element, but has better support to display images, as it does not resizing to fit icon sizes.

class Icon¶

Creates a small icon element with various options to style it.

Icons can be picked from the mdi icon library via "mdi:icon", or can be set to an image file. Also allows adding an additional icon via a badge. If an image file is supplied, it is automatically converted to the same sizing as mdi icons use, so the icon margins are constant.

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to None

property icon_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | bool: Color of the icon. If a boolean and an mdi icon, the color is set automatically for best contrast. If an image file, a boolean of True will fill the image with the a contrasting color, and if False, will use the original image. Otherwise will use the provided value as color. I would advise against using booleans on screens that are not black and white.

Optional, defaults to "black"

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property background_shape: Literal[None, 'circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED']: The shape of the element’s background. If not set, no shape is used and background color is used as the background color of the entire element of the area. Can be one of [“circle”, “square”, “rounded_square”, “rounded_rectangle”, “octagon”, “hexagon”], None or ADVANCED. See background_shapeDict for usage of advanced (Not fully tested, so be aware) Set to None for no background shape.

Optional, defaults to None

property badge_icon: mdi:icon | None: The current icon of the badge. Must be None, an mdi icon or a PIL image instance.

Optional, defaults to None

property badge_location: Literal['UR', 'LR', 'UL', 'LL']: The location of the badge. Can be Can be one of UR, LR, UL or LL (Upper Right, Lower Right, Upper Left, Lower Left). Also accepts the fully written strings, but will be set to the abbreviated location.

Optional, defaults to None

property badge_offset: int: Badge Offset from the edges of the icon in pixels.

Optional, defaults to 0

property badge_settings: dict: Dict with settings to apply to the badge.

Optional, defaults to {}

property badge_size: float | None: Size of the badge relative to the parent icon. Must be between 0 and 1. If set to a percantage, will be converted to such a value.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property force_aspect: bool: Forces the aspect ratio of the icon to fit.

Optional, defaults to True

property icon: str | Image | None: The element’s icon. Can be set to a str (either an mdi icon or image file), or a PIL image instance directly. If the latter, the image will still be treated as an image file i.e. any icon settings etc. are applied to it regardless (This does also mean you don’t need to worry about sizing, as that is also taken care of). Can also be set to None for no icon.

Optional, defaults to "mdi:sticker-outline"

property invert_icon: bool: Inverts only the icon, not the entier element. This works seperately from isInverted, which inverts an entire element, and is applicable to all elements. invert_icon is only applicable for icons, mainly to provide a way to give images which do not have a solid color (like filled meteocons) more contrast without being confined to a single colored icon.

Optional, defaults to False

property mirrored: bool: Mirrors the icon.

Optional, defaults to False

property shape_settings: dict: Settings for the background shape. Advanced setting, generally best to leave it as an emtpy dict. Stuff may not work as intended as I cannot test everything. Optional arguments are required using ADVANCED, except for icon_coords (icon will default to being centered). The following keys can be used:: method the ImageDraw method to call. Only used if background_shape is "ADVANCED"; icon_size the size of the icon. Accepts dimensional strings; icon_coords the center coordinates of the icon in case of an mdi icon. The upper left corner is used if an image is used as an icon; drawArgs a dict with arguments to pass to the ImageDraw function. Rather advanced method, don’t use it if you don’t know what you’re up to;

Optional, defaults to {}

Compact

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property icon_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | bool: Optional, defaults to "black"

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property background_shape: Literal[None, 'circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED']: Optional, defaults to None

property badge_icon: mdi:icon | None: Optional, defaults to None

property badge_location: Literal['UR', 'LR', 'UL', 'LL']: Optional, defaults to None

property badge_offset: int: Optional, defaults to 0

property badge_settings: dict: Optional, defaults to {}

property badge_size: float | None: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property force_aspect: bool: Optional, defaults to True

property icon: str | Image | None: Optional, defaults to "mdi:sticker-outline"

property invert_icon: bool: Optional, defaults to False

property mirrored: bool: Optional, defaults to False

property shape_settings: dict: Optional, defaults to {}

List

background_color, Optional, defaults to None. Color of the element background.
icon_color, Optional, defaults to "black". Color of the icon.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
background_shape, Optional, defaults to None. The shape of the element’s background.
badge_icon, Optional, defaults to None. The current icon of the badge.
badge_location, Optional, defaults to None. The location of the badge.
badge_offset, Optional, defaults to 0. Badge Offset from the edges of the icon in pixels
badge_settings, Optional, defaults to {}. Dict with settings to apply to the badge
badge_size, Optional, defaults to None. Size of the badge relative to the parent icon.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
force_aspect, Optional, defaults to True. Forces the aspect ratio of the icon to fit.
icon, Optional, defaults to "mdi:sticker-outline". The element’s icon.
invert_icon, Optional, defaults to False. Inverts only the icon, not the entier element.
mirrored, Optional, defaults to False. Mirrors the icon
shape_settings, Optional, defaults to {}. Settings for the background shape.

class Picture¶

Element that can be used to display picture files.

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property picture: str | Path | Image: Required. The file or Image object use as the picture. By default searched the folder that is set as the custom picture folder for the picture file.

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property background_shape: Literal[None, 'circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED']: The shape of the element’s background. If not set, no shape is used and background color is used as the background color of the entire element of the area. Can be one of [“circle”, “square”, “rounded_square”, “rounded_rectangle”, “octagon”, “hexagon”], None or ADVANCED. See background_shapeDict for usage of advanced (Not fully tested, so be aware) Set to None for no background shape.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property fit_method: Literal['contain', 'cover', 'fit', 'pad', 'resize', 'crop']: The way to fit the picture to the element area. Cover and Contain are the base methods, and will always work (i.e. won’t break no matter what is set in fit_method_arguments) All other functions do work without setting the fit_method_arguments, but can break when setting options for that. When using crop, the image will be resized to the alloted area if it is not the correct size If the image still does not happen to be the correct size, it will be forcibly fitted.

Optional, defaults to "fit"

property fit_method_arguments: dict: Arguments to apply to the fitting method. For resize, see https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.resize For crop, see https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.crop For the other methods, see https://pillow.readthedocs.io/en/stable/reference/ImageOps.html.

Optional, defaults to {}

property mirrored: bool: Mirrors the element.

Optional, defaults to False

property shape_settings: dict: Settings for the background shape. Advanced setting, generally best to leave it as an emtpy dict. Stuff may not work as intended as I cannot test everything. Optional arguments are required using ADVANCED, except for icon_coords (icon will default to being centered).

Optional, defaults to {}

Compact

property picture: str | Path | Image: Required

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property background_shape: Literal[None, 'circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED']: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property fit_method: Literal['contain', 'cover', 'fit', 'pad', 'resize', 'crop']: Optional, defaults to "fit"

property fit_method_arguments: dict: Optional, defaults to {}

property mirrored: bool: Optional, defaults to False

property shape_settings: dict: Optional, defaults to {}

List

picture, Required. The file or Image object use as the picture.
background_color, Optional, defaults to None. Color of the element background.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
background_shape, Optional, defaults to None. The shape of the element’s background.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
fit_method, Optional, defaults to "fit". The way to fit the picture to the element area.
fit_method_arguments, Optional, defaults to {}. Arguments to apply to the fitting method.
mirrored, Optional, defaults to False. Mirrors the element
shape_settings, Optional, defaults to {}. Settings for the background shape.