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 35.
|
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 | |
AutoCapitalizeType | |
InputContext | |
MenuItemStyle | |
MenuItem | |
UnderlineStyle | |
WindowPosition | |
ScreenType | |
MouseButton | |
AssistiveWindowType | |
AssistiveWindowProperties | |
AssistiveWindowButton | |
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)
| |
setAssistiveWindowProperties −
chrome.input.ime.setAssistiveWindowProperties(object parameters, function callback)
| |
setAssistiveWindowButtonHighlighted −
chrome.input.ime.setAssistiveWindowButtonHighlighted(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 | |
onAssistiveWindowButtonClicked |
Types
KeyboardEventType
Enum |
---|
"keyup" ,
or "keydown"
|
KeyboardEvent
properties | ||
---|---|---|
KeyboardEventType | type |
One of keyup or keydown. |
string | (optional) requestId |
(Deprecated) The ID of the request. Use the |
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. |
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) altgrKey |
Since Chrome 79. Whether or not the ALTGR 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. |
InputContextType
Enum |
---|
"text" ,
"search" ,
"tel" ,
"url" ,
"email" ,
"number" ,
"password" ,
or "null"
|
AutoCapitalizeType
Enum |
---|
"characters" ,
"words" ,
or "sentences"
|
InputContext
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. |
AutoCapitalizeType | autoCapitalize |
Since Chrome 69. The auto-capitalize type of the text field. |
boolean | spellCheck |
Since Chrome 40. Whether the text field wants spell-check. |
boolean | shouldDoLearning |
Since Chrome 68. Whether text entered into the text field should be used to improve typing suggestions for the user. |
MenuItemStyle
Enum |
---|
"check" ,
"radio" ,
or "separator"
|
MenuItem
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
Enum |
---|
"underline" ,
"doubleUnderline" ,
or "noUnderline"
|
WindowPosition
Enum |
---|
"cursor" ,
or "composition"
|
ScreenType
Enum |
---|
"normal" ,
"login" ,
"lock" ,
or "secondary-login"
|
MouseButton
Enum |
---|
"left" ,
"middle" ,
or "right"
|
AssistiveWindowType
Enum |
---|
"undo"
|
AssistiveWindowProperties
Since Chrome 85. Warning: this is the current Dev channel. Learn more.
properties | ||
---|---|---|
AssistiveWindowType | type | |
boolean | visible |
Sets true to show AssistiveWindow, sets false to hide. |
string | (optional) announceString |
Strings for ChromeVox to announce. |
AssistiveWindowButton
Enum |
---|
"undo" ,
or "addToDictionary"
|
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 |
|
|||||||||||||||||||||||||||
function | (optional) callback |
Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, runtime.lastError is set. If you specify the callback parameter, it should be a function that looks like this: function(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 |
|
|||
function | (optional) callback |
Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, runtime.lastError is set. If you specify the callback parameter, it should be a function that looks like this: function(boolean success) {...};
|
commitText
chrome.input.ime.commitText(object parameters, function callback)
Commits the provided text to the current input.
Parameters | ||||||||
---|---|---|---|---|---|---|---|---|
object | parameters |
|
||||||
function | (optional) callback |
Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, runtime.lastError is set. If you specify the callback parameter, it should be a function that looks like this: function(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 |
|
||||||
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 |
|
|||||||||||||||||||||||||||||||||
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) {...};
|
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 |
|
||||||||||||||||||||||||||||||
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) {...};
|
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 |
|
||||||
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) {...};
|
setAssistiveWindowProperties
chrome.input.ime.setAssistiveWindowProperties(object parameters, function callback)
Since Chrome 85. Warning: this is the current Dev channel. Learn more.
Shows/Hides an assistive window with the given properties.
Parameters | ||||||||
---|---|---|---|---|---|---|---|---|
object | 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(boolean success) {...};
|
setAssistiveWindowButtonHighlighted
chrome.input.ime.setAssistiveWindowButtonHighlighted(object parameters, function callback)
Not fully implemented. You must build Chromium from source to try this API. Learn more.
Highlights/Unhighlights a button in an assistive window.
Parameters | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | parameters |
|
|||||||||||||||
function | (optional) callback |
Called when the operation completes. On failure, runtime.lastError is set. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
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 |
|
||||||
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 |
|
||||||
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 |
|
||||||||||||
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, ScreenType screen) {...};
|
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) {...};
|
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) {...};
|
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) {...};
|
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) {...};
|
onKeyEvent
Fired when a key event is sent from the operating system. The event will be sent to the extension if this extension owns the active IME. The listener function should return true if the event was handled false if it was not. If the event will be evaluated asynchronously, this function must return undefined and the IME must later call keyEventHandled() with the result.
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 requestId) {...};
|
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) {...};
|
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) {...};
|
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) {...};
|
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) {...};
|
onAssistiveWindowButtonClicked
Since Chrome 85. Warning: this is the current Dev channel. Learn more.
This event is sent when a button in an assistive window is clicked.
addListener
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(function callback)
Parameters | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object details) {...};
|