bw logo
Chapter 19. Input Method Editors (IME)
Prev     Next

Chapter 19. Input Method Editors (IME)

Table of Contents

19.1. Components of an IME interface
19.1.1. Examples
19.1.2. Recommended Reading
19.2. IME Python API
19.2.1. Enabling IME
19.2.2. Receiving IME events
19.2.3. Displaying the IME

An Input Method Editor (IME) is an advanced user interface which is used to enter input text for East Asian such as Chinese where the character set is much larger than can be practically mapped directly to keyboard buttons. This is a mechanism provided by Windows and is determined by the currently installed keyboard layout.

Unfortunately the default IME interfaces used by Windows overlay additional child pop-up windows which do not work well within the context of a game. These pop-ups will conflict with the Direct3D device (especially in full-screen mode), are not skinnable, and, since Windows has no knowledge about your in-game user interface, it will not be positioned to line up with your in-game edit controls. Thus in order to integrate nicely with a game and deliver a smooth experience for the user, the IME interface should be rendered using the in-game GUI system.

The BigWorld engine provides an API which allows the Python scripts to respond to IME events generated by the operating system and populate an in-game IME based on the current state of the system input driver.

The currently supported IME types are:

  • Chinese Simplified (PRC)

    • Microsoft Pinyin

    • QuanPin

    • Sogou Pinyin

    • Sogou Wubi

    • Google Pinyin

  • Chinese Traditional (Taiwan)

    • Microsoft New Phonetic IME

  • Japanese

    • Microsoft IME

  • Korean

    • Microsoft IME

This chapter describes how to setup Python scripts to respond to IME events and display an interface accordingly.

In addition to this document, there is an example implementation located at fantasydemo/res/scripts/client/Helpers/PyGUI/IME.py. This script is used by the PyGUI.EditField class.

Please note that the BigWorld IME system will be disabled if the Scaleform IME library is enabled.

19.1. Components of an IME interface

There are three main components that make up an Input Method Editor:

  • Composition string. This contains the characters that the user has composed with the IME and is the string that will be sent to the application once it has been finalised by the user. The composition string is usually drawn on top of the edit control at the current location of the input cursor.

  • Reading window. Typically used only by Chinese IME's, this contains the most recent keystrokes which have not yet been translated to the target language.

  • Candidate list. This is a list of candidate characters based on the current contents of the composition string. The user can use the arrow keys to cycle through the available options and can use page-up and page-down if there are multiple pages of options. The desired candidate is selected by pressing the number key corresponding to the candidate list item, or by pressing enter on the highlighted item.

A particular IME may use all or only some of these components. The PyIME object is used by the Python scripts to determine when a particular component needs to be drawn (e.g. the BigWorld.ime.readingVisible flag can be used to determine whether or not the reading window should be drawn at any particular time).

While not strictly part of the IME itself, including a language indicator on your edit control is useful as a visual aid to keep track of which language is currently active. By changing its colour, you can also indicate the current state of the IME (e.g. whether or not the IME is currently in alpha-numeric mode).

19.1.1. Examples

Japanese IME

Chinese IME

19.1.2. Recommended Reading

[Installing and Using Input Method Editors, MSDN - http://msdn.microsoft.com/en-us/library/bb174599%28VS.85%29.aspx]

[Using an Input Method Editor in a Game, MSDN - http://msdn.microsoft.com/en-us/library/bb206300%28VS.85%29.aspx]

19.2. IME Python API

The BigWorld IME Python API is accessed via the BigWorld.ime object. This is a singleton instance of the PyIME class.

See the Python client API documentation for details on all methods and properties mentioned here.

19.2.1. Enabling IME

Disabled by default, IME can be enabled and disabled from the Python script. Typically, an application would enable IME when a text-input interface comes into focus (e.g. an edit box), and disable it again once it has lost focus. The enabled property on the PyIME object controls the current state: 

BigWorld.ime.enabled = enableBoolean

The internal state will be reset when IME is disabled.

19.2.2. Receiving IME events

Once the IME system is enabled, the engine will start posting events to the personality script.

19.2.2.1. BWPersonality.handleInputLangChangeEvent

The BWPersonality.handleInputLangChangeEvent will be called whenever the user has switched the current input language. The function does not take any parameters, so the handler should check the BigWorld.ime.language property and the BigWorld.localeInfo function to check the new language and update accordingly.

Typically, an application would update language indicators and/or fonts based on the new language.

19.2.2.2. BWPersonality.handleIMEEvent

The BWPersonality.handleIMEEvent gets called whenever the user performs some action (usually a keystroke) that causes the internal IME state to be changed. The only parameter to the handleIMEEvent is a PyIMEEvent object. The event object itself does not have any data, rather it has a set of flags which indicate which BigWorld.ime properties have been updated. The handleIMEEvent function will be called when the following events occur:

  • The current IME state has been changed (e.g. switching between alpha-numeric mode and Hiragana mode whilst in the Japanese language).

  • The composition string has been modified.

  • The cursor position within the composition string has been modified.

  • The reading window string has changed.

  • The reading window visibility has changed.

  • The candidate list visibility has changed.

  • The candidate list items have changed.

  • The user has changed the highlighted item within the candidate list.

19.2.2.3. Finalising characters

When the user has finished entering their desired text into the method editor they will press enter to commit the string. When this occurs, BWPersonality.handleKeyEvent will be called for each unicode character in the finalised string, and will be posted with the key code Keys.KEY_IME_CHAR.

19.2.3. Displaying the IME

The task of actually displaying the IME interface based on the current underlying state is a task for the Python script programmer. The complexity of the IME presentation scripts will be determined by how many languages need to be supported, as each language has their own standard way of presenting the IME.

Note that due to the number of different IME's available for a single language, and due to differences between Windows XP and Windows Vista, it is recommended to test across these different configurations as much as possible.

Generally, when constructing an IME interface, the scripts will do the following:

  • Build a composition string window based on the contents of BigWorld.ime.composition. Each character in the composition string will have a different attribute associated with it which determine its state (e.g. whether or not it is highlighted). This is determined by the BigWorld.ime.compositionAttr property (an array of the same length as the composition string).

    A cursor should be drawn within the composition string based on the BigWorld.ime.compositionCursorPosition attribute.

  • If BigWorld.ime.readingVisible is True, build a reading window based on the contents of BigWorld.ime.reading.

    The orientation of the reading window is determined by the BigWorld.ime.readingVertical property.

  • If BigWorld.ime.candidatesVisible is True, build a candidate window based on the contents of BigWorld.ime.candidates. This is an array of candidate strings for the current page (each page has a maximum of 9 entries). The highlighted item of the composition is determined by the BigWorld.ime.selectedCandidate property.

    The candidate window should be placed so it appears just under the location of the composition window cursor.

    The orientation of the candidate window is determined by the BigWorld.ime.candidatesVertical property.

19.2.3.1. Japanese

  • Rather than placing the candidate window at the location of the composition string cursor, the candidate window should be placed below the first target converted character (determined via the compositionAttr property).

19.2.3.2. Korean

Korean IME's require a bit more specialisation than Chinese and Japanese. The main considerations for creating a Korean IME are:

  • The composition string is edited in-line. In other words, the composition character is directly inserted into the edit box immediately so that the character to the right of the cursor is moved across. The underlying Korean IME implements this by injecting keystrokes such as LEFTARROW, RIGHTARROW and BACKSPACE into the input stream to automatically insert and remove a character into your edit box.

  • The composition string background blinks, itself acting as the cursor. As such, BigWorld.ime.compositionCursorPosition can be ignored.

Prev     Next
Chapter 18. Fonts  Home  Chapter 20. BigWorld Web Integration
Copyright 1999-2012 BigWorld Pty. Ltd. All rights reserved. Proprietary commercial in confidence.