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:	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
KeyboardEventType
KeyboardEvent
InputContextType
InputContext
MenuItemStyle
MenuItem
UnderlineStyle
WindowPosition
ScreenType
CallbackStyle
MouseButton
WindowType
Bounds
CreateWindowOptions
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)`
createWindow − `chrome.input.ime.createWindow( CreateWindowOptions options, function callback)`
showWindow − `chrome.input.ime.showWindow(integer windowId, function callback)`
hideWindow − `chrome.input.ime.hideWindow(integer windowId, function callback)`
activate − `chrome.input.ime.activate(function callback)`
deactivate − `chrome.input.ime.deactivate(function callback)`
Events
onActivate
onDeactivated
onFocus
onBlur
onInputContextUpdate
onKeyEvent
onCandidateClicked
onMenuItemActivated
onSurroundingTextChanged
onReset
onCompositionBoundsChanged

Types

KeyboardEventType

Enum
`"keyup"`, or `"keydown"`

KeyboardEvent

See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent

properties
KeyboardEventType	type	One of keyup or keydown.
string	requestId	The ID of the request.
string	(optional) extensionId	Since Chrome 34. The extension ID of the sender of this keyevent.
string	key	Value of the key being pressed
string	code	Since Chrome 26. Value of the physical key being pressed. The value is not affected by current keyboard layout or modifier state.
integer	(optional) keyCode	Since Chrome 37. The deprecated HTML keyCode, which is system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed.
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	Since Chrome 29. Whether or not the CAPS_LOCK is enabled.

InputContextType

Type of value this text field edits, (Text, Number, URL, etc)

Enum
`"text"`, `"search"`, `"tel"`, `"url"`, `"email"`, `"number"`, or `"password"`

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.
InputContextType	type	Type of value this text field edits, (Text, Number, URL, etc)
boolean	autoCorrect	Since Chrome 40. Whether the text field wants auto-correct.
boolean	autoComplete	Since Chrome 40. Whether the text field wants auto-complete.
boolean	spellCheck	Since Chrome 40. Whether the text field wants spell-check.

MenuItemStyle

The type of menu item. Radio buttons between separators are considered grouped.

Enum
`"check"`, `"radio"`, or `"separator"`

MenuItem

Since Chrome 30.

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.
MenuItemStyle	(optional) style	The type of menu item.
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.

UnderlineStyle

The type of the underline to modify this segment.

Enum
`"underline"`, `"doubleUnderline"`, or `"noUnderline"`

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.

Enum
`"cursor"`, or `"composition"`

ScreenType

The screen type under which the IME is activated.

Enum
`"normal"`, `"login"`, `"lock"`, or `"secondary-login"`

CallbackStyle

Enum
`"async"`

MouseButton

Which mouse buttons was clicked.

Enum
`"left"`, `"middle"`, or `"right"`

WindowType

The IME window types.

Enum
`"normal"`, or `"followCursor"`

Bounds

Since Chrome 50.

Describes the screen coordinates of a rect.

properties
integer	left	The left of the bounds.
integer	top	The top of the bounds.
integer	width	The width of the bounds.
integer	height	The height of the bounds .

CreateWindowOptions

Since Chrome 50.

The options to create an IME window

properties
WindowType	windowType
string	(optional) url
Bounds	(optional) bounds

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.
UnderlineStyle	style	The type of the underline to modify 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)

Since Chrome 33.

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()

Since Chrome 34.

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.
WindowPosition	(optional) windowPosition	Since Chrome 28. Where to display the candidate window.

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

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)

Since Chrome 27.

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)

Since Chrome 25.

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

createWindow


              chrome.input.ime.createWindow(    CreateWindowOptions options, function callback)

Since Chrome 50.

Creates IME window.

Parameters

CreateWindowOptions

options

The options of the newly created IME window.

function

callback

Called when the operation completes.

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

function(Window windowObject) {...};

Window

windowObject

The JavaScript 'window' object of the newly created IME window. It contains the additional 'id' property for the parameters of the other functions like showWindow/hideWindow.

showWindow


              chrome.input.ime.showWindow(integer windowId, function callback)

Since Chrome 51.

Shows the IME window. This makes the hidden window visible.

Parameters

integer

windowId

Parameters
integer	windowId	The ID of the IME window.
function	(optional) callback	Called when the operation completes. If you specify the callback parameter, it should be a function that looks like this: `function() {...};`

The ID of the IME window.

function

(optional) callback

Called when the operation completes.

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

function() {...};

hideWindow


              chrome.input.ime.hideWindow(integer windowId, function callback)

Since Chrome 51.

Hides the IME window. This doesn't close the window. Instead, it makes the window invisible. The extension can cache the window and show/hide it for better performance.

Parameters

integer

windowId

The ID of the IME window.

function

(optional) callback

Called when the operation completes.

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

function() {...};

activate


              chrome.input.ime.activate(function callback)

Since Chrome 50.

Activates the IME extension so that it can receive events.

Parameters

function

(optional) callback

Called when the operation completes.

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

function() {...};

deactivate


              chrome.input.ime.deactivate(function callback)

Since Chrome 50.

Deactivates the IME extension so that it cannot receive events.

Parameters

function

(optional) callback

Called when the operation completes.

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

function() {...};

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


                    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, MouseButton button) {...};

string	engineID	ID of the engine receiving the event
integer	candidateID	ID of the candidate that was clicked.
MouseButton	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

Since Chrome 27.

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 the cursor. This is only a subset of all text in the input field.
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 there is no selection.
integer	offset	Since Chrome 46. The offset position of `text`. Since `text` only includes a subset of text around the cursor, offset indicates the absolute position of the first character of `text`.

onReset

Since Chrome 29.

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

onCompositionBoundsChanged

Since Chrome 50.

Triggered when the bounds of the IME composition text or cursor are changed. The IME composition text is the instance of text produced in the input method editor.

addListener


                    chrome.input.ime.onCompositionBoundsChanged.addListener(function callback)

Parameters

function

callback

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

function(array of Bounds boundsList) {...};

array of Bounds

boundsList

List of bounds information for each character on IME composition text. If there's no composition text in the editor, this array contains the bound information of the cursor.