InputMethodService

The back button will close the input window.

This input method will consume the back key.

This input method will not consume the back key.

You can call this to try to enable hardware accelerated drawing for your IME. This must be set before onCreate(), so you will typically call it in your constructor. It is not always possible to use hardware accelerated drawing in an IME (for example on low-end devices that do not have the resources to support this), so the call returns true if it succeeds otherwise false if you will need to draw in software. You must be able to handle either case.

Returns the visibility mode (either View.INVISIBLE or View.GONE) of the candidates view when it is not shown. The default implementation returns GONE when isExtractViewShown() returns true, otherwise VISIBLE. Be careful if you change this to return GONE in other situations -- if showing or hiding the candidates view causes your window to resize, this can cause temporary drawing artifacts as the resize takes place.

Return the currently active InputBinding for the input method, or null if there is none.

Retrieve the currently active InputConnection that is bound to the input method, or null if there is none.

Return the maximum width, in pixels, available the input method. Input methods are positioned at the bottom of the screen and, unless running in fullscreen, will generally want to be as short as possible so should compute their height based on their contents. However, they can stretch as much as needed horizontally. The function returns to you the maximum amount of space available horizontally, which you can use if needed for UI placement.

In many cases this is not needed, you can just rely on the normal view layout mechanisms to position your views within the full horizontal space given to the input method.

Note that this value can change dynamically, in particular when the screen orientation changes.

Return text that can be used as a button label for the given EditorInfo.imeOptions. Returns null if there is no action requested. Note that there is no guarantee that the returned text will be relatively short, so you probably do not want to use it as text on a soft keyboard key label.

Return whether the fullscreen extract view is shown. This will only return true if isFullscreenMode() returns true, and in that case its value depends on the last call to setExtractViewShown(boolean). This effectively lets you determine if the application window is entirely covered (when this returns true) or if some part of it may be shown (if this returns false, though if isFullscreenMode() returns true in that case then it is probably only a sliver of the application).

Return whether the input method is currently running in fullscreen mode. This is the mode that was last determined and applied by updateFullscreenMode().

Return whether the soft input view is currently shown to the user. This is the state that was last determined and applied by updateInputViewShown().

Returns true if we have been asked to show our input view.

Called when a new client has bound to the input method. This may be followed by a series of onStartInput(EditorInfo, boolean) and onFinishInput() calls as the user navigates through its UI. Upon this call you know that getCurrentInputBinding() and getCurrentInputConnection() return valid objects.

Compute the interesting insets into your UI. The default implementation uses the top of the candidates frame for the visible insets, and the top of the input frame for the content insets. The default touchable insets are TOUCHABLE_INSETS_VISIBLE.

Note that this method is not called when isExtractViewShown() returns true, since in that case the application is left as-is behind the input method and not impacted by anything in its UI.

Take care of handling configuration changes. Subclasses of InputMethodService generally don't need to deal directly with this on their own; the standard implementation here takes care of regenerating the input method UI as a result of the configuration change, so you can rely on your onCreateInputView() and other methods being called as appropriate due to a configuration change.

When a configuration change does happen, onInitializeInterface() is guaranteed to be called the next time prior to any of the other input or UI creation callbacks. The following will be called immediately depending if appropriate for current state: onStartInput(EditorInfo, boolean) if input is active, and onCreateInputView() and onStartInputView(EditorInfo, boolean) and related appropriate functions if the UI is displayed.

Update the given window's parameters for the given mode. This is called when the window is first displayed and each time the fullscreen or candidates only mode changes.

The default implementation makes the layout for the window MATCH_PARENT x MATCH_PARENT when in fullscreen mode, and MATCH_PARENT x WRAP_CONTENT when in non-fullscreen mode.

Called by the system when the service is first created. Do not call this method directly.

Create and return the view hierarchy used to show candidates. This will be called once, when the candidates are first displayed. You can return null to have no candidates view; the default implementation returns null.

To control when the candidates view is displayed, use setCandidatesViewShown(boolean). To change the candidates view after the first one is created by this function, use setCandidatesView(View).

Called by the framework to create the layout for showing extacted text. Only called when in fullscreen mode. The returned view hierarchy must have an ExtractEditText whose ID is inputExtractEditText.

Implement to return our standard InputMethodService.InputMethodImpl. Subclasses can override to provide their own customized version.

Implement to return our standard InputMethodService.InputMethodSessionImpl. Subclasses can override to provide their own customized version.

Create and return the view hierarchy used for the input area (such as a soft keyboard). This will be called once, when the input area is first displayed. You can return null to have no input area; the default implementation returns null.

To control when the input view is displayed, implement onEvaluateInputViewShown(). To change the input view after the first one is created by this function, use setInputView(View).

Called by the system to notify a Service that it is no longer used and is being removed. The service should clean up any resources it holds (threads, registered receivers, etc) at this point. Upon return, there will be no more calls in to this Service object and it is effectively dead. Do not call this method directly.

Called when the application has reported auto-completion candidates that it would like to have the input method displayed. Typically these are only used when an input method is running in full-screen mode, since otherwise the user can see and interact with the pop-up window of completions shown by the application.

The default implementation here does nothing.

Override this to control when the input method should run in fullscreen mode. The default implementation runs in fullsceen only when the screen is in landscape mode. If you change what this returns, you will need to call updateFullscreenMode() yourself whenever the returned value may have changed to have it re-evaluated and applied.

Override this to control when the soft input area should be shown to the user. The default implementation only shows the input view when there is no hard keyboard or the keyboard is hidden. If you change what this returns, you will need to call updateInputViewShown() yourself whenever the returned value may have changed to have it re-evaluated and applied.

This is called when the user has selected a context menu item from the extracted text view, when running in fullscreen mode. The default implementation sends this action to the current InputConnection's performContextMenuAction(int), for it to be processed in underlying "real" editor. Re-implement this to provide whatever behavior you want.

This is called when the user has performed a cursor movement in the extracted text view, when it is running in fullscreen mode. The default implementation hides the candidates view when a vertical movement happens, but only if the extracted text editor has a vertical scroll bar because its text doesn't fit. Re-implement this to provide whatever behavior you want.

This is called when the user has moved the cursor in the extracted text view, when running in fullsreen mode. The default implementation performs the corresponding selection change on the underlying text editor.

This is called when the user has clicked on the extracted text view, when running in fullscreen mode. The default implementation hides the candidates view when this happens, but only if the extracted text editor has a vertical scroll bar because its text doesn't fit. Re-implement this to provide whatever behavior you want.

This is called when, while currently displayed in extract mode, the current input target changes. The default implementation will auto-hide the IME if the new target is not a full editor, since this can be a confusing experience for the user.

Called when the candidates view is being hidden from the user. This will be called either prior to hiding the window, or prior to switching to another target for editing.

The default implementation uses the InputConnection to clear any active composing text; you can override this (not calling the base class implementation) to perform whatever behavior you would like.

Called to inform the input method that text input has finished in the last editor. At this point there may be a call to onStartInput(EditorInfo, boolean) to perform input in a new editor, or the input method may be left idle. This method is not called when input restarts in the same editor.

The default implementation uses the InputConnection to clear any active composing text; you can override this (not calling the base class implementation) to perform whatever behavior you would like.

Called when the input view is being hidden from the user. This will be called either prior to hiding the window, or prior to switching to another target for editing.

The default implementation uses the InputConnection to clear any active composing text; you can override this (not calling the base class implementation) to perform whatever behavior you would like.

Override this to intercept generic motion events before they are processed by the application. If you return true, the application will not itself process the event. If you return false, the normal application processing will occur as if the IME had not seen the event at all.

This is a hook that subclasses can use to perform initialization of their interface. It is called for you prior to any of your UI objects being created, both after the service is first created and after a configuration change happens.

Override this to intercept key down events before they are processed by the application. If you return true, the application will not process the event itself. If you return false, the normal application processing will occur as if the IME had not seen the event at all.

The default implementation intercepts KeyEvent.KEYCODE_BACK if the IME is currently shown, to possibly hide it when the key goes up (if not canceled or long pressed). In addition, in fullscreen mode only, it will consume DPAD movement events to move the cursor in the extracted text view, not allowing them to perform navigation in the underlying application.

Default implementation of KeyEvent.Callback.onKeyLongPress(): always returns false (doesn't handle the event).

Override this to intercept special key multiple events before they are processed by the application. If you return true, the application will not itself process the event. If you return false, the normal application processing will occur as if the IME had not seen the event at all.

The default implementation always returns false, except when in fullscreen mode, where it will consume DPAD movement events to move the cursor in the extracted text view, not allowing them to perform navigation in the underlying application.

Override this to intercept key up events before they are processed by the application. If you return true, the application will not itself process the event. If you return false, the normal application processing will occur as if the IME had not seen the event at all.

The default implementation intercepts KeyEvent.KEYCODE_BACK to hide the current IME UI if it is shown. In addition, in fullscreen mode only, it will consume DPAD movement events to move the cursor in the extracted text view, not allowing them to perform navigation in the underlying application.

The system has decided that it may be time to show your input method. This is called due to a corresponding call to your InputMethod.showSoftInput() method. The default implementation uses onEvaluateInputViewShown(), onEvaluateFullscreenMode(), and the current configuration to decide whether the input view should be shown at this point.

Called when only the candidates view has been shown for showing processing as the user enters text through a hard keyboard. This will always be called after onStartInput(EditorInfo, boolean), allowing you to do your general setup there and just view-specific setup here. You are guaranteed that onCreateCandidatesView() will have been called some time before this function is called.

Note that this will not be called when the input method is running in full editing mode, and thus receiving onStartInputView(EditorInfo, boolean) to initiate that operation. This is only for the case when candidates are being shown while the input method editor is hidden but wants to show its candidates UI as text is entered through some other mechanism.

Called to inform the input method that text input has started in an editor. You should use this callback to initialize the state of your input to match the state of the editor given to it.

Called when the input view is being shown and input has started on a new editor. This will always be called after onStartInput(EditorInfo, boolean), allowing you to do your general setup there and just view-specific setup here. You are guaranteed that onCreateInputView() will have been called some time before this function is called.

Override this to intercept trackball motion events before they are processed by the application. If you return true, the application will not itself process the event. If you return false, the normal application processing will occur as if the IME had not seen the event at all.

Called when the previous bound client is no longer associated with the input method. After returning getCurrentInputBinding() and getCurrentInputConnection() will no longer return valid objects.

Called when the application has reported a new location of its text cursor. This is only called if explicitly requested by the input method. The default implementation does nothing.

Called when the application has reported a new location of its text insertion point and characters in the composition string. This is only called if explicitly requested by the input method. The default implementation does nothing.

Called when the application has reported new extracted text to be shown due to changes in its current text state. The default implementation here places the new text in the extract edit text, when the input method is running in fullscreen mode.

Called when the fullscreen-mode extracting editor info has changed, to update the state of its UI such as the action buttons shown. You do not need to deal with this if you are using the standard full screen extract UI. If replacing it, you will need to re-implement this to put the appropriate action button in your own UI and handle it, and perform any other changes.

The standard implementation turns on or off its accessory area depending on whether there is an action button, and hides or shows the entire extract area depending on whether it makes sense for the current editor. In particular, a TYPE_NULL or TYPE_TEXT_VARIATION_FILTER input type will turn off the extract area since there is no text to be shown.

Called when the fullscreen-mode extracting editor info has changed, to determine whether the extracting (extract text and candidates) portion of the UI should be shown. The standard implementation hides or shows the extract area depending on whether it makes sense for the current editor. In particular, a TYPE_NULL input type or IME_FLAG_NO_EXTRACT_UI flag will turn off the extract area since there is no text to be shown.

Called when the application has reported a new selection region of the text. This is called whether or not the input method has requested extracted text updates, although if so it will not receive this call if the extracted text has changed as well.

Be careful about changing the text in reaction to this call with methods such as setComposingText, commitText or deleteSurroundingText. If the cursor moves as a result, this method will be called again, which may result in an infinite loop.

The default implementation takes care of updating the cursor in the extract text, if it is being shown.

Called when the user tapped or clicked a text view. IMEs can't rely on this method being called because this was not part of the original IME protocol, so applications with custom text editing written before this method appeared will not call to inform the IME of this interaction.

Called when the input method window has been hidden from the user, after previously being visible.

Called when the input method window has been shown to the user, after previously not being visible. This is done after all of the UI setup for the window has occurred (creating its views etc).

Close this input method's soft input area, removing it from the display. The input method will continue running, but the user can no longer use it to generate input by touching the screen.

Ask the input target to execute its default action via InputConnection.performEditorAction().

Send the given key event code (as defined by KeyEvent) to the current input connection is a key down + key up event pair. The sent events have KeyEvent.FLAG_SOFT_KEYBOARD set, so that the recipient can identify them as coming from a software input method, and KeyEvent.FLAG_KEEP_TOUCH_MODE, so that they don't impact the current touch mode of the UI.

Note that it's discouraged to send such key events in normal operation; this is mainly for use with TYPE_NULL type text fields, or for non-rich input methods. A reasonably capable software input method should use the commitText(CharSequence, int) family of methods to send text to an application, rather than sending key events.

Send the given UTF-16 character to the current input connection. Most characters will be delivered simply by calling InputConnection.commitText() with the character; some, however, may be handled different. In particular, the enter character ('\n') will either be delivered as an action code or a raw key event, as appropriate. Consider this as a convenience method for IMEs that do not have a full implementation of actions; a fully complying IME will decide of the right action for each event and will likely never call this method except maybe to handle events coming from an actual hardware keyboard.

Replaces the current candidates view with a new one. You only need to call this when dynamically changing the view; normally, you should implement onCreateCandidatesView() and create your view when first needed by the input method.

Controls the visibility of the candidates display area. By default it is hidden.

Controls the visibility of the extracted text area. This only applies when the input method is in fullscreen mode, and thus showing extracted text. When false, the extracted text will not be shown, allowing some of the application to be seen behind. This is normally set for you by onUpdateExtractingVisibility(EditorInfo). This controls the visibility of both the extracted text and candidate view; the latter since it is not useful if there is no text to see.

Replaces the current input view with a new one. You only need to call this when dynamically changing the view; normally, you should implement onCreateInputView() and create your view when first needed by the input method.

You can call this to customize the theme used by your IME's window. This theme should typically be one that derives from Theme_InputMethod, which is the default theme you will get. This must be set before onCreate(), so you will typically call it in your constructor with the resource ID of your custom theme.

Force switch to a new input method, as identified by id. This input method will be destroyed, and the requested one started on the current input field.

Re-evaluate whether the input method should be running in fullscreen mode, and update its UI if this has changed since the last time it was evaluated. This will call onEvaluateFullscreenMode() to determine whether it should currently run in fullscreen mode. You can use isFullscreenMode() to determine if the input method is currently running in fullscreen mode.

Re-evaluate whether the soft input area should currently be shown, and update its UI if this has changed since the last time it was evaluated. This will call onEvaluateInputViewShown() to determine whether the input view should currently be shown. You can use isInputViewShown() to determine if the input view is currently shown.

Performs a dump of the InputMethodService's internal state. Override to add your own information to the dump.

Called when the subtype was changed.