specification of "legacy" key events

[Hallvord R. M. Steen]

Below are some attempts at specifying the "DOM0" legacy key events (mainly  
keypress events, also how to determine keyCode/charCode for keydown and  
keyup). I believe it's very important to specify this in DOM3 Events  
because I've seen several problems caused by new web applications trying  
to define keyboard shortcuts and running into incompatibilities in key  
event handling.

I've never really written English specification prose before (though I've  
been an avid reader of W3C TRs) so please give this stuff a critical but  
patient review ;-)

The text below refers to a table of virtual key codes. This is attached in  
OpenOffice spreadsheet format, and can also be viewed here:
http://spreadsheets.google.com/pub?key=p32PJW4aXyuBDbcEUj4dmaw

Rough table of contents is introduction blurb, spec text, notes, todo, and  
references. I hope this is useful.


INTRODUCTION
The specification of key events describes processing of input from  
keyboard devices. Key events rely on hardware support and DOM applications  
should not assume that any specific keys will be available, meaning they  
should be designed so that no information or command can be accessed only  
through generating a key event.

On many operating system, the system will handle character mappings but on  
devices where such mappings are not available an implementation may  
include its own conversion tables and for example decide to send ENTER key  
events with key code 13 if a joystick-type control in a mobile phone UI is  
pressed down.

Key input normally has a default action, e.g. inserting text. The default  
action of a key depends on what sort of element has focus, for example if  
focus is in a TEXTAREA the default action of the ENTER key is to insert a  
line break. If focus is on a link, the default action for ENTER usually is  
to follow the link. What the default action for a certain key is can not  
be determined from an event listener. The default action can be prevented  
by calling the event.preventDefault() method or returning false from an  
event handler, but implementations MAY make this configurable and let the  
user specify either globally or on a per-key basis that event listeners  
are not allowed to override the defaults.

INPUT METHOD EDITORS
Input method editors or IMEs are frequently used to type for example  
Chinese, Japanese and Korean characters. An active IME captures all  
keypresses and processes them to determine what character the user wants  
to insert.

Depending on the IME and its settings, most keys will either initiate,  
contribute to or finish the conversion process. For example, with the  
standard Microsoft Japanese IME active in Hiragana mode, pressing the "K"  
key will start a conversion process. Pressing "U" will contribute to it  
and the IME will show the Hiragana "ku" character. Pressing Enter will  
complete the conversion and insert the character into the document.

In this specification, the expression "input used for IME character  
creation" means input the IME is processing to transform into the actual  
output character(s). The expression "IME character insertion" means the  
insertion that occurs when the IME is done and the user confirms the  
generated characters to insert them into the text.

Note that IMEs can also insert text without any key events occurring at  
all, e.g. with handwriting recognition or on-screen keyboards.

KEY TYPES
Some key types defined by ranges of Microsoft Windows virtual key codes:
        * Alphanumerical keys: all keys with key codes in the ranges 48-57 and  
65-90.
        * function keys: keys with key code in range 112 - 135
        * dead keys: keys that are used to add accents to the next key that is  
typed. One example is an U+00A8 DIARESIS key. On many keyboard layouts,  
dead keys are in the OEM range and their placement and key codes vary by  
keyboard layout. It is not possible to specify virtual key codes for them  
and the implementation must query the system whether the key that was  
pressed was a dead key or not.
        * navigation keys: keys with key code in range 33 - 40 (arrows, Home/End,  
page navigation)

RELATIONSHIP BETWEEN EVENT TYPES

There are two types of key events:
        * Hardware reference events. The keydown and keyup events report that a  
key was pressed down and released. These events include keyboard reference  
information but do not confirm what character(s) if any will be inserted.  
Keyboard reference codes are hardware-, software-, locale- and  
system-dependent, but implementations should map as many keys as possible  
to virtual key codes as defined below.
        * Text insertion events. The keypress and textInput events include  
complete information about the character the input is generating, if any,  
taking into account shift states, previous dead keys and other contextual  
information required to decide what character will be inserted by a key  
press. The textInput event also shows what character(s) were generated by  
an active input method editor. The keypress event MUST NOT fire when an  
IME is processing the input for conversion.

All keys except dead keys fire the hardware reference events. What other  
events are fired depends on the type of key that is pressed and response  
 from the event listeners. Typically, alphanumerical keys and punctuation  
keys fire text insertion events while control keys and navigation keys do  
not. Dead keys may fire text insertion events if pressed twice or followed  
by a space. The first time a dead key is pressed fires no events at all.

KEY CODE CALCULCATION FOR HARDWARE REFERENCE EVENTS
The key code for keydown / keyup events is calculated as follows:
        1. If input is a numerical character (0-9), return the ASCII code of the  
character.
        2. If input is a lower case character (not limited to English a-z),  
return the ASCII code of the upper case equivalent. [TODO#1]
        3. Look up key code in table of Microsoft Windows virtual key codes,  
return it if found. [NOTE#2]
        4. Read virtual key code from system if possible. [TODO#2]
        5. If no key code was found, return 0.

PROCESSING OF KEYPRESS EVENTS

When a key is pressed, and the keydown event has been processed an  
implementation must behave as if it implemented this algorithm when firing  
keypress events:

        * If the keypress follows a keydown event on the same key and the earlier  
keydown event had its default action cancelled, terminate this algorithm.  
[NOTE#1]

        * If the input is key input used for IME character creation, terminate  
this algorithm. [TODO#3]

        * If the key does not cause text input and is not the Escape key (i.e. if  
the key is not is an alphanumerical key, a punctuation key, a repeated  
press of a dead key or the Escape key), terminate this algorithm.

        * Set event meta key properties (shiftKey, ctrlKey, altKey, metaKey)  
depending on what meta keys are pressed, if any

        * For backwards compatibility reasons the character code property has two  
different names. Define charCode and keyCode, set both to the decimal  
value of the unicode reference number of the corresponding character.

        * Fire the event. If it was not cancelled with event.preventDefault()  
proceed to fire a textInput event.

        * If the same keystroke inserts several characters, fire one keypress  
event for each

        * If the key is held down, repeatedly fire one keydown event and one or  
more keypress events at a rate determined by the system's repeat key  
interval setting


NOTE#1: follow Firefox or IE on what to do if keydown's preventDefault()  
was called? Test results:
  * IE, Safari: fire keydown, keyup. No text insertion. (Above text  
standardises this)
  * Firefox: fires keydown, keypress (does not insert text), keyup (and  
apparently web content relies on this)
  * Opera: ignores preventDefault() on keydown, does not insert text if  
preventDefault() is called on keypress

NOTE#2: Microsoft virtual key codes attached as spreadsheet (Open Office  
format). Since step 1 and 2 of this algorithm handle alphanumerical keys,  
this step will mainly deal with punctuation characters. Their placements  
and virtual key codes vary greatly between keyboard layouts on Windows.  
The reason key codes for punctuation characters are so weird in a typical  
MSIE implementation are that they are usually placed on the keys Microsoft  
defines as "OEM keys". These are numbered OEM 1 - OEM 7 (with another  
OEM_102 on some layouts) plus OEM_COMMA, OEM_PERIOD, OEM_PLUS and  
OEM_MINUS.

However, different keyboard layouts change what OEM reference a certain  
key has! So the letter "ø" on a Norwegian keyboard is considered an OEM_3  
key (code 192) but on EN-US layout the very same key is called OEM_1 and  
has code 186. Thus, even striking the *very same* key gives different  
virtual key codes on different keyboard layouts. Neither are those virtual  
key codes mapped to actual input: typing the *very same* character on  
different keyboard layouts can produce different key codes because these  
keys are associated with different "OEM" keys under the hood.

OEM_COMMA, OEM_PERIOD, OEM_PLUS, OEM_MINUS are obviously meant to map to  
the corresponding punctuation on most keyboards, but even this is not  
consistently applied. For example, on a Norwegian keyboard layout the +  
character is on the OEM_PLUS key and returns the virtual key code 187 but  
on the Icelandic layout + is on the OEM_2 key and returns its virtual key  
code 191.

There is no really consistent way to figure out how this should work for  
any OS and device. The assignment of keys to virtual key codes in  
Microsoft's OEM range is too chaotic to emulate, and not useful to  
authors. The way forward would be to specify explicit keyCode/charCode  
values for the following keys that never change with keyboard layouts:
        Backspace
        Tab
        Caps Lock
        Shift
        Control
        Alt
        Enter
And those punctuation characters that are *meant* to not change virtual  
codes between keyboard layouts:
        Period (.)
        Comma (,)
        Plus (+)
        Minus (-)
        Decimal key (on numpad)
        Space
Then leave other punctuation characters implementation dependent and  
inform script authors that they should listen to keypress or textInput  
events to reliably detect those.

TODO#1: note that IE does NOT take the upper-case value of certain  
non-English character (for example ø/Ø on Norwegian keyboards). I believe  
doing so makes the model cleaner and is unlikely to cause compatibility  
problems - this needs investigation though. Here we also probably need to  
specify some specific algorithm for upper/lower-casing characters?

TODO#2: Step 4 of this algorithm is incomplete, probably needs to specify  
how to get a virtual key from system? The issue step 4 is trying to solve  
is: If a given key, say the I key is mapped to something else, say  
"Hiragana I" keydown/keyup will still have the key code of an upper-case I  
in reference implementations but not according to this algorithm without  
some magic in step 4. Hence we need to fall back to reading virtual key  
codes from the system in step 4, but how to do this exactly is  
underspecified and will probably vary between operating systems.

TODO#3: If the IME is NOT in the middle of a conversion, keys that do not  
initiate a conversion in that IME (such as ESC and Enter) *do* fire  
keypress events. Is the text clear enough?

TODO: dead keys pressed twice fire two keypress events. Dead keys followed  
by space fire keydown space, keypress for the dead key's accent, keyup  
space (!). Dead keys are currently a bit underspecified in the above text.


USEFUL LINKS ON WINDOWS KEY HANDLING
http://www.microsoft.com/globaldev/handson/dev/inputinwin.mspx
http://www.woodmann.com/fravia/sources/WINUSER.H
http://tonesnotes.com/blog/2003/03/keycodes_defined_in_winuserh.html
http://www.microsoft.com/globaldev/tools/msklc.mspx

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Alexey Proskuryakov-4]

On Apr 26, 2008, at 6:06 PM, Hallvord R. M. Steen wrote:

> All keys except dead keys fire the hardware reference events. What  
> other events are fired depends on the type of key that is pressed  
> and response from the event listeners. Typically, alphanumerical  
> keys and punctuation keys fire text insertion events while control  
> keys and navigation keys do not. Dead keys may fire text insertion  
> events if pressed twice or followed by a space. The first time a  
> dead key is pressed fires no events at all.


This is strange, in Internet Explorer and Safari (haven't tested other  
browsers), I'm observing a different behavior: pressing a dead key  
does fire keydown/keyup. I was testing with a German keyboard layout,  
pressing a key to the left from "1" (dead key for "^").

I also don't see any reason to avoid having the events fired.

> However, different keyboard layouts change what OEM reference a  
> certain key has!

Ugh! Yes, I agree that this is probably too chaotic to specify or  
emulate.

> When a key is pressed, and the keydown event has been processed an  
> implementation must behave as if it implemented this algorithm when  
> firing keypress events:
>
> * If the keypress follows a keydown event on the same key and the  
> earlier keydown event had its default action cancelled, terminate  
> this algorithm.  [NOTE#1]

I think that this is a logical loop - since there is no keypress event  
in existence yet, it cannot follow a keydown, or be otherwise referred  
to :).

In my mental model, a keypress is a product of keydown default  
handling, and not something directly caused by a physical keystroke.  
It has been mentioned before that default handlers are out of scope  
for DOM Events; not sure how to resolve this. Possibly, the event  
could be specified by itself "in vacuum", and an informal note could  
describe when it actually gets fired?

> TODO: dead keys pressed twice fire two keypress events. Dead keys  
> followed by space fire keydown space, keypress for the dead key's  
> accent


Similarly, this is not necessarily something that the spec should  
formally define - although dead key handling is very similar between  
Mac and Windows (and presumably elsewhere), such details may not  
remain unchanged forever. It's just that the OS-specific default  
handler decides to fire two keypress events in some circumstances, etc.

- WBR, Alexey Proskuryakov

[Olli Pettay]

Hallvord R. M. Steen wrote:
  > RELATIONSHIP BETWEEN EVENT TYPES

>
> There are two types of key events:
> * Hardware reference events. The keydown and keyup events report that a
> key was pressed down and released. These events include keyboard
> reference information but do not confirm what character(s) if any will
> be inserted. Keyboard reference codes are hardware-, software-, locale-
> and system-dependent, but implementations should map as many keys as
> possible to virtual key codes as defined below.
> * Text insertion events. The keypress and textInput events include
> complete information about the character the input is generating, if
> any, taking into account shift states, previous dead keys and other
> contextual information required to decide what character will be
> inserted by a key press.

But does insertion mean anything visible. Or is it more like
"pass a command to the application". So if focus is for example
on <input> and the character is visible, let's say an 'A', the text is
added to the <input>. But if 'ESC' is pressed, keypress is dispatched
but nothing gets updated. Or if 'ESC' is special, what about 'Backspace'?

> The textInput event also shows what
> character(s) were generated by an active input method editor.
textInput should be dispatched also when IME isn't active, right?

> The
> keypress event MUST NOT fire when an IME is processing the input for
> conversion.
Why not? IME could emulate normal keydown/keypress/keyup.


-Olli

[Hallvord R. M. Steen]

On Wed, 07 May 2008 17:13:12 +0200, Olli Pettay <Olli.Pettay@...>  
wrote:

>> There are two types of key events:
>> * Hardware reference events.

>> * Text insertion events. The keypress and textInput events include
>> complete information about the character the input is generating, if
>> any, taking into account shift states, previous dead keys and other
>> contextual information required to decide what character will be
>> inserted by a key press.

> But does insertion mean anything visible. Or is it more like
> "pass a command to the application".

The keypress event fires even if no text is inserted, for example if a web  
page has focus but focus is not in any input field or textarea pressing  
'A' will still fire a keypress event.
Regarding textInput I guess that's up to us to specify. By the name I  
would say it sounds like it should fire only when text is actually  
inserted in some editable element.

> So if focus is for example
> on <input> and the character is visible, let's say an 'A', the text is
> added to the <input>. But if 'ESC' is pressed, keypress is dispatched
> but nothing gets updated. Or if 'ESC' is special, what about 'Backspace'?

ESC is special, I don't know why but it does fire keypress events in all  
legacy UAs I tested. Backspace does too, which in a way makes sense  
because it does cause changes to text being edited.

>> The textInput event also shows what
>> character(s) were generated by an active input method editor.

> textInput should be dispatched also when IME isn't active, right?

Up to us to specify but I'd say yes.

>> The
>> keypress event MUST NOT fire when an IME is processing the input for
>> conversion.

> Why not? IME could emulate normal keydown/keypress/keyup.

For legacy content compatibility. IMEs that process key input do not  
currently cause keypress events to fire, and I believe changing this would  
break legacy content for IME users. (I'm fairly sure this point has been  
raised by implementors and I could try to find the relevant E-mails if you  
need them.)

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Olli Pettay]

Hallvord R. M. Steen wrote:
>> Why not? IME could emulate normal keydown/keypress/keyup.
>
> For legacy content compatibility. IMEs that process key input do not
> currently cause keypress events to fire, and I believe changing this
> would break legacy content for IME users. (I'm fairly sure this point
> has been raised by implementors and I could try to find the relevant
> E-mails if you need them.)
>

Mozilla does dispatch a keypress with IME (at least when testing MS IME
Standard 2002 ver 8.1 / Hiragana) . So if you know some relevant
emails, would be great have the links.

[Hallvord R. M. Steen]

On Thu, 08 May 2008 03:22:08 +0200, Olli Pettay <Olli.Pettay@...>  
wrote:

>>> Why not? IME could emulate normal keydown/keypress/keyup.
>>
>> For legacy content compatibility. IMEs that process key input do not
>> currently cause keypress events to fire, and I believe changing this
>> would break legacy content for IME users. (I'm fairly sure this point
>> has been raised by implementors and I could try to find the relevant
>> E-mails if you need them.)

> Mozilla does dispatch a keypress with IME (at least when testing MS IME
> Standard 2002 ver 8.1 / Hiragana) . So if you know some relevant
> emails, would be great have the links.

Hi,
one E-mail I had in mind was from Oliver Hunt on August 1st 2007 [1],  
where he says:

> * KeyPress and TextInput events are *not* fired if an Input Method has  
> handled the event

but when re-reading the E-mail what Oliver actually said is a bit more  
complex than I managed to capture in the proposed spec.

The most important point is that the keyCode of any keydown and keypress  
event must be 229 if an IME is processing the input. Apart from that there  
is some inconsistency -

Firefox fires keydown and keypress for the *first* character - the one  
that initiates IME processing. Then it fires no keydown/press/up events  
until character conversion is confirmed in the IME (for Japanese IME this  
is done by pressing enter and Firefox fires a keyUp for the enter key).

On the other hand, MSIE fires keydown and keyup events - keydown has code  
229 and keyup has the virtual key code normally associated with the given  
key.

Safari behaves like IE.

Opera seems to fire an initial keydown and no more events - nearly what  
Firefox does but without the keypress.

IMHO, there is no strong use case for firing events while IME is  
processing - AFAIK there is nothing the web app can do about the input  
except confuse itself. Unless someone brings up use cases or content that  
depends on what Safari&IE do I'd suggest we specify something along the  
lines of what Firefox&Opera do. To be specific, a keydown and a keypress  
with codes 229 initally and no events while IME is handling input.  
Inserting the text might cause a keyup for enter (if that IME uses enter  
to confirm input) and must cause a textInput event.

[1] http://lists.w3.org/Archives/Public/public-webapi/2007Aug/0007.html

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Maciej Stachowiak]

On May 8, 2008, at 2:14 AM, Hallvord R. M. Steen wrote:

>
> but when re-reading the E-mail what Oliver actually said is a bit  
> more complex than I managed to capture in the proposed spec.
>
> The most important point is that the keyCode of any keydown and  
> keypress event must be 229 if an IME is processing the input. Apart  
> from that there is some inconsistency -
>
> Firefox fires keydown and keypress for the *first* character - the  
> one that initiates IME processing. Then it fires no keydown/press/up  
> events until character conversion is confirmed in the IME (for  
> Japanese IME this is done by pressing enter and Firefox fires a  
> keyUp for the enter key).
>
> On the other hand, MSIE fires keydown and keyup events - keydown has  
> code 229 and keyup has the virtual key code normally associated with  
> the given key.
>
> Safari behaves like IE.
>
> Opera seems to fire an initial keydown and no more events - nearly  
> what Firefox does but without the keypress.
>
> IMHO, there is no strong use case for firing events while IME is  
> processing - AFAIK there is nothing the web app can do about the  
> input except confuse itself. Unless someone brings up use cases or  
> content that depends on what Safari&IE do I'd suggest we specify  
> something along the lines of what Firefox&Opera do. To be specific,  
> a keydown and a keypress with codes 229 initally and no events while  
> IME is handling input. Inserting the text might cause a keyup for  
> enter (if that IME uses enter to confirm input) and must cause a  
> textInput event.

We have had requests to fire some kind of identifiable event when  
typing occurs during IME processing for use cases like the following:

1) To resize an area based on user typing, even during IME entry (yes,  
this works right, the text is in the text field even when unconfirmed..
2) To have special keyboard shortcuts work in a text field even during  
IME entry.

We originally had the Firefox-like model and deliberately switched to  
the IE-like model to cater to use cases like this and because we  
believe it is more Web compatible.

As such, I would strongly argue for the IE/Safari model instead of the  
Firefox/Opera model.

Regards,
Maciej

[Hallvord R. M. Steen]

On Thu, 08 May 2008 11:41:10 +0200, Maciej Stachowiak <mjs@...>  
wrote:

> We originally had the Firefox-like model and deliberately switched to  
> the IE-like model to cater to use cases like this and because we believe  
> it is more Web compatible.
>  As such, I would strongly argue for the IE/Safari model instead of the  
> Firefox/Opera model.

OK, thanks. Nothing is more convincing than use cases so of course I now  
entirely agree that the spec should follow IE and Safari :)

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Ian Hickson]

On Thu, 8 May 2008, Maciej Stachowiak wrote:
>
> We have had requests to fire some kind of identifiable event when typing
> occurs during IME processing for use cases like the following:
>
> 1) To resize an area based on user typing, even during IME entry (yes, this
> works right, the text is in the text field even when unconfirmed..
> 2) To have special keyboard shortcuts work in a text field even during IME
> entry.

Indeed, we (Google) would very much like our scripts to be notified of
what's going on, keyboard-wise, during IME. In particular when the user is
working with a contentEditable section we really need to have access to
these events so that, for example, we can, if the user so desires, cancel
them and provide our own IME implementation (which might hook into
user-specific information that the UA might not be able to provide).

--
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

[Olli Pettay]

Maciej Stachowiak wrote:
>
> We have had requests to fire some kind of identifiable event when typing
> occurs during IME processing
Firefox does fire events for this
http://lists.w3.org/Archives/Public/public-webapi/2008Apr/0034.html

> As such, I would strongly argue for the IE/Safari model instead of the
> Firefox/Opera model.
>
Firefox and Opera behave quite differently. And Safari dispatches lots
of 'input' events.



-Olli

[Hallvord R. M. Steen]

On Thu, 08 May 2008 12:05:23 +0200, Ian Hickson <ian@...> wrote:

>> We have had requests to fire some kind of identifiable event when typing
>> occurs during IME processing for use cases like the following:
>>
>> 1) To resize an area based on user typing, even during IME entry (yes,  
>> this
>> works right, the text is in the text field even when unconfirmed..
>> 2) To have special keyboard shortcuts work in a text field even during  
>> IME entry.

As I already said, nice use cases and we should accomodate them. I think  
all UAs I tested send keyup events - perhaps that's all we need though?

> Indeed, we (Google) would very much like our scripts to be notified of
> what's going on, keyboard-wise, during IME. In particular when the user  
> is working with a contentEditable section we really need to have access  
> to
> these events so that, for example, we can, if the user so desires, cancel
> them

I think this can not be specified for the legacy key events (keydown,  
keypress) since existing IMEs and browser implementations ignore  
cancelling these events while an IME is processing the input. Firing "some  
kind of identifiable event" might be for example the input events Safari  
is currently firing, it does not have to be keydown and keypress.

> and provide our own IME implementation (which might hook into
> user-specific information that the UA might not be able to provide).

Ian, in general it's unclear to me how you see this working - if I have  
selected a specific IME and input mode to type in some text it's likely  
that this is a VERY conscious choice, and that the IME I'm using has  
learnt what words I'm more likely to want to type. (Pretty much any  
Japanese IME I've used does remember what kanji combinations I've used,  
and mobile phone IMEs are very good at re-ordering kanji options by your  
usage statistics.) I think any sort of script interference with this would  
be *extremely* annoying to me as an end user, and if you want to implement  
input method editors in JS you would be more likely to build this on top  
of an ASCII input mode anyway.

If we do want to go there, I think we should investigate specifying either  
Firefox's composition events or Safari's "input during IME composition"  
events and whether these could be made cancellable. We also need a  
developer who has worked on IME integration to confirm that the UA is  
technically able to "undo" a character that has been sent to the IME (and  
in a clean way please, not sending a backspace char or some hack like  
that!). I'm not sure if this is the case.

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Hallvord R. M. Steen]

On Wed, 14 May 2008 22:17:39 +0200, Hallvord R. M. Steen  
<hallvord@...> wrote:

> I think all UAs I tested send keyup events - perhaps that's all we need  
> though?

(Sorry, ignore that. Only IE does - I should have re-tested before sending  
the E-mail..)

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Bjoern Hoehrmann]

* Hallvord R. M. Steen wrote:
>I've never really written English specification prose before (though I've  
>been an avid reader of W3C TRs) so please give this stuff a critical but  
>patient review ;-)

I don't think it is useful to discuss specification prose if it's
unclear what is to be specified, and what the requirements are. I
am only familiar with how key events function in the Win32 API, I
will just point out some differences. This should be the same as
the differences to Internet Explorer running on Windows since it
essentially just passes the events along as far as I understand it.

> * If the key does not cause text input and is not the Escape key (i.e. if  
>the key is not is an alphanumerical key, a punctuation key, a repeated  
>press of a dead key or the Escape key), terminate this algorithm.

I may be misparsing this, but Escape key occurs twice, and I am not sure
what the text in the parens actually refers to (what is a key that ge-
nerates my name, or a combining character? those do not fall in any of
the items you list, yet they do generate text); I would also suggest to
remove some of the negations here.

> * Set event meta key properties (shiftKey, ctrlKey, altKey, metaKey)  
>depending on what meta keys are pressed, if any

This should not be part of this, or you have to complete it and say,
among other things, to set the .view attribute.

> * For backwards compatibility reasons the character code property has two  
>different names. Define charCode and keyCode, set both to the decimal  
>value of the unicode reference number of the corresponding character.

See below.

> * Fire the event. If it was not cancelled with event.preventDefault()  
>proceed to fire a textInput event.
>
> * If the same keystroke inserts several characters, fire one keypress  
>event for each
>
> * If the key is held down, repeatedly fire one keydown event and one or  
>more keypress events at a rate determined by the system's repeat key  
>interval setting

I think the order here is off, and this is easy to misread. For example,
if the key generates multiple characters, do you send textInput only for
the first character, or one for each character, or one for all chars?

Further, some keys may generate multiple keydown events, for example,
the AltGr key on my keyboard will generate sequences of CTRL and Menu
keydown events; also, you may hold some keys down without any repetition
(e.g., hold a, additionally hold shift, release shift; you are holding
the a key but don't get events for that).

>TODO#1: note that IE does NOT take the upper-case value of certain  
>non-English character (for example ø/Ø on Norwegian keyboards). I believe  
>doing so makes the model cleaner and is unlikely to cause compatibility  
>problems - this needs investigation though. Here we also probably need to  
>specify some specific algorithm for upper/lower-casing characters?

If you use a cyrillic keyboard layout, you may not have any "english"
characters on it, but all the cyrillic keys specify the virtual key
codes in their keyboard events. So a U+0439 key may generate the same
code as a 'q' key. With your proposal, pretty much all the letter keys
would generate different codes. That seems a compatibility issue to me.

Also note that for keypress, Windows, and I would expect other systems
that use a UTF-16 variant internally, you get pairs of events specifying
surrogate codes points, rather than the unicode scalar value for non-BMP
characters.

>TODO#2: Step 4 of this algorithm is incomplete, probably needs to specify  
>how to get a virtual key from system? The issue step 4 is trying to solve  
>is: If a given key, say the I key is mapped to something else, say  
>"Hiragana I" keydown/keyup will still have the key code of an upper-case I  
>in reference implementations but not according to this algorithm without  
>some magic in step 4. Hence we need to fall back to reading virtual key  
>codes from the system in step 4, but how to do this exactly is  
>underspecified and will probably vary between operating systems.

It seems to me, at least in the cyrillic case above, nothing in step 4
can help there, since the algorithm exits at step 2.

>TODO: dead keys pressed twice fire two keypress events. Dead keys followed  
>by space fire keydown space, keypress for the dead key's accent, keyup  
>space (!). Dead keys are currently a bit underspecified in the above text.

Is there anything peculiar about this? `keypress` in Internet Explorer
maps to a WM_CHAR notification, and if you press a dead key twice you'll
generally get two characters, followed by space generates one character,
and the ups and downs follow naturally.
--
Björn Höhrmann · mailto:bjoern@... · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: [phone] · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/ 

[Hallvord R. M. Steen]

On Thu, 15 May 2008 01:56:10 +0200, Bjoern Hoehrmann <derhoermi@...>  
wrote:

> * Hallvord R. M. Steen wrote:
>> I've never really written English specification prose before (though  
>> I've
>> been an avid reader of W3C TRs) so please give this stuff a critical but
>> patient review ;-)
>
> I don't think it is useful to discuss specification prose if it's
> unclear what is to be specified, and what the requirements are.

Hi Björn, thanks for your thorough review - so thorough you even sent  
feedback on the phrasing of the request for comments paragraph.. :)

> I am only familiar with how key events function in the Win32 API, I
> will just point out some differences. This should be the same as
> the differences to Internet Explorer running on Windows since it
> essentially just passes the events along as far as I understand it.
>
>> * If the key does not cause text input and is not the Escape key (i.e.  
>> if
>> the key is not is an alphanumerical key, a punctuation key, a repeated
>> press of a dead key or the Escape key), terminate this algorithm.
>
> I may be misparsing this, but Escape key occurs twice, and I am not sure
> what the text in the parens actually refers to (what is a key that ge-
> nerates my name, or a combining character? those do not fall in any of
> the items you list, yet they do generate text); I would also suggest to
> remove some of the negations here.

Can you help me rephrase it? As you see I'm trying to pin down what key  
input exactly should cause keypress events. I think it makes sense to say  
something to the effect of "input that generates text" or "input that  
would generate text if the target was an editable element" - with an  
exception that also includes Esc because all browsers do that.

(Some browsers send more keypress events than this. Opera and Firefox send  
keypress events for navigation and function keys. I know it causes web  
application bugs for us to do so, if it's not a problem for Firefox I  
guess the reason is browser sniffing. IMO it simplifies things to only  
send keypress for keys that would cause text input and at least for Opera  
this also seems to be more compatible with what web content expects though  
I'm sure we'll also see something break if we make this change..)

>> * Set event meta key properties (shiftKey, ctrlKey, altKey, metaKey)
>> depending on what meta keys are pressed, if any
>
> This should not be part of this, or you have to complete it and say,
> among other things, to set the .view attribute.

OK. We can drop it and focus on the two issues of when to send what  
events, and how keyCode/charCode should be defined.

>> * For backwards compatibility reasons the character code property has  
>> two
>> different names. Define charCode and keyCode, set both to the decimal
>> value of the unicode reference number of the corresponding character.
>
> See below.
>
>> * Fire the event. If it was not cancelled with event.preventDefault()
>> proceed to fire a textInput event.
>>
>> * If the same keystroke inserts several characters, fire one keypress
>> event for each
>>
>> * If the key is held down, repeatedly fire one keydown event and one or
>> more keypress events at a rate determined by the system's repeat key
>> interval setting
>
> I think the order here is off, and this is easy to misread.

If we call those bullets 1, 2 and 3 should we re-order them to be 2,3,1 or  
3,2,1?

> For example,
> if the key generates multiple characters, do you send textInput only for
> the first character, or one for each character, or one for all chars?

I'll leave that to the WG specifying textInput - my main interest here is  
getting the legacy stuff really documented and specified. I've described  
how keypress works for keys that generate multiple characters and the WG  
should specify how textInput should work for this case.

> Further, some keys may generate multiple keydown events, for example,
> the AltGr key on my keyboard will generate sequences of CTRL and Menu
> keydown events;

This indeed happens in Opera and Safari (Win), but not in IE and Firefox..  
If browsers are inconsistent and we can assume no web content relies on  
this can the spec ignore that detail? :-p

> also, you may hold some keys down without any repetition
> (e.g., hold a, additionally hold shift, release shift; you are holding
> the a key but don't get events for that).

Yes, I do. IE, Firefox and Safari generate repeated keydown events, Opera  
repeated keypress events. My spec text should be fixed to say fire  
repeated keydown events if the key does not generate key press events..

>> TODO#1: note that IE does NOT take the upper-case value of certain
>> non-English character (for example ø/Ø on Norwegian keyboards). I  
>> believe
>> doing so makes the model cleaner and is unlikely to cause compatibility
>> problems - this needs investigation though. Here we also probably need  
>> to
>> specify some specific algorithm for upper/lower-casing characters?
>
> If you use a cyrillic keyboard layout, you may not have any "english"
> characters on it, but all the cyrillic keys specify the virtual key
> codes in their keyboard events. So a U+0439 key may generate the same
> code as a 'q' key. With your proposal, pretty much all the letter keys
> would generate different codes. That seems a compatibility issue to me.

Absolutely. TODO#2 was meant to be sort of an open issue on fixing this.

What about something like this for the keydown/keyup keyCode calculation?

1 If system's keyCode is in the range 48-57, use the given value for  
keyCode (0-9 keys)
2 If system's keyCode is in the range 65-90, use given value for keyCode  
(A-Z)
3 If system's keyCode is in the range 97-122, subtract 32 and use the  
result for keyCode (a-z becomes A-Z)
4 If the corresponding character has an upper-case form, use the ASCII  
value of the upper case form
5 Else, use the system supplied keyCode

(Perhaps add a step between 4 and 5 to handle comma, period, plus, minus,  
space and enter and specify what key codes they should have..)

> Also note that for keypress, Windows, and I would expect other systems
> that use a UTF-16 variant internally, you get pairs of events specifying
> surrogate codes points, rather than the unicode scalar value for non-BMP
> characters.

Well, I plead guilty to not having ventured beyond BMP in my testing :-p

>> TODO#2: Step 4 of this algorithm is incomplete, probably needs to  
>> specify
>> how to get a virtual key from system? The issue step 4 is trying to  
>> solve
>> is: If a given key, say the I key is mapped to something else, say
>> "Hiragana I" keydown/keyup will still have the key code of an  
>> upper-case I
>> in reference implementations but not according to this algorithm without
>> some magic in step 4. Hence we need to fall back to reading virtual key
>> codes from the system in step 4, but how to do this exactly is
>> underspecified and will probably vary between operating systems.
>
> It seems to me, at least in the cyrillic case above, nothing in step 4
> can help there, since the algorithm exits at step 2.

Yes, this TODO implies some re-ordering of those steps..

>> TODO: dead keys pressed twice fire two keypress events. Dead keys  
>> followed
>> by space fire keydown space, keypress for the dead key's accent, keyup
>> space (!). Dead keys are currently a bit underspecified in the above  
>> text.
>
> Is there anything peculiar about this? `keypress` in Internet Explorer
> maps to a WM_CHAR notification, and if you press a dead key twice you'll
> generally get two characters, followed by space generates one character,
> and the ups and downs follow naturally.

It just seems a bit convoluted to specify. I understand what's going on  
but I'm not sure how to phrase it..

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Bjoern Hoehrmann]

* Hallvord R. M. Steen wrote:
>>> * If the key does not cause text input and is not the Escape key (i.e.  
>>> if
>>> the key is not is an alphanumerical key, a punctuation key, a repeated
>>> press of a dead key or the Escape key), terminate this algorithm.

>Can you help me rephrase it? As you see I'm trying to pin down what key  
>input exactly should cause keypress events. I think it makes sense to say  
>something to the effect of "input that generates text" or "input that  
>would generate text if the target was an editable element" - with an  
>exception that also includes Esc because all browsers do that.

There are several posibilities, it could be defined in relation to text-
Input, it could be a default action of the keydown event, you could have
some external character input event, similar to an external mouse move-
ment event, which would pretty much amount to saying, it occurs when the
user enters text, and so on. Simply dropping the "i.e." clause would be
a good first step. I note that there need not be keys involved at all,
you might be using a tablet computer and input text via handwriting.

Obviously picking good text here depends on how other issues are handled
like whether preventing the default action of the keydown event prevents
the keypress, hence my point about solving the issues before writing the
specification text.

>> Further, some keys may generate multiple keydown events, for example,
>> the AltGr key on my keyboard will generate sequences of CTRL and Menu
>> keydown events;
>
>This indeed happens in Opera and Safari (Win), but not in IE and Firefox..  
>If browsers are inconsistent and we can assume no web content relies on  
>this can the spec ignore that detail? :-p

This very much happens in Internet Explorer on Windows on my system, but
sure, you can leave undefined whatever you like, so long as you point
out what is undefined. My intent was simply to point out exceptions to
the rules you were giving (without allowing for those exceptions).

>> also, you may hold some keys down without any repetition
>> (e.g., hold a, additionally hold shift, release shift; you are holding
>> the a key but don't get events for that).
>
>Yes, I do. IE, Firefox and Safari generate repeated keydown events, Opera  
>repeated keypress events. My spec text should be fixed to say fire  
>repeated keydown events if the key does not generate key press events..

I think you misread what I said. The point is, if you do the sequence
above, you will be holding a key down, but won't get any events from
Windows, until you press other keys, or release the key you are holding.
Your text required events when a key is pressed down, so the current
behavior of Windows and therefore most browsers would be non-compliant.
--
Björn Höhrmann · mailto:bjoern@... · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: [phone] · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/ 

[Olli Pettay]

Hallvord R. M. Steen wrote:

> RELATIONSHIP BETWEEN EVENT TYPES
>
> There are two types of key events:
> * Hardware reference events. The keydown and keyup events report that a
> key was pressed down and released. These events include keyboard
> reference information but do not confirm what character(s) if any will
> be inserted. Keyboard reference codes are hardware-, software-, locale-
> and system-dependent, but implementations should map as many keys as
> possible to virtual key codes as defined below.
> * Text insertion events. The keypress and textInput events include
> complete information about the character the input is generating, if
> any, taking into account shift states, previous dead keys and other
> contextual information required to decide what character will be
> inserted by a key press. The textInput event also shows what
> character(s) were generated by an active input method editor. The
> keypress event MUST NOT fire when an IME is processing the input for
> conversion.

textInput isn't DOM0 event, right? It is (or will be defined) in DOM 3
Events.

>
> All keys except dead keys fire the hardware reference events.
...
 > The first time a dead key is pressed fires no
> events at all.
Based on testing on Windows Vista, all browsers do generate keydown/up
also with dead keys (at least with ¨ and ´). And pressing space creates
then keydown/keypress/keyup (and input, except not in IE)

On Linux things are different. FF3 fires only keyup (and input event
after space), Opera doesn't fire anything, not even input.

So, I think we should follow the event handling which browsers have on
Windows.

> * If the key does not cause text input and is not the Escape key (i.e.
> if the key is not is an alphanumerical key, a punctuation key, a
> repeated press of a dead key or the Escape key), terminate this algorithm.
Why this behavior? Opera and FF do dispatch keypress in many other cases
too. (And Safari doesn't dispatch with ESC).


-Olli

[Hallvord R. M. Steen]

On Wed, 28 May 2008 16:32:22 +0200, Olli Pettay <Olli.Pettay@...>  
wrote:

>> * Text insertion events. The keypress and textInput events include  
>> complete information about the character the input is generating

> textInput isn't DOM0 event, right? It is (or will be defined) in DOM 3
> Events.

Yes, one of the questions I was trying to get at was how we should define  
relationships between the "legacy" and the DOM3 events. So my proposal is  
to define that keypress fires first and then textInput.

>>  All keys except dead keys fire the hardware reference events.
> ...
>  > The first time a dead key is pressed fires no
>> events at all.
> Based on testing on Windows Vista, all browsers do generate keydown/up  
> also with dead keys (at least with ¨ and ´). And pressing space creates
> then keydown/keypress/keyup (and input, except not in IE)
>
> On Linux things are different. FF3 fires only keyup (and input event  
> after space), Opera doesn't fire anything, not even input.
>
> So, I think we should follow the event handling which browsers have on
> Windows.

OK.

>> * If the key does not cause text input and is not the Escape key (i.e.  
>> if the key is not is an alphanumerical key, a punctuation key, a  
>> repeated press of a dead key or the Escape key), terminate this  
>> algorithm.
> Why this behavior? Opera and FF do dispatch keypress in many other cases  
> too. (And Safari doesn't dispatch with ESC).

This part is basically trying to make sense of and pin down something like  
what IE does, because
a) I thought it makes sense that way
and
b) Opera has had problems and caused web application bugs that as far as I  
remember were tracked down to us firing keypress events the web content  
did not expect.

--
Hallvord R. M. Steen
Core QA JavaScript tester, Opera Software
http://www.opera.com/
Opera - simply the best Internet experience

[Oliver Hunt-2]

On May 28, 2008, at 12:47 PM, Hallvord R. M. Steen wrote:

>
> On Wed, 28 May 2008 16:32:22 +0200, Olli Pettay <Olli.Pettay@...
> > wrote:
>
>>> * Text insertion events. The keypress and textInput events include  
>>> complete information about the character the input is generating
>
>> textInput isn't DOM0 event, right? It is (or will be defined) in  
>> DOM 3
>> Events.
>
> Yes, one of the questions I was trying to get at was how we should  
> define relationships between the "legacy" and the DOM3 events. So my  
> proposal is to define that keypress fires first and then textInput.

You would have to fire textInput after keyPress, that ordering is  
required due to existing API -- you can't find out what the textInput  
info will be until the event has been pushed through the Input Method  
(Editor), which you can't do if the keyPress is cancelled or otherwise  
had its default action prevented.  The ordering must be keyPress-
 >textInput (ignoring the cases where the IM prevents you from seeing  
the keyPress event, and the cases where the IM consumes an event so  
you never fire textInput..)

--Oliver