diff --git a/docs/input.dox b/docs/input.dox index 814e1ea8..6bfa5e08 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -220,9 +220,8 @@ All desktop operating systems support IME (Input Method Editor) to input charact that are not mapped with physical keys. IME have been popular among East Asian people. And some operating systems start supporting voice input via IME mechanism. -GLFW provides IME support functions to help -you implement better text input features. You should add suitable visualization code for -preedit text. +GLFW provides IME support functions to help you implement better text input features. +You should add suitable visualization code for preedit text. IME works in front of actual character input events (@ref input_char). If your application uses text input and you want to support IME, @@ -232,7 +231,7 @@ you should register preedit callback to receive preedit text before committed. glfwSetPreeditCallback(window, preedit_callback); @endcode -The callback function receives chunk of text and focused block information. +The callback receives the following information. @code void preedit_callback(GLFWwindow* window, @@ -245,9 +244,11 @@ void preedit_callback(GLFWwindow* window, } @endcode -"preedit_length" and "preedit_string" parameter represent whole preedit text. Each character of the preedit string is a codepoint like @ref input_char. +"preedit_length" and "preedit_string" parameter represent the whole preedit text. +Each character of the preedit string is a native endian UTF-32 like @ref input_char. -If you want to type the text "寿司(sushi)", Usually the callback is called several times like the following sequence: +If you want to type the text "寿司(sushi)", Usually the callback is called several +times like the following sequence: -# key event: s -# preedit: [preedit_string: "s", block_sizes: [1], focused_block: 0] @@ -265,30 +266,32 @@ If you want to type the text "寿司(sushi)", Usually the callback is called sev -# char: '司' -# preedit: [preedit_string: "", block_sizes: [], focused_block: 0] -If preedit text includes several semantic blocks, preedit callbacks returns several blocks after a space key pressed: +If preedit text includes several semantic blocks, the callback returns several blocks: -# preedit: [preedit_string: "わたしはすしをたべます", block_sizes: [11], focused_block: 0] -# preedit: [preedit_string: "私は寿司を食べます", block_sizes: [2, 7], focused_block: 1] -"block_sizes" is a list of block length. The above case, it contains the following blocks and second block is focused. +"block_sizes" is a list of block length. The above case, it contains the following +blocks and the second block is focused. - 私は - [寿司を食べます] -committed text(passed via regular @ref input_char event), unfocused block, focused block should have different text style. +The application side should draw a focused block and unfocused blocks +in different styles. - -GLFW provides helper function to teach suitable position of the candidate window to window system. -Window system decides the best position from text cursor geometry (x, y coords and height). You should call this function -in the above preedit text callback function. +GLFW provides helper functions to teach the suitable position of the candidate window +to the window system. The window system decides the best position from text cursor +geometry (x, y coords and height). @code glfwSetPreeditCursorPos(window, x, y, h); glfwGetPreeditCursorPos(window, &x, &y, &h); @endcode -Sometimes IME task is interrupted by user or application. There are several functions to support these situation. -You can receive notification about IME status change(on/off) by using the following function: +Sometimes IME task is interrupted by user or application. There are several functions +to support these situation. You can receive notification about IME status change(on/off) +by using the following functions: @code glfwSetIMEStatusCallback(window, imestatus_callback); @@ -297,18 +300,21 @@ glfwSetIMEStatusCallback(window, imestatus_callback); imestatus_callback has simple signature like this: @code -static void imestatus_callback(GLFWwindow* window) { +void imestatus_callback(GLFWwindow* window) +{ } @endcode -You can implement the code that resets or commits preedit text when IME status is changed and preedit text is not empty. +You can implement the code that resets or commits the preedit text when IME status +is changed and the preedit text is not empty. -When the focus is gone from text box, you can use the following functions to reset IME status: +When the focus is gone from a text box, you can use the following functions to reset +IME status: @code void glfwResetPreeditText(GLFWwindow* window); -void glfwSetIMEStatus(GLFWwindow* window, int active) -int glfwGetIMEStatus(GLFWwindow* window) +void glfwSetIMEStatus(GLFWwindow* window, int active); +int glfwGetIMEStatus(GLFWwindow* window); @endcode @subsection input_key_name Key names