To run unit tests:
$ cd noVNC/tests
$ npm install mocha
$ npm install chai
<open keyboard-tests.html in a browser>
To manually test:
<open keytest.html in a browser>
Design overview:
The big complex browser-dependent keyboard input events are replaced by custom
objects containing only the data we put there. These objects always have a
'keyId' property, which is mainly used to compare events, to determine if
they represent the same key (in order to match keydown/keypress/keyup
events for the same key together), and do not have a 'keysym' property
until we know that the specified keysym should be sent to the VNC server.
(In other words, even if we know which keysym a keypress represents, a
'keysym' property is not added to the object until we also know that the
keysym should be sent as-is to the VNC server.
Modifiers are divided into two groups: char modifiers and shortcut
modifiers. The latter never have an effect in themselves, but an
application may react to them to implement keyboard shortcuts (CTRL-C for
example). The former *may* be used to transform the character they are
combined with, and in those cases, the modifier press itself should not be
sent to the VNC server. For example, AltGr on European keyboards can be
combined with many, but not all, keys, to produce different characters.
The new keyboard handling is effectively a pipeline where each stage
performs a single well-defined transformation to clean up the input and
eliminate browser quirks. It can easily be extended with new stages, but
currently consists of the following:
1. KeyEventDecoder: takes the raw keydown/keyup/keypress event sent by the
browser, and converts it to our custom event wrapper, adding some hints
for later stages. If we get a keydown event, and we can't rely on getting
a subsequent keypress with more accurate information, we also try to
determine the keysym here. Also uses a ModifierSync object to keep track
of the state of modifier keys, and insert fake events to compensate when
the browser forgets to generate modifier key events.
2. VerifyCharModifier: When a char modifier is combined with another key,
we need to know if this creates a new keypress (for example AltGr + 2 on a
DK keyboard yields @), or if it has no effect. This stage handles this by
"stalling" the pipeline in cases where this is uncertain, giving us time
to see if a keypress event is coming.
3. TrackKeyState: since some browsers forget to send keyup events, we need
to keep track of which keys are currently down. This also means we need to
"collapse" keydown and keypress events into one: only one of them should
result in an event sent to the VNC server.
4. EscapeModifiers: when a char modifier is used to generate a character
(say, AltGr creating a @), we need to "undo" the modifier itself while
sending the character - the VNC server should see the sequence
keyup(AltGr), keydown(@), keydown(AltGr), keyup(@).
the commenting!
Jesper Dam