Input Methods

An input method composes text from what is typed, as for Chinese and Japanese: the user types, sees the text being composed, and chooses the result from the input method's candidates. A text field takes text from one while it has the focus.

Taking text from an input method

(win:start-text-input window)                        ; the field gains the focus
(win:set-text-input-caret window x y 2 line-height)  ; its caret, in window coordinates
(win:set-text-input-surrounding window line cursor)  ; the text around the caret
…
(win:stop-text-input window)                         ; the field loses the focus

• start-text-input has the window take text from the input method, and stop-text-input ends it, dropping any text being composed, with a :preedit of "" if there was some. text-input-active-p says whether the window takes text now.
• set-text-input-caret tells the input method where the caret is, as a rectangle in the window's coordinates, such as the caret's line with the text being composed in it. The input method shows its candidates beside it without covering it.
• set-text-input-surrounding tells it the text around the caret, without the text being composed, and the caret's place in it as a character index; an optional anchor is the other end of the selection. Give the line or paragraph being edited rather than a whole document. An input method may then convert text already typed, or ask to delete some.
• text-input-caret and text-input-surrounding return what was given last; both are forgotten at stop-text-input.

Give the caret and the surrounding text again whenever they change, as after handling the input method's events. Unchanged ones cost nothing, so a text field may give them every frame.

The events

While a window takes text, the input method's work arrives as events, in the order to apply them:

Type	Meaning	Fields
:delete-surrounding	Delete characters around the caret.	event-delete-before characters before the caret, event-delete-after after it
:text	The text the user chose, to insert at the caret, as typing's.	event-text
:preedit	The text being composed, to show at the caret, underlined and apart from the field's text, until the next :preedit replaces it; "" when nothing is composed.	event-text, and event-caret-start and event-caret-end, the input method's caret in it, or nil

(case (win:event-type event)
  (:delete-surrounding
   (delete-around-caret (win:event-delete-before event) (win:event-delete-after event)))
  (:text
   (insert-at-caret (copy-seq (win:event-text event))))
  (:preedit
   (show-preedit (copy-seq (win:event-text event))
                 (win:event-caret-start event) (win:event-caret-end event))))

delete-around-caret, insert-at-caret and show-preedit stand for your own code. The text of an event is overwritten by the next poll-event into it: copy it, or the whole event with copy-event, to keep it.

Typing without an input method, and keys an input method does not take, still come as :key-press and :text events, as before.

On each platform

• Wayland: input methods speak text-input-v3, where the compositor offers it.
• Windows: input methods speak IMM32. A window's input method is off while it takes no text input, so keys reach it as they are typed. Windows' input methods are not told the surrounding text, so they never ask to delete some, and they do not compose in popups.