EmojiCompat

public class EmojiCompat
extends Object

java.lang.Object
   ↳ androidx.emoji2.text.EmojiCompat


Main class to keep Android devices up to date with the newest emojis by adding EmojiSpans to a given CharSequence.

By default, EmojiCompat is initialized by EmojiCompatInitializer, which performs deferred font loading to avoid potential app startup delays. The default behavior is to load the font shortly after the first Activity resumes. EmojiCompatInitializer will configure EmojiCompat to use the system emoji font provider via DefaultEmojiCompatConfig and always creates a new background thread for font loading.

EmojiCompat will only allow one instance to be initialized and any calls to init(Config) after the first one will have no effect. As a result, configuration options may not be provided when using EmojiCompatInitializer. To provide a custom configuration, disable EmojiCompatInitializer in the manifest with:

     
         
     
 
When not using EmojiCompatInitializer, EmojiCompat must to be initialized manually using init(EmojiCompat.Config). It is recommended to make the initialization as early as possible in your app, such as from Application.onCreate().

init(Config) is fast and may be called from the main thread on the path to displaying the first activity. However, loading the emoji font takes significant resources on a background thread, so it is suggested to use LOAD_STRATEGY_MANUAL in all manual configurations to defer font loading until after the first screen displays. Font loading may be started by calling load()}. See the implementation EmojiCompatInitializer for ideas when building a manual configuration.

After initialization the get() function can be used to get the configured instance and the process(CharSequence) function can be used to update a CharSequence with emoji EmojiSpans.

CharSequence processedSequence = EmojiCompat.get().process("some string")

During loading information about emojis is not available. Before the EmojiCompat instance has finished loading, calls to functions such as process(CharSequence) will throw an exception. It is safe to call process when getLoadState() returns LOAD_STATE_SUCCEEDED. To register a callback when loading completes use EmojiCompat.InitCallback.

Summary

Nested classes

class EmojiCompat.Config

Configuration class for EmojiCompat. 

interface EmojiCompat.GlyphChecker

Interface to check if a given emoji exists on the system. 

class EmojiCompat.InitCallback

Listener class for the initialization of the EmojiCompat. 

interface EmojiCompat.MetadataRepoLoader

Interface to load emoji metadata. 

class EmojiCompat.MetadataRepoLoaderCallback

Callback to inform EmojiCompat about the state of the metadata load. 

Constants

String EDITOR_INFO_METAVERSION_KEY

Key in EditorInfo.extras that represents the emoji metadata version used by the widget.

String EDITOR_INFO_REPLACE_ALL_KEY

Key in EditorInfo.extras that represents EmojiCompat.Config.setReplaceAll(boolean) configuration parameter.

int LOAD_STATE_DEFAULT

EmojiCompat instance is constructed, however the initialization did not start yet.

int LOAD_STATE_FAILED

An unrecoverable error occurred during initialization of EmojiCompat.

int LOAD_STATE_LOADING

EmojiCompat is initializing.

int LOAD_STATE_SUCCEEDED

EmojiCompat successfully initialized.

int LOAD_STRATEGY_DEFAULT

EmojiCompat will start loading metadata when init(Config) is called.

int LOAD_STRATEGY_MANUAL

EmojiCompat will wait for load() to be called by developer in order to start loading metadata.

int REPLACE_STRATEGY_ALL

Replace strategy to add EmojiSpans for all emoji that were found.

int REPLACE_STRATEGY_DEFAULT

Replace strategy that uses the value given in EmojiCompat.Config.

int REPLACE_STRATEGY_NON_EXISTENT

Replace strategy to add EmojiSpans only for emoji that do not exist in the system.

Public methods

static EmojiCompat get()

Return singleton EmojiCompat instance.

String getAssetSignature()

Returns signature for the currently loaded emoji assets.

int getLoadState()

Returns loading state of the EmojiCompat instance.

static boolean handleDeleteSurroundingText(InputConnection inputConnection, Editable editable, int beforeLength, int afterLength, boolean inCodePoints)

Handles deleteSurroundingText commands from InputConnection and tries to delete an EmojiSpan from an Editable.

static boolean handleOnKeyDown(Editable editable, int keyCode, KeyEvent event)

Handles onKeyDown commands from a KeyListener and if keyCode is one of KeyEvent.KEYCODE_DEL or KeyEvent.KEYCODE_FORWARD_DEL it tries to delete an EmojiSpan from an Editable.

boolean hasEmojiGlyph(CharSequence sequence)

Returns true if EmojiCompat is capable of rendering an emoji.

boolean hasEmojiGlyph(CharSequence sequence, int metadataVersion)

Returns true if EmojiCompat is capable of rendering an emoji at the given metadata version.

static EmojiCompat init(EmojiCompat.Config config)

Initialize the singleton instance with a configuration.

static EmojiCompat init(Context context)

Initialize the singleton instance with the default system-provided configuration.

static boolean isConfigured()

Return true if EmojiCompat has been configured by a successful call to init(Context).

void load()

When EmojiCompat.Config.setMetadataLoadStrategy(int) is set to LOAD_STRATEGY_MANUAL, this function starts loading the metadata.

CharSequence process(CharSequence charSequence)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.

CharSequence process(CharSequence charSequence, int start, int end, int maxEmojiCount, int replaceStrategy)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.

CharSequence process(CharSequence charSequence, int start, int end, int maxEmojiCount)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.

CharSequence process(CharSequence charSequence, int start, int end)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.

void registerInitCallback(EmojiCompat.InitCallback initCallback)

Registers an initialization callback.

void unregisterInitCallback(EmojiCompat.InitCallback initCallback)

Unregisters a callback that was added before.

void updateEditorInfo(EditorInfo outAttrs)

Updates the EditorInfo attributes in order to communicate information to Keyboards.

Inherited methods

Constants

EDITOR_INFO_METAVERSION_KEY

public static final String EDITOR_INFO_METAVERSION_KEY

Key in EditorInfo.extras that represents the emoji metadata version used by the widget. The existence of the value means that the widget is using EmojiCompat.

If exists, the value for the key is an int and can be used to query EmojiCompat to see whether the widget has the ability to display a certain emoji using hasEmojiGlyph(CharSequence, int).

Constant Value: "android.support.text.emoji.emojiCompat_metadataVersion"

EDITOR_INFO_REPLACE_ALL_KEY

public static final String EDITOR_INFO_REPLACE_ALL_KEY

Key in EditorInfo.extras that represents EmojiCompat.Config.setReplaceAll(boolean) configuration parameter. The key is added only if EmojiCompat is used by the widget. If exists, the value is a boolean.

Constant Value: "android.support.text.emoji.emojiCompat_replaceAll"

LOAD_STATE_DEFAULT

public static final int LOAD_STATE_DEFAULT

EmojiCompat instance is constructed, however the initialization did not start yet.

See also:

Constant Value: 3 (0x00000003)

LOAD_STATE_FAILED

public static final int LOAD_STATE_FAILED

An unrecoverable error occurred during initialization of EmojiCompat. Calls to functions such as process(CharSequence) will fail.

See also:

Constant Value: 2 (0x00000002)

LOAD_STATE_LOADING

public static final int LOAD_STATE_LOADING

EmojiCompat is initializing.

See also:

Constant Value: 0 (0x00000000)

LOAD_STATE_SUCCEEDED

public static final int LOAD_STATE_SUCCEEDED

EmojiCompat successfully initialized.

See also:

Constant Value: 1 (0x00000001)

LOAD_STRATEGY_DEFAULT

public static final int LOAD_STRATEGY_DEFAULT

EmojiCompat will start loading metadata when init(Config) is called.

Constant Value: 0 (0x00000000)

LOAD_STRATEGY_MANUAL

public static final int LOAD_STRATEGY_MANUAL

EmojiCompat will wait for load() to be called by developer in order to start loading metadata.

Constant Value: 1 (0x00000001)

REPLACE_STRATEGY_ALL

public static final int REPLACE_STRATEGY_ALL

Replace strategy to add EmojiSpans for all emoji that were found.

Constant Value: 1 (0x00000001)

REPLACE_STRATEGY_DEFAULT

public static final int REPLACE_STRATEGY_DEFAULT

Replace strategy that uses the value given in EmojiCompat.Config.

Constant Value: 0 (0x00000000)

REPLACE_STRATEGY_NON_EXISTENT

public static final int REPLACE_STRATEGY_NON_EXISTENT

Replace strategy to add EmojiSpans only for emoji that do not exist in the system.

Constant Value: 2 (0x00000002)

Public methods

get

public static EmojiCompat get ()

Return singleton EmojiCompat instance. Should be called after init(EmojiCompat.Config) is called to initialize the singleton instance.

Returns
EmojiCompat EmojiCompat instance

Throws
IllegalStateException if called before init(EmojiCompat.Config)

getAssetSignature

public String getAssetSignature ()

Returns signature for the currently loaded emoji assets. The signature is a SHA that is constructed using emoji assets. Can be used to detect if currently loaded asset is different then previous executions. When used on devices running API 18 or below, returns empty string.

Returns
String

Throws
IllegalStateException if not initialized yet

getLoadState

public int getLoadState ()

Returns loading state of the EmojiCompat instance. When used on devices running API 18 or below always returns LOAD_STATE_SUCCEEDED.

Returns
int one of LOAD_STATE_DEFAULT, LOAD_STATE_LOADING, LOAD_STATE_SUCCEEDED, LOAD_STATE_FAILED

handleDeleteSurroundingText

public static boolean handleDeleteSurroundingText (InputConnection inputConnection, 
                Editable editable, 
                int beforeLength, 
                int afterLength, 
                boolean inCodePoints)

Handles deleteSurroundingText commands from InputConnection and tries to delete an EmojiSpan from an Editable. Returns true if an EmojiSpan is deleted.

If there is a selection where selection start is not equal to selection end, does not delete.

When used on devices running API 18 or below, always returns false.

Parameters
inputConnection InputConnection: InputConnection instance

editable Editable: TextView.Editable instance

beforeLength int: the number of characters before the cursor to be deleted

afterLength int: the number of characters after the cursor to be deleted

inCodePoints boolean: true if length parameters are in codepoints

Returns
boolean true if an EmojiSpan is deleted

handleOnKeyDown

public static boolean handleOnKeyDown (Editable editable, 
                int keyCode, 
                KeyEvent event)

Handles onKeyDown commands from a KeyListener and if keyCode is one of KeyEvent.KEYCODE_DEL or KeyEvent.KEYCODE_FORWARD_DEL it tries to delete an EmojiSpan from an Editable. Returns true if an EmojiSpan is deleted with the characters it covers.

If there is a selection where selection start is not equal to selection end, does not delete.

When used on devices running API 18 or below, always returns false.

Parameters
editable Editable: Editable instance passed to KeyListener.onKeyDown(android.view.View, Editable, int, KeyEvent)

keyCode int: keyCode passed to KeyListener.onKeyDown(android.view.View, Editable, int, KeyEvent)

event KeyEvent: KeyEvent passed to KeyListener.onKeyDown(android.view.View, Editable, int, KeyEvent)

Returns
boolean true if an EmojiSpan is deleted

hasEmojiGlyph

public boolean hasEmojiGlyph (CharSequence sequence)

Returns true if EmojiCompat is capable of rendering an emoji. When used on devices running API 18 or below, always returns false.

Parameters
sequence CharSequence: CharSequence representing the emoji

Returns
boolean true if EmojiCompat can render given emoji, cannot be null

Throws
IllegalStateException if not initialized yet

hasEmojiGlyph

public boolean hasEmojiGlyph (CharSequence sequence, 
                int metadataVersion)

Returns true if EmojiCompat is capable of rendering an emoji at the given metadata version. When used on devices running API 18 or below, always returns false.

Parameters
sequence CharSequence: CharSequence representing the emoji

metadataVersion int: the metadata version to check against, should be greater than or equal to 0,

Returns
boolean true if EmojiCompat can render given emoji, cannot be null

Throws
IllegalStateException if not initialized yet

init

public static EmojiCompat init (EmojiCompat.Config config)

Initialize the singleton instance with a configuration. When used on devices running API 18 or below, the singleton instance is immediately