Developing¶

Widgets¶

Developers can create their own widgets with their own packages. This section aims at explaining how to do this. This guide assumes that you already know how to create a python package for pip using pyproject.toml files.

Assuming your package architecture looks like this

widget_package
├── pyproject.toml
├── src
│   └── widget_package
│       ├── __init__.py
│       └── my_widgets.py
└── test
        ...

First you need to provide the my_widgets module to the jinks.widgets entry-point

[project.entry-points."jinks.widgets"]
my_widgets_ep = "widget_package.my_widgets"

The name my_widgets_ep doesn’t matter at all as this is only for jinks to load the module.

To register one or several widgets, the jinks_core.widget.register_widget method must be used

from jinks_core.widget import register_widget

@register_widget(name="my_widget")
class my_widget:
     ...

The register_widget can be called several times in the same module.

A widget class must specifically adhere to the jinks_core.widget.WidgetProtocol protocol. Which includes the following

@register_widget(name="my_widget")
class my_widget:
    width: int
    """Width in terms of display units (not pixels)."""
    height: int
    """Height in terms of display units (not pixels)."""

    color: ColorType
    """Color type of the widget."""

    def display(...) -> Image.Image:
        ...

The protocol does not include the data method as this is optional and looks as the following:

@register_widget(name="my_widget")
class my_widget:
    def data(...) -> Any:
        ...

For the display and data methods, jinks provides the following arguments if requested in their inputs. Do not use these names for other inputs.

data:

device : un-initialised class of the device
display : un-initialised class of the display
density : the unit_density of a display (pixels in a unit x and y directions are identical)

display: same as data but with

Devices and Displays¶

Registering devices and displays is done exactly in the same way as widgets only with different entry-points and registering methods. Simply use jinks.devices or jinks.displays as entrypoints. And register classes using either jinks_core.device.register_device or jinks_core.display.register_display. And should follow the jinks_core.device.DeviceProtocol or jinks_core.display.DisplayProtocol protocols (currently in development)

At the __init__ of the display, jinks will give the initialised class of the device for it to talk to the hardware.