chrome.input.ime
- Description
Use the
chrome.input.imeAPI to implement a custom IME for Chrome OS. This allows your extension to handle keystrokes, set the composition, and manage the candidate window. - 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
- Methods
- Events
Types
AssistiveWindowButton
ID of buttons in assistive window.
Type
"undo"
, or"addToDictionary"
AssistiveWindowProperties
Properties of the assistive window.
Properties
- announceString
string optional
Strings for ChromeVox to announce.
- type
"undo"
- visible
boolean
Sets true to show AssistiveWindow, sets false to hide.
AssistiveWindowType
Type of assistive window.
Value
"undo"
AutoCapitalizeType
The auto-capitalize type of the text field.
Type
"characters"
,"words"
, or"sentences"
InputContext
Describes an input Context
Properties
- autoCapitalizeChrome 69+
The auto-capitalize type of the text field.
- autoComplete
boolean
Whether the text field wants auto-complete.
- autoCorrect
boolean
Whether the text field wants auto-correct.
- contextID
number
This is used to specify targets of text field operations. This ID becomes invalid as soon as onBlur is called.
- shouldDoLearning
boolean
Chrome 68+Whether text entered into the text field should be used to improve typing suggestions for the user.
- spellCheck
boolean
Whether the text field wants spell-check.
- type
Type of value this text field edits, (Text, Number, URL, etc)
InputContextType
Type of value this text field edits, (Text, Number, URL, etc)
Type
"text"
,"search"
,"tel"
,"url"
,"email"
,"number"
,"password"
, or"null"
KeyboardEvent
See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
Properties
- altKey
boolean optional
Whether or not the ALT key is pressed.
- altgrKey
boolean optional
Chrome 79+Whether or not the ALTGR key is pressed.
- capsLock
boolean optional
Whether or not the CAPS_LOCK is enabled.
- code
string
Value of the physical key being pressed. The value is not affected by current keyboard layout or modifier state.
- ctrlKey
boolean optional
Whether or not the CTRL key is pressed.
- extensionId
string optional
The extension ID of the sender of this keyevent.
- key
string
Value of the key being pressed
- keyCode
number optional
The deprecated HTML keyCode, which is system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed.
- requestId
string optional
(Deprecated) The ID of the request. Use the
requestIdparam from theonKeyEventevent instead. - shiftKey
boolean optional
Whether or not the SHIFT key is pressed.
One of keyup or keydown.
KeyboardEventType
Type
"keyup"
, or"keydown"
MenuItem
A menu item used by an input method to interact with the user from the language menu.
Properties
- checked
boolean optional
Indicates this item should be drawn with a check.
- enabled
boolean optional
Indicates this item is enabled.
- id
string
String that will be passed to callbacks referencing this MenuItem.
- label
string optional
Text displayed in the menu for this item.
- style
MenuItemStyle optional
The type of menu item.
- visible
boolean optional
Indicates this item is visible.
MenuItemStyle
The type of menu item. Radio buttons between separators are considered grouped.
Type
"check"
,"radio"
, or"separator"
MenuParameters
Properties
- engineID
string
ID of the engine to use.
- items
MenuItem[]
MenuItems to add or update. They will be added in the order they exist in the array.
MouseButton
Which mouse buttons was clicked.
Type
"left"
,"middle"
, or"right"
ScreenType
The screen type under which the IME is activated.
Type
"normal"
,"login"
,"lock"
, or"secondary-login"
UnderlineStyle
The type of the underline to modify this segment.
Type
"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.
Type
"cursor"
, or"composition"
Methods
clearComposition
chrome.input.ime.clearComposition(
parameters:
object,
callback?:
function,
)
Clear the current composition. If this extension does not own the active IME, this fails.
Parameters
- parameters
object
- contextID
number
ID of the context where the composition will be cleared
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
commitText
chrome.input.ime.commitText(
parameters:
object,
callback?:
function,
)
Commits the provided text to the current input.
Parameters
- parameters
object
- contextID
number
ID of the context where the text will be committed
- text
string
The text to commit
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
deleteSurroundingText
chrome.input.ime.deleteSurroundingText(
parameters:
object,
callback?:
function,
)
Deletes the text around the caret.
Parameters
- parameters
object
- contextID
number
ID of the context where the surrounding text will be deleted.
- engineID
string
ID of the engine receiving the event.
- length
number
The number of characters to be deleted
- offset
number
The offset from the caret position where deletion will start. This value can be negative.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
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.
keyEventHandled
chrome.input.ime.keyEventHandled(
requestId:
string,
response:
boolean,
)
Indicates that the key event received by onKeyEvent is handled. This should only be called if the onKeyEvent listener is asynchronous.
Parameters
- requestId
string
Request id of the event that was handled. This should come from keyEvent.requestId
- response
boolean
True if the keystroke was handled, false if not
sendKeyEvents
chrome.input.ime.sendKeyEvents(
parameters:
object,
callback?:
function,
)
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
- parameters
object
- contextID
number
ID of the context where the key events will be sent, or zero to send key events to non-input field.
- keyData
Data on the key event.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setAssistiveWindowButtonHighlighted
chrome.input.ime.setAssistiveWindowButtonHighlighted(
parameters:
object,
callback?:
function,
)
Highlights/Unhighlights a button in an assistive window.
Parameters
- parameters
object
- announceString
string optional
The text for the screenreader to announce.
- buttonID
The ID of the button
- contextID
number
ID of the context owning the assistive window.
- highlighted
boolean
Whether the button should be highlighted.
- windowType
"undo"
The window type the button belongs to.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setAssistiveWindowProperties
chrome.input.ime.setAssistiveWindowProperties(
parameters:
object,
callback?:
function,
)
Shows/Hides an assistive window with the given properties.
Parameters
- parameters
object
- contextID
number
ID of the context owning the assistive window.
- properties
Properties of the assistive window.
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setCandidates
chrome.input.ime.setCandidates(
parameters:
object,
callback?:
function,
)
Sets the current candidate list. This fails if this extension doesn't own the active IME
Parameters
- parameters
object
- candidates
object[]
List of candidates to show in the candidate window
- annotation
string optional
Additional text describing the candidate
- candidate
string
The candidate
- id
number
The candidate's id
- label
string optional
Short string displayed to next to the candidate, often the shortcut key or index
- parentId
number optional
The id to add these candidates under
- usage
object optional
The usage or detail description of word.
- body
string
The body string of detail description.
- title
string
The title string of details description.
- contextID
number
ID of the context that owns the candidate window.
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setCandidateWindowProperties
chrome.input.ime.setCandidateWindowProperties(
parameters:
object,
callback?:
function,
)
Sets the properties of the candidate window. This fails if the extension doesn't own the active IME
Parameters
- parameters
object
- engineID
string
ID of the engine to set properties on.
- properties
object
- auxiliaryText
string optional
Text that is shown at the bottom of the candidate window.
- auxiliaryTextVisible
boolean optional
True to display the auxiliary text, false to hide it.
- currentCandidateIndex
number optional
Chrome 84+The index of the current chosen candidate out of total candidates.
- cursorVisible
boolean optional
True to show the cursor, false to hide it.
- pageSize
number optional
The number of candidates to display per page.
- totalCandidates
number optional
Chrome 84+The total number of candidates for the candidate window.
- vertical
boolean optional
True if the candidate window should be rendered vertical, false to make it horizontal.
- visible
boolean optional
True to show the Candidate window, false to hide it.
- windowPosition
WindowPosition optional
Where to display the candidate window.
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setComposition
chrome.input.ime.setComposition(
parameters:
object,
callback?:
function,
)
Set the current composition. If this extension does not own the active IME, this fails.
Parameters
- parameters
object
- contextID
number
ID of the context where the composition text will be set
- cursor
number
Position in the text of the cursor.
- segments
object[] optional
List of segments and their associated types.
- end
number
Index of the character to end this segment after.
- start
number
Index of the character to start this segment at
- style
The type of the underline to modify this segment.
- selectionEnd
number optional
Position in the text that the selection ends at.
- selectionStart
number optional
Position in the text that the selection starts at.
- text
string
Text to set
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setCursorPosition
chrome.input.ime.setCursorPosition(
parameters:
object,
callback?:
function,
)
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
- parameters
object
- candidateID
number
ID of the candidate to select.
- contextID
number
ID of the context that owns the candidate window.
- callback
function optional
The
callbackparameter looks like:(success: boolean) => void- success
boolean
Returns
Promise<boolean>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setMenuItems
chrome.input.ime.setMenuItems(
parameters:
MenuParameters,
callback?:
function,
)
Adds the provided menu items to the language menu when this IME is active.
Parameters
- parameters
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
updateMenuItems
chrome.input.ime.updateMenuItems(
parameters:
MenuParameters,
callback?:
function,
)
Updates the state of the MenuItems specified
Parameters
- parameters
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 111+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onActivate
chrome.input.ime.onActivate.addListener(
callback:
function,
)
This event is sent when an IME is activated. It signals that the IME will be receiving onKeyPress events.
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string, screen: ScreenType) => void- engineID
string
- screen
onAssistiveWindowButtonClicked
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
callback:
function,
)
This event is sent when a button in an assistive window is clicked.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void- details
object
- buttonID
The ID of the button clicked.
- windowType
The type of the assistive window.
onBlur
chrome.input.ime.onBlur.addListener(
callback:
function,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(contextID: number) => void- contextID
number
onCandidateClicked
chrome.input.ime.onCandidateClicked.addListener(
callback:
function,
)
This event is sent if this extension owns the active IME.
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string, candidateID: number, button: MouseButton) => void- engineID
string
- candidateID
number
- button
onDeactivated
chrome.input.ime.onDeactivated.addListener(
callback:
function,
)
This event is sent when an IME is deactivated. It signals that the IME will no longer be receiving onKeyPress events.
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string) => void- engineID
string
onFocus
chrome.input.ime.onFocus.addListener(
callback:
function,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(context: InputContext) => void- context
onInputContextUpdate
chrome.input.ime.onInputContextUpdate.addListener(
callback:
function,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(context: InputContext) => void- context
onKeyEvent
chrome.input.ime.onKeyEvent.addListener(
callback:
function,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined- engineID
string
- keyData
- requestId
string
- returns
boolean | undefined
onMenuItemActivated
chrome.input.ime.onMenuItemActivated.addListener(
callback:
function,
)
Called when the user selects a menu item
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string, name: string) => void- engineID
string
- name
string
onReset
chrome.input.ime.onReset.addListener(
callback:
function,
)
This event is sent when chrome terminates ongoing text input session.
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string) => void- engineID
string
onSurroundingTextChanged
chrome.input.ime.onSurroundingTextChanged.addListener(
callback:
function,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(engineID: string, surroundingInfo: object) => void- engineID
string
- surroundingInfo
object
- anchor
number
The beginning position of the selection. This value indicates caret position if there is no selection.
- focus
number
The ending position of the selection. This value indicates caret position if there is no selection.
- offset
number
Chrome 46+The offset position of
text. Sincetextonly includes a subset of text around the cursor, offset indicates the absolute position of the first character oftext. - text
string
The text around the cursor. This is only a subset of all text in the input field.