sdl (master post 3.1 preview) Merge commit 'e4f454091a943345938608570b104400f62fd625'

external/sdl/SDL/include/SDL3/SDL_keyboard.h

@@ -39,6 +39,8 @@
 extern "C" {
 #endif
 
+typedef Uint32 SDL_KeyboardID;
+
 /**
  *  The SDL keysym structure, used in key events.
  *
@@ -54,6 +56,52 @@ typedef struct SDL_Keysym
 
 /* Function prototypes */
 
+/**
+ * Return whether a keyboard is currently connected.
+ *
+ * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetKeyboards
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
+
+/**
+ * Get a list of currently connected keyboards.
+ *
+ * Note that this will include any device or virtual driver that includes
+ * keyboard functionality, including some mice, KVM switches, motherboard
+ * power buttons, etc. You should wait for input from a device before you
+ * consider it actively in use.
+ *
+ * \param count a pointer filled in with the number of keyboards returned
+ * \returns a 0 terminated array of keyboards instance IDs which should be
+ *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          more details.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetKeyboardInstanceName
+ * \sa SDL_HasKeyboard
+ */
+extern DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
+
+/**
+ * Get the name of a keyboard.
+ *
+ * This function returns "" if the keyboard doesn't have a name.
+ *
+ * \param instance_id the keyboard instance ID
+ * \returns the name of the selected keyboard, or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetKeyboards
+ */
+extern DECLSPEC const char *SDLCALL SDL_GetKeyboardInstanceName(SDL_KeyboardID instance_id);
+
 /**
  * Query the window which currently has keyboard focus.
  *
@@ -251,6 +299,8 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
  * and SDL_TextEditingEvent (SDL_EVENT_TEXT_EDITING) events. Please use this
  * function in pair with SDL_StopTextInput().
  *
+ * Text input events are received by default.
+ *
  * On some platforms using this function activates the screen keyboard.
  *
  * \since This function is available since SDL 3.0.0.
@@ -274,6 +324,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(void);
 /**
  * Stop receiving any text input events.
  *
+ * Text input events are received by default.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_StartTextInput
@@ -290,15 +342,6 @@ extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
  */
 extern DECLSPEC void SDLCALL SDL_ClearComposition(void);
 
-/**
- * Returns if an IME Composite or Candidate window is currently shown.
- *
- * \returns SDL_TRUE if shown, else SDL_FALSE
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_TextInputShown(void);
-
 /**
  * Set the rectangle used to type Unicode text inputs.
  *