Add dispatch key shortcut window callback.

Enables Activities and Dialogs to implement key shortcut behavior.
Useful for global key shortcuts that are not bound to the focused
view or to a menu.

Change-Id: If377d20b227ee1c5cac84c47c9630b2d77f67e2c

5 files changed, 103 insertions, 8 deletions

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index 77cbe0a..938c47d 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -2071,7 +2071,21 @@ public class Activity extends ContextThemeWrapper
             finish();
         }
     }
-    
+
+    /**
+     * Called when a key shortcut event is not handled by any of the views in the Activity.
+     * Override this method to implement global key shortcuts for the Activity.
+     * Key shortcuts can also be implemented by setting the
+     * {@link MenuItem#setShortcut(char, char) shortcut} property of menu items.
+     *
+     * @param keyCode The value in event.getKeyCode().
+     * @param event Description of the key event.
+     * @return True if the key shortcut was handled.
+     */
+    public boolean onKeyShortcut(int keyCode, KeyEvent event) {
+        return false;
+    }
+
     /**
      * Called when a touch screen event was not handled by any of the views
      * under it.  This is most useful to process touch events that happen
@@ -2232,6 +2246,23 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
+     * Called to process a key shortcut event.
+     * You can override this to intercept all key shortcut events before they are
+     * dispatched to the window.  Be sure to call this implementation for key shortcut
+     * events that should be handled normally.
+     *
+     * @param event The key shortcut event.
+     * @return True if this event was consumed.
+     */
+    public boolean dispatchKeyShortcutEvent(KeyEvent event) {
+        onUserInteraction();
+        if (getWindow().superDispatchKeyShortcutEvent(event)) {
+            return true;
+        }
+        return onKeyShortcut(event.getKeyCode(), event);
+    }
+
+    /**
      * Called to process touch screen events.  You can override this to
      * intercept all touch screen events before they are dispatched to the
      * window.  Be sure to call this implementation for touch screen events
diff --git a/core/java/android/app/Dialog.java b/core/java/android/app/Dialog.java
index e69e664..6791400 100644
--- a/core/java/android/app/Dialog.java
+++ b/core/java/android/app/Dialog.java
@@ -571,7 +571,21 @@ public class Dialog implements DialogInterface, Window.Callback,
             cancel();
         }
     }
-    
+
+    /**
+     * Called when an key shortcut event is not handled by any of the views in the Dialog.
+     * Override this method to implement global key shortcuts for the Dialog.
+     * Key shortcuts can also be implemented by setting the
+     * {@link MenuItem#setShortcut(char, char) shortcut} property of menu items.
+     *
+     * @param keyCode The value in event.getKeyCode().
+     * @param event Description of the key event.
+     * @return True if the key shortcut was handled.
+     */
+    public boolean onKeyShortcut(int keyCode, KeyEvent event) {
+        return false;
+    }
+
     /**
      * Called when a touch screen event was not handled by any of the views
      * under it. This is most useful to process touch events that happen outside
@@ -659,6 +673,22 @@ public class Dialog implements DialogInterface, Window.Callback,
     }
 
     /**
+     * Called to process a key shortcut event.
+     * You can override this to intercept all key shortcut events before they are
+     * dispatched to the window.  Be sure to call this implementation for key shortcut
+     * events that should be handled normally.
+     *
+     * @param event The key shortcut event.
+     * @return True if this event was consumed.
+     */
+    public boolean dispatchKeyShortcutEvent(KeyEvent event) {
+        if (mWindow.superDispatchKeyShortcutEvent(event)) {
+            return true;
+        }
+        return onKeyShortcut(event.getKeyCode(), event);
+    }
+
+    /**
      * Called to process touch screen events.  You can override this to
      * intercept all touch screen events before they are dispatched to the
      * window.  Be sure to call this implementation for touch screen events
diff --git a/core/java/android/view/KeyEvent.java b/core/java/android/view/KeyEvent.java
index 3a3d1d8..ecf1aef 100755
--- a/core/java/android/view/KeyEvent.java
+++ b/core/java/android/view/KeyEvent.java
@@ -990,20 +990,32 @@ public class KeyEvent extends InputEvent implements Parcelable {
      */
     public static final int META_SCROLL_LOCK_ON = 0x400000;
 
-    /** {@hide} */
+    /**
+     * This mask is a combination of {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}
+     * and {@link #META_SHIFT_RIGHT_ON}.
+     */
     public static final int META_SHIFT_MASK = META_SHIFT_ON
             | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON;
 
-    /** {@hide} */
+    /**
+     * This mask is a combination of {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}
+     * and {@link #META_ALT_RIGHT_ON}.
+     */
     public static final int META_ALT_MASK = META_ALT_ON
             | META_ALT_LEFT_ON | META_ALT_RIGHT_ON;
 
-    /** {@hide} */
+    /**
+     * This mask is a combination of {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}
+     * and {@link #META_CTRL_RIGHT_ON}.
+     */
     public static final int META_CTRL_MASK = META_CTRL_ON
             | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON;
 
-    /** {@hide} */
-    public static final int META_META_MASK = META_ALT_ON
+    /**
+     * This mask is a combination of {@link #META_META_ON}, {@link #META_META_LEFT_ON}
+     * and {@link #META_META_RIGHT_ON}.
+     */
+    public static final int META_META_MASK = META_META_ON
             | META_META_LEFT_ON | META_META_RIGHT_ON;
 
     /**
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 9550090..48f9e81 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -4768,7 +4768,10 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
     }
 
     /**
-     * Called when an unhandled key shortcut event occurs.
+     * Called on the focused view when a key shortcut event is not handled.
+     * Override this method to implement local key shortcuts for the View.
+     * Key shortcuts can also be implemented by setting the
+     * {@link MenuItem#setShortcut(char, char) shortcut} property of menu items.
      *
      * @param keyCode The value in event.getKeyCode().
      * @param event Description of the key event.
diff --git a/core/java/android/view/Window.java b/core/java/android/view/Window.java
index 8446a8f..2f27935 100644
--- a/core/java/android/view/Window.java
+++ b/core/java/android/view/Window.java
@@ -150,6 +150,17 @@ public abstract class Window {
         public boolean dispatchKeyEvent(KeyEvent event);
 
         /**
+         * Called to process a key shortcut event.
+         * At the very least your implementation must call
+         * {@link android.view.Window#superDispatchKeyShortcutEvent} to do the
+         * standard key shortcut processing.
+         *
+         * @param event The key shortcut event.
+         * @return True if this event was consumed.
+         */
+        public boolean dispatchKeyShortcutEvent(KeyEvent event);
+
+        /**
          * Called to process touch screen events.  At the very least your
          * implementation must call
          * {@link android.view.Window#superDispatchTouchEvent} to do the
@@ -1028,6 +1039,14 @@ public abstract class Window {
     public abstract boolean superDispatchKeyEvent(KeyEvent event);
 
     /**
+     * Used by custom windows, such as Dialog, to pass the key shortcut press event
+     * further down the view hierarchy. Application developers should
+     * not need to implement or call this.
+     *
+     */
+    public abstract boolean superDispatchKeyShortcutEvent(KeyEvent event);
+
+    /**
      * Used by custom windows, such as Dialog, to pass the touch screen event
      * further down the view hierarchy. Application developers should
      * not need to implement or call this.