PackageSystem
Classpublic class IME
InheritanceIME Inheritance Object

Player version: Flash Player 8

The IME class lets you directly manipulate the operating system's input method editor (IME) in the Flash Player application that is running on a client computer. You can determine whether an IME is installed, whether or not the IME is enabled, and which IME is enabled. You can disable or enable the IME in the Flash Player application, and you can perform other limited functions, depending on the operating system.

Input method editors let users type non-ASCII text characters in Asian languages such as Chinese, Japanese, and Korean. For more information on IMEs, see the operating system documentation for the platform for which you are developing applications. Some additional resources for information about input methods are listed here:

On the Macintosh, calls to the IME application programming interface (API) fail if you do not have the IME enabled. Once you manually enable the IME, subsequent calls work as expected. For example, if you are using Japanese IME on your system, it must be enabled and in one of four possible modes (Hiragana, Full-width Katakana, Full-width Alphanumeric, Half-width Katakana) before this API is called.

The following table shows the platform coverage of this class:

Capability Windows Macintosh OSX Macintosh Classic Linux/Solaris XIM
Determine whether the IME is installed
   System.capabilities.hasIME		 Yes Yes Yes Yes
Set IME on or off
   System.IME.setEnabled()		 Yes Yes Yes *** Yes
Find out whether IME is on or off
   System.IME.getEnabled()		 Yes Yes Yes Yes
Set IME conversion mode
   System.IME.setConversionMode()		 Yes Yes ** No Yes
Get IME conversion mode
   System.IME.getConversionMode()		 Yes Yes ** No Yes
Send IME the string to be converted
   System.IME.setCompositionString()		 Yes * No No Yes
Get from IME the original string before conversion
   System.IME.addListener()
   listener.onIMEComposition()
   System.IME.removeListener()		 Yes * No No Yes
Send request to convert to IME
   System.IME.doConversion()		 Yes * No No Yes

* Not all Windows IMEs support all of these operations. So far the only IME that supports them all is the Japanese IME. Every IME differs in its support of the OS calls.

** On Macintosh these methods are supported only for Japanese, and they are not supported for third-party IMEs.

*** One of the Japanese modes (Hiragana, Full & Half-width Katakana, Full-width alphanumeric) must be enabled before using this API.


Public Methods
 Method
  
addListener(listener:Object):Void
[static]Registers an object to receive notification when an IME event handler is invoked by the onIMEComposition event.
  
doConversion():Boolean
[static]Instructs the IME to select the first candidate for the current composition string.
  
getConversionMode():String
[static]Indicates the conversion mode of the current IME.
  
getEnabled():Boolean
[static]Indicates whether the system IME is enabled.
  
removeListener(listener:Object):Boolean
[static]Removes a listener object that was previously registered to an IME instance with IME.addListener().
  
setCompositionString(composition:String):Boolean
[static]Sets the IME composition string.
  
setConversionMode(mode:String):Boolean
[static]Sets the conversion mode of the current IME.
  
setEnabled(enabled:Boolean):Boolean
[static]Enables or disables the system IME.
 Methods inherited from class Object
 addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch
Events
 EventSummaryDefined by
  
onIMEComposition = function([readingString:String]) {}
Notified when the IME composition string is being set.IME
Public Constants
 Constant
  ALPHANUMERIC_FULL : String
[static]A string with the value "ALPHANUMERIC_FULL" for use with setConversionMode() and getConversionMode().
  ALPHANUMERIC_HALF : String
[static]A string with the value "ALPHANUMERIC_HALF" for use with setConversionMode() and getConversionMode().
  CHINESE : String
[static]A string with the value "CHINESE" for use with setConversionMode() and getConversionMode().
  JAPANESE_HIRAGANA : String
[static]A string with the value "JAPANESE_HIRAGANA" for use with setConversionMode() and getConversionMode().
  JAPANESE_KATAKANA_FULL : String
[static]A string with the value "JAPANESE_KATAKANA_FULL" for use with setConversionMode() and getConversionMode().
  JAPANESE_KATAKANA_HALF : String
[static]A string with the value "JAPANESE_KATAKANA_HALF" for use with setConversionMode() and getConversionMode().
  KOREAN : String
[static]A string with the value "KOREAN" for use with setConversionMode() and getConversionMode().
  UNKNOWN : String
[static]A string with the value "UNKNOWN" for use with getConversionMode().
 Properties inherited from class Object
 __proto__, __resolve, constructor, prototype
Method detail
addListener()method
public static function addListener(listener:Object):Void

Player version: Flash Player 8

Registers an object to receive notification when an IME event handler is invoked by the onIMEComposition event.

Parameters
listener:Object — An object, with an onIMEComposition (readingString) method, that listens for a callback notification from the IME event handlers. The reading string passed to this method is in the composition mode of the IME. For example, if the user enters text in Hiragana and then selects a Kanji candidate, the reading string is the original Hiragana.

Example
The following example shows how to add a listener object to System.IME that outputs notification when a user sets the composition string by clicking in the text field. 
var IMEListener:Object = new Object();
IMEListener.onIMEComposition = function(str:String) {
    trace(">> onIMEComposition: " + str);
}
System.IME.addListener(IMEListener);
trace(System.IME.length);

var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc.createTextField("txt", this.getNextHighestDepth(), 0, 0, 0, 0);
mc.txt.border = true;
mc.txt.background = true;
mc.txt.autoSize = "left";
mc.txt.text = "Click this text to add a listener.";

mc.onPress = function() {
    if(System.capabilities.hasIME) {
        Selection.setFocus(mc.txt);
        System.IME.setCompositionString(mc.txt.text);
    }
}

doConversion()method 
public static function doConversion():Boolean

Player version: Flash Player 8

Instructs the IME to select the first candidate for the current composition string.

Returns
Boolean — Returns true if the call is successful; otherwise false.

Example
The following example shows how to select the first candidate for the IME composition string. If the user's system has IME, clicking in the text field selects the candidate. 
var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc.createTextField("txt", this.getNextHighestDepth(), 0, 0, 0, 0);
mc.txt.border = true;
mc.txt.background = true;
mc.txt.autoSize = "left";
mc.txt.text = "Set this text as the composition string and convert it.";

mc.onPress = function() {
    if(System.capabilities.hasIME) {
        Selection.setFocus(mc.txt);
        System.IME.setCompositionString(mc.txt.text);
        trace(System.IME.doConversion());
    }
}

getConversionMode()method 
public static function getConversionMode():String

Player version: Flash Player 8

Indicates the conversion mode of the current IME.

Returns
String — The conversion mode. Possible values are IME mode string constants that indicate the conversion mode:
  • ALPHANUMERIC_FULL
  • ALPHANUMERIC_HALF
  • CHINESE
  • JAPANESE_HIRAGANA
  • JAPANESE_KATAKANA_FULL
  • JAPANESE_KATAKANA_HALF
  • KOREAN
  • UNKNOWN

See also

IME.ALPHANUMERIC_FULL
IME.ALPHANUMERIC_HALF
IME.CHINESE
IME.JAPANESE_HIRAGANA
IME.JAPANESE_KATAKANA_FULL
IME.JAPANESE_KATAKANA_HALF
IME.KOREAN
IME.UNKNOWN

Example
The following example gets the IME if the system has an Input Method Editor (IME) installed ( System.capabilities.hasIME). 
var mode:String = System.IME.UNKNOWN;
if(System.capabilities.hasIME) {
    mode = System.IME.getConversionMode();
}
trace(mode);

getEnabled()method 
public static function getEnabled():Boolean

Player version: Flash Player 8

Indicates whether the system IME is enabled. An enabled IME performs multibyte input; a disabled IME performs alphanumeric input.

Returns
Boolean — Returns true if the system IME is enabled, false if it is disabled.

Example
The following example checks to see whether IME is enabled by calling the isEnabled() method. 
if(System.capabilities.hasIME) {
    var isImeEnabled:Boolean = System.IME.getEnabled();
    trace(isImeEnabled);
}

removeListener()method 
public static function removeListener(listener:Object):Boolean

Player version: Flash Player 8

Removes a listener object that was previously registered to an IME instance with IME.addListener().

Parameters
listener:Object — The object that no longer receives callback notification from the IME event handlers.

Returns
Boolean — Returns true if the listener object is removed; otherwise false.

Example
The following example shows how to remove a listener object from System.IME when a user sets the composition string by clicking in the text field. 
var IMEListener:Object = new Object();
IMEListener.onIMEComposition = function(str:String) {
    trace(">> onIMEComposition: " + str);

    System.IME.removeListener(this);
    trace(System.IME.length);    // 0
}
System.IME.addListener(IMEListener);
trace(System.IME.length);        // 1

var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc.createTextField("txt", this.getNextHighestDepth(), 0, 0, 0, 0);
mc.txt.border = true;
mc.txt.background = true;
mc.txt.autoSize = "left";
mc.txt.text = "Click this text to add and remove a listener.";

mc.onPress = function() {
    if(System.capabilities.hasIME) {
        Selection.setFocus(mc.txt);
        System.IME.setCompositionString(mc.txt.text);
    }
}

setCompositionString()method 
public static function setCompositionString(composition:String):Boolean

Player version: Flash Player 8

Sets the IME composition string. When this string is set, the user can select IME candidates before committing the result to the text field that currently has focus.

Parameters
composition:String — The string to send to the IME.

Returns
Boolean — If the IME composition string is successfully set, returns true. This method fails and returns false if no text field has focus.

Example
The following example shows how to set the IME composition string. If the user's system has IME, clicking in the text field shows the IME options. 
var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc.createTextField("txt", this.getNextHighestDepth(), 0, 0, 0, 0);
mc.txt.border = true;
mc.txt.background = true;
mc.txt.autoSize = "left";
mc.txt.text = "Set this text as the composition string.";

mc.onPress = function() {
    if(System.capabilities.hasIME) {
        Selection.setFocus(mc.txt);
        trace(System.IME.setCompositionString(mc.txt.text));
    }
}

setConversionMode()method 
public static function setConversionMode(mode:String):Boolean

Player version: Flash Player 8

Sets the conversion mode of the current IME.

Parameters
mode:String — The conversion mode. Possible values are the IME mode string constants:
  • ALPHANUMERIC_FULL
  • ALPHANUMERIC_HALF
  • CHINESE
  • JAPANESE_HIRAGANA
  • JAPANESE_KATAKANA_FULL
  • JAPANESE_KATAKANA_HALF
  • KOREAN

Returns
Boolean — Returns true if the conversion mode was successfully set; otherwise false.

See also

IME.ALPHANUMERIC_FULL
IME.ALPHANUMERIC_HALF
IME.CHINESE
IME.JAPANESE_HIRAGANA
IME.JAPANESE_KATAKANA_FULL
IME.JAPANESE_KATAKANA_HALF
IME.KOREAN

Example
The following example gets the IME if the system has an Input Method Editor (IME) installed ( System.capabilities.hasIME) and sets the variable mode to that value. 
var mode:String = System.IME.UNKNOWN;
if(System.capabilities.hasIME) {
    mode = System.IME.getConversionMode();
}
System.IME.setConversionMode(mode);
trace(System.IME.getConversionMode());

setEnabled()method 
public static function setEnabled(enabled:Boolean):Boolean

Player version: Flash Player 8

Enables or disables the system IME. An enabled IME performs multibyte input; a disabled IME performs alphanumeric input.

Parameters
enabled:Boolean — Set to true to enable the system IME, false to disable it.

Returns
Boolean — If the attempt to enable the system IME is successful, returns true; otherwise false.

Example
The following example checks to see whether IME is enabled by calling the isEnabled() method and then changes its enabled state to the opposite by calling the setEnabled() method. 
if(System.capabilities.hasIME) {
    var isImeEnabled:Boolean = System.IME.getEnabled();
    trace(isImeEnabled);
    
    if(isImeEnabled) {
        System.IME.setEnabled(false);
    }
    else {
        System.IME.setEnabled(true);
    }

    var isImeEnabled:Boolean = System.IME.getEnabled();
    trace(isImeEnabled);
}

Event detail
onIMECompositionevent listener

public onIMEComposition = function([readingString:String]) {}

Player version: Flash Player 8

Notified when the IME composition string is being set. To use this listener, you must create a listener object. You can then define a function for this listener and use IME.addListener() to register the listener with the IME object, as in the following code: 

var someListener:Object = new Object();
someListener.onIMEComposition = function () {
    // statements
}
System.IME.addListener(someListener);

Listeners enable different pieces of code to cooperate because multiple listeners can receive notification about a single event.

Parameters
readingString:String [optional] — The original text typed into the IME before the user started picking candidates.

Example
The following example shows how to add a listener object with the callback method onIMEComposition() to System.IME, which outputs notification when a user sets the composition string by clicking in the text field. 
var IMEListener:Object = new Object();
IMEListener.onIMEComposition = function(str:String) {
    trace(">> onIMEComposition: " + str);
}
System.IME.addListener(IMEListener);
trace(System.IME.length);

var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc.createTextField("txt", this.getNextHighestDepth(), 0, 0, 0, 0);
mc.txt.border = true;
mc.txt.background = true;
mc.txt.autoSize = "left";
mc.txt.text = "Click this text to add a listener.";

mc.onPress = function() {
    if(System.capabilities.hasIME) {
        Selection.setFocus(mc.txt);
        System.IME.setCompositionString(mc.txt.text);
    }
}

See also

System.IME.addListener()
System.IME.setCompositionString()
Constant detail
ALPHANUMERIC_FULLconstant
public static var ALPHANUMERIC_FULL:String

Player version: Flash Player 8

A string with the value "ALPHANUMERIC_FULL" for use with setConversionMode() and getConversionMode(). This constant is used with all IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()
capabilities.hasIME

Example
The following example sets the IME to ALPHANUMERIC_FULL if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.ALPHANUMERIC_FULL);
    trace(System.IME.getConversionMode());
}

ALPHANUMERIC_HALFconstant 
public static var ALPHANUMERIC_HALF:String

Player version: Flash Player 8

A string with the value "ALPHANUMERIC_HALF" for use with setConversionMode() and getConversionMode(). This constant is used with all IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()

Example
The following example sets the IME to ALPHANUMERIC_HALF if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.ALPHANUMERIC_HALF);
    trace(System.IME.getConversionMode());
}

CHINESEconstant 
public static var CHINESE:String

Player version: Flash Player 8

A string with the value "CHINESE" for use with setConversionMode() and getConversionMode(). This constant is used with simplified and traditional Chinese IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()

Example
The following example sets the IME to CHINESE if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.CHINESE);
    trace(System.IME.getConversionMode());
}

JAPANESE_HIRAGANAconstant 
public static var JAPANESE_HIRAGANA:String

Player version: Flash Player 8

A string with the value "JAPANESE_HIRAGANA" for use with setConversionMode() and getConversionMode(). This constant is used with Japanese IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()

Example
The following example sets the IME to JAPANESE_HIRAGANA if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.JAPANESE_HIRAGANA);
    trace(System.IME.getConversionMode());
}

JAPANESE_KATAKANA_FULLconstant 
public static var JAPANESE_KATAKANA_FULL:String

Player version: Flash Player 8

A string with the value "JAPANESE_KATAKANA_FULL" for use with setConversionMode() and getConversionMode(). This constant is used with Japanese IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()

Example
The following example sets the IME to JAPANESE_KATAKANA_FULL if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.JAPANESE_KATAKANA_FULL);
    trace(System.IME.getConversionMode());
}

JAPANESE_KATAKANA_HALFconstant 
public static var JAPANESE_KATAKANA_HALF:String

Player version: Flash Player 8

A string with the value "JAPANESE_KATAKANA_HALF" for use with setConversionMode() and getConversionMode(). This constant is used with Japanese IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()

Example
The following example sets the IME to JAPANESE_KATAKANA_HALF if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.JAPANESE_KATAKANA_HALF);
    trace(System.IME.getConversionMode());
}

KOREANconstant 
public static var KOREAN:String

Player version: Flash Player 8

A string with the value "KOREAN" for use with setConversionMode() and getConversionMode(). This constant is used with Korean IMEs.

See also

IME.setConversionMode()
IME.getConversionMode()

Example
The following example sets the IME to KOREAN if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.KOREAN);
    trace(System.IME.getConversionMode());
}

UNKNOWNconstant 
public static var UNKNOWN:String

Player version: Flash Player 8

A string with the value "UNKNOWN" for use with getConversionMode(). This constant is used with all IMEs.

See also

IME.getConversionMode()

Example
The following example sets the IME to UNKNOWN if the system has an Input Method Editor (IME) installed (System.capabilities.hasIME). 
if(System.capabilities.hasIME) {
    trace(System.IME.getConversionMode());

    System.IME.setConversionMode(System.IME.UNKNOWN);
    trace(System.IME.getConversionMode());
}




© 2004-2010 Adobe Systems Incorporated. All rights reserved.
Wed Apr 7 2010, 4:41 PM GMT-07:00