.. _developing:

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 :code:`pyproject.toml` files.

Assuming your package architecture looks like this

.. code-block:: text

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

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

.. code-block:: toml

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

The name :code:`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 :code:`jinks_core.widget.register_widget` method must be used

.. code-block:: python

    from jinks_core.widget import register_widget

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

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

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

.. code-block:: python

    @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 :code:`data` method as this is optional and looks as the following:

.. code-block:: python

    @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:

- :code:`device` : un-initialised class of the device
- :code:`display` : un-initialised class of the display
- :code:`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 :code:`jinks.devices` or :code:`jinks.displays` as entrypoints.
And register classes using either :code:`jinks_core.device.register_device`
or :code:`jinks_core.display.register_display`.
And should follow the :code:`jinks_core.device.DeviceProtocol` or
:code:`jinks_core.display.DisplayProtocol` protocols (currently in development)

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