Round 2, Input in SDL 1.3

SDL Development
1

?
Round 2

Ok, the following is what I think we have decided and some open
questions.

Text Input Event

This event returns the fully modified text generated by a sequence of
characters. This is how you get the input from an IME or get control x
from the keyboard.

SDLKey

SDLKey is an unsigned 32 bit integer. Its values come from two distinct
sets. It can either hold a Unicode code point or a value from the
SDLPhysicalKey enumeration. Values in the enumeration are distinguished
from Unicode code points by a single “magic”.

The name and location of the magic bit have not been determined, but I
would suggest SDL_KEY_BIT and I would suggest putting it in bit 30. Bit
30 is better than bit 31 because of sign extension in left shifts and
the possibility of making the value negative even though it is an
unsigned value.

When returned by an SDL function the Unicode code point is always the
unmodified character on the key. That means the effect of num lock,
shift lock, shift, ctrl, alt, super, and any other modifier keys are
ignored.

Key Press/Release Event

Within the limits of what is possible and practical this event returns
the SDLPhysicalKey value that is closest to the actual location of the
key on the keyboard (as defined by USB HID usage tables, version 1.12
http://www.usb.org/developers/devclass_docs/Hut1_12.pdf, section “10
Keyboard/Keypad Page (0x07)”. This information is meant to provide
positional information, not the key name on any particular keyboard.

The only open question is what to do with the Unicode field of the
event. Should we return the Unicode code point when it is available? If
so, these would be unmodified values that are compatible with the
definition of SDLKey given above.

SDL_GetLayoutKey()

Given an SDLKey value from a key press/release event this function
converts it to either an unmodified Unicode code point representing the
label of the key or it returns a member of the SDLPhysicalKey
enumeration that matches the function of the key.

SDL_GetKeyName()

What this function returns seems to have become an open question. I’m
going along with Sam and suggesting that it should return a pointer to
the string for the name of the key in the SDLPhysicalKey enumeration
minus the leading “SDL_”. That means that when given the values:

SDL_KP_1 == "KP_1"
SDL_F6 == “F6”

and so on…

If passed a Unicode code point this function would simply return it.

Classification Functions.

This is a very open question. There was some discussion about the need
to be able to classify SDLKey values so you could quickly find out if a
key is a modifier, a command key, a key pad key, and so on. It looks
like this could be handled with a table and an enumeration of the key
class bits. Does any one feel the need for this feature?

Bob Pendleton--

±-------------------------------------+

2

Text Input Event

This event returns the fully modified text generated by a sequence of
characters. This is how you get the input from an IME or get control x
from the keyboard.

Correct.

SDLKey

SDLKey is an unsigned 32 bit integer. Its values come from two distinct
sets. It can either hold a Unicode code point or a value from the
SDLPhysicalKey enumeration. Values in the enumeration are distinguished
from Unicode code points by a single “magic”.

Correct.

The name and location of the magic bit have not been determined, but I
would suggest SDL_KEY_BIT and I would suggest putting it in bit 30. Bit
30 is better than bit 31 because of sign extension in left shifts and
the possibility of making the value negative even though it is an
unsigned value.

Sounds fine to me.

When returned by an SDL function the Unicode code point is always the
unmodified character on the key. That means the effect of num lock,
shift lock, shift, ctrl, alt, super, and any other modifier keys are
ignored.

Yes, or one of the SDLK_* constants that are used for keys that do not
generate character codes.

Key Press/Release Event

Within the limits of what is possible and practical this event returns
the SDLPhysicalKey value that is closest to the actual location of the
key on the keyboard (as defined by USB HID usage tables, version 1.12
http://www.usb.org/developers/devclass_docs/Hut1_12.pdf, section “10
Keyboard/Keypad Page (0x07)”. This information is meant to provide
positional information, not the key name on any particular keyboard.

Correct.

The only open question is what to do with the Unicode field of the
event. Should we return the Unicode code point when it is available? If
so, these would be unmodified values that are compatible with the
definition of SDLKey given above.

Currently the unicode field is set to 0 for all events. It may be useful
to set it to the return value of SDL_GetLayoutKey(), possibly changing the
name of the field to clarify usage.

The more I think about it, the more I think setting any value in this field
would be confusing. The SDL 1.2 meaning is the composed text input for the
key press, which is no longer available.

SDL_GetLayoutKey()

Given an SDLKey value from a key press/release event this function
converts it to either an unmodified Unicode code point representing the
label of the key or it returns a member of the SDLPhysicalKey
enumeration that matches the function of the key.

Correct.

SDL_GetKeyName()

What this function returns seems to have become an open question. I’m
going along with Sam and suggesting that it should return a pointer to
the string for the name of the key in the SDLPhysicalKey enumeration
minus the leading “SDL_”. That means that when given the values:

SDL_KP_1 == "KP_1"
SDL_F6 == “F6”

and so on…

For backwards compatibility, it may be worth using the existing strings
from SDL 1.2. It doesn’t matter much what they actually are, as long as
they are unique and meaningful.

I don’t have a strong opinion on this though, I’m open to suggestion.

If passed a Unicode code point this function would simply return it.

As UTF-8.

Classification Functions.

This is a very open question. There was some discussion about the need
to be able to classify SDLKey values so you could quickly find out if a
key is a modifier, a command key, a key pad key, and so on. It looks
like this could be handled with a table and an enumeration of the key
class bits. Does any one feel the need for this feature?

Punt. :slight_smile:

Thanks for collecting and clarifying this, Bob! :slight_smile:

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment

3

Sam Lantinga wrote:

Currently the unicode field is set to 0 for all events. It may be useful
to set it to the return value of SDL_GetLayoutKey(), possibly changing the
name of the field to clarify usage.

The more I think about it, the more I think setting any value in this field
would be confusing. The SDL 1.2 meaning is the composed text input for the
key press, which is no longer available.

Why do we need to keep it at all? Source compatibility with SDL 1.2
applications? It would be a very weak form of compatibility anyway -
“compiles but doesn’t work” instead of “doesn’t compile”, which doesn’t
seem all that much better to me.

-Christian

4

Bob Pendleton wrote:

When returned by an SDL function the Unicode code point is always the
unmodified character on the key. That means the effect of num lock,
shift lock, shift, ctrl, alt, super, and any other modifier keys are
ignored.
…
SDL_GetKeyName()
…
If passed a Unicode code point this function would simply return it.

Together, this would mean that (on a US layout)
SDL_GetKeyName(SDL_GetLayoutKey(SDLK_A)) is “a”? Shouldn’t it be “A”?

SDL_GetKeyName()

What this function returns seems to have become an open question. I’m
going along with Sam and suggesting that it should return a pointer to
the string for the name of the key in the SDLPhysicalKey enumeration
minus the leading “SDL_”.

That would mean SDL_GetKeyName(SDLK_LMETA) would be “LMETA” everywhere,
not “left command” on Mac OS and “left windows” on Windows? I don’t like
that.

-Christian

5

Sam Lantinga wrote:

Currently the unicode field is set to 0 for all events. It may be useful
to set it to the return value of SDL_GetLayoutKey(), possibly changing the
name of the field to clarify usage.

The more I think about it, the more I think setting any value in this field
would be confusing. The SDL 1.2 meaning is the composed text input for the
key press, which is no longer available.

Why do we need to keep it at all? Source compatibility with SDL 1.2
applications? It would be a very weak form of compatibility anyway -
“compiles but doesn’t work” instead of “doesn’t compile”, which doesn’t
seem all that much better to me.

I agree. I think we’ll just have to educate people to use the new text
input event for SDL 1.3.

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment

6

Bob Pendleton wrote:

When returned by an SDL function the Unicode code point is always the
unmodified character on the key. That means the effect of num lock,
shift lock, shift, ctrl, alt, super, and any other modifier keys are
ignored.
…
SDL_GetKeyName()
…
If passed a Unicode code point this function would simply return it.

Together, this would mean that (on a US layout)
SDL_GetKeyName(SDL_GetLayoutKey(SDLK_A)) is “a”? Shouldn’t it be “A”?

Well, we should be consistent, either picking ‘a’ or ‘A’ and SDL_GetKeyName()
on either would return “a” or “A” whichever one was passed in.

SDL_GetKeyName()

What this function returns seems to have become an open question. I’m
going along with Sam and suggesting that it should return a pointer to
the string for the name of the key in the SDLPhysicalKey enumeration
minus the leading “SDL_”.

That would mean SDL_GetKeyName(SDLK_LMETA) would be “LMETA” everywhere,
not “left command” on Mac OS and “left windows” on Windows? I don’t like
that.

Hmm. Good point. Unless there are specific concerns lets go with the same
names that SDL 1.2 uses.

I think that this means that we’re using lower case letters for alpha keys,
right?

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment

7

Sam Lantinga wrote:

Currently the unicode field is set to 0 for all events. It may be useful
to set it to the return value of SDL_GetLayoutKey(), possibly changing the
name of the field to clarify usage.

The more I think about it, the more I think setting any value in this field
would be confusing. The SDL 1.2 meaning is the composed text input for the
key press, which is no longer available.

Why do we need to keep it at all? Source compatibility with SDL 1.2
applications? It would be a very weak form of compatibility anyway -
“compiles but doesn’t work” instead of “doesn’t compile”, which doesn’t
seem all that much better to me.

I agree. I think we’ll just have to educate people to use the new text
input event for SDL 1.3.

Ok, I’ll yank the field.

	Bob PendletonOn Thu, 2008-01-24 at 13:27 -0800, Sam Lantinga wrote:

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

–
±-------------------------------------+

8

Bob Pendleton wrote:

When returned by an SDL function the Unicode code point is always the
unmodified character on the key. That means the effect of num lock,
shift lock, shift, ctrl, alt, super, and any other modifier keys are
ignored.
…
SDL_GetKeyName()
…
If passed a Unicode code point this function would simply return it.

Together, this would mean that (on a US layout)
SDL_GetKeyName(SDL_GetLayoutKey(SDLK_A)) is “a”? Shouldn’t it be “A”?

Well, we should be consistent, either picking ‘a’ or ‘A’ and SDL_GetKeyName()
on either would return “a” or “A” whichever one was passed in.

SDL_GetKeyName()

What this function returns seems to have become an open question. I’m
going along with Sam and suggesting that it should return a pointer to
the string for the name of the key in the SDLPhysicalKey enumeration
minus the leading “SDL_”.

That would mean SDL_GetKeyName(SDLK_LMETA) would be “LMETA” everywhere,
not “left command” on Mac OS and “left windows” on Windows? I don’t like
that.

Hmm. Good point. Unless there are specific concerns lets go with the same
names that SDL 1.2 uses.

I think that this means that we’re using lower case letters for alpha keys,
right?

Mostly, yeah. Easy fix.

	Bob PendletonOn Thu, 2008-01-24 at 13:30 -0800, Sam Lantinga wrote:

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

–
±-------------------------------------+

9

Bob Pendleton wrote:

When returned by an SDL function the Unicode code point is always the
unmodified character on the key. That means the effect of num lock,
shift lock, shift, ctrl, alt, super, and any other modifier keys are
ignored.
…
SDL_GetKeyName()
…
If passed a Unicode code point this function would simply return it.

Together, this would mean that (on a US layout)
SDL_GetKeyName(SDL_GetLayoutKey(SDLK_A)) is “a”? Shouldn’t it be “A”?

Well, we should be consistent, either picking ‘a’ or ‘A’ and SDL_GetKeyName()
on either would return “a” or “A” whichever one was passed in.

SDL_GetKeyName()

What this function returns seems to have become an open question. I’m
going along with Sam and suggesting that it should return a pointer to
the string for the name of the key in the SDLPhysicalKey enumeration
minus the leading “SDL_”.

That would mean SDL_GetKeyName(SDLK_LMETA) would be “LMETA” everywhere,
not “left command” on Mac OS and “left windows” on Windows? I don’t like
that.

Hmm. Good point. Unless there are specific concerns lets go with the same
names that SDL 1.2 uses.

I really like to use the key pad number names the way Walther has them
with KP_0 instead of KP0. There are bound to be other cases. But, most
of them should stay the same names as in 1.2.

Bob PendletonOn Thu, 2008-01-24 at 13:30 -0800, Sam Lantinga wrote:

I think that this means that we’re using lower case letters for alpha keys,
right?

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

–
±-------------------------------------+

10

I really like to use the key pad number names the way Walther has them
with KP_0 instead of KP0. There are bound to be other cases. But, most
of them should stay the same names as in 1.2.

Sure, renaming them to make sense is fine, and we can always throw the
old names in SDL_compat.h

See ya,
-Sam Lantinga, Lead Software Engineer, Blizzard Entertainment