Module Useri.Key

module Key: sig .. end

User keyboard.

These events and signals should only be used for treating keys as actuators. For getting textual input use the support in the Useri.Text module.

For the `Jsoo backend consult the important information about key handling.

Useri_jsoo.Key has important information about key handling in the `Jsoo backend.

Note about the absence of key repeat events.

Key identifiers

type id = [ `Alt of [ `Left | `Right ]
       | `Arrow of [ `Down | `Left | `Right | `Up ]
       | `Backspace
       | `Ctrl of [ `Left | `Right ]
       | `Digit of int
       | `End
       | `Enter
       | `Escape
       | `Function of int
       | `Home
       | `Meta of [ `Left | `Right ]
       | `Page of [ `Down | `Up ]
       | `Return
       | `Shift of [ `Left | `Right ]
       | `Space
       | `Tab
       | `Uchar of int
       | `Unknown of int ]

The type for key identifiers.

A key identifier corresponds to a physical key on a given keyboard. It is not related to the textual character that will be inserted by depressing that key. Use Useri.Text events for getting textual data inserted by a user.

val uchar : char -> [> `Uchar of int ]

uchar c is a key identifier from c.

val pp_id : Format.formatter -> id -> unit

pp_id ppf id prints an unspecified representation of id on ppf.

Key events and signals

Some of the signals below have caveats to consider in very improbable corner cases, see note on semantics.

val any_down : id React.event

any_down occurs whenever a key goes down.

val any_up : id React.event

any_up occurs whenever a key goes up.

val any_holds : bool React.signal

any_holds is true whenever any key is down.

val down : id -> unit React.event

down id occurs whenever the key id goes down.

val up : id -> unit React.event

up id occurs whenever the key id goes up.

val holds : id -> bool React.signal

holds id is true whenever the key id is down.

Key modifiers signals

val alt : bool React.signal

alt is true whenever an alt key is down. Equivalent to:

S.Bool.(holds (`Alt `Left) || holds (`Right `Right))

val ctrl : bool React.signal

ctrl is true whenever a ctrl key is down. Equivalent to:

S.Bool.(holds (`Ctrl `Left) || holds (`Ctrl `Right))

val meta : bool React.signal

meta is true whenever a meta key is down. Equivalent to:

S.Bool.(holds (`Meta `Left) || holds (`Meta `Right))

val shift : bool React.signal

shift is true whenever a shift key is down. Equivalent to:

S.Bool.(holds (`Shift `Left) || holds (`Shift `Right))

Semantic subtleties

If keys are hold by the user during initialisation of Useri, Useri.Key.any_holds and Useri.Key.holds may initially wrongly be false until corresponding keys are released.

Useri.Key.down, Useri.Key.up and Useri.Key.holds may not be accurate the first time they are created inside a React update cycle in which they should occur or update themselves. Note that this is quite unlikely, the only case where this can occur is if these functions are called as a dependency of the Useri.Key.any_* events or signals.

Key repeat events

Useri doesn't expose key repeat events. There are two main use cases for key repeat. First during text input, this is handled by Useri.Text events. Second, for controlling changes to a variable over time (e.g. scrolling with the keyboard). In the latter case it is better to use a function over a Surface.stopwatch signal until the key is up.