Web UI Widgets

This module contains all the predefined user interface widget (shc.web.WebPageItem) classes, which can be instantiated and added to WebPage s in order to compose the web user interface.

In addition, there are descriptor classes, like the button classes (e.g. ToggleButton) and the ImageMapLabel. Instances of these classes are used to create an interactive element within another widget. They cannot be added to a ui page directly, but must be added to a compatible container element (like ButtonGroup or ImageMap) instead. Still, they form the endpoint for the dynamic interaction and thus are Connectable objects.

Please note that each widget or button instance must not be used multiple times (neither on the same nor on different pages). To create two or more similar and synchronized widgets/buttons, create two instances with the same settings and connect both of them to the same shc.Variable.

Helper Functions

class shc.web.widgets.icon(icon_name: str, label: str = '')

Create HTML markup for a Fontawesome/Semantic UI icon, to be used in PageItem labels, button labels, etc.

Parameters:

icon_name – Name of the icon. See https://fomantic-ui.com/elements/icon.html for reference.
label – Optional textual label to be placed along with the icon. The styling of the icon is slightly changed, when label is non-empty to optimize the spacing between icon an text.

Returns:

(safe) HTML markup to be passed to a Jinja template (of a web page or web widget), e.g. via one of the label attributes.

Switches and Buttons

class shc.web.widgets.Switch(label: Union[str, Markup], color: str = '', confirm_message: str = '', confirm_values: Iterable[bool] = (False, True))

A WebPageItem showing a label and a right-aligned toggle switch.

This widget is a Connectable object with type bool. It should be connected to a Readable object for initialization, e.g. a shc.Variable of bool type.

Parameters:

label – The label to be displayed near the switch. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – Background color of the switch, when in ‘on’ position. The available colors are the same as for buttons. See https://fomantic-ui.com/elements/button.html#colored for reference.
confirm_message – If provided, the user is asked for confirmation of each interaction with the switch with this message and “OK” and “Cancel” buttons. confirm_values may be used to restrict the confirmation to switching on or switching off.
confirm_values – If confirm_message is given, this parameter specifies, which changes of the switch must be confirmed by the user. When set to [True], only switching on (sending True) must be confirmed, when set to [False], only switching off must be confirmed. Defaults to [False, True], i.e. every change must be confirmed.

class shc.web.widgets.ButtonGroup(label: Union[str, Markup], buttons: Iterable[AbstractButton])

A ui widget consisting of one or more (right-aligned) buttons with a label.

The appearance (color, label, etc.) and possible interactions of each individual button is specified by a button descriptor (any subclass of AbstractButton) for each button. These button descriptors form the SHC-side interface to the buttons to connect them with other Connectable objects. The ButtonGroup itself is not Connectable.

Parameters:

label – The label to be shown left of the buttons
buttons – List of button descriptors

class shc.web.widgets.ToggleButton(label: Union[str, Markup] = '', color: str = 'blue', confirm_message: str = '', confirm_values: Iterable[bool] = (False, True), outline: bool = False)

Button descriptor for an on/off button.

Click such a button once to turn it ‘on’, click it again to turn it ‘off’. The button is lit up (fully colored), when in ‘on’ state (the connected object’s value is True) and shown in the grey-ish default color, when in ‘off’ state (unless outline==True). When clicked in ‘on’ state, a False value is published and vice versa.

A ToggleButton is a Connectable object with type bool´. It should be connected to a `Readable object for initialization of the ui – otherwise it will show a spinner animation until the first True/False value is received.

Parameters:

label – The label/text content of the button. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – The color of the button when in ‘on’ state. Must be one of the Semantic UI button colors. See https://fomantic-ui.com/elements/button.html#colored for reference. Defaults to ‘blue’.
confirm_message – If provided, the user is asked for confirmation of each interaction with the button with this message and “OK” and “Cancel” buttons. confirm_values may be used to restrict the confirmation to switching on or switching off.
confirm_values – If confirm_message is given, this parameter specifies, which changes of the button must be confirmed by the user. When set to [True], only switching on (sending True, i.e. clicking in ‘off’ state) must be confirmed; when set to [False], only switching off must be confirmed. Defaults to [False, True], i.e. every click must be confirmed.
outline – If True, the button is shown with a colored outline in its configured color in ‘off’ state, instead of its grey-ish default appearance.

class shc.web.widgets.ValueButton(value: T, label: Union[str, Markup] = '', color: str = 'blue', confirm_message: str = '', outline: bool = False)

Button descriptor for a button with a fixed value.

This button publishes a fixed value upon every click, just like the StatelessButton. Unlike a StatelessButton, it is dynamically lit up (shown in full color) when the current value of the connected object matches the fixed value of the button.

The type of this Connectable object is determined from the value. The ValueButton should be connected to a Readable object for initialization of the ui.

For creating multiple ValueButtons with different values for the same variable, take a look a the ValueListButtonGroup widget.

Parameters:

value – The value to be published by this object when the button is clicked by the user. Also the value which is compared to the connected object’s current value to determine if the button should be lit up.
label – The label/text content of the button. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – The color of the button when it is lit up (i.e. conncted object’s current value matches the value). Must be one of the Semantic UI button colors. See https://fomantic-ui.com/elements/button.html#colored for reference. Defaults to ‘blue’.
confirm_message – If not empty, the user must confirm each click on the button in a confirm windows with this message.
outline – If True, the button is shown with a colored outline in its configured color when not lit up, instead of its grey-ish default appearance.

class shc.web.widgets.StatelessButton(value: T, label: Union[str, Markup] = '', color: str = '', confirm_message: str = '', outline: bool = False)

Button descriptor for a stateless button, i.e. a button that has no visual on/off state and always sends the same value, when clicked.

StatelessButtons are Subscribable, but not Writable. The type is the type of their value.

Parameters:

value – The value to be published by this object when the button is clicked by the user
label – The label/text content of the button. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – The color of the button. One of the Semantic UI button colors. See https://fomantic-ui.com/elements/button.html#colored for reference. If not specified, the button is shown in the grey-ish default color. Since the button has no on/off state, the specified color is always shown.
confirm_message – If not empty, the user must confirm each click on the button in a confirm windows with this message.
outline – If True, the button is not shown fully colored, but only with its outline (Semantic UI basic button). Since the button has no on/off state, this holds all the time.

class shc.web.widgets.DisplayButton(value: T = True, label: Union[str, Markup] = '', color: str = 'blue', outline: bool = False)

Button descriptor for a read-only (non-clickable) button.

A DisplayButton behaves similar to a ValueButton: It has a preconfigured fixed value and is lit up (displayed in full color) when the connected object’s value equals this fixed value. However the DisplayButton is not clickable. It is a pure display widget, which does not provide user interaction. This, on the SHC-side it is not Subscribable.

The type of this Connectable object is determined from the value. The DisplayButton should be connected to a Readable object for initialization of the ui.

Parameters:

value – The value which is compared to the connected object’s current value to determine if the button should be lit up. Defaults to True, resulting in a behaviour of a disabled ToggleButton.
label – The label/text content of the button. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – The color of the button when in ‘on’ state. Must be one of the Semantic UI button colors. See https://fomantic-ui.com/elements/button.html#colored for reference. Defaults to ‘blue’.
outline – If True, the button is shown with a colored outline in its configured color when not lit up, instead of its grey-ish default appearance.

Dropdowns and Input Fields

class shc.web.widgets.Select(options: List[Tuple[T, Union[str, Markup]]], label: str = '')

A dropdown (HTML <select>) ui widget with label.

This widget is a generic Connectable object. The type is determined by the values’ type. It should be connected to a Readable object for initialization.

Parameters:

options – List of options in the dropdown. Each option is a tuple of (value, label). All values must be of the same type. Each label can either be a plain string or a markupsafe.Markup with pre-formatted HTML, e.g. from the icon() function. Since Semantic UI’s JavaScript-based <select>-replacement is used, even complex HTML should be rendered properly.
label – The label to be displayed near the dropdown. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().

class shc.web.widgets.EnumSelect(type_: Type[Enum], label: Union[str, Markup] = '')

Specialized version of Select for choosing between the entries of a given enum type by their name.

Parameters:

type – The enum type. It is used as the type attribute for connecting and to generate the dropdown entries from its enum members.
label – The label to be displayed near the dropdown. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().

class shc.web.widgets.TextDisplay(type_: Type[T], format: Union[str, Markup, Callable[[T], Union[str, Markup]]], label: Union[str, Markup])

A ui widget which simply displays the value of the connected Connectable object as text.

This widget is a generic Connectable object. The type is specified by the type_ parameter. The TextInput should be connected to a Readable object for initialization. In contrast to interactive widgets, it does only consume, but not produce values, so it’s not Subscribable.

The formatting of the value can be controlled via the format_string parameter, which is used with Python 3’s str.format() method. To show the value with default formatting, use the ‘{}’ format. Other format specifiers may be used, e.g. to specify the floating point accuracy:

TextDisplay(float, '{:.2f}', "Current value of my_float").connect(my_float_variable)

The format string may, of course, contain additional characters outside the format specifier to prepend and/or append static strings to the dynamically formatted value. See https://docs.python.org/3/library/string.html#formatstrings for a full reference of valid format strings.

Parameters:

type – The expected value type, used as the type attribute of this Connectable
format – Either a Python string or safely escpaed HTML markup, which is used to format the value into a string representation using the format() method or otherwise a callable which transforms a value to a string or escaped HTML Markup (in form of a markupsafe.Markup object).
label – A label to be displayed left of the formatted value. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().

class shc.web.widgets.TextInput(type_: Type[Ti], label: Union[str, Markup] = '', min: Optional[Ti] = None, max: Optional[Ti] = None, step: Optional[Ti] = None, input_suffix: Union[str, Markup] = '')

An input field ui widget for numbers and strings with label.

This widget is a generic Connectable object. The type is specified by the type_ parameter. The TextInput should be connected to a Readable object for initialization.

Parameters:

type – The value type to be entered. Used as the type for connecting with other Connectables and to determine the HTML input type. Must be int, float or str.
label – The label to be displayed near the input. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
min – The minimal value to be entered (only useful if type_ is int or float). Used as the HTML min attribute.
max – The maximal value to be entered (only useful if type_ is int or float). Used as the HTML max attribute.
step – The default increment step when using the arrow buttons or arrow keys in the input field (only useful if type_ is int or float). Used as the HTML step attribute.
input_suffix – A plain string or HTML markup to be appended to the right of the input field, using Semantic UI’s labeled inputs.

Slider

class shc.web.widgets.Slider(label: Union[str, Markup] = '', color: str = '', left_button: Optional[AbstractButton] = None, right_button: Optional[AbstractButton] = None)

A visual slider ui widget, labeled with a scale from 0%-100% to set range values.

This widget is a generic Connectable object with type shc.datatypes.RangeFloat1. It should be connected to a Readable object for initialization. Using the convert parameter of the connect() method, a Slider can be connected to Connectable objects of other default range types, like shc.datatypes.RangeUInt8.

Parameters:

label – The label to be displayed above the slider (left). Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – Background color of the slider and the upper right label showing the current value. Must be one of Semantic UI’s predefined slider colors: https://fomantic-ui.com/modules/slider.html#colored
left_button – An optional button descriptor to attach a button to the left end of the slider. All different kinds of buttons and all layout features of AbstractButton are supported.
right_button – An optional button descriptor to attach a button to the right end of the slider (can be used independently from left_button). All different kinds of buttons and all layout features of AbstractButton are supported.

class shc.web.widgets.MinMaxButtonSlider(label: Union[str, Markup] = '', color: str = '')

A pre-configured version of Slider with left_button and right_button for quick access to 0% and 100%

This object is a ConnectableWrapper that includes the Slider object as well as the two button descriptor objects. When connecting to it, using the connect() method, it will connect all three objects with the given other object.

The buttons are configured to be highlighted in the same color as the slider. They use the circle outline and (filled) circle icons as label.

Parameters:

label – The label to be displayed left above the slider. Either a plain string (which is automatically escaped for embedding in HTML) or a markupsafe.Markup object, which may contain pre-formattet HTML, e.g. produced by icon().
color – Background color of the slider, the upper right label showing the current value and the two buttons (when hightlighted). Must be one of Semantic UI’s predefined slider colors: https://fomantic-ui.com/modules/slider.html#colored

HideRows

class shc.web.widgets.HideRowBox(rows: List[HideRow])

A container for a list of HideRows

The HideRowBox is a WebPageItem, so it can be added to web pages, and takes a list of HideRow which are dynamically shown or hidden.

class shc.web.widgets.HideRow(label: Union[str, Markup], button: Optional[AbstractButton] = None, color: str = 'blue')

A colorful box that is dynamically shown or hidden inside a HideRowBox, based on a bool condition.

The HideRow is a Connectable widget of value type bool that is dynamically displayed when the connected object’s value is True and is hidden otherwise. It can be used as a kind of indicator: Create a HideRowBox with a HideRow for each light in your home and connect them to the respective Variables. Then, the HideRowBox will dynamically show a list of all turned-on lights at any time, because the HideRows of all turned-off lights are hidden. Similiarly, you can use it to indicate a list of different errors.

Each HideRow can be configured with an individual label (including icons) and an individual color.

In addition, it can take an optional button descriptor, which defines a button to be displayed on the right side of the HideRow, whenever it is visible. The button can be connected to any custom function. Typically, it will be a StatelessButton to turn off the light or acknowledge the error report.

Parameters:

label – The (static) label displayed in the HideRow
button – If not None: A button descriptor, describing (and connecting to) a button, displayed on the right side of the HideRow when displayed.
color – The background color of the HideRow when displayed. Must be one Fomantic UI’s color names

ColorChooser

class shc.web.widgets.ColorChoser

An interactive color chooser widget in the HSV color space for selecting 24bit RGB colors (RGBUInt8).

The ColorChooser widget uses the iro.js JavaScript library for displaying an interactive color chooser widget. It is updated dynamically from connected objects and allows the user to select a color, which is published by the ColorChoser object in SHC.

ImageMap

class shc.web.widgets.ImageMap(image: Union[PathLike, str], items: Iterable[Union[Tuple[float, float, Union[AbstractButton, ImageMapLabel]], Tuple[float, float, Union[AbstractButton, ImageMapLabel], List[WebPageItem]]]], max_width: Optional[int] = None)

A widget showing placeable buttons and labels on a background image.

The ImageMap allows to place dynamic and interactive items on a custom background image. The items are placed statically at a relative x and y coordinate of the image (in percent of the image width/height). The relative coordinates ensure a stable position of the items relative to the image, even when the image is automatically scaled to fit different screen sizes. Typically, the ImageMap widget is used to show smart home devices as interactive buttons at their respective location on a ground plan of the apartment.

The available items are:

buttons, definable via any of the button descriptors, described above (The styling of the buttons is slightly different from buttons in button groups, but the customization options work equivalently.)
text labels with dynamic text, defined via ImageMapLabel

Every item can carry an individual pop-up menu that is displayed, when the item is clicked. The pop-up menu can contain any number and any kind of web page widgets. A typical use case is showing the basic on/off state of a device as a DisplayButton on the ImageMap and providing fine-grained controls for the device in the pop-up menu, as demonstrated in the following example:

web_page.add_item(
    ImageMap(
        Path("background.png"),
        [
            # A simple ToggleButton for displaying/switching the ceiling lights
            (0.51, 0.665, ToggleButton(icon('lightbulb'), color='yellow', outline=True)
                          .connect(ceiling_lights)),
            # A DisplayButton with pop-up menu for controlling the stereo
            (
                0.375, 0.08,
                DisplayButton(label=icon('volume up'), color='blue', outline=True)
                    .connect(stereo_power),
                [
                    Switch("Power", color="blue").connect(stereo_power),
                    Slider("Volume", color='blue').connect(stereo_input_select),
                    EnumSelect(StereoInputOptions, "Select Input").connect(stereo_input_select),
                ]),
        ]
    ))

Currently, there are no invisible items (to create interactive “regions” on the background image) or user-definable interactive graphics.

Parameters:

image – The background image. Either a local path (preferably as a pathlib.Path object) or a URL. If a local path is given, we let the web server serve it as a static file. If an absolute URL (including the schema, like ‘https://’) is given, it will simply be used as the image source URL of the background image.
items –
The list of items to be positioned on the ImageMap. Each list element is a tuple (x, y, item) or (x, y, item, [pop_up_items]), where
- x and y are the relative coordinates on the background image in the range 0.0 (left/top edge) to 1.0 (right/bottom edge)
- item is the item descriptor, i.e. a ImageMapLabel or AbstractButton object
- (optional) [pop_up_items] is a list of web widgets to be displayed in the pop-up menu
max_width – If given and not None, defines the maximum width of the background image on large screens in pixels.

class shc.web.widgets.ImageMapLabel(type_: Type[T], format_string: str = '{}', color: str = '')