master db8f7ed7f65: Enable customization of the quit key on Android

[Po Lu]

branch: master
commit db8f7ed7f652c114e606de423e5094b4cefe49e2
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    Enable customization of the quit key on Android
    
    * doc/emacs/android.texi (Android Windowing):
    
    * doc/emacs/input.texi (On-Screen Keyboards): Document various
    tidbits related to the quit key.
    
    * java/org/gnu/emacs/EmacsNative.java (getQuitKeycode): New
    function.
    
    * java/org/gnu/emacs/EmacsWindow.java (EmacsWindow): Rename
    `lastVolumeButtonRelease' to `lastQuitKeyRelease'.
    (onKeyUp): Treat value returned by getQuitKeycode as the quit
    key rather than mandate KEYCODE_VOLUME_DOWN.
    
    * src/android.c (getQuitKeycode): Implement new function.
    
    * src/androidterm.c (syms_of_androidterm)
    <android_quit_keycode>: New variable.
---
 doc/emacs/android.texi              | 13 ++++++++-----
 doc/emacs/input.texi                |  8 +++++---
 java/org/gnu/emacs/EmacsNative.java |  4 ++++
 java/org/gnu/emacs/EmacsWindow.java | 17 +++++++----------
 src/android.c                       |  7 +++++++
 src/androidterm.c                   | 16 ++++++++++++++++
 6 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/doc/emacs/android.texi b/doc/emacs/android.texi
index 9e3716894ee..71bc6540760 100644
--- a/doc/emacs/android.texi
+++ b/doc/emacs/android.texi
@@ -948,13 +948,16 @@ application via cut-and-paste.
 
 @vindex android-pass-multimedia-buttons-to-system
 @cindex volume/multimedia buttons, Android
-  The volume keys are normally reserved by Emacs and used to provide
-the ability to quit Emacs without a physical keyboard
-(@pxref{On-Screen Keyboards}.)  However, if you want them to adjust
-the volume instead, you can set the variable
+  The volume keys are normally reserved by Emacs and used to provide the
+ability to quit Emacs without a physical keyboard (@pxref{On-Screen
+Keyboards}).  However, if you want them to adjust the volume instead,
+you can set the variable
 @code{android-pass-multimedia-buttons-to-system} to a non-@code{nil}
 value; note that you will no longer be able to quit Emacs using the
-volume buttons in that case.
+volume buttons in that case, and that it is generally easier to activate
+the notification shade or another interface that momentarily deprives
+Emacs of the keyboard focus while the volume buttons are being
+depressed.
 
 @cindex dialog boxes, android
   Emacs is unable to display dialog boxes (@pxref{Dialog Boxes}) while
diff --git a/doc/emacs/input.texi b/doc/emacs/input.texi
index 67679b00e89..96a20a9bc1b 100644
--- a/doc/emacs/input.texi
+++ b/doc/emacs/input.texi
@@ -156,9 +156,11 @@ which two rapid clicks of a hardware button that is always 
present on
 the device induces a quit.  @xref{Quitting}.
 
 @vindex x-quit-keysym
-  No such button is enabled on X, but one can be configured through
-the variable @code{x-quit-keysym}.  On Android this button is always
-the volume down button.
+@vindex android-quit-keycode
+  No such button is enabled on X, but one can be configured through the
+variable @code{x-quit-keysym}, whereas the default key is the volume
+down button on Android, which is also configurable through a variable,
+@code{android-quit-keycode}.
 
 @cindex text conversion, keyboards
   Most input methods designed to work with virtual keyboards edit text
diff --git a/java/org/gnu/emacs/EmacsNative.java 
b/java/org/gnu/emacs/EmacsNative.java
index 9b3e60e1a84..acf9e4b204b 100644
--- a/java/org/gnu/emacs/EmacsNative.java
+++ b/java/org/gnu/emacs/EmacsNative.java
@@ -228,6 +228,10 @@ public final class EmacsNative
      be prevented from reaching the system input method.  */
   public static native boolean shouldForwardCtrlSpace ();
 
+  /* Return the keycode repeated activation of which should signal
+     quit.  */
+  public static native int getQuitKeycode ();
+
   /* Initialize the current thread, by blocking signals that do not
      interest it.  */
   public static native void setupSystemThread ();
diff --git a/java/org/gnu/emacs/EmacsWindow.java 
b/java/org/gnu/emacs/EmacsWindow.java
index 911e082144e..961292af527 100644
--- a/java/org/gnu/emacs/EmacsWindow.java
+++ b/java/org/gnu/emacs/EmacsWindow.java
@@ -136,10 +136,10 @@ public final class EmacsWindow extends EmacsHandleObject
      there is no such window manager.  */
   private WindowManager windowManager;
 
-  /* The time of the last KEYCODE_VOLUME_DOWN release.  This is used
-     to quit Emacs upon two rapid clicks of the volume down
-     button.  */
-  private long lastVolumeButtonRelease;
+  /* The time of the last release of the quit keycode, generally
+     KEYCODE_VOLUME_DOWN.  This is used to signal quit upon two rapid
+     presses of such key.  */
+  private long lastQuitKeyRelease;
 
   /* Linked list of character strings which were recently sent as
      events.  */
@@ -790,15 +790,12 @@ public final class EmacsWindow extends EmacsHandleObject
 
        if ((event.getFlags () & KeyEvent.FLAG_CANCELED) != 0)
          return;
-
-       EmacsNative.sendKeyPress (this.handle, event.getEventTime (),
-                                 state, keyCode, unicode_char);
       }
 
     EmacsNative.sendKeyRelease (this.handle, event.getEventTime (),
                                state, keyCode, unicode_char);
 
-    if (keyCode == KeyEvent.KEYCODE_VOLUME_DOWN)
+    if (keyCode == EmacsNative.getQuitKeycode ())
       {
        /* Check if this volume down press should quit Emacs.
           Most Android devices have no physical keyboard, so it
@@ -806,10 +803,10 @@ public final class EmacsWindow extends EmacsHandleObject
 
        time = event.getEventTime ();
 
-       if (time - lastVolumeButtonRelease < 350)
+       if (time - lastQuitKeyRelease < 350)
          EmacsNative.quit ();
 
-       lastVolumeButtonRelease = time;
+        lastQuitKeyRelease = time;
       }
   }
 
diff --git a/src/android.c b/src/android.c
index e44b58c5973..00a77fc398d 100644
--- a/src/android.c
+++ b/src/android.c
@@ -2645,6 +2645,13 @@ NATIVE_NAME (shouldForwardMultimediaButtons) (JNIEnv 
*env,
   return !android_pass_multimedia_buttons_to_system;
 }
 
+JNIEXPORT jint JNICALL
+NATIVE_NAME (getQuitKeycode) (JNIEnv *env, jobject object)
+{
+  /* Likewise.  */
+  return (jint) android_quit_keycode;
+}
+
 JNIEXPORT jboolean JNICALL
 NATIVE_NAME (shouldForwardCtrlSpace) (JNIEnv *env, jobject object)
 {
diff --git a/src/androidterm.c b/src/androidterm.c
index e4f3abdb2d3..5de7b6f4e14 100644
--- a/src/androidterm.c
+++ b/src/androidterm.c
@@ -6703,6 +6703,22 @@ so it is important to limit the wait.
 If set to a non-float value, there will be no wait at all.  */);
   Vandroid_wait_for_event_timeout = make_float (0.1);
 
+  DEFVAR_INT ("android-quit-keycode", android_quit_keycode,
+    doc: /* Keycode that signals quit when typed twice in rapid succession.
+
+This is the key code of a key whose repeated activation should prompt
+Emacs to quit, enabling quitting on systems where a keyboard capable of
+typing C-g is unavailable, when set to a key that does exist on the
+device.  Its value must be a keycode defined by the operating system,
+and defaults to 25 (KEYCODE_VOLUME_DOWN), though one of the following
+values might be desired on those devices where this default is also
+unavailable, or if another key must otherwise serve this function
+instead:
+
+  - 4  (KEYCODE_BACK)
+  - 24 (KEYCODE_VOLUME_UP)  */);
+  android_quit_keycode = 25;
+
   DEFVAR_BOOL ("x-use-underline-position-properties",
               x_use_underline_position_properties,
      doc: /* SKIP: real doc in xterm.c.  */);