Synchronized the on-screen keyboard state with whether we are accepting text input.

The functions to show/hide/toggle the on-screen keyboard have been folded into the text input state.
Calling SDL_StartTextInput() will automatically show the on-screen keyboard if it's available.
Calling SDL_StopTextInput() will automatically hide the on-screen keyboard if it's available.
There is a new API function SDL_IsTextInputActive() which will return whether text input is currently active.
Text input is disabled by default, you must call SDL_StartTextInput() when you are ready to accept text input.
SDL_HasScreenKeyboardSupport() no longer needs to be passed a window.
The iPhone-specific on-screen keyboard functions have been removed.

README.iOS

@@ -80,14 +80,12 @@ Notes -- Keyboard
 
 The SDL keyboard API has been extended to support on-screen keyboards:
 
-int SDL_ShowScreenKeyboard(SDL_Window * window) 
+void SDL_StartTextInput()
-	-- reveals the onscreen keyboard.  Returns 0 on success and -1 on error.
+	-- enables text events and reveals the onscreen keyboard.
-int SDL_HideScreenKeyboard(SDL_Window * window) 
+void SDL_StopTextInput()
-	-- hides the onscreen keyboard.  Returns 0 on success and -1 on error.
+	-- disables text events and hides the onscreen keyboard.
-SDL_bool SDL_IsScreenKeyboardShown(SDL_Window * window) 
+SDL_bool SDL_IsTextInputActive()
-	-- returns whether or not the onscreen keyboard is currently visible.
+	-- returns whether or not text events are enabled (and the onscreen keyboard is visible)
-int SDL_ToggleScreenKeyboard(SDL_Window * window) 	
-	-- toggles the visibility of the onscreen keyboard.  Returns 0 on success and -1 on error.
 
 ==============================================================================
 Notes -- Reading and Writing files

Xcode-iOS/Demos/src/keyboard.c

@@ -291,7 +291,11 @@ main(int argc, char *argv[])
             break;
         case SDL_MOUSEBUTTONUP:
             /*      mouse up toggles onscreen keyboard visibility */
-            SDL_ToggleScreenKeyboard(window);
+            if (SDL_IsTextInputActive()) {
+                SDL_StopTextInput();
+            } else {
+                SDL_StartTextInput();
+            }
             break;
         }
     }

android-project/src/org/libsdl/app/SDLActivity.java

@@ -119,7 +119,7 @@ public class SDLActivity extends Activity {
 
     // Messages from the SDLMain thread
     static final int COMMAND_CHANGE_TITLE = 1;
-    static final int COMMAND_KEYBOARD_SHOW = 2;
+    static final int COMMAND_UNUSED = 2;
     static final int COMMAND_TEXTEDIT_HIDE = 3;
 
     // Handler for the messages
@@ -130,22 +130,6 @@ public class SDLActivity extends Activity {
             case COMMAND_CHANGE_TITLE:
                 setTitle((String)msg.obj);
                 break;
-            case COMMAND_KEYBOARD_SHOW:
-                InputMethodManager manager = (InputMethodManager) getSystemService(INPUT_METHOD_SERVICE);
-                if (manager != null) {
-                    switch (((Integer)msg.obj).intValue()) {
-                    case 0:
-                        manager.hideSoftInputFromWindow(mSurface.getWindowToken(), 0);
-                        break;
-                    case 1:
-                        manager.showSoftInput(mSurface, 0);
-                        break;
-                    case 2:
-                        manager.toggleSoftInputFromWindow(mSurface.getWindowToken(), 0, 0);
-                        break;
-                    }
-                }
-               break;
             case COMMAND_TEXTEDIT_HIDE:
                 if (mTextEdit != null) {
                     mTextEdit.setVisibility(View.GONE);

include/SDL_keyboard.h

@@ -151,21 +151,34 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
 
 /**
  *  \brief Start accepting Unicode text input events.
+ *         This function will show the on-screen keyboard if supported.
  *  
  *  \sa SDL_StopTextInput()
  *  \sa SDL_SetTextInputRect()
+ *  \sa SDL_HasScreenKeyboardSupport()
  */
 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 
+/**
+ *  \brief Return whether or not Unicode text input events are enabled.
+ *
+ *  \sa SDL_StartTextInput()
+ *  \sa SDL_StopTextInput()
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
+
 /**
  *  \brief Stop receiving any text input events.
+ *         This function will hide the on-screen keyboard if supported.
  *  
  *  \sa SDL_StartTextInput()
+ *  \sa SDL_HasScreenKeyboardSupport()
  */
 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
 
 /**
  *  \brief Set the rectangle used to type Unicode text inputs.
+ *         This is used as a hint for IME and on-screen keyboard placement.
  *  
  *  \sa SDL_StartTextInput()
  */
@@ -174,60 +187,13 @@ extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
 /**
  *  \brief Returns whether the platform has some screen keyboard support.
  *  
- *  \param window The window for which screen keyboard should be checked.
- *  
  *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
  *  
  *  \note Not all screen keyboard functions are supported on all platforms.
  *  
- *  \sa SDL_ShowScreenKeyboard()
- *  \sa SDL_HideScreenKeyboard()
- *  \sa SDL_IsScreenKeyboardShown()
- *  \sa SDL_ToggleScreenKeyboard()
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(SDL_Window *window);
-
-/**
- *  \brief Requests to show a screen keyboard for given window.
- *  
- *  \param window The window for which screen keyboard should be shown.
- *  
- *  \return 0 if request will be processed or -1 on error (e.g. no support).
- *  
- *  \note Showing screen keyboards is asynchronous on some platforms.
- *  
- *  \sa SDL_HasScreenKeyboardSupport()
- *  \sa SDL_HideScreenKeyboard()
- */
-extern DECLSPEC int SDLCALL SDL_ShowScreenKeyboard(SDL_Window *window);
-
-/**
- *  \brief Requests to hide a screen keyboard for given window.
- *  
- *  \param window The window for which screen keyboard should be shown.
- *  
- *  \return 0 if request will be processed or -1 on error (e.g. no support).
- *  
- *  \note Hiding screen keyboards is asynchronous on some platforms.
- *  
- *  \sa SDL_HasScreenKeyboardSupport()
- *  \sa SDL_ShowScreenKeyboard()
- */
-extern DECLSPEC int SDLCALL SDL_HideScreenKeyboard(SDL_Window *window);
-
-/**
- *  \brief Requests to toggle a screen keyboard for given window.
- *  
- *  \param window The window for which screen keyboard should be toggled.
- *  
- *  \return 0 if request will be processed or -1 on error (e.g. no support).
- *  
- *  \note Showing and hiding screen keyboards is asynchronous on some platforms.
- *  
- *  \sa SDL_HasScreenKeyboardSupport()
  *  \sa SDL_IsScreenKeyboardShown()
  */
-extern DECLSPEC int SDLCALL SDL_ToggleScreenKeyboard(SDL_Window * window);
+extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport();
 
 /**
  *  \brief Returns whether the screen keyboard is shown for given window.
@@ -236,11 +202,7 @@ extern DECLSPEC int SDLCALL SDL_ToggleScreenKeyboard(SDL_Window * window);
  *  
  *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
  *  
- *  \note May always return SDL_FALSE on some platforms (not implemented there).
- *  
  *  \sa SDL_HasScreenKeyboardSupport()
- *  \sa SDL_ShowScreenKeyboard()
- *  \sa SDL_HideScreenKeyboard()
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
 

include/SDL_system.h

@@ -49,11 +49,6 @@ extern "C" {
 extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
 extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
 
-#define SDL_iPhoneKeyboardShow  SDL_ShowScreenKeyboard
-#define SDL_iPhoneKeyboardHide  SDL_HideScreenKeyboard
-#define SDL_iPhoneKeyboardToggle    SDL_ToggleScreenKeyboard
-#define SDL_iPhoneKeyboardIsShown   SDL_IsScreenKeyboardShown
-
 #endif /* __IPHONEOS__ */
 
 

src/core/android/SDL_android.cpp

@@ -957,39 +957,30 @@ extern "C" int Android_JNI_SendMessage(int command, int param)
     return 0;
 }
 
-extern "C" int Android_JNI_ShowTextInput(SDL_Rect *inputRect)
+extern "C" void Android_JNI_ShowTextInput(SDL_Rect *inputRect)
 {
     JNIEnv *env = Android_JNI_GetEnv();
     if (!env) {
-        return -1;
+        return;
     }
 
     jmethodID mid = env->GetStaticMethodID(mActivityClass, "showTextInput", "(IIII)V");
     if (!mid) {
-        return -1;
+        return;
     }
     env->CallStaticVoidMethod( mActivityClass, mid,
                                inputRect->x,
                                inputRect->y,
                                inputRect->w,
                                inputRect->h );
-    return 0;
 }
 
-/*extern "C" int Android_JNI_HideTextInput()
+extern "C" void Android_JNI_HideTextInput()
 {
-    JNIEnv *env = Android_JNI_GetEnv();
+    // has to match Activity constant
-    if (!env) {
+    const int COMMAND_TEXTEDIT_HIDE = 3;
-        return -1;
+    Android_JNI_SendMessage(COMMAND_TEXTEDIT_HIDE, 0);
-    }
+}
-
-    jmethodID mid = env->GetStaticMethodID(mActivityClass, "hideTextInput", "()V");
-    if (!mid) {
-        return -1;
-    }
-    env->CallStaticVoidMethod(mActivityClass, mid);
-    return 0;
-}*/
 
 //////////////////////////////////////////////////////////////////////////////
 //

src/core/android/SDL_android.h

@@ -34,7 +34,8 @@ extern SDL_bool Android_JNI_CreateContext(int majorVersion, int minorVersion);
 extern void Android_JNI_SwapWindow();
 extern void Android_JNI_SetActivityTitle(const char *title);
 extern SDL_bool Android_JNI_GetAccelerometerValues(float values[3]);
-extern int Android_JNI_ShowTextInput(SDL_Rect *inputRect);
+extern void Android_JNI_ShowTextInput(SDL_Rect *inputRect);
+extern void Android_JNI_HideTextInput();
 
 // Audio support
 extern int Android_JNI_OpenAudioDevice(int sampleRate, int is16Bit, int channelCount, int desiredBufferFrames);

src/events/SDL_events.c

@@ -125,6 +125,8 @@ SDL_StartEventLoop(void)
 
     /* No filter to start with, process most event types */
     SDL_EventOK = NULL;
+    SDL_EventState(SDL_TEXTINPUT, SDL_DISABLE);
+    SDL_EventState(SDL_TEXTEDITING, SDL_DISABLE);
     SDL_EventState(SDL_SYSWMEVENT, SDL_DISABLE);
 
     /* Create the lock and set ourselves active */

src/video/SDL_sysvideo.h

@@ -236,10 +236,9 @@ struct SDL_VideoDevice
     void (*SetTextInputRect) (_THIS, SDL_Rect *rect);
 
     /* Screen keyboard */
-    SDL_bool (*SDL_HasScreenKeyboardSupport) (_THIS, SDL_Window *window);
+    SDL_bool (*SDL_HasScreenKeyboardSupport) (_THIS);
-    int (*SDL_ShowScreenKeyboard) (_THIS, SDL_Window *window);
+    void (*SDL_ShowScreenKeyboard) (_THIS, SDL_Window *window);
-    int (*SDL_HideScreenKeyboard) (_THIS, SDL_Window *window);
+    void (*SDL_HideScreenKeyboard) (_THIS, SDL_Window *window);
-    int (*SDL_ToggleScreenKeyboard) (_THIS, SDL_Window *window);
     SDL_bool (*SDL_IsScreenKeyboardShown) (_THIS, SDL_Window *window);
 
     /* Clipboard */

src/video/SDL_video.c

@@ -2771,19 +2771,47 @@ SDL_GetWindowWMInfo(SDL_Window * window, struct SDL_SysWMinfo *info)
 void
 SDL_StartTextInput(void)
 {
+    SDL_Window *window;
+
+    /* First, enable text events */
+    SDL_EventState(SDL_TEXTINPUT, SDL_ENABLE);
+    SDL_EventState(SDL_TEXTEDITING, SDL_ENABLE);
+
+    /* Then show the on-screen keyboard, if any */
+    window = SDL_GetFocusWindow();
+    if (window && _this && _this->SDL_ShowScreenKeyboard) {
+        _this->SDL_ShowScreenKeyboard(_this, window);
+    }
+
+    /* Finally start the text input system */
     if (_this && _this->StartTextInput) {
         _this->StartTextInput(_this);
     }
-    SDL_EventState(SDL_TEXTINPUT, SDL_ENABLE);
+}
-    SDL_EventState(SDL_TEXTEDITING, SDL_ENABLE);
+
+SDL_bool
+SDL_IsTextInputActive(void)
+{
+    return (SDL_GetEventState(SDL_TEXTINPUT) == SDL_ENABLE);
 }
 
 void
 SDL_StopTextInput(void)
 {
+    SDL_Window *window;
+
+    /* Stop the text input system */
     if (_this && _this->StopTextInput) {
         _this->StopTextInput(_this);
     }
+
+    /* Hide the on-screen keyboard, if any */
+    window = SDL_GetFocusWindow();
+    if (window && _this && _this->SDL_HideScreenKeyboard) {
+        _this->SDL_HideScreenKeyboard(_this, window);
+    }
+
+    /* Finally disable text events */
     SDL_EventState(SDL_TEXTINPUT, SDL_DISABLE);
     SDL_EventState(SDL_TEXTEDITING, SDL_DISABLE);
 }
@@ -2797,41 +2825,14 @@ SDL_SetTextInputRect(SDL_Rect *rect)
 }
 
 SDL_bool
-SDL_HasScreenKeyboardSupport(SDL_Window *window)
+SDL_HasScreenKeyboardSupport(void)
 {
-    if (window && _this && _this->SDL_HasScreenKeyboardSupport) {
+    if (_this && _this->SDL_HasScreenKeyboardSupport) {
-        return _this->SDL_HasScreenKeyboardSupport(_this, window);
+        return _this->SDL_HasScreenKeyboardSupport(_this);
     }
     return SDL_FALSE;
 }
 
-int
-SDL_ShowScreenKeyboard(SDL_Window *window)
-{
-    if (window && _this && _this->SDL_ShowScreenKeyboard) {
-        return _this->SDL_ShowScreenKeyboard(_this, window);
-    }
-    return -1;
-}
-
-int
-SDL_HideScreenKeyboard(SDL_Window *window)
-{
-    if (window && _this && _this->SDL_HideScreenKeyboard) {
-        return _this->SDL_HideScreenKeyboard(_this, window);
-    }
-    return -1;
-}
-
-int
-SDL_ToggleScreenKeyboard(SDL_Window *window)
-{
-    if (window && _this && _this->SDL_ToggleScreenKeyboard) {
-        return _this->SDL_ToggleScreenKeyboard(_this, window);
-    }
-    return -1;
-}
-
 SDL_bool
 SDL_IsScreenKeyboardShown(SDL_Window *window)
 {

src/video/android/SDL_androidkeyboard.c

@@ -287,37 +287,16 @@ Android_OnKeyUp(int keycode)
     return SDL_SendKeyboardKey(SDL_RELEASED, TranslateKeycode(keycode));
 }
 
-// has to fit Activity constant
-#define COMMAND_KEYBOARD_SHOW 2
-
 SDL_bool
-Android_HasScreenKeyboardSupport(_THIS, SDL_Window * window)
+Android_HasScreenKeyboardSupport(_THIS)
 {
-    return Android_Window ? SDL_TRUE : SDL_FALSE;
+    return SDL_TRUE;
-}
-
-int
-Android_ShowScreenKeyboard(_THIS, SDL_Window * window)
-{
-    return Android_Window ? Android_JNI_SendMessage(COMMAND_KEYBOARD_SHOW, 1) : -1;
-}
-
-int
-Android_HideScreenKeyboard(_THIS, SDL_Window * window)
-{
-    return Android_Window ? Android_JNI_SendMessage(COMMAND_KEYBOARD_SHOW, 0) : -1;
-}
-
-int
-Android_ToggleScreenKeyboard(_THIS, SDL_Window * window)
-{
-    return Android_Window ? Android_JNI_SendMessage(COMMAND_KEYBOARD_SHOW, 2) : -1;
 }
 
 SDL_bool
 Android_IsScreenKeyboardShown(_THIS, SDL_Window * window)
 {
-    return SDL_FALSE;
+    return SDL_IsTextInputActive();
 }
 
 void
@@ -327,11 +306,10 @@ Android_StartTextInput(_THIS)
     Android_JNI_ShowTextInput(&videodata->textRect);
 }
 
-#define COMMAND_TEXTEDIT_HIDE 3
 void
 Android_StopTextInput(_THIS)
 {
-    Android_JNI_SendMessage(COMMAND_TEXTEDIT_HIDE, 0);
+    Android_JNI_HideTextInput();
 }
 
 void

src/video/android/SDL_androidkeyboard.h

@@ -26,10 +26,7 @@ extern void Android_InitKeyboard();
 extern int Android_OnKeyDown(int keycode);
 extern int Android_OnKeyUp(int keycode);
 
-extern SDL_bool Android_HasScreenKeyboardSupport(_THIS, SDL_Window * window);
+extern SDL_bool Android_HasScreenKeyboardSupport(_THIS);
-extern int Android_ShowScreenKeyboard(_THIS, SDL_Window * window);
-extern int Android_HideScreenKeyboard(_THIS, SDL_Window * window);
-extern int Android_ToggleScreenKeyboard(_THIS, SDL_Window * window);
 extern SDL_bool Android_IsScreenKeyboardShown(_THIS, SDL_Window * window);
 
 extern void Android_StartTextInput(_THIS);

src/video/android/SDL_androidvideo.c

@@ -127,11 +127,13 @@ Android_CreateDevice(int devindex)
     device->GL_SwapWindow = Android_GL_SwapWindow;
     device->GL_DeleteContext = Android_GL_DeleteContext;
 
+    /* Text input */
+    device->StartTextInput = Android_StartTextInput;
+    device->StopTextInput = Android_StopTextInput;
+    device->SetTextInputRect = Android_SetTextInputRect;
+
     /* Screen keyboard */
     device->SDL_HasScreenKeyboardSupport = Android_HasScreenKeyboardSupport;
-    device->SDL_ShowScreenKeyboard = Android_ShowScreenKeyboard;
-    device->SDL_HideScreenKeyboard = Android_HideScreenKeyboard;
-    device->SDL_ToggleScreenKeyboard = Android_ToggleScreenKeyboard;
     device->SDL_IsScreenKeyboardShown = Android_IsScreenKeyboardShown;
 
     /* Clipboard */
@@ -139,11 +141,6 @@ Android_CreateDevice(int devindex)
     device->GetClipboardText = Android_GetClipboardText;
     device->HasClipboardText = Android_HasClipboardText;
 
-    /* Text input */
-    device->StartTextInput = Android_StartTextInput;
-    device->StopTextInput = Android_StopTextInput;
-    device->SetTextInputRect = Android_SetTextInputRect;
-
     return device;
 }
 

src/video/android/SDL_androidwindow.c

@@ -52,7 +52,7 @@ Android_CreateWindow(_THIS, SDL_Window * window)
 
     /* One window, it always has focus */
     SDL_SetMouseFocus(window);
-    //SDL_SetKeyboardFocus(window);
+    SDL_SetKeyboardFocus(window);
 
     return 0;
 }

src/video/uikit/SDL_uikitvideo.m

@@ -89,7 +89,6 @@ UIKit_CreateDevice(int devindex)
     device->SDL_HasScreenKeyboardSupport = UIKit_HasScreenKeyboardSupport;
     device->SDL_ShowScreenKeyboard = UIKit_ShowScreenKeyboard;
     device->SDL_HideScreenKeyboard = UIKit_HideScreenKeyboard;
-    device->SDL_ToggleScreenKeyboard = UIKit_ToggleScreenKeyboard;
     device->SDL_IsScreenKeyboardShown = UIKit_IsScreenKeyboardShown;
 
     /* OpenGL (ES) functions */

src/video/uikit/SDL_uikitview.h

@@ -61,10 +61,9 @@
 - (void)initializeKeyboard;
 @property (readonly) BOOL keyboardVisible;
 
-SDL_bool UIKit_HasScreenKeyboardSupport(_THIS, SDL_Window *window);
+SDL_bool UIKit_HasScreenKeyboardSupport(_THIS);
-int UIKit_ShowScreenKeyboard(_THIS, SDL_Window *window);
+void UIKit_ShowScreenKeyboard(_THIS, SDL_Window *window);
-int UIKit_HideScreenKeyboard(_THIS, SDL_Window *window);
+void UIKit_HideScreenKeyboard(_THIS, SDL_Window *window);
-int UIKit_ToggleScreenKeyboard(_THIS, SDL_Window *window);
 SDL_bool UIKit_IsScreenKeyboardShown(_THIS, SDL_Window *window);
 
 #endif

src/video/uikit/SDL_uikitview.m

@@ -313,7 +313,7 @@
 {
     SDL_SendKeyboardKey(SDL_PRESSED, SDL_SCANCODE_RETURN);
     SDL_SendKeyboardKey(SDL_RELEASED, SDL_SCANCODE_RETURN);
-    [self hideKeyboard];
+    SDL_StopTextInput();
     return YES;
 }
 
@@ -341,36 +341,25 @@ static SDL_uikitview * getWindowView(SDL_Window * window)
     return view;
 }
 
-SDL_bool UIKit_HasScreenKeyboardSupport(_THIS, SDL_Window *window)
+SDL_bool UIKit_HasScreenKeyboardSupport(_THIS)
 {
-    SDL_uikitview *view = getWindowView(window);
-    if (view == nil) {
-        return SDL_FALSE;
-    }
-
     return SDL_TRUE;
 }
 
-int UIKit_ShowScreenKeyboard(_THIS, SDL_Window *window)
+void UIKit_ShowScreenKeyboard(_THIS, SDL_Window *window)
 {
     SDL_uikitview *view = getWindowView(window);
-    if (view == nil) {
+    if (view != nil) {
-        return -1;
+        [view showKeyboard];
     }
-
-    [view showKeyboard];
-    return 0;
 }
 
-int UIKit_HideScreenKeyboard(_THIS, SDL_Window *window)
+void UIKit_HideScreenKeyboard(_THIS, SDL_Window *window)
 {
     SDL_uikitview *view = getWindowView(window);
-    if (view == nil) {
+    if (view != nil) {
-        return -1;
+        [view hideKeyboard];
     }
-
-    [view hideKeyboard];
-    return 0;
 }
 
 SDL_bool UIKit_IsScreenKeyboardShown(_THIS, SDL_Window *window)
@@ -383,22 +372,6 @@ SDL_bool UIKit_IsScreenKeyboardShown(_THIS, SDL_Window *window)
     return view.keyboardVisible;
 }
 
-int UIKit_ToggleScreenKeyboard(_THIS, SDL_Window *window)
-{
-    SDL_uikitview *view = getWindowView(window);
-    if (view == nil) {
-        return -1;
-    }
-
-    if (UIKit_IsScreenKeyboardShown(_this, window)) {
-        UIKit_HideScreenKeyboard(_this, window);
-    }
-    else {
-        UIKit_ShowScreenKeyboard(_this, window);
-    }
-    return 0;
-}
-
 #endif /* SDL_IPHONE_KEYBOARD */
 
 #endif /* SDL_VIDEO_DRIVER_UIKIT */

test/checkkeys.c

@@ -166,9 +166,7 @@ main(int argc, char *argv[])
     SDL_GL_CreateContext(window);
 #endif
 
-    if (SDL_HasScreenKeyboardSupport(window)) {
+    SDL_StartTextInput();
-        SDL_ShowScreenKeyboard(window);
-    }
 
     /* Watch keystrokes */
     done = 0;