Copy `winit` docs for `input_method::Event`

1 files changed, 64 insertions, 12 deletions

diff --git a/core/src/input_method.rs b/core/src/input_method.rs
index ceda39c3..d282d404 100644
--- a/core/src/input_method.rs
+++ b/core/src/input_method.rs
@@ -1,24 +1,76 @@
 //! Listen to input method events.
+use std::ops::Range;
 
-/// A input method event.
+/// Describes [input method](https://en.wikipedia.org/wiki/Input_method) events.
 ///
-/// _**Note:** This type is largely incomplete! If you need to track
-/// additional events, feel free to [open an issue] and share your use case!_
+/// This is also called a "composition event".
 ///
-/// [open an issue]: https://github.com/iced-rs/iced/issues
-#[derive(Debug, Clone, PartialEq, Eq)]
+/// Most keypresses using a latin-like keyboard layout simply generate a
+/// [`WindowEvent::KeyboardInput`]. However, one couldn't possibly have a key for every single
+/// unicode character that the user might want to type
+/// - so the solution operating systems employ is to allow the user to type these using _a sequence
+///   of keypresses_ instead.
+///
+/// A prominent example of this is accents - many keyboard layouts allow you to first click the
+/// "accent key", and then the character you want to apply the accent to. In this case, some
+/// platforms will generate the following event sequence:
+///
+/// ```ignore
+/// // Press "`" key
+/// Ime::Preedit("`", Some((0, 0)))
+/// // Press "E" key
+/// Ime::Preedit("", None) // Synthetic event generated by winit to clear preedit.
+/// Ime::Commit("é")
+/// ```
+///
+/// Additionally, certain input devices are configured to display a candidate box that allow the
+/// user to select the desired character interactively. (To properly position this box, you must use
+/// [`Window::set_ime_cursor_area`].)
+///
+/// An example of a keyboard layout which uses candidate boxes is pinyin. On a latin keyboard the
+/// following event sequence could be obtained:
+///
+/// ```ignore
+/// // Press "A" key
+/// Ime::Preedit("a", Some((1, 1)))
+/// // Press "B" key
+/// Ime::Preedit("a b", Some((3, 3)))
+/// // Press left arrow key
+/// Ime::Preedit("a b", Some((1, 1)))
+/// // Press space key
+/// Ime::Preedit("啊b", Some((3, 3)))
+/// // Press space key
+/// Ime::Preedit("", None) // Synthetic event generated by winit to clear preedit.
+/// Ime::Commit("啊不")
+/// ```
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Event {
-    // These events correspond to underlying winit ime events.
-    // https://docs.rs/winit/latest/winit/event/enum.Ime.html
-    /// the IME was enabled.
+    /// Notifies when the IME was enabled.
+    ///
+    /// After getting this event you could receive [`Preedit`][Self::Preedit] and
+    /// [`Commit`][Self::Commit] events. You should also start performing IME related requests
+    /// like [`Window::set_ime_cursor_area`].
     Enabled,
 
-    /// new composing text should be set at the cursor position.
-    Preedit(String, Option<(usize, usize)>),
+    /// Notifies when a new composing text should be set at the cursor position.
+    ///
+    /// The value represents a pair of the preedit string and the cursor begin position and end
+    /// position. When it's `None`, the cursor should be hidden. When `String` is an empty string
+    /// this indicates that preedit was cleared.
+    ///
+    /// The cursor range is byte-wise indexed.
+    Preedit(String, Option<Range<usize>>),
 
-    /// text should be inserted into the editor widget.
+    /// Notifies when text should be inserted into the editor widget.
+    ///
+    /// Right before this event winit will send empty [`Self::Preedit`] event.
     Commit(String),
 
-    /// the IME was disabled.
+    /// Notifies when the IME was disabled.
+    ///
+    /// After receiving this event you won't get any more [`Preedit`][Self::Preedit] or
+    /// [`Commit`][Self::Commit] events until the next [`Enabled`][Self::Enabled] event. You should
+    /// also stop issuing IME related requests like [`Window::set_ime_cursor_area`] and clear
+    /// pending preedit text.
     Disabled,
 }