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. - 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
chrome.input.ime.clearComposition(parameters: object, callback: function)
chrome.input.ime.commitText(parameters: object, callback: function)
chrome.input.ime.deleteSurroundingText(parameters: object, callback: function)
chrome.input.ime.hideInputView()
chrome.input.ime.keyEventHandled(requestId: string, response: boolean)
chrome.input.ime.sendKeyEvents(parameters: object, callback: function)
chrome.input.ime.setAssistiveWindowButtonHighlighted(parameters: object, callback: function)
chrome.input.ime.setAssistiveWindowProperties(parameters: object, callback: function)
chrome.input.ime.setCandidateWindowProperties(parameters: object, callback: function)
chrome.input.ime.setCandidates(parameters: object, callback: function)
chrome.input.ime.setComposition(parameters: object, callback: function)
chrome.input.ime.setCursorPosition(parameters: object, callback: function)
chrome.input.ime.setMenuItems(parameters: MenuParameters, callback: function)
chrome.input.ime.updateMenuItems(parameters: MenuParameters, callback: function)
- Events
Types
AssistiveWindowProperties
Properties of the assistive window.
Properties
- announceStringstring optional
Strings for ChromeVox to announce.
- visibleboolean
Sets true to show AssistiveWindow, sets false to hide.
InputContext
Describes an input Context
Properties
- autoCapitalize
The auto-capitalize type of the text field.
- autoCompleteboolean
Whether the text field wants auto-complete.
- autoCorrectboolean
Whether the text field wants auto-correct.
- contextIDnumber
This is used to specify targets of text field operations. This ID becomes invalid as soon as onBlur is called.
- shouldDoLearningboolean
Whether text entered into the text field should be used to improve typing suggestions for the user.
- spellCheckboolean
Whether the text field wants spell-check.
- type
Type of value this text field edits, (Text, Number, URL, etc)
KeyboardEvent
See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
Properties
- altKeyboolean optional
Whether or not the ALT key is pressed.
- altgrKeyboolean optional
Whether or not the ALTGR key is pressed.
- capsLockboolean optional
Whether or not the CAPS_LOCK is enabled.
- codestring
Value of the physical key being pressed. The value is not affected by current keyboard layout or modifier state.
- ctrlKeyboolean optional
Whether or not the CTRL key is pressed.
- extensionIdstring optional
The extension ID of the sender of this keyevent.
- keystring
Value of the key being pressed
- keyCodenumber optional
The deprecated HTML keyCode, which is system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed.
- requestIdstring optional
(Deprecated) The ID of the request. Use the
requestId
param from theonKeyEvent
event instead. - shiftKeyboolean optional
Whether or not the SHIFT key is pressed.
One of keyup or keydown.
MenuItem
A menu item used by an input method to interact with the user from the language menu.
Properties
- checkedboolean optional
Indicates this item should be drawn with a check.
- enabledboolean optional
Indicates this item is enabled.
- idstring
String that will be passed to callbacks referencing this MenuItem.
- labelstring optional
Text displayed in the menu for this item.
- styleMenuItemStyle optional
The type of menu item.
- visibleboolean optional
Indicates this item is visible.
MenuParameters
Properties
- engineIDstring
ID of the engine to use.
- itemsMenuItem[]
MenuItems to add or update. They will be added in the order they exist in the array.
AssistiveWindowButton
ID of buttons in assistive window.
Enum
"undo"
, or "addToDictionary"
AssistiveWindowType
Type of assistive window.
Enum
"undo"
AutoCapitalizeType
The auto-capitalize type of the text field.
Enum
"characters"
, "words"
, or "sentences"
InputContextType
Type of value this text field edits, (Text, Number, URL, etc)
Enum
"text"
, "search"
, "tel"
, "url"
, "email"
, "number"
, "password"
, or "null"
KeyboardEventType
Enum
"keyup"
, or "keydown"
MenuItemStyle
The type of menu item. Radio buttons between separators are considered grouped.
Enum
"check"
, "radio"
, or "separator"
MouseButton
Which mouse buttons was clicked.
Enum
"left"
, "middle"
, or "right"
ScreenType
The screen type under which the IME is activated.
Enum
"normal"
, "login"
, "lock"
, or "secondary-login"
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"
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
- parametersobject
- contextIDnumber
ID of the context where the composition will be cleared
- callbackfunction
Called when the operation completes with a boolean indicating if the text was accepted or not. On failure,
runtime.lastError
is set.The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
commitText
chrome.input.ime.commitText(parameters: object, callback: function)
Commits the provided text to the current input.
Parameters
- parametersobject
- contextIDnumber
ID of the context where the text will be committed
- textstring
The text to commit
- callbackfunction
Called when the operation completes with a boolean indicating if the text was accepted or not. On failure,
runtime.lastError
is set.The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
deleteSurroundingText
chrome.input.ime.deleteSurroundingText(parameters: object, callback: function)
Deletes the text around the caret.
Parameters
- parametersobject
- contextIDnumber
ID of the context where the surrounding text will be deleted.
- engineIDstring
ID of the engine receiving the event.
- lengthnumber
The number of characters to be deleted
- offsetnumber
The offset from the caret position where deletion will start. This value can be negative.
- callbackfunction
Called when the operation completes.
The callback parameter should be a function that looks like this:
() => {...}
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
- requestIdstring
Request id of the event that was handled. This should come from keyEvent.requestId
- responseboolean
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
- parametersobject
- contextIDnumber
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.
- callbackfunction
Called when the operation completes.
The callback parameter should be a function that looks like this:
() => {...}
setAssistiveWindowButtonHighlighted
chrome.input.ime.setAssistiveWindowButtonHighlighted(parameters: object, callback: function)
Highlights/Unhighlights a button in an assistive window.
Parameters
- parametersobject
- announceStringstring optional
The text for the screenreader to announce.
- buttonID
The ID of the button
- contextIDnumber
ID of the context owning the assistive window.
- highlightedboolean
Whether the button should be highlighted.
- windowType
The window type the button belongs to.
- callbackfunction
Called when the operation completes. On failure,
runtime.lastError
is set.The callback parameter should be a function that looks like this:
() => {...}
setAssistiveWindowProperties
chrome.input.ime.setAssistiveWindowProperties(parameters: object, callback: function)
Shows/Hides an assistive window with the given properties.
Parameters
- parametersobject
- contextIDnumber
ID of the context owning the assistive window.
- properties
Properties of the assistive window.
- callbackfunction
Called when the operation completes.
The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
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
- parametersobject
- engineIDstring
ID of the engine to set properties on.
- propertiesobject
- auxiliaryTextstring optional
Text that is shown at the bottom of the candidate window.
- auxiliaryTextVisibleboolean optional
True to display the auxiliary text, false to hide it.
- currentCandidateIndexnumber optional
The index of the current chosen candidate out of total candidates.
- cursorVisibleboolean optional
True to show the cursor, false to hide it.
- pageSizenumber optional
The number of candidates to display per page.
- totalCandidatesnumber optional
The total number of candidates for the candidate window.
- verticalboolean optional
True if the candidate window should be rendered vertical, false to make it horizontal.
- visibleboolean optional
True to show the Candidate window, false to hide it.
- windowPositionWindowPosition optional
Where to display the candidate window.
- callbackfunction
Called when the operation completes.
The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
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
- parametersobject
- candidatesobject[]
List of candidates to show in the candidate window
- annotationstring optional
Additional text describing the candidate
- candidatestring
The candidate
- idnumber
The candidate's id
- labelstring optional
Short string displayed to next to the candidate, often the shortcut key or index
- parentIdnumber optional
The id to add these candidates under
- usageobject optional
The usage or detail description of word.
- bodystring
The body string of detail description.
- titlestring
The title string of details description.
- contextIDnumber
ID of the context that owns the candidate window.
- callbackfunction
Called when the operation completes.
The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
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
- parametersobject
- contextIDnumber
ID of the context where the composition text will be set
- cursornumber
Position in the text of the cursor.
- segmentsobject[] optional
List of segments and their associated types.
- endnumber
Index of the character to end this segment after.
- startnumber
Index of the character to start this segment at
- style
The type of the underline to modify this segment.
- selectionEndnumber optional
Position in the text that the selection ends at.
- selectionStartnumber optional
Position in the text that the selection starts at.
- textstring
Text to set
- callbackfunction
Called when the operation completes with a boolean indicating if the text was accepted or not. On failure,
runtime.lastError
is set.The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
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
- parametersobject
- candidateIDnumber
ID of the candidate to select.
- contextIDnumber
ID of the context that owns the candidate window.
- callbackfunction
Called when the operation completes
The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
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
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
updateMenuItems
chrome.input.ime.updateMenuItems(parameters: MenuParameters, callback: function)
Updates the state of the MenuItems specified
Parameters
- parameters
- callbackfunction
Called when the operation completes
The callback parameter should be a function that looks like this:
() => {...}
Events
onActivate
chrome.input.ime.onActivate.addListener(listener: function)
This event is sent when an IME is activated. It signals that the IME will be receiving onKeyPress events.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string, screen: ScreenType) => {...}
- engineIDstring
ID of the engine receiving the event
- screen
The screen type under which the IME is activated.
onAssistiveWindowButtonClicked
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(listener: function)
This event is sent when a button in an assistive window is clicked.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(details: object) => {...}
- detailsobject
- buttonID
The ID of the button clicked.
- windowType
The type of the assistive window.
onBlur
chrome.input.ime.onBlur.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(contextID: number) => {...}
- contextIDnumber
The ID of the text field that has lost focus. The ID is invalid after this call
onCandidateClicked
chrome.input.ime.onCandidateClicked.addListener(listener: function)
This event is sent if this extension owns the active IME.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string, candidateID: number, button: MouseButton) => {...}
- engineIDstring
ID of the engine receiving the event
- candidateIDnumber
ID of the candidate that was clicked.
- button
Which mouse buttons was clicked.
onDeactivated
chrome.input.ime.onDeactivated.addListener(listener: function)
This event is sent when an IME is deactivated. It signals that the IME will no longer be receiving onKeyPress events.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string) => {...}
- engineIDstring
ID of the engine receiving the event
onFocus
chrome.input.ime.onFocus.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(context: InputContext) => {...}
- context
Describes the text field that has acquired focus.
onInputContextUpdate
chrome.input.ime.onInputContextUpdate.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(context: InputContext) => {...}
- context
An InputContext object describing the text field that has changed.
onKeyEvent
chrome.input.ime.onKeyEvent.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string, keyData: KeyboardEvent, requestId: string) => {...}
- engineIDstring
ID of the engine receiving the event
- keyData
Data on the key event
- requestIdstring
ID of the request. If the event listener returns undefined, then
keyEventHandled
must be called later with thisrequestId
.
onMenuItemActivated
chrome.input.ime.onMenuItemActivated.addListener(listener: function)
Called when the user selects a menu item
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string, name: string) => {...}
- engineIDstring
ID of the engine receiving the event
- namestring
Name of the MenuItem which was activated
onReset
chrome.input.ime.onReset.addListener(listener: function)
This event is sent when chrome terminates ongoing text input session.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string) => {...}
- engineIDstring
ID of the engine receiving the event
onSurroundingTextChanged
chrome.input.ime.onSurroundingTextChanged.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(engineID: string, surroundingInfo: object) => {...}
- engineIDstring
ID of the engine receiving the event
- surroundingInfoobject
The surrounding information.
- anchornumber
The beginning position of the selection. This value indicates caret position if there is no selection.
- focusnumber
The ending position of the selection. This value indicates caret position if there is no selection.
- offsetnumber
The offset position of
text
. Sincetext
only includes a subset of text around the cursor, offset indicates the absolute position of the first character oftext
. - textstring
The text around the cursor. This is only a subset of all text in the input field.