src/events/SDL_keyboard_c.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 19 Aug 2007 14:52:52 +0000
changeset 2268 4baee598306d
parent 2129 047245361002
child 2300 c97ad1abe05b
permissions -rw-r--r--
Date: Thu, 05 Jul 2007 14:02:33 -0700
From: Sam Lantinga
Subject: SDL 1.3 keyboard plan

After lots of discussion with Christian, this is what we came up with:

> So, to sum up...
> SDLK_* become the physical keys, starting at > (1<<21)
> We create a macro SDLK_INDEX(X)
> We have two functions SDL_GetLayoutKey(SDLKey) and SDL_GetKeyName()
> SDL_GetLayoutKey maps to UCS4 for printable characters, and SDLK* for
non-printable characters
> and does so based on the OS's current keyboard layout
> SDL_GetKeyName() handles both SDLK_* and UCS4, converting UCS4 to UTF-8 and
converting SDLK_* into our names, which are UTF-8 for printable characters.
> WASD folks use SDLK_*, and 'I' folks use SDL_GetLayoutKey(SDLK_*)

Here is the patch he came up with, and his e-mail about it:

Date: Fri, 17 Aug 2007 19:50:28 +0200
From: Christian Walther
Subject: Re: SDL 1.3 keyboard plan

> Sounds great, go ahead and send me a patch.

Here goes! Thanks for having a look. Don't hesitate to comment if
anything does not conform to your ideas.

One caveat: Committing this now may break compilability of some video
drivers - specifically, if they use any of the SDLK_* codes that were
obsoleted and moved into SDL_compat.h. I only tried Cocoa (which did
break, but is already fixed) and X11 (which didn't, but then its key
handling is #iffed out). If that's a problem, it may need to go into
a branch.

-Christian
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2006 Sam Lantinga
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 #include "SDL_config.h"
    23 
    24 #ifndef _SDL_keyboard_c_h
    25 #define _SDL_keyboard_c_h
    26 
    27 #include "SDL_keysym.h"
    28 #include "SDL_events.h"
    29 
    30 typedef struct SDL_Keyboard SDL_Keyboard;
    31 
    32 struct SDL_Keyboard
    33 {
    34     /* Free the keyboard when it's time */
    35     void (*FreeKeyboard) (SDL_Keyboard * keyboard);
    36 
    37     /* Data common to all keyboards */
    38     SDL_WindowID focus;
    39     Uint16 modstate;
    40     Uint8 keystate[SDLK_LAST];
    41 
    42     void *driverdata;
    43 };
    44 
    45 /* Used by the OS keyboard code to detect whether or not to do UNICODE */
    46 #ifndef DEFAULT_UNICODE_TRANSLATION
    47 #define DEFAULT_UNICODE_TRANSLATION 0   /* Default off because of overhead */
    48 #endif
    49 extern int SDL_TranslateUNICODE;
    50 
    51 /* Initialize the keyboard subsystem */
    52 extern int SDL_KeyboardInit(void);
    53 
    54 /* Get the keyboard at an index */
    55 extern SDL_Keyboard *SDL_GetKeyboard(int index);
    56 
    57 /* Add a keyboard, possibly reattaching at a particular index (or -1),
    58    returning the index of the keyboard, or -1 if there was an error.
    59  */
    60 extern int SDL_AddKeyboard(const SDL_Keyboard * keyboard, int index);
    61 
    62 /* Remove a keyboard at an index, clearing the slot for later */
    63 extern void SDL_DelKeyboard(int index);
    64 
    65 /* Clear the state of a keyboard at an index */
    66 extern void SDL_ResetKeyboard(int index);
    67 
    68 /* Set a platform-dependent key name, overriding the default platform-agnostic
    69    name. Encoded as UTF-8. The string is not copied, thus the pointer given to
    70    this function must stay valid forever (or at least until the call to
    71    VideoQuit()). */
    72 extern void SDL_SetKeyName(SDLKey physicalKey, const char *name);
    73 
    74 /* Set the keyboard focus window */
    75 extern void SDL_SetKeyboardFocus(int index, SDL_WindowID windowID);
    76 
    77 /* Send a keyboard event for a keyboard at an index */
    78 extern int SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode,
    79                                SDLKey key);
    80 
    81 /* Send keyboard text input for a keyboard at an index */
    82 extern int SDL_SendKeyboardText(int index, const char *text);
    83 
    84 /* Shutdown the keyboard subsystem */
    85 extern void SDL_KeyboardQuit(void);
    86 
    87 #endif /* _SDL_keyboard_c_h */
    88 
    89 /* vi: set ts=4 sw=4 expandtab: */