cranpose_ui/
text_input_session.rs

1//! Platform text-input session: soft-keyboard visibility hooks.
2//!
3//! Platforms with an on-screen keyboard (Android, iOS, some Linux shells)
4//! install a [`PlatformTextInputHandler`] so the framework can tell them when
5//! editable text gains or loses focus. The text-field focus manager
6//! ([`crate::text_field_focus`]) fires these notifications:
7//!
8//! - a text field requests the keyboard → `notify_text_input_focus_gained` →
9//!   `show_keyboard`
10//! - focus was explicitly cleared, or the focused field left the composition →
11//!   `notify_text_input_focus_lost` → `hide_keyboard`
12//!
13//! Focus requests show the keyboard when the field's `show_keyboard_on_focus`
14//! option is true. A pointer tap always requests it, including on an
15//! already-focused field. The user may have dismissed the
16//! keyboard (e.g. Android back gesture) without the framework knowing, and
17//! tapping the field again must bring it back. Platform show/hide calls are
18//! expected to be idempotent. `hide_keyboard` is only forwarded when the
19//! framework previously requested the keyboard, so repeated stale-focus checks
20//! do not spam the platform.
21//!
22//! The handler is stored per [`AppContext`](crate::render_state::AppContext),
23//! like the focus state itself, so multiple app instances in one process do
24//! not observe each other's keyboards.
25
26use std::{
27    cell::{Cell, RefCell},
28    rc::Rc,
29};
30
31/// Callbacks a platform installs to control its on-screen keyboard.
32///
33/// Implementations must be idempotent: `show_keyboard` may be invoked while
34/// the keyboard is already visible (every tap on a text field re-requests it)
35/// and `hide_keyboard` may race a keyboard the user already dismissed.
36pub trait PlatformTextInputHandler {
37    /// A focused text field requests its software keyboard.
38    fn show_keyboard(&self);
39    /// No text field is focused anymore; the platform should hide its soft
40    /// keyboard.
41    fn hide_keyboard(&self);
42}
43
44pub(crate) struct PlatformTextInputState {
45    handler: RefCell<Option<Rc<dyn PlatformTextInputHandler>>>,
46    keyboard_requested: Cell<bool>,
47}
48
49impl PlatformTextInputState {
50    pub(crate) fn new() -> Self {
51        Self {
52            handler: RefCell::new(None),
53            keyboard_requested: Cell::new(false),
54        }
55    }
56
57    fn set_handler(&self, handler: Option<Rc<dyn PlatformTextInputHandler>>) {
58        *self.handler.borrow_mut() = handler;
59        self.keyboard_requested.set(false);
60    }
61
62    fn handler(&self) -> Option<Rc<dyn PlatformTextInputHandler>> {
63        self.handler.borrow().clone()
64    }
65}
66
67/// Installs the platform soft-keyboard handler for the current app context.
68///
69/// Replaces any previously installed handler. Must be called inside an app
70/// context (platform runtimes go through
71/// `AppShell::set_platform_text_input`).
72pub fn set_platform_text_input_handler(handler: Rc<dyn PlatformTextInputHandler>) {
73    crate::render_state::with_text_input_session(|state| state.set_handler(Some(handler)));
74}
75
76/// Removes the installed platform soft-keyboard handler, if any.
77pub fn clear_platform_text_input_handler() {
78    crate::render_state::with_text_input_session(|state| state.set_handler(None));
79}
80
81pub(crate) fn notify_text_input_focus_gained() {
82    let handler = crate::render_state::with_text_input_session(|state| {
83        let handler = state.handler();
84        if handler.is_some() {
85            state.keyboard_requested.set(true);
86        }
87        handler
88    });
89    if let Some(handler) = handler {
90        handler.show_keyboard();
91    }
92}
93
94pub(crate) fn notify_text_input_focus_lost() {
95    let handler = crate::render_state::with_text_input_session(|state| {
96        if !state.keyboard_requested.replace(false) {
97            return None;
98        }
99        state.handler()
100    });
101    if let Some(handler) = handler {
102        handler.hide_keyboard();
103    }
104}
105
106/// Notifies the framework that the host app was paused (backgrounded — e.g.
107/// Android `onPause`).
108///
109/// Any outstanding soft-keyboard request is withdrawn and the platform is told
110/// to hide its keyboard, clearing the "keyboard shown" state so it cannot
111/// survive into the next resume. Without this, a platform that remembers the
112/// last editor view (Android's `InputMethodManager`) re-shows the keyboard when
113/// the app returns to the foreground even though the framework no longer has a
114/// focused field. Gated on an outstanding request, so it is a no-op when the
115/// keyboard was not showing.
116pub fn notify_app_paused() {
117    notify_text_input_focus_lost();
118}
119
120/// Notifies the framework that the host app resumed (foregrounded — e.g.
121/// Android `onResume`).
122///
123/// The soft keyboard is **never** auto-shown on resume, even when a text field
124/// is still focused. A warm resume (return from HOME / task switch / back-exit
125/// then relaunch) restores the process with the field's focus and caret intact,
126/// but the framework must not resurrect the keyboard for it: the platform's
127/// `InputMethodManager` remembers the last editor and would otherwise pop the
128/// keyboard back open on its own. The user brings it back by tapping the field
129/// (which re-requests it through `notify_text_input_focus_gained`).
130///
131/// Always returns `false` so the platform runtime force-hides the OS-restored
132/// keyboard. Pruning stale focus here keeps the keyboard-request bookkeeping
133/// consistent (a focused-but-detached field is dropped and its outstanding
134/// request withdrawn) without ever calling `show`.
135pub fn notify_app_resumed() -> bool {
136    let _ = crate::text_field_focus::has_focused_field();
137    false
138}
139
140#[cfg(test)]
141#[path = "tests/text_input_session_tests.rs"]
142mod tests;
cranpose_ui/text_input_session.rs

cranpose_ui/
text_input_session.rs
