Description
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 usinganchor_pointandanchored_positionshould 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 (seeanchor_pointdescription above)width: in pixelsheight: in pixelsbounding_box: (x, y, width, height), *getter only
- Touch-related
touch_padding: in pixels, additional space around thebounding_boxthat accept touch input (alternately, modifytouch_boundarydirectly)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’stouch_boundaryselected(touch_point): widget was just touched, reaction to selection will depend upon the widget’s needsstill_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 buttondisplay_label: Boolean, setTrueto display the name of the widgetlabel_font: fontlabel_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_colorsomewhere 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_strokein 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, seeselectedfunction)orientation:horizontalorverticalflip: 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:
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:
