It's happening now, watch the livestream.

EmojiCompat

@AnyThread open class EmojiCompat
kotlin.Any
   ↳ androidx.emoji.text.EmojiCompat

Main class to keep Android devices up to date with the newest emojis by adding EmojiSpans to a given . It is a singleton class that can be configured using a instance.

EmojiCompat has to be initialized using init(EmojiCompat.Config) function before it can process a CharSequence.
<code>EmojiCompat.init(/* a config instance */);</code>

It is suggested to make the initialization as early as possible in your app. Please check for more configuration parameters. Once init(EmojiCompat.Config) is called a singleton instance will be created. Any call after that will not create a new instance and will return immediately.

During initialization information about emojis is loaded on a background thread. Before the EmojiCompat instance is initialized, calls to functions such as will throw an exception. You can use the InitCallback class to be informed about the state of initialization.

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.

<code>CharSequence processedSequence = EmojiCompat.get().process("some string")</code>

Summary

Nested classes

abstract

Configuration class for EmojiCompat.

abstract

Listener class for the initialization of the EmojiCompat.

abstract

Interface to load emoji metadata.

abstract

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

Constants

static String

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

static String

Key in EditorInfo#extras that represents configuration parameter.

static Int

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

static Int

An unrecoverable error occurred during initialization of EmojiCompat.

static Int

EmojiCompat is initializing.

static Int

EmojiCompat successfully initialized.

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

Public methods

open static EmojiCompat!
get()

Return singleton EmojiCompat instance.

open String

Returns signature for the currently loaded emoji assets.

open Int

Returns loading state of the EmojiCompat instance.

open static Boolean
handleDeleteSurroundingText(@NonNull inputConnection: InputConnection, @NonNull editable: Editable, beforeLength: Int, afterLength: Int, inCodePoints: Boolean)

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

open static Boolean
handleOnKeyDown(@NonNull editable: Editable, keyCode: Int, event: KeyEvent!)

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.

open Boolean
hasEmojiGlyph(@NonNull sequence: CharSequence)

Returns true if EmojiCompat is capable of rendering an emoji.

open Boolean
hasEmojiGlyph(@NonNull sequence: CharSequence, metadataVersion: Int)

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

open static EmojiCompat!
init(@NonNull config: EmojiCompat.Config)

Initialize the singleton instance with a configuration.

open Unit

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

open CharSequence!
process(@NonNull charSequence: CharSequence)

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

open CharSequence!
process(@NonNull charSequence: CharSequence, start: Int, end: Int)

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

open CharSequence!
process(@NonNull charSequence: CharSequence, start: Int, end: Int, maxEmojiCount: Int)

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

open CharSequence!
process(@NonNull charSequence: CharSequence, start: Int, end: Int, maxEmojiCount: Int, replaceStrategy: Int)

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

open Unit

Registers an initialization callback.

open Unit

Unregisters a callback that was added before.

Constants

EDITOR_INFO_METAVERSION_KEY

static val EDITOR_INFO_METAVERSION_KEY: String

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).
Value: "android.support.text.emoji.emojiCompat_metadataVersion"

EDITOR_INFO_REPLACE_ALL_KEY

static val EDITOR_INFO_REPLACE_ALL_KEY: String

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

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

LOAD_STATE_DEFAULT

static val LOAD_STATE_DEFAULT: Int

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

Value: 3

See Also

LOAD_STATE_FAILED

static val LOAD_STATE_FAILED: Int

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

Value: 2

See Also

LOAD_STATE_LOADING

static val LOAD_STATE_LOADING: Int

EmojiCompat is initializing.

Value: 0

See Also

LOAD_STATE_SUCCEEDED

static val LOAD_STATE_SUCCEEDED: Int

EmojiCompat successfully initialized.

Value: 1

See Also

LOAD_STRATEGY_DEFAULT

static val LOAD_STRATEGY_DEFAULT: Int

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

Value: 0

LOAD_STRATEGY_MANUAL

static val LOAD_STRATEGY_MANUAL: Int

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

Value: 1

REPLACE_STRATEGY_ALL

static val REPLACE_STRATEGY_ALL: Int

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

Value: 1

REPLACE_STRATEGY_DEFAULT

static val REPLACE_STRATEGY_DEFAULT: Int

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

Value: 0

REPLACE_STRATEGY_NON_EXISTENT

static val REPLACE_STRATEGY_NON_EXISTENT: Int

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

Value: 2

Public methods

get

open static fun get(): EmojiCompat!

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

Return
EmojiCompat!: EmojiCompat instance
Exceptions
IllegalStateException if called before init(EmojiCompat.Config)

getAssetSignature

@NonNull open fun getAssetSignature(): String

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.

Exceptions
IllegalStateException if not initialized yet

getLoadState

open fun getLoadState(): Int

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

Return
Int: one of LOAD_STATE_DEFAULT, LOAD_STATE_LOADING, LOAD_STATE_SUCCEEDED, LOAD_STATE_FAILED

handleDeleteSurroundingText

open static fun handleDeleteSurroundingText(@NonNull inputConnection: InputConnection, @NonNull editable: Editable, beforeLength: Int, afterLength: Int, inCodePoints: Boolean): Boolean

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 InputConnection: TextView.Editable instance
beforeLength InputConnection: the number of characters before the cursor to be deleted
afterLength InputConnection: the number of characters after the cursor to be deleted
inCodePoints InputConnection: true if length parameters are in codepoints
Return
Boolean: true if an EmojiSpan is deleted

handleOnKeyDown

open static fun handleOnKeyDown(@NonNull editable: Editable, keyCode: Int, event: KeyEvent!): Boolean

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 Editable: keyCode passed to KeyListener#onKeyDown(android.view.View, Editable, * int, KeyEvent)
event Editable: KeyEvent passed to KeyListener#onKeyDown(android.view.View, Editable, * int, KeyEvent)
Return
Boolean: true if an EmojiSpan is deleted

hasEmojiGlyph

open fun hasEmojiGlyph(@NonNull sequence: CharSequence): Boolean

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
Return
Boolean: true if EmojiCompat can render given emoji, cannot be null
Exceptions
IllegalStateException if not initialized yet

hasEmojiGlyph

open fun hasEmojiGlyph(@NonNull sequence: CharSequence, metadataVersion: Int): Boolean

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 CharSequence: the metadata version to check against, should be greater than or equal to 0,
Return
Boolean: true if EmojiCompat can render given emoji, cannot be null
Exceptions
IllegalStateException if not initialized yet

init

open static fun init(@NonNull config: EmojiCompat.Config): EmojiCompat!

Initialize the singleton instance with a configuration. When used on devices running API 18 or below, the singleton instance is immediately moved into LOAD_STATE_SUCCEEDED state without loading any metadata. When called for the first time, the library will create the singleton instance and any call after that will not create a new instance and return immediately.

load

open fun load(): Unit

When Config#setMetadataLoadStrategy(int) is set to LOAD_STRATEGY_MANUAL, this function starts loading the metadata. Calling the function when Config#setMetadataLoadStrategy(int) is not set to LOAD_STRATEGY_MANUAL will throw an exception. The load will not start if:

Exceptions
IllegalStateException when Config#setMetadataLoadStrategy(int) is not set to LOAD_STRATEGY_MANUAL

process

@CheckResult open fun process(@NonNull charSequence: CharSequence): CharSequence!

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found. When used on devices running API 18 or below, returns the given charSequence without processing it.

Parameters
charSequence CharSequence: CharSequence to add the EmojiSpans
Exceptions
IllegalStateException if not initialized yet

process

@CheckResult open fun process(@NonNull charSequence: CharSequence, start: Int, end: Int): CharSequence!

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

  • If no emojis are found, charSequence given as the input is returned without any changes. i.e. charSequence is a String, and no emojis are found, the same String is returned.
  • If the given input is not a Spannable (such as String), and at least one emoji is found a new android.text.Spannable instance is returned.
  • If the given input is a Spannable, the same instance is returned.
When used on devices running API 18 or below, returns the given charSequence without processing it.
Parameters
charSequence CharSequence: CharSequence to add the EmojiSpans, cannot be null
start CharSequence: start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than charSequence.length()
end CharSequence: end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than charSequence.length()
Exceptions
IllegalStateException if not initialized yet
IllegalArgumentException in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length()

process

@CheckResult open fun process(@NonNull charSequence: CharSequence, start: Int, end: Int, maxEmojiCount: Int): CharSequence!

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

  • If no emojis are found, charSequence given as the input is returned without any changes. i.e. charSequence is a String, and no emojis are found, the same String is returned.
  • If the given input is not a Spannable (such as String), and at least one emoji is found a new android.text.Spannable instance is returned.
  • If the given input is a Spannable, the same instance is returned.
When used on devices running API 18 or below, returns the given charSequence without processing it.
Parameters
charSequence CharSequence: CharSequence to add the EmojiSpans, cannot be null
start CharSequence: start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than charSequence.length()
end CharSequence: end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than charSequence.length()
maxEmojiCount CharSequence: maximum number of emojis in the charSequence, should be greater than or equal to 0
Exceptions
IllegalStateException if not initialized yet
IllegalArgumentException in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length() maxEmojiCount < 0

process

@CheckResult open fun process(@NonNull charSequence: CharSequence, start: Int, end: Int, maxEmojiCount: Int, replaceStrategy: Int): CharSequence!

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

  • If no emojis are found, charSequence given as the input is returned without any changes. i.e. charSequence is a String, and no emojis are found, the same String is returned.
  • If the given input is not a Spannable (such as String), and at least one emoji is found a new android.text.Spannable instance is returned.
  • If the given input is a Spannable, the same instance is returned.
When used on devices running API 18 or below, returns the given charSequence without processing it.
Parameters
charSequence CharSequence: CharSequence to add the EmojiSpans, cannot be null
start CharSequence: start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than charSequence.length()
end CharSequence: end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than charSequence.length()
maxEmojiCount CharSequence: maximum number of emojis in the charSequence, should be greater than or equal to 0
replaceStrategy CharSequence: whether to replace all emoji with EmojiSpans, should be one of REPLACE_STRATEGY_DEFAULT, REPLACE_STRATEGY_NON_EXISTENT, REPLACE_STRATEGY_ALL
Exceptions
IllegalStateException if not initialized yet
IllegalArgumentException in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length() maxEmojiCount < 0

registerInitCallback

open fun registerInitCallback(@NonNull initCallback: EmojiCompat.InitCallback): Unit

Registers an initialization callback. If the initialization is already completed by the time the listener is added, the callback functions are called immediately. Callbacks are called on the main looper.

When used on devices running API 18 or below, InitCallback#onInitialized() is called without loading any metadata. In such cases InitCallback#onFailed(Throwable) is never called.
Parameters
initCallback EmojiCompat.InitCallback: the initialization callback to register, cannot be null

unregisterInitCallback

open fun unregisterInitCallback(@NonNull initCallback: EmojiCompat.InitCallback): Unit

Unregisters a callback that was added before.

Parameters
initCallback EmojiCompat.InitCallback: the callback to be removed, cannot be null