Struct android_activity::AndroidApp

source ·
pub struct AndroidApp { /* private fields */ }
Expand description

The top-level state and interface for a native Rust application

AndroidApp provides an interface to query state for the application as well as monitor events, such as lifecycle and input events, that are marshalled between the Java thread that owns the Activity and the native thread that runs the android_main() code.

§Cheaply Clonable AndroidApp

AndroidApp is intended to be something that can be cheaply passed around by referenced within an application. It is reference counted and can be cheaply cloned.

§Send and Sync AndroidApp

Although an AndroidApp implements Send and Sync you do need to take into consideration that some APIs, such as AndroidApp::poll_events() are explicitly documented to only be usable from your android_main() thread.

Implementations§

source§

impl AndroidApp

source

pub fn native_window(&self) -> Option<NativeWindow>

Queries the current NativeWindow for the application.

This will only return Some(window) between MainEvent::InitWindow and MainEvent::TerminateWindow events.

source

pub fn vm_as_ptr(&self) -> *mut c_void

Returns a pointer to the Java Virtual Machine, for making JNI calls

This returns a pointer to the Java Virtual Machine which can be used with the jni crate (or similar crates) to make JNI calls that bridge between native Rust code and Java/Kotlin code running within the JVM.

If you use the jni crate you can wrap this as a JavaVM via:

let vm = unsafe { JavaVM::from_raw(app.vm_as_ptr()) };
source

pub fn activity_as_ptr(&self) -> *mut c_void

Returns a JNI object reference for this application’s JVM Activity as a pointer

If you use the jni crate you can wrap this as an object reference via:

let activity = unsafe { JObject::from_raw(app.activity_as_ptr()) };
§JNI Safety

Note that the object reference will be a JNI global reference, not a local reference and it should not be deleted. Don’t wrap the reference in an AutoLocal which would try to explicitly delete the reference when dropped. Similarly, don’t wrap the reference as a GlobalRef which would also try to explicitly delete the reference when dropped.

source

pub fn poll_events<F>(&self, timeout: Option<Duration>, callback: F)
where F: FnMut(PollEvent<'_>),

Polls for any events associated with this AndroidApp and processes those events (such as lifecycle events) via the given callback.

It’s important to use this API for polling, and not call ALooper_pollAll directly since some events require pre- and post-processing either side of the callback. For correct behavior events should be handled immediately, before returning from the callback and not simply queued for batch processing later. For example the existing NativeWindow is accessible during a MainEvent::TerminateWindow callback and will be set to None once the callback returns, and this is also synchronized with the Java main thread. The MainEvent::SaveState event is also synchronized with the Java main thread.

§Panics

This must only be called from your android_main() thread and it may panic if called from another thread.

source

pub fn create_waker(&self) -> AndroidAppWaker

Creates a means to wake up the main loop while it is blocked waiting for events within AndroidApp::poll_events().

source

pub fn config(&self) -> ConfigurationRef

Returns a (cheaply clonable) reference to this application’s ndk::configuration::Configuration

source

pub fn content_rect(&self) -> Rect

Queries the current content rectangle of the window; this is the area where the window’s content should be placed to be seen by the user.

source

pub fn asset_manager(&self) -> AssetManager

Queries the Asset Manager instance for the application.

Use this to access binary assets bundled inside your application’s .apk file.

source

pub fn set_window_flags( &self, add_flags: WindowManagerFlags, remove_flags: WindowManagerFlags )

Change the window flags of the given activity.

Note that some flags must be set before the window decoration is created, see <https://developer.android.com/reference/android/view/Window#setFlags(int,%20int)>.

source

pub fn enable_motion_axis(&self, axis: Axis)

Enable additional input axis

To reduce overhead, by default only input::Axis::X and input::Axis::Y are enabled and other axis should be enabled explicitly.

source

pub fn disable_motion_axis(&self, axis: Axis)

Disable input axis

To reduce overhead, by default only input::Axis::X and input::Axis::Y are enabled and other axis should be enabled explicitly.

source

pub fn show_soft_input(&self, show_implicit: bool)

Explicitly request that the current input method’s soft input area be shown to the user, if needed.

Call this if the user interacts with your view in such a way that they have expressed they would like to start performing input into it.

source

pub fn hide_soft_input(&self, hide_implicit_only: bool)

Request to hide the soft input window from the context of the window that is currently accepting input.

This should be called as a result of the user doing some action that fairly explicitly requests to have the input window hidden.

source

pub fn text_input_state(&self) -> TextInputState

Fetch the current input text state, as updated by any active IME.

source

pub fn set_text_input_state(&self, state: TextInputState)

Forward the given input text state to any active IME.

source

pub fn input_events_iter(&self) -> Result<InputIterator<'_>>

Get an exclusive, lending iterator over buffered input events

Applications are expected to call this in-sync with their rendering or in response to a MainEvent::InputAvailable event being delivered.

Note: your application is will only be delivered a single MainEvent::InputAvailable event between calls to this API.

To reduce overhead, by default, only input::Axis::X and input::Axis::Y are enabled and other axis should be enabled explicitly via Self::enable_motion_axis.

This isn’t the most ergonomic iteration API since we can’t return a standard Iterator:

  • This API returns a lending iterator may borrow from the internal buffer of pending events without copying them.
  • For each event we want to ensure the application reports whether the event was handled.
§Example

Code to iterate all pending input events would look something like this:

match app.input_events_iter() {
    Ok(mut iter) => {
        loop {
            let read_input = iter.next(|event| {
                let handled = match event {
                    InputEvent::KeyEvent(key_event) => {
                        // Snip
                    }
                    InputEvent::MotionEvent(motion_event) => {
                        // Snip
                    }
                    event => {
                        // Snip
                    }
                };

                handled
            });

            if !read_input {
                break;
            }
        }
    }
    Err(err) => {
        log::error!("Failed to get input events iterator: {err:?}");
    }
}
§Panics

This must only be called from your android_main() thread and it may panic if called from another thread.

source

pub fn device_key_character_map( &self, device_id: i32 ) -> Result<KeyCharacterMap>

Lookup the KeyCharacterMap for the given input device_id

Use KeyCharacterMap::get to map key codes + meta state into unicode characters or dead keys that compose with the next key.

§Example

Code to handle unicode character mapping as well as combining dead keys could look some thing like:

let mut combining_accent = None;
// Snip

let combined_key_char = if let Ok(map) = app.device_key_character_map(device_id) {
    match map.get(key_event.key_code(), key_event.meta_state()) {
        Ok(KeyMapChar::Unicode(unicode)) => {
            let combined_unicode = if let Some(accent) = combining_accent {
                match map.get_dead_char(accent, unicode) {
                    Ok(Some(key)) => {
                        info!("KeyEvent: Combined '{unicode}' with accent '{accent}' to give '{key}'");
                        Some(key)
                    }
                    Ok(None) => None,
                    Err(err) => {
                        log::error!("KeyEvent: Failed to combine 'dead key' accent '{accent}' with '{unicode}': {err:?}");
                        None
                    }
                }
            } else {
                info!("KeyEvent: Pressed '{unicode}'");
                Some(unicode)
            };
            combining_accent = None;
            combined_unicode.map(|unicode| KeyMapChar::Unicode(unicode))
        }
        Ok(KeyMapChar::CombiningAccent(accent)) => {
            info!("KeyEvent: Pressed 'dead key' combining accent '{accent}'");
            combining_accent = Some(accent);
            Some(KeyMapChar::CombiningAccent(accent))
        }
        Ok(KeyMapChar::None) => {
            info!("KeyEvent: Pressed non-unicode key");
            combining_accent = None;
            None
        }
        Err(err) => {
            log::error!("KeyEvent: Failed to get key map character: {err:?}");
            combining_accent = None;
            None
        }
    }
} else {
    None
};
§Errors

Since this API needs to use JNI internally to call into the Android JVM it may return a error::AppError::JavaError in case there is a spurious JNI error or an exception is caught.

source

pub fn sdk_version() -> i32

The user-visible SDK version of the framework

Also referred to as Build.VERSION_CODES

source

pub fn internal_data_path(&self) -> Option<PathBuf>

Path to this application’s internal data directory

source

pub fn external_data_path(&self) -> Option<PathBuf>

Path to this application’s external data directory

source

pub fn obb_path(&self) -> Option<PathBuf>

Path to the directory containing the application’s OBB files (if any).

Trait Implementations§

source§

impl Clone for AndroidApp

source§

fn clone(&self) -> AndroidApp

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for AndroidApp

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Hash for AndroidApp

source§

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl PartialEq for AndroidApp

source§

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for AndroidApp

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.