add Input Method Editor support (bevyengine#7325)

# Objective

- Fix bevyengine#7315
- Add IME support

## Solution

- Add two new fields to `Window`, to control if IME is enabled and the candidate box position

This allows the use of dead keys which are needed in French, or the full IME experience to type using Pinyin

I also added a basic general text input example that can handle IME input.

https://user-images.githubusercontent.com/8672791/213941353-5ed73a73-5dd1-4e66-a7d6-a69b49694c52.mp4

Cargo.toml

@@ -1147,6 +1147,16 @@ description = "Prints out all touch inputs"
 category = "Input"
 wasm = false
 
+[[example]]
+name = "text_input"
+path = "examples/input/text_input.rs"
+
+[package.metadata.example.text_input]
+name = "Text Input"
+description = "Simple text input with IME support"
+category = "Input"
+wasm = false
+
 # Reflection
 [[example]]
 name = "reflection"

crates/bevy_window/src/event.rs

@@ -153,6 +153,52 @@ pub struct ReceivedCharacter {
     pub char: char,
 }
 
+/// A Input Method Editor event.
+///
+/// This event is the translated version of the `WindowEvent::Ime` from the `winit` crate.
+///
+/// It is only sent if IME was enabled on the window with [`Window::ime_enabled`](crate::window::Window::ime_enabled).
+#[derive(Debug, Clone, PartialEq, Eq, Reflect, FromReflect)]
+#[reflect(Debug, PartialEq)]
+#[cfg_attr(
+    feature = "serialize",
+    derive(serde::Serialize, serde::Deserialize),
+    reflect(Serialize, Deserialize)
+)]
+pub enum Ime {
+    /// Notifies when a new composing text should be set at the cursor position.
+    Preedit {
+        /// Window that received the event.
+        window: Entity,
+        /// Current value.
+        value: String,
+        /// Cursor begin and end position.
+        ///
+        /// `None` indicated the cursor should be hidden
+        cursor: Option<(usize, usize)>,
+    },
+    /// Notifies when text should be inserted into the editor widget.
+    Commit {
+        /// Window that received the event.
+        window: Entity,
+        /// Input string
+        value: String,
+    },
+    /// Notifies when the IME was enabled.
+    ///
+    /// After this event, you will receive events `Ime::Preedit` and `Ime::Commit`,
+    /// and stop receiving events [`ReceivedCharacter`].
+    Enabled {
+        /// Window that received the event.
+        window: Entity,
+    },
+    /// Notifies when the IME was disabled.
+    Disabled {
+        /// Window that received the event.
+        window: Entity,
+    },
+}
+
 /// An event that indicates a window has received or lost focus.
 #[derive(Debug, Clone, PartialEq, Eq, Reflect, FromReflect)]
 #[reflect(Debug, PartialEq)]

crates/bevy_window/src/lib.rs

@@ -15,7 +15,7 @@ pub use window::*;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        CursorEntered, CursorIcon, CursorLeft, CursorMoved, FileDragAndDrop, MonitorSelection,
+        CursorEntered, CursorIcon, CursorLeft, CursorMoved, FileDragAndDrop, Ime, MonitorSelection,
         ReceivedCharacter, Window, WindowMoved, WindowPlugin, WindowPosition,
         WindowResizeConstraints,
     };
@@ -79,6 +79,7 @@ impl Plugin for WindowPlugin {
             .add_event::<CursorEntered>()
             .add_event::<CursorLeft>()
             .add_event::<ReceivedCharacter>()
+            .add_event::<Ime>()
             .add_event::<WindowFocused>()
             .add_event::<WindowScaleFactorChanged>()
             .add_event::<WindowBackendScaleFactorChanged>()

crates/bevy_window/src/window.rs

@@ -167,6 +167,24 @@ pub struct Window {
     pub prevent_default_event_handling: bool,
     /// Stores internal state that isn't directly accessible.
     pub internal: InternalWindowState,
+    /// Should the window use Input Method Editor?
+    ///
+    /// If enabled, the window will receive [`Ime`](crate::Ime) events instead of
+    /// [`ReceivedCharacter`](crate::ReceivedCharacter) or
+    /// [`KeyboardInput`](bevy_input::keyboard::KeyboardInput).
+    ///
+    /// IME should be enabled during text input, but not when you expect to get the exact key pressed.
+    ///
+    ///  ## Platform-specific
+    ///
+    /// - iOS / Android / Web: Unsupported.
+    pub ime_enabled: bool,
+    /// Sets location of IME candidate box in client area coordinates relative to the top left.
+    ///
+    ///  ## Platform-specific
+    ///
+    /// - iOS / Android / Web: Unsupported.
+    pub ime_position: Vec2,
 }
 
 impl Default for Window {
@@ -181,6 +199,8 @@ impl Default for Window {
             internal: Default::default(),
             composite_alpha_mode: Default::default(),
             resize_constraints: Default::default(),
+            ime_enabled: Default::default(),
+            ime_position: Default::default(),
             resizable: true,
             decorations: true,
             transparent: false,

crates/bevy_winit/src/lib.rs

@@ -25,9 +25,10 @@ use bevy_utils::{
     Instant,
 };
 use bevy_window::{
-    CursorEntered, CursorLeft, CursorMoved, FileDragAndDrop, ModifiesWindows, ReceivedCharacter,
-    RequestRedraw, Window, WindowBackendScaleFactorChanged, WindowCloseRequested, WindowCreated,
-    WindowFocused, WindowMoved, WindowResized, WindowScaleFactorChanged,
+    CursorEntered, CursorLeft, CursorMoved, FileDragAndDrop, Ime, ModifiesWindows,
+    ReceivedCharacter, RequestRedraw, Window, WindowBackendScaleFactorChanged,
+    WindowCloseRequested, WindowCreated, WindowFocused, WindowMoved, WindowResized,
+    WindowScaleFactorChanged,
 };
 
 use winit::{
@@ -170,6 +171,7 @@ struct InputEvents<'w> {
     mouse_button_input: EventWriter<'w, MouseButtonInput>,
     mouse_wheel_input: EventWriter<'w, MouseWheel>,
     touch_input: EventWriter<'w, TouchInput>,
+    ime_input: EventWriter<'w, Ime>,
 }
 
 #[derive(SystemParam)]
@@ -555,6 +557,25 @@ pub fn winit_runner(mut app: App) {
                             position,
                         });
                     }
+                    WindowEvent::Ime(event) => match event {
+                        event::Ime::Preedit(value, cursor) => {
+                            input_events.ime_input.send(Ime::Preedit {
+                                window: window_entity,
+                                value,
+                                cursor,
+                            });
+                        }
+                        event::Ime::Commit(value) => input_events.ime_input.send(Ime::Commit {
+                            window: window_entity,
+                            value,
+                        }),
+                        event::Ime::Enabled => input_events.ime_input.send(Ime::Enabled {
+                            window: window_entity,
+                        }),
+                        event::Ime::Disabled => input_events.ime_input.send(Ime::Disabled {
+                            window: window_entity,
+                        }),
+                    },
                     _ => {}
                 }
             }

crates/bevy_winit/src/system.rs

@@ -13,7 +13,7 @@ use bevy_window::{RawHandleWrapper, Window, WindowClosed, WindowCreated};
 use raw_window_handle::{HasRawDisplayHandle, HasRawWindowHandle};
 
 use winit::{
-    dpi::{LogicalSize, PhysicalPosition, PhysicalSize},
+    dpi::{LogicalPosition, LogicalSize, PhysicalPosition, PhysicalSize},
     event_loop::EventLoopWindowTarget,
 };
 
@@ -278,6 +278,17 @@ pub(crate) fn changed_window(
                 );
             }
 
+            if window.ime_enabled != previous.ime_enabled {
+                winit_window.set_ime_allowed(window.ime_enabled);
+            }
+
+            if window.ime_position != previous.ime_position {
+                winit_window.set_ime_position(LogicalPosition::new(
+                    window.ime_position.x,
+                    window.ime_position.y,
+                ));
+            }
+
             info.previous = window.clone();
         }
     }

examples/README.md

@@ -234,6 +234,7 @@ Example | Description
 [Mouse Grab](../examples/input/mouse_grab.rs) | Demonstrates how to grab the mouse, locking the cursor to the app's screen
 [Mouse Input](../examples/input/mouse_input.rs) | Demonstrates handling a mouse button press/release
 [Mouse Input Events](../examples/input/mouse_input_events.rs) | Prints out all mouse events (buttons, movement, etc.)
+[Text Input](../examples/input/text_input.rs) | Simple text input with IME support
 [Touch Input](../examples/input/touch_input.rs) | Displays touch presses, releases, and cancels
 [Touch Input Events](../examples/input/touch_input_events.rs) | Prints out all touch inputs