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.
When the input file descriptor of the `pipe()` is `dup2()`'d into
`stdin` and `stdout` it is effectively copied, leaving the original file
descriptor open and leaking at the end of these statements. Only the
output file descriptor has its ownership transferred to `File` and will
be cleaned up properly.
This should cause the reading end to read EOF and return zero bytes when
`stdin` and `stdout` is open, rather than remaining open "indefinitely"
(barring the whole process being taken down) as there will always be
that one file descriptor referencing the input end of the pipe.
- Lets us build with cargo ndk 3+
- Lets us remove suppression for false-negative clippy warning about unsafe
blocks in unsafe functions
- 1.68.0 notably also builds the standard library with a newer r25 NDK
toolchain which avoid the need for awkward libgcc workarounds, so it's
anyway a desirable baseline for Android projects.
Some of the dates were wrong from copy&pasting, there was no changelog
entry for adding `InputEvent::TextEvent`, and the release date for
0.5.0-beta.0/1 was missing.
If an app tries to iterate input events while there's no input queue
(e.g. before onStart) then just behave like there are no events
available instead of returning an error.
This also reduces the logging level of some messages to reduce the
verbosity of info logs.
The following types have been moved from game_activity/input.rs to
input.rs so they can be shared by both backends:
Axis, ButtonState, EdgeFlags, KeyAction, KeyEventFlags, Keycode,
MetaState, MotionAction, MotionEventFlags
This addresses a portability hazard whereby code (such as Winit)
would inadvertently use the `ndk` type which works OK with the
native-activity backend but then wouldn't compile against the
game-activity backend.
The alternative of consolidating on the `ndk::events` types instead was
considered but we've repeatedly needed to diverge from the `ndk` API for
the sake of maintaining a consistent input API across the
`game-activity` and `native-activity` backends (input is an area where
the backends differ significantly in their implementation) and so it
generally seems slightly preferable to consolidate on types from this
crate (though it shouldn't make much difference for these types which
are almost direct bindings from ndk_sys).
The types can be converted to their `ndk::events` counterpart
via the `From` trait.
For now some of the `From` trait implementations rely on
`try_from().unwrap()` but the intention is to replace these with
infallible implementations once we bump the MSRV > 1.66
where we can use `num_enum::FromPrimitive` after adding a
catch-all `Other(u32)` to these enums.
The `unicodeChar` in `GameActivityKeyEvent` wasn't being exposed by
`android-activity` because we couldn't expose the unicode character in
the same way with the native-activity backend - due to how events are
received via an `InputQueue` that doesn't expose the underlying Java
references for the key events.
Now that we have a consistent way of supporting unicode character
mapping via `KeyCharacterMap` bindings it's redundant for the
`GameActivity` backend to call `getUnicodeChar` automatically for
each key press.
With the way events are delivered via an `InputQueue` with
`NativeActivity` there is no direct access to the underlying KeyEvent
and MotionEvent Java objects and no `ndk` API that supports the
equivalent of `KeyEvent.getUnicodeChar()`
What `getUnicodeChar` does under the hood though is to do lookups into a
`KeyCharacterMap` for the corresponding `InputDevice` based on the
event's `key_code` and `meta_state` - which are things we can do via
some JNI bindings for `KeyCharacterMap`.
Although it's still awkward to expose an API like
`key_event.get_unicode_char()` we can instead provide an API that
lets you look up a `KeyCharacterMap` for any `device_id` and
applications can then use that for character mapping.
This approach is also more general than the `getUnicodeChar` utility
since it exposes other useful state, such as being able to check what
kind of keyboard input events are coming from (such as a full physical
keyboard vs a virtual / 'predictive' keyboard)
For consistency this exposes the same API through the game-activity
backend, even though the game-activity backend is technically able to
support unicode lookups via `getUnicodeChar` (since it has access to the
Java `KeyEvent` object).
This highlighted a need to be able to use other `AndroidApp` APIs while
processing input, which wasn't possible with the `.input_events()` API
design because the `AndroidApp` held a lock over the backend while
iterating events.
This changes `input_events()` to `input_events_iter()` which now returns
a form of lending iterator and instead of taking a callback that gets
called repeatedly by `input_events()` a similar callback is now passed
to `iter.next(callback)`.
The API isn't as ergonomic as I would have liked, considering that
lending iterators aren't a standard feature for Rust yet but also since
we still want to have the handling for each individual event go via a
callback that can report whether an event was "handled". I think the
slightly awkward ergonomics are acceptable though considering that
the API will generally be used as an implementation detail within
middleware frameworks like Winit.
Since this is the first example where we're creating non-trivial Java
bindings for an Android SDK API this adds some JNI utilities and
establishes a pattern for how we can implement a class binding.
It's an implementation detail but with how I wrote the binding I tried
to keep in mind the possibility of creating a procmacro later that would
generate some of the JNI boilerplate involved.
This effectively reverts 66cfc68dac
and adds some comments explaining that we're currently blocked by
Winit's MSRV policy + CI from being able to increase our
rust-version.
This is a frustrating conflict that I hope can be addressed by
updating Winit's CI system to allow different platforms to require
more recent versions of Rust (which notably isn't in conflict with
setting a conservative rust-version in Winit for supporting Debian
on Linux)
This re-instates building android-activity with cargo-ndk 2 because
building on Android with 1.64 requires a linker workaround that's
not implemented in newer version of cargo-ndk.
This also reinstates the clippy false-negative warning suppression
for unsafe blocks. Again it's frustrating that we can't have good
things because of how Winit wants to support Debian which shouldn't
be relevant for Android development.
Here is an upstream issue to discuss a potential solution for this:
https://github.com/rust-windowing/winit/issues/3000
- Lets us build with cargo ndk 3+
- Lets us remove suppression for false-negative clippy warning about unsafe
blocks in unsafe functions
- Should unblock CI for #102
- 1.68.0 notably also builds the standard library with a newer r25 NDK
toolchain which avoid the need for awkward libgcc workarounds, so it's
anyway a desirable baseline for Android projects.
This also adds `InputEvent::TextEvent` for notifying applications of IME
state changes as well as explicit getter/setter APIs for tracking IME
selection + compose region state. (only supported with GameActivity)
Fixes: #18
Robert Bragg