rio_winit_fork/platform/android.rs
1//! # Android
2//!
3//! The Android backend builds on (and exposes types from) the [`ndk`](https://docs.rs/ndk/) crate.
4//!
5//! Native Android applications need some form of "glue" crate that is responsible
6//! for defining the main entry point for your Rust application as well as tracking
7//! various life-cycle events and synchronizing with the main JVM thread.
8//!
9//! Winit uses the [android-activity](https://docs.rs/android-activity/) as a
10//! glue crate (prior to `0.28` it used
11//! [ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue)).
12//!
13//! The version of the glue crate that your application depends on _must_ match the
14//! version that Winit depends on because the glue crate is responsible for your
15//! application's main entry point. If Cargo resolves multiple versions, they will
16//! clash.
17//!
18//! `winit` glue compatibility table:
19//!
20//! | winit | ndk-glue |
21//! | :---: | :--------------------------: |
22//! | 0.30 | `android-activity = "0.6"` |
23//! | 0.29 | `android-activity = "0.5"` |
24//! | 0.28 | `android-activity = "0.4"` |
25//! | 0.27 | `ndk-glue = "0.7"` |
26//! | 0.26 | `ndk-glue = "0.5"` |
27//! | 0.25 | `ndk-glue = "0.3"` |
28//! | 0.24 | `ndk-glue = "0.2"` |
29//!
30//! The recommended way to avoid a conflict with the glue version is to avoid explicitly
31//! depending on the `android-activity` crate, and instead consume the API that
32//! is re-exported by Winit under `winit::platform::android::activity::*`
33//!
34//! Running on an Android device needs a dynamic system library. Add this to Cargo.toml:
35//!
36//! ```toml
37//! [lib]
38//! name = "main"
39//! crate-type = ["cdylib"]
40//! ```
41//!
42//! All Android applications are based on an `Activity` subclass, and the
43//! `android-activity` crate is designed to support different choices for this base
44//! class. Your application _must_ specify the base class it needs via a feature flag:
45//!
46//! | Base Class | Feature Flag | Notes |
47//! | :--------------: | :---------------: | :-----: |
48//! | `NativeActivity` | `android-native-activity` | Built-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass `NativeActivity` to access some platform features. It does not derive from the [`AndroidAppCompat`] base class.|
49//! | [`GameActivity`] | `android-game-activity` | Derives from [`AndroidAppCompat`], a defacto standard `Activity` base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a [Maven repository][agdk_jetpack] (or link with an embedded [release][agdk_releases] of [`GameActivity`]) |
50//!
51//! [`GameActivity`]: https://developer.android.com/games/agdk/game-activity
52//! [`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input
53//! [`AndroidAppCompat`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity
54//! [agdk_jetpack]: https://developer.android.com/jetpack/androidx/releases/games
55//! [agdk_releases]: https://developer.android.com/games/agdk/download#agdk-libraries
56//! [Gradle]: https://developer.android.com/studio/build
57//!
58//! For more details, refer to these `android-activity` [example applications](https://github.com/rust-mobile/android-activity/tree/main/examples).
59//!
60//! ## Converting from `ndk-glue` to `android-activity`
61//!
62//! If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building
63//! with `cargo apk`, then the minimal changes would be:
64//! 1. Remove `ndk-glue` from your `Cargo.toml`
65//! 2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.30.0",
66//! features = [ "android-native-activity" ] }`
67//! 3. Add an `android_main` entrypoint (as above), instead of using the '`[ndk_glue::main]` proc
68//! macro from `ndk-macros` (optionally add a dependency on `android_logger` and initialize
69//! logging as above).
70//! 4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your
71//! event loop (as shown above).
72
73use crate::event_loop::{ActiveEventLoop, EventLoop, EventLoopBuilder};
74use crate::window::{Window, WindowAttributes};
75
76use self::activity::{AndroidApp, ConfigurationRef, Rect};
77
78/// Additional methods on [`EventLoop`] that are specific to Android.
79pub trait EventLoopExtAndroid {}
80
81impl<T> EventLoopExtAndroid for EventLoop<T> {}
82
83/// Additional methods on [`ActiveEventLoop`] that are specific to Android.
84pub trait ActiveEventLoopExtAndroid {}
85
86/// Additional methods on [`Window`] that are specific to Android.
87pub trait WindowExtAndroid {
88 fn content_rect(&self) -> Rect;
89
90 fn config(&self) -> ConfigurationRef;
91}
92
93impl WindowExtAndroid for Window {
94 fn content_rect(&self) -> Rect {
95 self.window.content_rect()
96 }
97
98 fn config(&self) -> ConfigurationRef {
99 self.window.config()
100 }
101}
102
103impl ActiveEventLoopExtAndroid for ActiveEventLoop {}
104
105/// Additional methods on [`WindowAttributes`] that are specific to Android.
106pub trait WindowAttributesExtAndroid {}
107
108impl WindowAttributesExtAndroid for WindowAttributes {}
109
110pub trait EventLoopBuilderExtAndroid {
111 /// Associates the `AndroidApp` that was passed to `android_main()` with the event loop
112 ///
113 /// This must be called on Android since the `AndroidApp` is not global state.
114 fn with_android_app(&mut self, app: AndroidApp) -> &mut Self;
115
116 /// Calling this will mark the volume keys to be manually handled by the application
117 ///
118 /// Default is to let the operating system handle the volume keys
119 fn handle_volume_keys(&mut self) -> &mut Self;
120}
121
122impl<T> EventLoopBuilderExtAndroid for EventLoopBuilder<T> {
123 fn with_android_app(&mut self, app: AndroidApp) -> &mut Self {
124 self.platform_specific.android_app = Some(app);
125 self
126 }
127
128 fn handle_volume_keys(&mut self) -> &mut Self {
129 self.platform_specific.ignore_volume_keys = false;
130 self
131 }
132}
133
134/// Re-export of the `android_activity` API
135///
136/// Winit re-exports the `android_activity` API for convenience so that most
137/// applications can rely on the Winit crate to resolve the required version of
138/// `android_activity` and avoid any chance of a conflict between Winit and the
139/// application crate.
140///
141/// Unlike most libraries there can only be a single implementation
142/// of the `android_activity` glue crate linked with an application because
143/// it is responsible for the application's `android_main()` entry point.
144///
145/// Since Winit depends on a specific version of `android_activity` the simplest
146/// way to avoid creating a conflict is for applications to avoid explicitly
147/// depending on the `android_activity` crate, and instead consume the API that
148/// is re-exported by Winit.
149///
150/// For compatibility applications should then import the `AndroidApp` type for
151/// their `android_main(app: AndroidApp)` function like:
152/// ```rust
153/// #[cfg(target_os = "android")]
154/// use winit::platform::android::activity::AndroidApp;
155/// ```
156pub mod activity {
157 // We enable the `"native-activity"` feature just so that we can build the
158 // docs, but it'll be very confusing for users to see the docs with that
159 // feature enabled, so we avoid inlining it so that they're forced to view
160 // it on the crate's own docs.rs page.
161 #[doc(no_inline)]
162 #[cfg(android_platform)]
163 pub use android_activity::*;
164
165 #[cfg(not(android_platform))]
166 #[doc(hidden)]
167 pub struct Rect;
168 #[cfg(not(android_platform))]
169 #[doc(hidden)]
170 pub struct ConfigurationRef;
171 #[cfg(not(android_platform))]
172 #[doc(hidden)]
173 pub struct AndroidApp;
174}