Skip to main content

gpui/
input.rs

1use crate::{App, Bounds, Context, Entity, InputHandler, Pixels, UTF16Selection, Window};
2use std::ops::Range;
3
4/// Implement this trait to allow views to handle textual input when implementing an editor, field, etc.
5///
6/// Once your view implements this trait, you can use it to construct an [`ElementInputHandler<V>`].
7/// This input handler can then be assigned during paint by calling [`Window::handle_input`].
8///
9/// All text offsets and ranges use UTF-16 code units, not UTF-8 bytes or graphemes.
10/// Geometry uses window-local logical pixels, including `element_bounds`.
11/// Registration is frame-scoped: [`Window::handle_input`] installs the handler
12/// for the focused element during paint. Replacing a handler does not itself
13/// call `unmark_text` or synthesize a commit. Consumers must not rely on a
14/// focus change alone to finalize their composition state; native IME lifecycle
15/// callbacks and application focus policy must be considered together.
16/// See [`InputHandler`] for details on how to implement each method.
17pub trait EntityInputHandler: 'static + Sized {
18    /// See [`InputHandler::text_for_range`] for details
19    fn text_for_range(
20        &mut self,
21        range: Range<usize>,
22        adjusted_range: &mut Option<Range<usize>>,
23        window: &mut Window,
24        cx: &mut Context<Self>,
25    ) -> Option<String>;
26
27    /// See [`InputHandler::selected_text_range`] for details
28    fn selected_text_range(
29        &mut self,
30        ignore_disabled_input: bool,
31        window: &mut Window,
32        cx: &mut Context<Self>,
33    ) -> Option<UTF16Selection>;
34
35    /// See [`InputHandler::marked_text_range`] for details
36    fn marked_text_range(
37        &self,
38        window: &mut Window,
39        cx: &mut Context<Self>,
40    ) -> Option<Range<usize>>;
41
42    /// See [`InputHandler::unmark_text`] for details
43    fn unmark_text(&mut self, window: &mut Window, cx: &mut Context<Self>);
44
45    /// See [`InputHandler::replace_text_in_range`] for details
46    fn replace_text_in_range(
47        &mut self,
48        range: Option<Range<usize>>,
49        text: &str,
50        window: &mut Window,
51        cx: &mut Context<Self>,
52    );
53
54    /// See [`InputHandler::replace_and_mark_text_in_range`] for details
55    fn replace_and_mark_text_in_range(
56        &mut self,
57        range: Option<Range<usize>>,
58        new_text: &str,
59        new_selected_range: Option<Range<usize>>,
60        window: &mut Window,
61        cx: &mut Context<Self>,
62    );
63
64    /// See [`InputHandler::bounds_for_range`] for details
65    fn bounds_for_range(
66        &mut self,
67        range_utf16: Range<usize>,
68        element_bounds: Bounds<Pixels>,
69        window: &mut Window,
70        cx: &mut Context<Self>,
71    ) -> Option<Bounds<Pixels>>;
72
73    /// See [`InputHandler::character_index_for_point`] for details
74    fn character_index_for_point(
75        &mut self,
76        point: crate::Point<Pixels>,
77        window: &mut Window,
78        cx: &mut Context<Self>,
79    ) -> Option<usize>;
80
81    /// See [`InputHandler::set_selected_text_range`] for details
82    fn set_selected_text_range(
83        &mut self,
84        _range_utf16: Range<usize>,
85        _window: &mut Window,
86        _cx: &mut Context<Self>,
87    ) {
88    }
89
90    /// See [`InputHandler::text_length_utf16`] for details
91    fn text_length_utf16(
92        &mut self,
93        _window: &mut Window,
94        _cx: &mut Context<Self>,
95    ) -> Option<usize> {
96        None
97    }
98
99    /// See [`InputHandler::accepts_text_input`] for details
100    fn accepts_text_input(&self, _window: &mut Window, _cx: &mut Context<Self>) -> bool {
101        true
102    }
103}
104
105/// The canonical implementation of [`crate::PlatformInputHandler`]. Call [`Window::handle_input`]
106/// with an instance during your element's paint.
107pub struct ElementInputHandler<V> {
108    view: Entity<V>,
109    element_bounds: Bounds<Pixels>,
110}
111
112impl<V: 'static> ElementInputHandler<V> {
113    /// Used in [`Element::paint`][element_paint] with the element's bounds, a `Window`, and a `App` context.
114    ///
115    /// [element_paint]: crate::Element::paint
116    pub fn new(element_bounds: Bounds<Pixels>, view: Entity<V>) -> Self {
117        ElementInputHandler {
118            view,
119            element_bounds,
120        }
121    }
122}
123
124impl<V: EntityInputHandler> InputHandler for ElementInputHandler<V> {
125    fn selected_text_range(
126        &mut self,
127        ignore_disabled_input: bool,
128        window: &mut Window,
129        cx: &mut App,
130    ) -> Option<UTF16Selection> {
131        self.view.update(cx, |view, cx| {
132            view.selected_text_range(ignore_disabled_input, window, cx)
133        })
134    }
135
136    fn marked_text_range(&mut self, window: &mut Window, cx: &mut App) -> Option<Range<usize>> {
137        self.view
138            .update(cx, |view, cx| view.marked_text_range(window, cx))
139    }
140
141    fn text_for_range(
142        &mut self,
143        range_utf16: Range<usize>,
144        adjusted_range: &mut Option<Range<usize>>,
145        window: &mut Window,
146        cx: &mut App,
147    ) -> Option<String> {
148        self.view.update(cx, |view, cx| {
149            view.text_for_range(range_utf16, adjusted_range, window, cx)
150        })
151    }
152
153    fn replace_text_in_range(
154        &mut self,
155        replacement_range: Option<Range<usize>>,
156        text: &str,
157        window: &mut Window,
158        cx: &mut App,
159    ) {
160        self.view.update(cx, |view, cx| {
161            view.replace_text_in_range(replacement_range, text, window, cx)
162        });
163    }
164
165    fn replace_and_mark_text_in_range(
166        &mut self,
167        range_utf16: Option<Range<usize>>,
168        new_text: &str,
169        new_selected_range: Option<Range<usize>>,
170        window: &mut Window,
171        cx: &mut App,
172    ) {
173        self.view.update(cx, |view, cx| {
174            view.replace_and_mark_text_in_range(
175                range_utf16,
176                new_text,
177                new_selected_range,
178                window,
179                cx,
180            )
181        });
182    }
183
184    fn unmark_text(&mut self, window: &mut Window, cx: &mut App) {
185        self.view
186            .update(cx, |view, cx| view.unmark_text(window, cx));
187    }
188
189    fn bounds_for_range(
190        &mut self,
191        range_utf16: Range<usize>,
192        window: &mut Window,
193        cx: &mut App,
194    ) -> Option<Bounds<Pixels>> {
195        self.view.update(cx, |view, cx| {
196            view.bounds_for_range(range_utf16, self.element_bounds, window, cx)
197        })
198    }
199
200    fn character_index_for_point(
201        &mut self,
202        point: crate::Point<Pixels>,
203        window: &mut Window,
204        cx: &mut App,
205    ) -> Option<usize> {
206        self.view.update(cx, |view, cx| {
207            view.character_index_for_point(point, window, cx)
208        })
209    }
210
211    fn set_selected_text_range(
212        &mut self,
213        range_utf16: Range<usize>,
214        window: &mut Window,
215        cx: &mut App,
216    ) {
217        self.view.update(cx, |view, cx| {
218            view.set_selected_text_range(range_utf16, window, cx)
219        })
220    }
221
222    fn element_bounds(&mut self, _window: &mut Window, _cx: &mut App) -> Option<Bounds<Pixels>> {
223        Some(self.element_bounds)
224    }
225
226    fn text_length_utf16(&mut self, window: &mut Window, cx: &mut App) -> Option<usize> {
227        self.view
228            .update(cx, |view, cx| view.text_length_utf16(window, cx))
229    }
230
231    fn accepts_text_input(&mut self, window: &mut Window, cx: &mut App) -> bool {
232        self.view
233            .update(cx, |view, cx| view.accepts_text_input(window, cx))
234    }
235
236    fn prefers_ime_for_printable_keys(&mut self, window: &mut Window, cx: &mut App) -> bool {
237        self.view
238            .update(cx, |view, cx| view.accepts_text_input(window, cx))
239    }
240}