Using the IME class
Flash Player 9 and later, Adobe AIR 1.0 and
The IME class lets you manipulate
the operating system’s IME within Flash Player or Adobe AIR.
Using ActionScript, you can determine the following:
If an IME is installed on the user's computer (Capabilities.hasIME)
If the IME is enabled or disabled on the user’s computer
The conversion mode the current IME is using (IME.conversionMode)
You can associate an input text field with a particular IME context.
When you switch between input fields, you can also switch the IME
between Hiragana (Japanese), full-width numbers, half-width numbers,
direct input, and so on.
An IME lets users type non-ASCII text characters in multibyte
languages, such as Chinese, Japanese, and Korean.
For more information on working with IMEs, see the documentation
for the operating system for which you are developing the application.
For additional resources, see the following web sites:
Note: If an IME is not active on the user's computer,
calls to IME methods or properties, other than Capabilities.hasIME,
will fail. Once you manually activate an IME, subsequent ActionScript
calls to IME methods and properties will work as expected. For example,
if you are using a Japanese IME, you must activate it before you
can call any IME method or property.
Checking if an IME is installed and enabled
you call any of the IME methods or properties, you should always
check to see if the user’s computer currently has an IME installed
and enabled. The following code illustrates how to check that the
user has an IME both installed and active before you call any methods:
trace("IME is installed and enabled.");
trace("IME is installed but not enabled. Please enable your IME and try again.");
trace("IME is not installed. Please install an IME and try again.");
The previous code first checks to see if the user has an IME
installed using the Capabilities.hasIME property.
If this property is set to true, the code then
checks whether the user’s IME is currently enabled, using the IME.enabled property.
Determining which IME conversion mode is currently enabled
building multilingual applications, you may need to determine which conversion
mode the user currently has active. The following code demonstrates how
to check whether the user has an IME installed, and if so, which
IME conversion mode is currently active:
tf.text = "Current conversion mode is alphanumeric (full-width).";
tf.text = "Current conversion mode is alphanumeric (half-width).";
tf.text = "Current conversion mode is Chinese.";
tf.text = "Current conversion mode is Japananese Hiragana.";
tf.text = "Current conversion mode is Japanese Katakana (full-width).";
tf.text = "Current conversion mode is Japanese Katakana (half-width).";
tf.text = "Current conversion mode is Korean.";
tf.text = "Current conversion mode is " + IME.conversionMode + ".";
tf.text = "Please install an IME and try again.";
The previous code first checks to see whether the user has an
IME installed. Next it checks which conversion mode the current
IME is using by comparing the IME.conversionMode property
against each of the constants in the IMEConversionMode class.
Setting the IME conversion mode
you change the conversion mode of the user’s IME, you need to make
sure that the code is wrapped in a try..catch block,
because setting a conversion mode using the conversionMode property
can throw an error if the IME is unable to set the conversion mode.
The following code demonstrates how to use a try..catch block
when setting the IME.conversionMode property:
var statusText:TextField = new TextField;
statusText.autoSize = TextFieldAutoSize.LEFT;
IME.enabled = true;
IME.conversionMode = IMEConversionMode.KOREAN;
statusText.text = "Conversion mode is " + IME.conversionMode + ".";
statusText.text = "Unable to set conversion mode.\n" + error.message;
The previous code first creates a text field, which is used to
display a status message to the user. Next, if the IME is installed,
the code enables the IME and sets the conversion mode to Korean.
If the user’s computer does not have a Korean IME installed, an
error is thrown by Flash Player or AIR and is caught by the try..catch block.
The try..catch block displays the error message
in the previously created text field.
Disabling the IME for certain text fields
some cases, you may want to disable the user’s IME while they type
characters. For example, if you had a text field that only accepts
numeric input, you may not want the IME to come up and slow down
The following example demonstrates how you can listen for the FocusEvent.FOCUS_IN and FocusEvent.FOCUS_OUT events
and disable the user’s IME accordingly:
var phoneTxt:TextField = new TextField();
var nameTxt:TextField = new TextField();
phoneTxt.type = TextFieldType.INPUT;
phoneTxt.restrict = "0-9";
phoneTxt.width = 100;
phoneTxt.height = 18;
phoneTxt.background = true;
phoneTxt.border = true;
nameField.type = TextFieldType.INPUT;
nameField.x = 120;
nameField.width = 100;
nameField.height = 18;
nameField.background = true;
nameField.border = true;
IME.enabled = false;
IME.enabled = true;
This example creates two input text fields, phoneTxt and nameTxt,
and then adds two event listeners to the phoneTxt text
field. When the user sets focus to the phoneTxt text
field, a FocusEvent.FOCUS_IN event is dispatched
and the IME is disabled. When the phoneTxt text
field loses focus, the FocusEvent.FOCUS_OUT event
is dispatched to re-enable the IME.
Listening for IME composition events
events are dispatched when a composition string is being set. For
example, if the user has their IME enabled and active and types
a string in Japanese, the IMEEvent.IME_COMPOSITION event
would dispatch as soon as the user selects the composition string.
In order to listen for the IMEEvent.IME_COMPOSITION event,
you need to add an event listener to the static ime property
in the System class (flash.system.System.ime.addEventListener(...)),
as shown in the following example:
inputTxt = new TextField();
inputTxt.type = TextFieldType.INPUT;
inputTxt.width = 200;
inputTxt.height = 18;
inputTxt.border = true;
inputTxt.background = true;
outputTxt = new TextField();
outputTxt.autoSize = TextFieldAutoSize.LEFT;
outputTxt.y = 20;
IME.enabled = true;
IME.conversionMode = IMEConversionMode.JAPANESE_HIRAGANA;
outputTxt.text = "Unable to change IME.";
outputTxt.text = "Please install IME and try again.";
outputTxt.text = "you typed: " + event.text;
The previous code creates two text fields and adds them to the
display list. The first text field, inputTxt, is
an input text field that allows the user to enter Japanese text.
The second text field, outputTxt, is a dynamic
text field that displays error messages to the user, or echoes the
Japanese string that the user types into the inputTxt text