See Also: InputMethodService Members
InputMethodService provides a standard implementation of an InputMethod, which final implementations can derive from and customize. See the base class Android.InputMethodServices.AbstractInputMethodService and the Android.Views.InputMethods.InputMethod interface for more information on the basics of writing input methods.
In addition to the normal Service lifecycle methods, this class introduces some new specific callbacks that most subclasses will want to make use of:
An input method has significant discretion in how it goes about its work: the Android.InputMethodServices.InputMethodService provides a basic framework for standard UI elements (input view, candidates view, and running in fullscreen mode), but it is up to a particular implementor to decide how to use them. For example, one input method could implement an input area with a keyboard, another could allow the user to draw text, while a third could have no input area (and thus not be visible to the user) but instead listen to audio and perform text to speech conversion.
In the implementation provided here, all of these elements are placed together in a single window managed by the InputMethodService. It will execute callbacks as it needs information about them, and provides APIs for programmatic control over them. They layout of these elements is explicitly defined:
Central to most input methods is the soft input view. This is where most user interaction occurs: pressing on soft keys, drawing characters, or however else your input method wants to generate text. Most implementations will simply have their own view doing all of this work, and return a new instance of it when InputMethodService.OnCreateInputView is called. At that point, as long as the input view is visible, you will see user interaction in that view and can call back on the InputMethodService to interact with the application as appropriate.
There are some situations where you want to decide whether or not your soft input view should be shown to the user. This is done by implementing the InputMethodService.OnEvaluateInputViewShown to return true or false based on whether it should be shown in the current environment. If any of your state has changed that may impact this, call InputMethodService.UpdateInputViewShown to have it re-evaluated. The default implementation always shows the input view unless there is a hard keyboard available, which is the appropriate behavior for most input methods.
Often while the user is generating raw text, an input method wants to provide them with a list of possible interpretations of that text that can be selected for use. This is accomplished with the candidates view, and like the soft input view you implement InputMethodService.OnCreateCandidatesView to instantiate your own view implementing your candidates UI.
Management of the candidates view is a little different than the input view, because the candidates view tends to be more transient, being shown only when there are possible candidates for the current text being entered by the user. To control whether the candidates view is shown, you use InputMethodService.SetCandidatesViewShown(bool). Note that because the candidate view tends to be shown and hidden a lot, it does not impact the application UI in the same way as the soft input view: it will never cause application windows to resize, only cause them to be panned if needed for the user to see the current focus.
Sometimes your input method UI is too large to integrate with the application UI, so you just want to take over the screen. This is accomplished by switching to full-screen mode, causing the input method window to fill the entire screen and add its own "extracted text" editor showing the user the text that is being typed. Unlike the other UI elements, there is a standard implementation for the extract editor that you should not need to change. The editor is placed at the top of the IME, above the input and candidates views.
Similar to the input view, you control whether the IME is running in fullscreen mode by implementing InputMethodService.OnEvaluateFullscreenMode to return true or false based on whether it should be fullscreen in the current environment. If any of your state has changed that may impact this, call InputMethodService.UpdateFullscreenMode to have it re-evaluated. The default implementation selects fullscreen mode when the screen is in a landscape orientation, which is appropriate behavior for most input methods that have a significant input area.
When in fullscreen mode, you have some special requirements because the user can not see the application UI. In particular, you should implement InputMethodService.OnDisplayCompletions(Android.Views.InputMethods.CompletionInfo[]) to show completions generated by your application, typically in your candidates view like you would normally show candidates.
The key part of an IME is of course generating text for the application. This is done through calls to the Android.Views.InputMethods.InputConnection interface to the application, which can be retrieved from InputMethodService.CurrentInputConnection. This interface allows you to generate raw key events or, if the target supports it, directly edit in strings of candidates and committed text.
Information about what the target is expected and supports can be found through the Android.Views.InputMethods.EditorInfo class, which is retrieved with InputMethodService.CurrentInputEditorInfo method. The most important part of this is Android.Views.InputMethods.EditorInfo.InputType; in particular, if this is Android.Text.IInputType.TYPE_NULL, then the target does not support complex edits and you need to only deliver raw key events to it. An input method will also want to look at other values here, to for example detect password mode, auto complete text views, phone number entry, etc.
When the user switches between input targets, you will receive calls to InputMethodService.OnFinishInput and InputMethodService.OnStartInput(Android.Views.InputMethods.EditorInfo, System.Boolean). You can use these to reset and initialize your input state for the current target. For example, you will often want to clear any input state, and update a soft keyboard to be appropriate for the new inputType.