include/SDL_keyboard.h
changeset 7191 75360622e65f
parent 6885 700f1b25f77f
child 7258 89d47188c9a4
equal deleted inserted replaced
7190:11612d544fcd 7191:75360622e65f
    19   3. This notice may not be removed or altered from any source distribution.
    19   3. This notice may not be removed or altered from any source distribution.
    20 */
    20 */
    21 
    21 
    22 /**
    22 /**
    23  *  \file SDL_keyboard.h
    23  *  \file SDL_keyboard.h
    24  *  
    24  *
    25  *  Include file for SDL keyboard event handling
    25  *  Include file for SDL keyboard event handling
    26  */
    26  */
    27 
    27 
    28 #ifndef _SDL_keyboard_h
    28 #ifndef _SDL_keyboard_h
    29 #define _SDL_keyboard_h
    29 #define _SDL_keyboard_h
    34 #include "SDL_video.h"
    34 #include "SDL_video.h"
    35 
    35 
    36 #include "begin_code.h"
    36 #include "begin_code.h"
    37 /* Set up for C function definitions, even when using C++ */
    37 /* Set up for C function definitions, even when using C++ */
    38 #ifdef __cplusplus
    38 #ifdef __cplusplus
    39 /* *INDENT-OFF* */
       
    40 extern "C" {
    39 extern "C" {
    41 /* *INDENT-ON* */
       
    42 #endif
    40 #endif
    43 
    41 
    44 /**
    42 /**
    45  *  \brief The SDL keysym structure, used in key events.
    43  *  \brief The SDL keysym structure, used in key events.
    46  */
    44  */
    59  */
    57  */
    60 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
    58 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
    61 
    59 
    62 /**
    60 /**
    63  *  \brief Get a snapshot of the current state of the keyboard.
    61  *  \brief Get a snapshot of the current state of the keyboard.
    64  *  
    62  *
    65  *  \param numkeys if non-NULL, receives the length of the returned array.
    63  *  \param numkeys if non-NULL, receives the length of the returned array.
    66  *  
    64  *
    67  *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
    65  *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
    68  *  
    66  *
    69  *  \b Example:
    67  *  \b Example:
    70  *  \code
    68  *  \code
    71  *  Uint8 *state = SDL_GetKeyboardState(NULL);
    69  *  Uint8 *state = SDL_GetKeyboardState(NULL);
    72  *  if ( state[SDL_SCANCODE_RETURN] )   {
    70  *  if ( state[SDL_SCANCODE_RETURN] )   {
    73  *      printf("<RETURN> is pressed.\n");
    71  *      printf("<RETURN> is pressed.\n");
    81  */
    79  */
    82 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
    80 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
    83 
    81 
    84 /**
    82 /**
    85  *  \brief Set the current key modifier state for the keyboard.
    83  *  \brief Set the current key modifier state for the keyboard.
    86  *  
    84  *
    87  *  \note This does not change the keyboard state, only the key modifier flags.
    85  *  \note This does not change the keyboard state, only the key modifier flags.
    88  */
    86  */
    89 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
    87 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
    90 
    88 
    91 /**
    89 /**
    92  *  \brief Get the key code corresponding to the given scancode according
    90  *  \brief Get the key code corresponding to the given scancode according
    93  *         to the current keyboard layout.
    91  *         to the current keyboard layout.
    94  *  
    92  *
    95  *  See ::SDL_Keycode for details.
    93  *  See ::SDL_Keycode for details.
    96  *  
    94  *
    97  *  \sa SDL_GetKeyName()
    95  *  \sa SDL_GetKeyName()
    98  */
    96  */
    99 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
    97 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
   100 
    98 
   101 /**
    99 /**
   102  *  \brief Get the scancode corresponding to the given key code according to the
   100  *  \brief Get the scancode corresponding to the given key code according to the
   103  *         current keyboard layout.
   101  *         current keyboard layout.
   104  *  
   102  *
   105  *  See ::SDL_Scancode for details.
   103  *  See ::SDL_Scancode for details.
   106  *  
   104  *
   107  *  \sa SDL_GetScancodeName()
   105  *  \sa SDL_GetScancodeName()
   108  */
   106  */
   109 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
   107 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
   110 
   108 
   111 /**
   109 /**
   112  *  \brief Get a human-readable name for a scancode.
   110  *  \brief Get a human-readable name for a scancode.
   113  *  
   111  *
   114  *  \return A pointer to the name for the scancode.
   112  *  \return A pointer to the name for the scancode.
   115  *          If the scancode doesn't have a name, this function returns
   113  *          If the scancode doesn't have a name, this function returns
   116  *          an empty string ("").
   114  *          an empty string ("").
   117  *
   115  *
   118  *  \sa SDL_Scancode
   116  *  \sa SDL_Scancode
   119  */
   117  */
   120 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
   118 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
   121 
   119 
   122 /**
   120 /**
   123  *  \brief Get a scancode from a human-readable name
   121  *  \brief Get a scancode from a human-readable name
   124  *  
   122  *
   125  *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
   123  *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
   126  *
   124  *
   127  *  \sa SDL_Scancode
   125  *  \sa SDL_Scancode
   128  */
   126  */
   129 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
   127 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
   130 
   128 
   131 /**
   129 /**
   132  *  \brief Get a human-readable name for a key.
   130  *  \brief Get a human-readable name for a key.
   133  *  
   131  *
   134  *  \return A pointer to a UTF-8 string that stays valid at least until the next
   132  *  \return A pointer to a UTF-8 string that stays valid at least until the next
   135  *          call to this function. If you need it around any longer, you must 
   133  *          call to this function. If you need it around any longer, you must
   136  *          copy it.  If the key doesn't have a name, this function returns an 
   134  *          copy it.  If the key doesn't have a name, this function returns an
   137  *          empty string ("").
   135  *          empty string ("").
   138  *  
   136  *
   139  *  \sa SDL_Key
   137  *  \sa SDL_Key
   140  */
   138  */
   141 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
   139 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
   142 
   140 
   143 /**
   141 /**
   144  *  \brief Get a key code from a human-readable name
   142  *  \brief Get a key code from a human-readable name
   145  *  
   143  *
   146  *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
   144  *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
   147  *
   145  *
   148  *  \sa SDL_Keycode
   146  *  \sa SDL_Keycode
   149  */
   147  */
   150 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
   148 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
   151 
   149 
   152 /**
   150 /**
   153  *  \brief Start accepting Unicode text input events.
   151  *  \brief Start accepting Unicode text input events.
   154  *         This function will show the on-screen keyboard if supported.
   152  *         This function will show the on-screen keyboard if supported.
   155  *  
   153  *
   156  *  \sa SDL_StopTextInput()
   154  *  \sa SDL_StopTextInput()
   157  *  \sa SDL_SetTextInputRect()
   155  *  \sa SDL_SetTextInputRect()
   158  *  \sa SDL_HasScreenKeyboardSupport()
   156  *  \sa SDL_HasScreenKeyboardSupport()
   159  */
   157  */
   160 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
   158 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
   168 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
   166 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
   169 
   167 
   170 /**
   168 /**
   171  *  \brief Stop receiving any text input events.
   169  *  \brief Stop receiving any text input events.
   172  *         This function will hide the on-screen keyboard if supported.
   170  *         This function will hide the on-screen keyboard if supported.
   173  *  
   171  *
   174  *  \sa SDL_StartTextInput()
   172  *  \sa SDL_StartTextInput()
   175  *  \sa SDL_HasScreenKeyboardSupport()
   173  *  \sa SDL_HasScreenKeyboardSupport()
   176  */
   174  */
   177 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
   175 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
   178 
   176 
   179 /**
   177 /**
   180  *  \brief Set the rectangle used to type Unicode text inputs.
   178  *  \brief Set the rectangle used to type Unicode text inputs.
   181  *         This is used as a hint for IME and on-screen keyboard placement.
   179  *         This is used as a hint for IME and on-screen keyboard placement.
   182  *  
   180  *
   183  *  \sa SDL_StartTextInput()
   181  *  \sa SDL_StartTextInput()
   184  */
   182  */
   185 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
   183 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
   186 
   184 
   187 /**
   185 /**
   188  *  \brief Returns whether the platform has some screen keyboard support.
   186  *  \brief Returns whether the platform has some screen keyboard support.
   189  *  
   187  *
   190  *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
   188  *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
   191  *  
   189  *
   192  *  \note Not all screen keyboard functions are supported on all platforms.
   190  *  \note Not all screen keyboard functions are supported on all platforms.
   193  *  
   191  *
   194  *  \sa SDL_IsScreenKeyboardShown()
   192  *  \sa SDL_IsScreenKeyboardShown()
   195  */
   193  */
   196 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
   194 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
   197 
   195 
   198 /**
   196 /**
   199  *  \brief Returns whether the screen keyboard is shown for given window.
   197  *  \brief Returns whether the screen keyboard is shown for given window.
   200  *  
   198  *
   201  *  \param window The window for which screen keyboard should be queried.
   199  *  \param window The window for which screen keyboard should be queried.
   202  *  
   200  *
   203  *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
   201  *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
   204  *  
   202  *
   205  *  \sa SDL_HasScreenKeyboardSupport()
   203  *  \sa SDL_HasScreenKeyboardSupport()
   206  */
   204  */
   207 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
   205 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
   208 
   206 
   209 /* Ends C function definitions when using C++ */
   207 /* Ends C function definitions when using C++ */
   210 #ifdef __cplusplus
   208 #ifdef __cplusplus
   211 /* *INDENT-OFF* */
       
   212 }
   209 }
   213 /* *INDENT-ON* */
       
   214 #endif
   210 #endif
   215 #include "close_code.h"
   211 #include "close_code.h"
   216 
   212 
   217 #endif /* _SDL_keyboard_h */
   213 #endif /* _SDL_keyboard_h */
   218 
   214