Skip to content

Most visited

Recently visited

navigation

Image Keyboard Support

Figure 1. Example of Image Keyboard Support

Users often want to communicate with emojis, stickers, and other kinds of rich content. In previous versions of Android, soft keyboards (also known as input method editors or IMEs) could send only unicode emoji to apps. For rich content, apps had to either build app-specific APIs that couldn't be used in other apps or use workaround like sending images through Easy Share Action or the clipboard.

With Android 7.1 (API level 25), the Android SDK includes the Commit Content API, which provides a universal way for IMEs to send images and other rich content directly to a text editor in an app. The API is also available in v13 Support Library as of revision 25.0.0. We recommend using the Support Library because it runs on devices as early as Android 3.2 (API Level 13), and it contains helper methods that simplify implementation.

With this API, you can build messaging apps that accept rich content from any keyboard, as well as, keyboards that can send rich content to any app. The Google Keyboard and apps like Google Messenger support the Commit Content API in Android 7.1 (see Figure 1).

This page shows you how to implement the Commit Content API in both IMEs and apps.

How it works

Keyboard image insertion requires participation from both the IME and the app. The following sequence describes each step in the image insertion process:

  1. When the user taps on an EditText, the editor sends a list of MIME content types that it accepts in EditorInfo.contentMimeTypes.

  2. The IME reads the list of supported types and displays content in the soft keyboard that the editor can accept.

  3. When the user selects an image, the IME calls commitContent() and sends an InputContentInfo to the editor. The commitContent() call is analogous to the commitText() call, but for rich content. InputContentInfo contains an URI that identifies the content in a content provider. Your app can then request permission and read the content from the URI.

Adding Image Support to Apps

To accept rich content from IMEs, apps must tell IMEs what content types it accepts and specify a callbackup method that is executed when content is received. The following example demonstrates how to create an EditText that accept PNG images:

EditText editText = new EditText(this) {
    @Override
    public InputConnection onCreateInputConnection(EditorInfo editorInfo) {
        final InputConnection ic = super.onCreateInputConnection(editorInfo);
        EditorInfoCompat.setContentMimeTypes(editorInfo,
                new String [] {"image/png"});

        final InputConnectionCompat.OnCommitContentListener callback =
            new InputConnectionCompat.OnCommitContentListener() {
                @Override
                public boolean onCommitContent(InputContentInfoCompat inputContentInfo,
                        int flags, Bundle opts) {
                    // read and display inputContentInfo asynchronously
                    if (BuildCompat.isAtLeastNMR1() && (flags &
                        InputConnectionCompat.INPUT_CONTENT_GRANT_READ_URI_PERMISSION) != 0) {
                        try {
                            inputContentInfo.requestPermission();
                        }
                        catch (Exception e) {
                            return false; // return false if failed
                        }
                    }

                    // read and display inputContentInfo asynchronously.
                    // call inputContentInfo.releasePermission() as needed.

                    return true;  // return true if succeeded
                }
            };
        return InputConnectionCompat.createWrapper(ic, editorInfo, callback);
    }
};

There’s a lot going on, so let’s explain what's going on.

Here are some recommended practices:

To test your app, make sure your device or emulator has a keyboard that is able to send rich content. You can either use the Google Keyboard in Android 7.1 or higher or install the CommitContent IME sample.

For a complete code sample, see the CommitContent App sample.

Adding Image Support to IMEs

IMEs that want to send rich content to apps must implement the Commit Content API as shown below:

@Override
public void onStartInputView(EditorInfo info, boolean restarting) {
    String[] mimeTypes = EditorInfoCompat.getContentMimeTypes(editorInfo);

    boolean gifSupported = false;
    for (String mimeType : mimeTypes) {
        if (ClipDescription.compareMimeTypes(mimeType, "image/gif")) {
            gifSupported = true;
        }
    }

    if (gifSupported) {
        // the target editor supports GIFs. enable corresponding content
    } else {
        // the target editor does not support GIFs. disable corresponding content
    }
}
/**
 * Commits a GIF image
 *
 * @param contentUri Content URI of the GIF image to be sent
 * @param imageDescription Description of the GIF image to be sent
 */
public static void commitGifImage(Uri contentUri, String imageDescription) {
    InputContentInfoCompat inputContentInfo = new InputContentInfoCompat(
            contentUri,
            new ClipDescription(imageDescription, new String[]{"image/gif"}));
    InputConnection inputConnection = getCurrentInputConnection();
    EditorInfo editorInfo = getCurrentInputEditorInfo();
    Int flags = 0;
    If (android.os.Build.VERSION.SDK_INT >= 25) {
        flags |= InputConnectionCompat.INPUT_CONTENT_GRANT_READ_URI_PERMISSION;
    }
    InputConnectionCompat.commitContent(
            inputConnection, editorInfo, inputContentInfo, flags, opts);
}

To test your IME, make sure your device or emulator has an app that is able to receive rich content. You can either use the Google Messenger app in Android 7.1 or higher or install the CommitContent App sample.

For a complete code sample, see the CommitContent IME sample.

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.