chrome.input.ime

Description: Use the chrome.input.ime API to implement a custom IME for Chrome OS. This allows your extension to handle keystrokes, set the composition, and manage the candidate window.
Availability: Stable since Chrome 21.
Permissions: "input"

Manifest

You must declare the "input" permission in the extension manifest to use the input.ime API. For example:

      {
        "name": "My extension",
        ...
        "permissions": [
          "input"
        ],
        ...
      }

Examples

The following code creates an IME that converts typed letters to upper case. 

      var context_id = -1;
      
      chrome.input.ime.onFocus.addListener(function(context) {
        context_id = context.contextID;
      });
      
      chrome.input.ime.onKeyEvent.addListener(
        function(engineID, keyData) {
          if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
            chrome.input.ime.commitText({"contextID": context_id,
                                         "text": keyData.key.toUpperCase()});
            return true;
          } else {
            return false;
          }
        });

For an example of using this API, see the basic input.ime sample. For other examples and for help in viewing the source code, see Samples.

Summary

Types
KeyboardEvent
InputContext
MenuItem
Methods
setComposition − chrome.input.ime.setComposition(object parameters, function callback)
clearComposition − chrome.input.ime.clearComposition(object parameters, function callback)
commitText − chrome.input.ime.commitText(object parameters, function callback)
sendKeyEvents − chrome.input.ime.sendKeyEvents(object parameters, function callback)
hideInputView − chrome.input.ime.hideInputView()
setCandidateWindowProperties − chrome.input.ime.setCandidateWindowProperties(object parameters, function callback)
setCandidates − chrome.input.ime.setCandidates(object parameters, function callback)
setCursorPosition − chrome.input.ime.setCursorPosition(object parameters, function callback)
setMenuItems − chrome.input.ime.setMenuItems(object parameters, function callback)
updateMenuItems − chrome.input.ime.updateMenuItems(object parameters, function callback)
deleteSurroundingText − chrome.input.ime.deleteSurroundingText(object parameters, function callback)
keyEventHandled − chrome.input.ime.keyEventHandled(string requestId, boolean response)
Events
onActivate
onDeactivated
onFocus
onBlur
onInputContextUpdate
onKeyEvent
onCandidateClicked
onMenuItemActivated
onSurroundingTextChanged
onReset

Types

KeyboardEvent

See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
properties
enum of "keyup", or "keydown" type One of keyup or keydown.
string requestId The ID of the request.
string (optional) extensionId The extension ID of the sender of this keyevent.
string key Value of the key being pressed
string code Value of the physical key being pressed. The value is not affected by current keyboard layout or modifier state.
boolean (optional) altKey Whether or not the ALT key is pressed.
boolean (optional) ctrlKey Whether or not the CTRL key is pressed.
boolean (optional) shiftKey Whether or not the SHIFT key is pressed.
boolean (optional) capsLock Whether or not the CAPS_LOCK is enabled.

InputContext

Describes an input Context
properties
integer contextID This is used to specify targets of text field operations. This ID becomes invalid as soon as onBlur is called.
enum of "text", "search", "tel", "url", "email", or "number" type Type of value this text field edits, (Text, Number, URL, etc)

MenuItem

A menu item used by an input method to interact with the user from the language menu.
properties
string id String that will be passed to callbacks referencing this MenuItem.
string (optional) label Text displayed in the menu for this item.
enum of "check", "radio", or "separator" (optional) style Enum representing if this item is: check, radio, or a separator. Radio buttons between separators are considered grouped.
boolean (optional) visible Indicates this item is visible.
boolean (optional) checked Indicates this item should be drawn with a check.
boolean (optional) enabled Indicates this item is enabled.

Methods

setComposition

chrome.input.ime.setComposition(object parameters, function callback)

Set the current composition. If this extension does not own the active IME, this fails.

Parameters
object parameters
integer contextID ID of the context where the composition text will be set
string text Text to set
integer (optional) selectionStart Position in the text that the selection starts at.
integer (optional) selectionEnd Position in the text that the selection ends at.
integer cursor Position in the text of the cursor.
array of object (optional) segments List of segments and their associated types.

Properties of each object

integer start Index of the character to start this segment at
integer end Index of the character to end this segment after.
enum of "underline", or "doubleUnderline" style How to render this segment
function (optional) callback Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, chrome.runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

clearComposition

chrome.input.ime.clearComposition(object parameters, function callback)

Clear the current composition. If this extension does not own the active IME, this fails.

Parameters
object parameters
integer contextID ID of the context where the composition will be cleared
function (optional) callback Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, chrome.runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

commitText

chrome.input.ime.commitText(object parameters, function callback)

Commits the provided text to the current input.

Parameters
object parameters
integer contextID ID of the context where the text will be committed
string text The text to commit
function (optional) callback Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, chrome.runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

sendKeyEvents

chrome.input.ime.sendKeyEvents(object parameters, function callback)

Sends the key events. This function is expected to be used by virtual keyboards. When key(s) on a virtual keyboard is pressed by a user, this function is used to propagate that event to the system.

Parameters
object parameters
integer contextID ID of the context where the key events will be sent, or zero to send key events to non-input field.
array of KeyboardEvent keyData Data on the key event.
function (optional) callback Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

hideInputView

chrome.input.ime.hideInputView()

Hides the input view window, which is popped up automatically by system. If the input view window is already hidden, this function will do nothing.

setCandidateWindowProperties

chrome.input.ime.setCandidateWindowProperties(object parameters, function callback)

Sets the properties of the candidate window. This fails if the extension doesn't own the active IME

Parameters
object parameters
string engineID ID of the engine to set properties on.
object properties
boolean (optional) visible True to show the Candidate window, false to hide it.
boolean (optional) cursorVisible True to show the cursor, false to hide it.
boolean (optional) vertical True if the candidate window should be rendered vertical, false to make it horizontal.
integer (optional) pageSize The number of candidates to display per page.
string (optional) auxiliaryText Text that is shown at the bottom of the candidate window.
boolean (optional) auxiliaryTextVisible True to display the auxiliary text, false to hide it.
enum of "cursor", or "composition" (optional) windowPosition Where to display the candidate window. If set to 'cursor', the window follows the cursor. If set to 'composition', the window is locked to the beginning of the composition.
function (optional) callback Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setCandidates

chrome.input.ime.setCandidates(object parameters, function callback)

Sets the current candidate list. This fails if this extension doesn't own the active IME

Parameters
object parameters
integer contextID ID of the context that owns the candidate window.
array of object candidates List of candidates to show in the candidate window

Properties of each object

string candidate The candidate
integer id The candidate's id
integer (optional) parentId The id to add these candidates under
string (optional) label Short string displayed to next to the candidate, often the shortcut key or index
string (optional) annotation Additional text describing the candidate
object (optional) usage The usage or detail description of word.
string title The title string of details description.
string body The body string of detail description.
function (optional) callback Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setCursorPosition

chrome.input.ime.setCursorPosition(object parameters, function callback)

Set the position of the cursor in the candidate window. This is a no-op if this extension does not own the active IME.

Parameters
object parameters
integer contextID ID of the context that owns the candidate window.
integer candidateID ID of the candidate to select.
function (optional) callback Called when the operation completes

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setMenuItems

chrome.input.ime.setMenuItems(object parameters, function callback)

Adds the provided menu items to the language menu when this IME is active.

Parameters
object parameters
string engineID ID of the engine to use
array of MenuItem items MenuItems to add. They will be added in the order they exist in the array.
function (optional) callback

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

updateMenuItems

chrome.input.ime.updateMenuItems(object parameters, function callback)

Updates the state of the MenuItems specified

Parameters
object parameters
string engineID ID of the engine to use
array of MenuItem items Array of MenuItems to update
function (optional) callback Called when the operation completes

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

deleteSurroundingText

chrome.input.ime.deleteSurroundingText(object parameters, function callback)

Deletes the text around the caret.

Parameters
object parameters
string engineID ID of the engine receiving the event.
integer contextID ID of the context where the surrounding text will be deleted.
integer offset The offset from the caret position where deletion will start. This value can be negative.
integer length The number of characters to be deleted
function (optional) callback Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

keyEventHandled

chrome.input.ime.keyEventHandled(string requestId, boolean response)

Indicates that the key event received by onKeyEvent is handled. This should only be called if the onKeyEvent listener is asynchronous.

Parameters
string requestId Request id of the event that was handled. This should come from keyEvent.requestId
boolean response True if the keystroke was handled, false if not

Events

onActivate

This event is sent when an IME is activated. It signals that the IME will be receiving onKeyPress events.

addListener

chrome.input.ime.onActivate.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID) {...};
string engineID ID of the engine receiving the event

onDeactivated

This event is sent when an IME is deactivated. It signals that the IME will no longer be receiving onKeyPress events.

addListener

chrome.input.ime.onDeactivated.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID) {...};
string engineID ID of the engine receiving the event

onFocus

This event is sent when focus enters a text box. It is sent to all extensions that are listening to this event, and enabled by the user.

addListener

chrome.input.ime.onFocus.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( InputContext context) {...};
InputContext context Describes the text field that has acquired focus.

onBlur

This event is sent when focus leaves a text box. It is sent to all extensions that are listening to this event, and enabled by the user.

addListener

chrome.input.ime.onBlur.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(integer contextID) {...};
integer contextID The ID of the text field that has lost focus. The ID is invalid after this call

onInputContextUpdate

This event is sent when the properties of the current InputContext change, such as the the type. It is sent to all extensions that are listening to this event, and enabled by the user.

addListener

chrome.input.ime.onInputContextUpdate.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( InputContext context) {...};
InputContext context An InputContext object describing the text field that has changed.

onKeyEvent

This event is sent if this extension owns the active IME.

addListener

chrome.input.ime.onKeyEvent.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, KeyboardEvent keyData) {...};
string engineID ID of the engine receiving the event
KeyboardEvent keyData Data on the key event

onCandidateClicked

This event is sent if this extension owns the active IME.

addListener

chrome.input.ime.onCandidateClicked.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, integer candidateID, enum of "left", "middle", or "right" button) {...};
string engineID ID of the engine receiving the event
integer candidateID ID of the candidate that was clicked.
enum of "left", "middle", or "right" button Which mouse buttons was clicked.

onMenuItemActivated

Called when the user selects a menu item

addListener

chrome.input.ime.onMenuItemActivated.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, string name) {...};
string engineID ID of the engine receiving the event
string name Name of the MenuItem which was activated

onSurroundingTextChanged

Called when the editable string around caret is changed or when the caret position is moved. The text length is limited to 100 characters for each back and forth direction.

addListener

chrome.input.ime.onSurroundingTextChanged.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, object surroundingInfo) {...};
string engineID ID of the engine receiving the event
object surroundingInfo The surrounding information.
string text The text around cursor.
integer focus The ending position of the selection. This value indicates caret position if there is no selection.
integer anchor The beginning position of the selection. This value indicates caret position if is no selection.

onReset

This event is sent when chrome terminates ongoing text input session.

addListener

chrome.input.ime.onReset.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID) {...};
string engineID ID of the engine receiving the event