8000 Draft proposal of standard parameters and functions for DisplayIO Widgets · Issue #3 · adafruit/Adafruit_CircuitPython_DisplayIO_Layout · GitHub
[go: up one dir, main page]

Skip to content
Draft proposal of standard parameters and functions for DisplayIO Widgets #3
Closed
@kmatch98

Description

@kmatch98

The DisplayIO_Layout library will rely on having several standard parameters for any "widgets" so this function can place them in the desired layout. Additionally, for any touch-related objects, it is useful to have standard response functions.

The starting point for this proposal was the Adafruit_CircuitPython_Display_Text library with the label item along with the Adafruit_CircuitPython_Display_Button library with the button item.

I'd especially like proposals on the standardized "Response functions" for widgets.


Proposed widget parameters and naming:

  • Position and sizing
    • x, y : upper left corner of the widget, in display pixel coordinates (see diagram)
    • anchor_point : (a, b) two values between 0 and 1. Widget placement using anchor_point and anchored_position should operate the same as display_text.Label (see candy hearts example: https://learn.adafruit.com/circuit-python-tft-gizmo-candy-hearts/how-it-works)
    • anchored_position : (C,D) in pixels (see anchor_point description above)
    • width : in pixels
    • height : in pixels
    • bounding_box : (x, y, width, height), *getter only
  • Touch-related
    • touch_padding : in pixels, additional space around the bounding_box that accept touch input (alternately, modify touch_boundary directly)
    • touch_boundary : (x, y, width, height) region that will accept touch input
  • Response functions and data
    • contains(touch_point) : responds True if touch-point is within the widget’s touch_boundary
    • selected(touch_point) : widget was just touched, reaction to selection will depend upon the widget’s needs
    • still_touched(touch_point) : widget remains touched (***?)
    • released(touch_point) : widget is released (***?)
    • value : type will depend upon the widget (getter/setter required)
  • Widget naming (*** Should each widget have a label that can be optionally displayed and positioned?)
    • label : text label to describe the button
    • display_label : Boolean, set True to display the name of the widget
    • label_font : font
    • label_anchor_point_on_widget : proposed (*need to add description and diagram)
    • label_anchor_point_on_label : proposed (*need to add description and diagram)
  • Optional parameters and naming recommendations:
    • _color : use as many parameters as needed for fill and outline colors for the widget structures, prefer to include _color somewhere in the parameter name. Should accommodate hex 0xFFFFFF 8-bit RGB color codes, but prefer to also support tuples (R, G, B).
    • _stroke : this is the width in pixels of outline features. Use as many as needed, prefer to include _stroke in the parameter name.
    • animation_time : in seconds, the time required for the widget’s animation. For example, for a switch, the time allotted for switching from off to on and vise versa. Preferably, the widget will check the elapsed animation time and redraw accordingly, so that the response time is the approximately the same even when run on different processors and systems. (see example in switch_round_horizontal.py, see selected function)
    • orientation : horizontal or vertical
    • flip : Boolean, default is False. Set True if mirror image is desired.

Coordinate scheme

Here is a graphic with a proposal of some of the naming of the pixel coordinate schemes:
image

Draft code snippet: Switch widget

Here is a code snippet of the __init__ function for a draft of a switch widget that runs on the Adafruit PyPortal:

class SwitchRoundHorizontal(displayio.Group):

    def __init__(
        self,
        *,
        x=0, # Placement of upper left corner pixel position on the display
        y=0,
        width=None, # defaults to the 4*radius
        height=30,
        name="",
        value=False,
        touch_padding=0,
        anchor_point=None,
        anchored_position=None,
        fill_color_off=(66, 44, 66),
        fill_color_on=(0,100,0),
        outline_color_off=(30,30,30),
        outline_color_on=(0,60,0),
        background_color_off=(255,255,255),
        background_color_on=(0,60,0),
        background_outline_color_off=None, # default to background_color_off
        background_outline_color_on=None, # default to background_color_on
        switch_stroke=2,
        text_stroke=None, # default to switch_stroke
        display_button_text=True,
        animation_time=0.2, # animation duration (in seconds)
        ):

        super().__init__(x=x, y=y, max_size=3)

Widget positioning

As described above, the widget position on the screen can be defined directly by widget.x and widget.y or by the combination of widget.anchor_point and widget.anchored_position.
Here is a reference image for the usage of anchor_point and anchored_position as snipped from the Adafruit Learn guide's Candy Hearts Example:
HELLO

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      0