Allow trapping the back button so right mouse click can work on some Android systems (thanks Rachel!)

Also, added a function SDL_AndroidBackButton() so applications can respond to the back button directly

2 files changed, 22 insertions, 0 deletions

diff --git a/include/SDL_hints.h b/include/SDL_hints.h
index 3834640f2d..cb8bed2c0c 100644
--- a/include/SDL_hints.h
+++ b/include/SDL_hints.h
@@ -753,6 +753,23 @@ extern "C" {
 #define SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH "SDL_ANDROID_SEPARATE_MOUSE_AND_TOUCH"
 
  /**
+ * \brief A variable to control whether we trap the Android back button to handle it manually.
+ *        This is necessary for the right mouse button to work on some Android devices, or
+ *        to be able to trap the back button for use in your code reliably.  If set to true,
+ *        the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of 
+ *        SDL_SCANCODE_AC_BACK.
+ *
+ * The variable can be set to the following values:
+ *   "0"       - Back button will be handled as usual for system. (default)
+ *   "1"       - Back button will be trapped, allowing you to handle the key press
+ *               manually.  (This will also let right mouse click work on systems 
+ *               where the right mouse button functions as back.)
+ *
+ * The value of this hint is used at runtime, so it can be changed at any time.
+ */
+#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
+
+ /**
  * \brief A variable to control whether the return key on the soft keyboard
  *        should hide the soft keyboard on Android and iOS.
  *
diff --git a/include/SDL_system.h b/include/SDL_system.h
index 06fce3537f..14b4dbeae8 100644
--- a/include/SDL_system.h
+++ b/include/SDL_system.h
@@ -136,6 +136,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
 extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
 
 /**
+ \brief Trigger the Android system back button behavior.
+ */
+extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
+
+/**
    See the official Android developer guide for more information:
    http://developer.android.com/guide/topics/data/data-storage.html
 */