`Control` class: Common response function names

[kmatch98]

With the advent of new widgets such as icon_widget, a clear need has arisen for common function naming schemes for the Control class. The objective is so that the main event handler can use a common approach for calling multiple widgets to respond to various input events.

Of course, widgets aren't required to conform to any pre-defined response functions, but it will likely make it easier to write a Main loop event handler if widgets have the same function naming and a common expected effect.

---

Here's one example. Looking at the PyGUI, it defines responses to four mouse events:

• mouse down
• mouse up
• mouse drag (button is pressed)
• mouse move (button is not pressed)

---

This issue is raised to gather suggestions for the basic response functions to use in the Control class.

Let's discuss a few basic functions that make sense in a touch environment on small microcontroller screens. The objective is not to collect 100% of cases, but to capture the few things that would be most used, and then grow from there.

[jposada202020]

I would add the events from the kivy project.

    on_touch_down()

    on_touch_move()

    on_touch_up()

https://kivy.org/doc/stable/guide/inputs.html. I thinks could be closer to our architecture and purposes

[kmatch98]

I like your set of functions. I agree that we just need a few basic functions.

I recommend we include a placeholder function for “no touch” or “update()”. I found a function like that is necessary if a widget is doing some kind of animation even when it’s not being interacted with. Like an animation of an icon or maybe a graph that needs to update its graphics in the background.

And if a widget doesn’t need one of these methods, it can just default to the superclass’s empty pass function.

[jposada202020]

@kmatch98 are you planning in doing a slider, meaning, a non-discrete switch button? to control PWM, voltage output, and other things like that? I am asking because:

1. it will be a good playground to try some of the above
2. If you are not planning to do it I can take a look.

[kmatch98]

I agree a slider is a great example that will need all those touch options. Go for it!

[jposada202020]

Kmatch, hardware will come at the end of this week, (meaning Touchscreen) So I could work on the actions, howeevr rough prototype

[jposada202020]

By the way I re-use your switch_round :)

[FoamyGuy]

I think we shouldn't use names with the on_ prefix for now. I feel like that prefix implies that the function will get called for you when an event happens. Since we don't support that type of behavior yet I think folks might be confused by these functions if they have experience with languages that use callback functions with similar names.

[jposada202020]

Good point, I am not familiar at all with other languages callbacks so the prefix on_ does not ring any bell, maybe it could be called when_moved, when_touched?
There are other alternatives, in matplotlib, a callback method is added to the class, this way when needed they add a .callback() to the object to trigger a behavior or in tkinter (and this is weird and I do not like it) they add the callbacks as a parameter or a lambda function inside class instance definitions.

[kmatch98]

How about the following:

Functions that send the touch position:

• contains - check if touch is within touch boundary
• touch_down - first time pressed down
• touch_move - still pressed down but moves somewhere else, location could be anywhere (within boundary or outside boundary)
• touch_up - touch was removed

Function with no touch position:

• update - if a widget needs to do some background tasks (maybe continuous animations, or other low priority housekeeping)

[jposada202020]

I like them

[jposada202020]

Moving here some discussion regarding this. Context here is a widget called Slider.

Comments from @kmatch98 regarding is first review, and the way to handle their behavior:

First Review

@jposada202020 This is a really cool. It really responds to the finger pretty fast! Here are my comments. Sorry if it looks like a lot of things, most are minor tweaks, I think the main question is about I expected the slider should respond to touch, and that's open for discussion.

---

graphics: The slider can go outside the background box’s range, if slid all the way to the right side.

touch behavior: The slider does not “center” on the touch point. I have some touch-calibration error on my screen, but I think there is some offset in the code.

touch action: For sliders, I think the touch-response should be as follows:

1. Must first receive a “touch_down” within the touch_boundary.

2. If touch is kept down, any “touch_move” actions will cause the slider to change values, even if the touchpoint is outside of the touch_boundary.

   • (Optional bonus behavior) The farther away the finger is from the slider, the “slower” the reaction. That means, that you can be more accurate if you touch the slider, then move your finger vertically down, and then the slider can be placed more accurately when your finger is farther away. I think this behavior is used on sliders for videos, and I appreciate it if you are trying to adjust the slider precisely. Maybe this could have a “gain” option to adjust the sensitivity based on vertical distance from the slider.

3. When the touch is released from the screen, the slider must be directly touched again to go back to Suggestions based on current status. #1.

Implementation: If you implement the behavior above, I think you will need a state variable to track whether the slider has received a “touch_down” event. To clear the state variable, I think you will need to create a “touch_up” Control function to let the slider know when it is released.

function names: I recommend changing the when_inside command and renaming it to the contains boolean function. Then your while loop can use:

if p:
    if my.slider.contains(p): 
        my_slider.touch_down(p) # let the slider know it has been touched down 
    my_slider.touch_move(p) # handle any touch movements if the slider is still touched down
else: 
    my_slider.touch_up(p) # let the slider know it has been released

Another option is to add a public state variable so you can check the slider's "touch" state. That way you could selectively call touch_move only when the "touch" state is "down". Not sure if that's better or worse than the above code suggestion.

touch boundary: I think that more padding should be available at the “bottom” of the slider than the top. When you touch the slider, you want to still be able to see the slider above your finger. So your finger’s touchpoint will likely be “below” the slider. I think it will be useful to have an option for non-uniform touch_padding. I suggest including some default bottom_touch_padding since that would be expected by the user.

simpletest example: The slider is really small on my pyPortal. Maybe make it a bit larger.

value: I think the value should default to be a float between 0 and 1.0. Or the min/max value could be set during the initialization, similar to what I think is done in the progress bar.

[jposada202020]

Same topic from @kmatch98 regarding the handle of the touch

I'm thinking about the touch-response some more and maybe what I said above needs to be updated. I don't think the simple code that I put above will work right in the case if you have multiple sliders.

We need to handle a situation where one slider receives a "touch_down" and then any other sliders (or other widgets for that matter) should not be triggered with touch events until the slider gets the "touch_up".

I suspect @FoamyGuy has some experience with this. Do you think that the event loop should handle which widget should have the "focus"? For example, once we first touch a slider, we should only send "touch_move" commands to slider, until the next "touch_up" (when finger is released from the screen).

Should this be handled by the event loop, or should each widget need to have the right state variables to understand whether it has focus.

Here's a suggestion:

The main event loop should keep track of the full "touch_down"->"touch_move"->"touch_up" cycle. (This means that the event loop must first send a "touch_down" signal before ever sending a "touch_move" or "touch_up".) The event loop needs to keep track of which "touch_*" state it is in. But it doesn't need to keep track of which widget should have "focus". It will keep sending these signals to all widgets and widgets have to decide if they have "focus".
The widget should keep track if it received a "touch_down" response.
The widget should only respond to "touch_move" or "touch_up" if it already received a "touch_down" response.

This is just a general concept (of course you could develop weird widgets that don't follow this exactly).

Your thoughts are welcome.

[jposada202020]

Comments from @jposada202020

@kmatch98 Interesting.... I did this in a different way in the past... as we are merging MP, I would like to see if we could use some of the new features introduced. Meaning, For me as it is, you would have an event loop, meaning, what you said, the main code will verify, but we add all the widgets to an event loop and all will get updated at the same time, instead have them async.

I agree with you, this discussion is very important, not only for this, but for all the widget development, we need to establish some kind of design rules. Our purpose here will be maintainability, easy of support, easy of maintainability and the most important that for the user will be as easy as to say

if widget.touch:
   ...do something

Proposal lets copy paste this comments to the graphics team, you know I am down for whatever is easier for the user, and it would be easier in the future to add more features.

I am a superfan of the text parameter keywords, because, if matplotlib taught us something is you always want to add more feature, and the enum thing restrict this, at least make it more difficult. But I understand why people like their ENUMS :)

After all this discussion, could you re-post this comments in the graphics team, I could do it, but do not want to do this without your approval

[jposada202020]

Comments from @FoamyGuy

Most of the systems I have experience with use some sort of callback type system for UI related events. I'm wondering if something like that might be possible with the new features from Micropython, but I am not sure.

In the absence of true callbacks. I do think having the logic in some sort of main event loop is probably the best way to go. I think What @TG-Techie has done with TG-Gui is great. Perhaps we should be working toward making our widgets compatible with this system. I'm not 100% how it handles "touch move" type actions, but I'm pretty sure it can, because I think I recall TG-Techie showing a sliding selector widget example on a stream one day.

[jposada202020]

Comments from @jposada202020

That is a good idea. I recall seeing somewhere too, maybe twitter... but yes you are right. I remember he mentions something about the event loop. Regarding the MP depending on what they decide to merge. Anyway as you said, we know now, that what TG does. works so we could build from that.