Module Useri

module Useri: sig .. end

Simple declarative user interaction with React.

Useri gathers user input as React signals and events from a single rendering surface.

Open the module to use it, this defines only modules in your scope.

Note. Before Useri.App.init is called all signals hold invalid data.

Caveat. Do not expect to be able to fully exploit the possibilities and flexibility of the platforms underlying the backends. This library is a simple abstraction library and thus remains limited by design.

Release 0.0.0-72-g9c6670f — Daniel Bünzli <daniel.buenzl i@erratique.ch>

Useri

module Time: sig .. end

Monotonic time.

module Surface: sig .. end

Rendering surface.

module Mouse: sig .. end

User mouse.

module Touch: sig .. end

User touches.

module Key: sig .. end

User keyboard.

module Text: sig .. end

User textual input and clipboard.

module Drop: sig .. end

User drag and drop.

module Human: sig .. end

Human factors.

module App: sig .. end

Application

Minimal example

This minimal example can be used on both synchronous and asynchronous backends.

Integration with cooperative concurency

A good way of managing side-effects at the boundaries of your functional reactive system is to use a cooperative concurency library and convert event occurences and signal changes to yielding futures/threads (to avoid the problem of forbidden recursive primitive feedback) and convert futures/threads to a primitive event with a single occurence.

You will need however need to cooperate with Useri's event loop and give it a high priority as the ability to interact should never take over a long running computation.

The following code shows how to do that with Lwt and Fut

Input, animation and rendering coordination

The Useri.Time and Useri.Surface modules provide support for coordinating input, animation and rendering. We can distinguish two patterns for rendering:

Rendering as an effectful event or signal. This is more likely to be done in simple cases whenever you are not using cooperative concurrency. In this case rendering is simply performed in a React update step simultanous with the Useri.Surface.refresh event, in this step you can sample signals needed for rendering (as long as they do not depend on Useri.Surface.refresh).
Rendering as a task, in more complex rendering scenarios and especially with cooperative concurency. In this case Useri.Surface.refresh occurences simply generate a task that is run outside React's update step, this means that the signals needed for rendering can be safely sampled using React.S.value for rendering data.

In both cases rendering is coordinated by the Useri.Surface.refresh event. It is important to use this event for the following reasons:

It occurs at important times in the life cycle of the application. For example whenever the application surface is first shown to the user or immediately after the application surface Useri.Surface.raster_size changes.
If steady refreshes or timing signals are requested to perform animation it allows them to occur in an energy efficient way, avoiding overdraw. It will also gracefully cope with processing load by dropping animation frames if the rendering system cannot follow.

There are various non-exclusive ways of generating occurences of Useri.Surface.refresh:

Steady refresh. If for a given time span until an event occurs (which may be E.never) you need steady refreshing, use Useri.Surface.steady_refresh.
Animation timing signals. Useri.Surface.refresh occurences are generated immediately after the following signals are created and updated:
- Useri.Time.unit, for animations with a known time span, returns a signal increasing from 0. to 1. during that time span.
- Useri.Time.count, for animations with an unknown time span, returns a signal monotically increasing from 0. to the time until a specified event occurs.
If there are a few events after which you know you need to redraw, E.select them and register the resulting event with Useri.Surface.set_refresher.