Inconsistent captouch/button APIs

There is an issue of two competing APIs for buttonlike elements which interpret the same keywords differently.

The old "pressed" API is still in use in CaptouchPetalState.pressed as documented here: https://docs.flow3r.garden/api/captouch.html

The new "pressed" API is documented in Example 1d here: https://docs.flow3r.garden/badge/programming.html

It is notable that CaptouchPetalState.whole.pressed uses the new API, so it's not distributed over different functional units but rubbing directly against each other.

So what's the difference?

The "pressed" property in the old API reflects whether a captouch element/button direction is currently being pressed. In the new API, "pressed" instead indicates a state change from not being pressed to being pressed. There is no direct equivalent in the new API to the old "pressed", users have to use "but.pressed and but.down and but.repeated" (source code says so, the documentation claims otherwise).

For a consistent user experience we should try to unify these APIs. Since applications that use both exist in the wild already, we should find a solution that does not break them yet avoids ambiguous terms.

Our proposition: Mark both old and new APIs as deprecated (what means do we have for that?) but keep them in the code base. Also deprecate all terms associated with either and create a single unified API from scratch. We propose the following attributes:

.is_pressed : returns true if button/captouch is being pressed equivalent to old API ".pressed"/new API ".pressed || .down || .repeated"

.press_event : returns true when a press just happened, equivalent to new API ".pressed"

.release_event : returns true when a release happened, equivalent to new API ".released"

.pressed_since_ms(): returns time in ms since the button has been pressed. It's a common UX pattern and should be useful here.

We see no need for the new API's "repeated" feature for the scope of the project, and since it allows users to change behavior of the API it just adds the extra complexity of the OS having to reset it on application exit.

We think in order to make app development for users a bunch nicer we should come to a decision here soon.