feat: Add AndroidKeyMetastate class for keyboard metastate constants (#1211)

* feat(android): add AndroidKeyMetastate class for keyboard metastate constants

* Reformat import statement for AndroidKey and Metastate

* add space

* fix(test): simplify assertion for AndroidKeyMetastate in test_has_some_metastates

* Update appium/webdriver/extensions/android/nativekey.py

---------

Co-authored-by: Kazuaki Matsuo <fly.49.89.over@gmail.com>

Author: Dor-bl

appium/webdriver/extensions/android/nativekey.py

@@ -13,6 +13,50 @@
 # limitations under the License.
 
 
+class AndroidKeyMetastate:
+    """Keyboard metastate constants for Android key events.
+
+    These constants can be combined with bitwise OR and passed to
+    Keyboard.press_keycode or Keyboard.long_press_keycode as metastate.
+    Values are based on android.view.KeyEvent.
+    https://developer.android.com/reference/android/view/KeyEvent
+    """
+
+    # No modifiers.
+    NONE = 0
+
+    # This mask is used to check whether one of the SHIFT meta keys is pressed.
+    META_SHIFT_ON = 0x01
+    META_SHIFT_LEFT_ON = 0x40
+    META_SHIFT_RIGHT_ON = 0x80
+
+    # This mask is used to check whether one of the ALT meta keys is pressed.
+    META_ALT_ON = 0x02
+    META_ALT_LEFT_ON = 0x10
+    META_ALT_RIGHT_ON = 0x20
+
+    # This mask is used to check whether one of the SYM meta keys is pressed.
+    META_SYM_ON = 0x04
+
+    # This mask is used to check whether the FUNCTION meta key is pressed.
+    META_FUNCTION_ON = 0x08
+
+    # This mask is used to check whether one of the CTRL meta keys is pressed.
+    META_CTRL_ON = 0x1000
+    META_CTRL_LEFT_ON = 0x2000
+    META_CTRL_RIGHT_ON = 0x4000
+
+    # This mask is used to check whether one of the META meta keys is pressed.
+    META_META_ON = 0x10000
+    META_META_LEFT_ON = 0x20000
+    META_META_RIGHT_ON = 0x40000
+
+    # Lock key states.
+    META_CAPS_LOCK_ON = 0x100000
+    META_NUM_LOCK_ON = 0x200000
+    META_SCROLL_LOCK_ON = 0x400000
+
+
 class AndroidKey:
     # Key code constant: Unknown key code.
     UNKNOWN = 0

test/unit/webdriver/device/keyboard_test.py

@@ -14,6 +14,7 @@
 
 import httpretty
 
+from appium.webdriver.extensions.android.nativekey import AndroidKeyMetastate
 from appium.webdriver.webdriver import WebDriver
 from test.unit.helper.test_helper import android_w3c_driver, appium_command, get_httpretty_request_body, ios_w3c_driver
 
@@ -71,7 +72,11 @@ def test_press_keycode_with_flags(self):
         # metastate is META_SHIFT_ON and META_NUM_LOCK_ON
         # flags is CANCELFLAG_CANCELEDED, FLAG_KEEP_TOUCH_MODE, FLAG_FROM_SYSTEM
         assert isinstance(
-            driver.press_keycode(86, metastate=0x00000001 | 0x00200000, flags=0x20 | 0x00000004 | 0x00000008),
+            driver.press_keycode(
+                86,
+                metastate=AndroidKeyMetastate.META_SHIFT_ON | AndroidKeyMetastate.META_NUM_LOCK_ON,
+                flags=0x20 | 0x00000004 | 0x00000008,
+            ),
             WebDriver,
         )
 
@@ -87,7 +92,11 @@ def test_long_press_keycode_with_flags(self):
         # metastate is META_SHIFT_ON and META_NUM_LOCK_ON
         # flags is CANCELFLAG_CANCELEDED, FLAG_KEEP_TOUCH_MODE, FLAG_FROM_SYSTEM
         assert isinstance(
-            driver.long_press_keycode(86, metastate=0x00000001 | 0x00200000, flags=0x20 | 0x00000004 | 0x00000008),
+            driver.long_press_keycode(
+                86,
+                metastate=AndroidKeyMetastate.META_SHIFT_ON | AndroidKeyMetastate.META_NUM_LOCK_ON,
+                flags=0x20 | 0x00000004 | 0x00000008,
+            ),
             WebDriver,
         )
 

test/unit/webdriver/nativekey_test.py

@@ -13,7 +13,10 @@
 # limitations under the License.
 
 
-from appium.webdriver.extensions.android.nativekey import AndroidKey
+from appium.webdriver.extensions.android.nativekey import (
+    AndroidKey,
+    AndroidKeyMetastate,
+)
 
 
 class TestAndroidKey:
@@ -23,6 +26,12 @@ def test_has_some_codes(self):
         assert AndroidKey.CAMERA == 27
         assert AndroidKey.SPACE == 62
 
+    def test_has_some_metastates(self):
+        assert AndroidKeyMetastate.NONE == 0
+        assert AndroidKeyMetastate.META_SHIFT_ON == 0x00000001
+        assert AndroidKeyMetastate.META_NUM_LOCK_ON == 0x00200000
+        assert (AndroidKeyMetastate.META_SHIFT_ON | AndroidKeyMetastate.META_NUM_LOCK_ON) == 0x00000001 | 0x00200000
+
     def test_is_gamepad_key(self):
         assert AndroidKey.is_gamepad_button(AndroidKey.BUTTON_8)
         assert not AndroidKey.is_gamepad_button(250)