Improve forwards compatibility of input API

This adds a `#[doc(hidden)]` `__Unknown(u32)` variant to the various
enums to keep them extensible without requiring API breaks.

We need to consider that most enums that are based on Android SDK enums
may be extended across different versions of Android (i.e. effectively
at runtime) or extended in new versions of `android-activity` when we
pull in the latest NDK/SDK constants.

In particular in the case that there is some unknown variant we at least
want to be able to preserve the integer value to allow the values to be
either passed back into the SDK (it doesn't always matter whether we
know the semantics of a variant at compile time) or passed on to
something downstream that could be independently updated to know the
semantics.

We don't want it to be an API break to extend these enums in future
releases of `android-activity`.

It's not enough to rely on `#[non-exhaustive]` because that only really
helps when adding new variants in sync with android-activity releases.

On the other hand we also can't rely on a catch-all `Unknown(u32)` that
only really helps with unknown variants seen at runtime. (If code were
to have an exhaustive match that would include matching on `Unknown(_)`
values then they wouldn't be compatible with new versions of
android-activity that would promote unknown values to known ones).

What we aim for instead is to have a hidden catch-all variant that is
considered (practically) unmatchable so code is forced to have a
`unknown => {}` catch-all pattern match that will cover unknown variants
either in the form of Rust variants added in future versions or in the
form of an `__Unknown(u32)` integer that represents an unknown variant
seen at runtime.

Any `unknown => {}` pattern match can rely on `IntoPrimitive` to convert
the `unknown` variant to the integer that comes from the Android SDK in
case that values needs to be passed on, even without knowing it's
semantic meaning at compile time.

Instead of adding an `__Unknown(u32)` variant to the `Class` enum though
this enum has been removed in favour of adding methods like
`is_button_class()` and `is_pointer_class()` to the `Source` type, since
the class flags aren't guaranteed to be mutually exclusive and since
they are an attribute of the `Source`.

This removes some reliance `try_into().unwrap()` that was put in place
anticipating that we would support `into()` via `num_enum`, once we
could update our rust-version.

Author: rib

android-activity/src/game_activity/input.rs

@@ -13,12 +13,10 @@
 // The `Class` was also bound differently to `android-ndk-rs` considering how the class is defined
 // by masking bits from the `Source`.
 
-use std::convert::TryInto;
-
 use crate::activity_impl::ffi::{GameActivityKeyEvent, GameActivityMotionEvent};
 use crate::input::{
-    Axis, ButtonState, Class, EdgeFlags, KeyAction, KeyEventFlags, Keycode, MetaState,
-    MotionAction, MotionEventFlags, Pointer, PointersIter, Source, ToolType,
+    Axis, ButtonState, EdgeFlags, KeyAction, KeyEventFlags, Keycode, MetaState, MotionAction,
+    MotionEventFlags, Pointer, PointersIter, Source, ToolType,
 };
 
 // Note: try to keep this wrapper API compatible with the AInputEvent API if possible
@@ -50,14 +48,7 @@ impl<'a> MotionEvent<'a> {
     #[inline]
     pub fn source(&self) -> Source {
         let source = self.ga_event.source as u32;
-        source.try_into().unwrap_or(Source::Unknown)
-    }
-
-    /// Get the class of the event source.
-    ///
-    #[inline]
-    pub fn class(&self) -> Class {
-        Class::from(self.source())
+        source.into()
     }
 
     /// Get the device id associated with the event.
@@ -73,7 +64,7 @@ impl<'a> MotionEvent<'a> {
     #[inline]
     pub fn action(&self) -> MotionAction {
         let action = self.ga_event.action as u32 & ndk_sys::AMOTION_EVENT_ACTION_MASK;
-        action.try_into().unwrap()
+        action.into()
     }
 
     /// Returns the pointer index of an `Up` or `Down` event.
@@ -275,7 +266,8 @@ impl<'a> PointerImpl<'a> {
     #[inline]
     pub fn axis_value(&self, axis: Axis) -> f32 {
         let pointer = &self.event.ga_event.pointers[self.index];
-        pointer.axisValues[axis as u32 as usize]
+        let axis: u32 = axis.into();
+        pointer.axisValues[axis as usize]
     }
 
     #[inline]
@@ -294,7 +286,7 @@ impl<'a> PointerImpl<'a> {
     pub fn tool_type(&self) -> ToolType {
         let pointer = &self.event.ga_event.pointers[self.index];
         let tool_type = pointer.toolType as u32;
-        tool_type.try_into().unwrap()
+        tool_type.into()
     }
 }
 
@@ -662,14 +654,7 @@ impl<'a> KeyEvent<'a> {
     #[inline]
     pub fn source(&self) -> Source {
         let source = self.ga_event.source as u32;
-        source.try_into().unwrap_or(Source::Unknown)
-    }
-
-    /// Get the class of the event source.
-    ///
-    #[inline]
-    pub fn class(&self) -> Class {
-        Class::from(self.source())
+        source.into()
     }
 
     /// Get the device id associated with the event.
@@ -685,13 +670,13 @@ impl<'a> KeyEvent<'a> {
     #[inline]
     pub fn action(&self) -> KeyAction {
         let action = self.ga_event.action as u32;
-        action.try_into().unwrap()
+        action.into()
     }
 
     #[inline]
     pub fn action_button(&self) -> KeyAction {
         let action = self.ga_event.action as u32;
-        action.try_into().unwrap()
+        action.into()
     }
 
     /// Returns the last time the key was pressed.  This is on the scale of
@@ -721,7 +706,7 @@ impl<'a> KeyEvent<'a> {
     #[inline]
     pub fn key_code(&self) -> Keycode {
         let keycode = self.ga_event.keyCode as u32;
-        keycode.try_into().unwrap_or(Keycode::Unknown)
+        keycode.into()
     }
 
     /// Returns the number of repeats of a key.

android-activity/src/game_activity/mod.rs

@@ -548,10 +548,12 @@ impl AndroidAppInner {
     }
 
     pub fn enable_motion_axis(&mut self, axis: Axis) {
+        let axis: u32 = axis.into();
         unsafe { ffi::GameActivityPointerAxes_enableAxis(axis as i32) }
     }
 
     pub fn disable_motion_axis(&mut self, axis: Axis) {
+        let axis: u32 = axis.into();
         unsafe { ffi::GameActivityPointerAxes_disableAxis(axis as i32) }
     }