diff --git a/docs/html/guide/topics/text/creating-input-method.jd b/docs/html/guide/topics/text/creating-input-method.jd index 205fd966654e4..4b6b7b7fb7ec9 100644 --- a/docs/html/guide/topics/text/creating-input-method.jd +++ b/docs/html/guide/topics/text/creating-input-method.jd @@ -4,6 +4,30 @@ page.tags=ime,keyboard,inputmethodservice
+

In This Document

+
    +
  1. + The IME Lifecycle +
    2. +
  2. + Declaring IME Components in the Manifest +
    3. +
  3. + The Input Method API +
    4. +
  4. + Designing the Input Method UI +
    5. +
  5. + Sending Text to the Application +
    6. +
  6. + Creating an IME Subtype +
    7. +
  7. + General IME Considerations +
    8. +

See also

  1. @@ -16,29 +40,20 @@ page.tags=ime,keyboard,inputmethodservice

- An input method editor (IME) is a user control that enables users to enter text. Android - provides an extensible input method framework that allows applications to provide users - alternative input methods, such as on-screen keyboards or even speech input. Once installed, - users can select which IME they want to use from the system settings and use it across the + An input method editor (IME) is a user control that enables users to enter text. Android + provides an extensible input method framework that allows applications to provide users + alternative input methods, such as on-screen keyboards or even speech input. Once installed, + users can select which IME they want to use from the system settings and use it across the entire system; only one IME may be enabled at a time.

To add an IME to the Android system, you create an Android application - containing a class that extends {@link android.inputmethodservice.InputMethodService}. In + containing a class that extends {@link android.inputmethodservice.InputMethodService}. In addition, you usually create a "settings" activity that passes options to the IME service. You can also define a settings UI that's displayed as part of the system settings.

-

This article covers the following:

-

- If you haven't worked with IMEs before, you should read the introductory article + If you haven't worked with IMEs before, you should read the introductory article Onscreen Input Methods first. Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify to start building your own IME. @@ -59,16 +74,16 @@ page.tags=ime,keyboard,inputmethodservice

Declaring IME Components in the Manifest

In the Android system, an IME is an Android application that contains a special IME service. - The application's manifest file must declare the service, request the necessary permissions, - provide an intent filter that matches the action action.view.InputMethod, and + The application's manifest file must declare the service, request the necessary permissions, + provide an intent filter that matches the action action.view.InputMethod, and provide metadata that defines characteristics of the IME. In addition, to provide a settings interface that allows the user to modify the behavior of the IME, you can define a "settings" activity that can be launched from System Settings.

The following snippet declares IME service. It requests the permission {@link - android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to - the system, sets up an intent filter that matches the action + android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to + the system, sets up an intent filter that matches the action android.view.InputMethod, and defines metadata for the IME: 

@@ -88,7 +103,7 @@ page.tags=ime,keyboard,inputmethodservice
     for the IME application:

 
     <!-- Optional: an activity for controlling the IME settings -->
-    <activity android:name="FastInputIMESettings" 
+    <activity android:name="FastInputIMESettings"
         android:label="@string/fast_input_settings">
         <intent-filter>
             <action android:name="android.intent.action.MAIN"/>
@@ -105,12 +120,12 @@ page.tags=ime,keyboard,inputmethodservice
     handling keyboard characters.
 

 

-    The central part of an IME is a service component, a class that extends 
-    {@link android.inputmethodservice.InputMethodService}. In addition to implementing the 
-    normal service lifecycle, this class has callbacks for providing your IME's UI, handling user 
+    The central part of an IME is a service component, a class that extends
+    {@link android.inputmethodservice.InputMethodService}. In addition to implementing the
+    normal service lifecycle, this class has callbacks for providing your IME's UI, handling user
     input, and delivering text to the field that currently has focus. By default, the
-    {@link android.inputmethodservice.InputMethodService} class provides most of the implementation 
-    for managing the state and visibility of the IME and communicating with the current 
+    {@link android.inputmethodservice.InputMethodService} class provides most of the implementation
+    for managing the state and visibility of the IME and communicating with the current
     input field.
 

 

@@ -122,13 +137,13 @@ page.tags=ime,keyboard,inputmethodservice
         Defines the communication channel from an {@link android.view.inputmethod.InputMethod}
         back to the application that is receiving its input. You use it to read text around the
         cursor, commit text to the text box, and send raw key events to the application.
-        Applications should extend this class rather than implementing the base interface 
+        Applications should extend this class rather than implementing the base interface
         {@link android.view.inputmethod.InputConnection}.
     
     
{@link android.inputmethodservice.KeyboardView}

     

         An extension of {@link android.view.View} that renders a keyboard and responds to user
-        input events. The keyboard layout is specified by an instance of 
+        input events. The keyboard layout is specified by an instance of
         {@link android.inputmethodservice.Keyboard}, which you can define in an XML file.
     

 
@@ -141,40 +156,40 @@ page.tags=ime,keyboard,inputmethodservice
 
Input view

 

     The input view is the UI where the user inputs text, in the form of keyclicks, handwriting or
-    gestures. When the iIME is displayed for the first time, the system calls the 
+    gestures. When the iIME is displayed for the first time, the system calls the
     {@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your
     implementation of this method, you create the layout you want to display in the IME
     window and return the layout to the system. This snippet is an example of implementing the
     {@link android.inputmethodservice.InputMethodService#onCreateInputView()} method:
 
-    @Override 
-    public View onCreateInputView() { 
-        MyKeyboardView inputView = 
+    @Override
+    public View onCreateInputView() {
+        MyKeyboardView inputView =
             (MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null);
-    
-        inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard); 
-        
-        return mInputView; 
-    } 
+
+        inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard);
+
+        return mInputView;
+    }
 

 

-    In this example, {@code MyKeyboardView} is an instance of a custom implementation of 
-    {@link android.inputmethodservice.KeyboardView} that renders a 
-    {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard, 
-    see the  Soft Keyboard sample 
+    In this example, {@code MyKeyboardView} is an instance of a custom implementation of
+    {@link android.inputmethodservice.KeyboardView} that renders a
+    {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard,
+    see the  Soft Keyboard sample
     app for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class.
 

 
Candidates view

 

     The candidates view is the UI where the IME displays potential word corrections or
-    suggestions for the user to select. In the IME lifecycle, the system calls 
-    {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready 
+    suggestions for the user to select. In the IME lifecycle, the system calls
+    {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready
     to display the candidate view. In your implementation of this method, return a layout that shows
     word suggestions, or return null if you don’t want to show anything (a null response is the
     default behavior, so you don’t have to implement this if you don’t provide suggestions).

 

-    For an example implementation that provides user suggestions, see the 
-    Soft Keyboard sample 
+    For an example implementation that provides user suggestions, see the
+    Soft Keyboard sample
     app.
 

 
UI design considerations

@@ -209,10 +224,10 @@ page.tags=ime,keyboard,inputmethodservice
     Figure 2. Latin IME input types.
 

 

-    When an input field receives focus and your IME starts, the system calls 
+    When an input field receives focus and your IME starts, the system calls
     {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean)
-    onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that 
-    contains details about the input type and other attributes of the text field. In this object, 
+    onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that
+    contains details about the input type and other attributes of the text field. In this object,
     the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input
     type.
 

@@ -223,7 +238,7 @@ page.tags=ime,keyboard,inputmethodservice
     this:
 

 
-inputType & InputType.TYPE_MASK_CLASS 
+inputType & InputType.TYPE_MASK_CLASS
 

 

 The input type bit pattern can have one of several values, including:
@@ -248,7 +263,7 @@ The input type bit pattern can have one of several values, including:
     
 
 

-    These constants are described in more detail in the reference documentation for 
+    These constants are described in more detail in the reference documentation for
     {@link android.text.InputType}.
 

 

@@ -287,8 +302,8 @@ The input type bit pattern can have one of several values, including:
 

     As the user inputs text with your IME, you can send text to the application by
     sending individual key events or by editing the text around the cursor in the application's text
-    field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} 
-    to deliver the text. To get this instance, call 
+    field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection}
+    to deliver the text. To get this instance, call
     {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection
     InputMethodService.getCurrentInputConnection()}.
 

@@ -336,18 +351,18 @@ The input type bit pattern can have one of several values, including:
 

 
     InputConnection ic = getCurrentInputConnection();
-    
+
     ic.deleteSurroundingText(4, 0);
-    
+
     ic.commitText("Hello", 1);
-    
+
     ic.commitText("!", 1);
 

 
Composing text before committing

 

     If your IME does text prediction or requires multiple steps to compose a glyph or
     word, you can show the progress in the text field until the user commits the word, and then you
-    can replace the partial composition with the completed text. You may give special treatment to 
+    can replace the partial composition with the completed text. You may give special treatment to
     the text by adding a "span" to it when you pass it to InputConnection#setComposingText().
 

 

@@ -385,10 +400,10 @@ The input type bit pattern can have one of several values, including:
     selection during composition. You may also want to trap the back key to dismiss any popups
     originating from the input method window.

 

-    To intercept hardware keys, override 
+    To intercept hardware keys, override
     {@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()}
-    and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. 
-    See the Soft Keyboard sample 
+    and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}.
+    See the Soft Keyboard sample
     app for an example.
 

 

@@ -396,7 +411,7 @@ The input type bit pattern can have one of several values, including:
 

 
Creating an IME Subtype

 

-    Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A 
+    Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A
     subtype can represent: