EmojiCompat


@AnyThread
class EmojiCompat


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

EmojiCompat has to be initialized using init function before it can process a CharSequence.
EmojiCompat.init(/* a config instance */);
It is suggested to make the initialization as early as possible in your app. Please check for more configuration parameters. Once init 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 process 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 function can be used to update a CharSequence with emoji EmojiSpans.
CharSequence processedSequence = EmojiCompat.get().process("some string")

Summary

Nested types

abstract class EmojiCompat.Config

Configuration class for EmojiCompat.

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

Listener class for the initialization of the EmojiCompat.

Interface to load emoji metadata.

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

Constants

const String!
EDITOR_INFO_METAVERSION_KEY = "android.support.text.emoji.emojiCompat_metadataVersion"

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

const String!
EDITOR_INFO_REPLACE_ALL_KEY = "android.support.text.emoji.emojiCompat_replaceAll"

Key in extras that represents setReplaceAll configuration parameter.

const Int

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

const Int

An unrecoverable error occurred during initialization of EmojiCompat.

const Int

EmojiCompat is initializing.

const Int

EmojiCompat successfully initialized.

const Int

EmojiCompat will start loading metadata when init is called.

const Int

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

const Int

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

const Int

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

const Int

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

Public functions

java-static EmojiCompat!
get()

Return singleton EmojiCompat instance.

String

Returns signature for the currently loaded emoji assets.

Int

Returns loading state of the EmojiCompat instance.

java-static Boolean
handleDeleteSurroundingText(
    inputConnection: InputConnection,
    editable: Editable,
    beforeLength: @IntRange(from = 0) Int,
    afterLength: @IntRange(from = 0) Int,
    inCodePoints: Boolean
)

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

java-static Boolean
handleOnKeyDown(editable: Editable, keyCode: Int, event: KeyEvent!)

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

Boolean

Returns true if EmojiCompat is capable of rendering an emoji.

Boolean
hasEmojiGlyph(
    sequence: CharSequence,
    metadataVersion: @IntRange(from = 0) Int
)

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

java-static EmojiCompat!

Initialize the singleton instance with a configuration.

Unit

When setMetadataLoadStrategy 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,
    start: @IntRange(from = 0) Int,
    end: @IntRange(from = 0) Int
)

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

CharSequence!
process(
    charSequence: CharSequence,
    start: @IntRange(from = 0) Int,
    end: @IntRange(from = 0) Int,
    maxEmojiCount: @IntRange(from = 0) Int
)

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

CharSequence!
process(
    charSequence: CharSequence,
    start: @IntRange(from = 0) Int,
    end: @IntRange(from = 0) Int,
    maxEmojiCount: @IntRange(from = 0) Int,
    replaceStrategy: Int
)

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

Unit

Registers an initialization callback.

Unit

Unregisters a callback that was added before.

Constants

EDITOR_INFO_METAVERSION_KEY

Added in 1.0.0
const val EDITOR_INFO_METAVERSION_KEY = "android.support.text.emoji.emojiCompat_metadataVersion": String!

Key in 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.

EDITOR_INFO_REPLACE_ALL_KEY

Added in 1.0.0
const val EDITOR_INFO_REPLACE_ALL_KEY = "android.support.text.emoji.emojiCompat_replaceAll": String!

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

LOAD_STATE_DEFAULT

Added in 1.0.0
const val LOAD_STATE_DEFAULT = 3: Int

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

See also
getLoadState

LOAD_STATE_FAILED

Added in 1.0.0
const val LOAD_STATE_FAILED = 2: Int

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

See also
getLoadState

LOAD_STATE_LOADING

Added in 1.0.0
const val LOAD_STATE_LOADING = 0: Int

EmojiCompat is initializing.

See also
getLoadState

LOAD_STATE_SUCCEEDED

Added in 1.0.0
const val LOAD_STATE_SUCCEEDED = 1: Int

EmojiCompat successfully initialized.

See also
getLoadState

LOAD_STRATEGY_DEFAULT

Added in 1.0.0
const val LOAD_STRATEGY_DEFAULT = 0: Int

EmojiCompat will start loading metadata when init is called.

LOAD_STRATEGY_MANUAL

Added in 1.0.0
const val LOAD_STRATEGY_MANUAL = 1: Int

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

REPLACE_STRATEGY_ALL

Added in 1.0.0
const val REPLACE_STRATEGY_ALL = 1: Int

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

See also
process

REPLACE_STRATEGY_DEFAULT

Added in 1.0.0
const val REPLACE_STRATEGY_DEFAULT = 0: Int

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

See also
process

REPLACE_STRATEGY_NON_EXISTENT

Added in 1.0.0
const val REPLACE_STRATEGY_NON_EXISTENT = 2: Int

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

Public functions

get

Added in 1.0.0
java-static fun get(): EmojiCompat!

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

Returns
EmojiCompat!

EmojiCompat instance

Throws
java.lang.IllegalStateException

if called before init

getAssetSignature

Added in 1.0.0
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.

Throws
java.lang.IllegalStateException

if not initialized yet

getLoadState

Added in 1.0.0
fun getLoadState(): Int

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

handleDeleteSurroundingText

Added in 1.0.0
java-static fun handleDeleteSurroundingText(
    inputConnection: InputConnection,
    editable: Editable,
    beforeLength: @IntRange(from = 0) Int,
    afterLength: @IntRange(from = 0) 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: Editable

TextView.Editable instance

beforeLength: @IntRange(from = 0) Int

the number of characters before the cursor to be deleted

afterLength: @IntRange(from = 0) 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

Added in 1.0.0
java-static fun handleOnKeyDown(editable: Editable, keyCode: Int, event: KeyEvent!): Boolean

Handles onKeyDown commands from a KeyListener and if keyCode is one of KEYCODE_DEL or 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 onKeyDown

keyCode: Int

keyCode passed to onKeyDown

event: KeyEvent!

KeyEvent passed to onKeyDown

Returns
Boolean

true if an EmojiSpan is deleted

hasEmojiGlyph

Added in 1.0.0
fun hasEmojiGlyph(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

Returns
Boolean

true if EmojiCompat can render given emoji, cannot be null

Throws
java.lang.IllegalStateException

if not initialized yet

hasEmojiGlyph

Added in 1.0.0
fun hasEmojiGlyph(
    sequence: CharSequence,
    metadataVersion: @IntRange(from = 0) 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: @IntRange(from = 0) 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
java.lang.IllegalStateException

if not initialized yet

init

Added in 1.0.0
java-static fun init(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

Added in 1.0.0
fun load(): Unit

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

process

Added in 1.0.0
fun process(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

Throws
java.lang.IllegalStateException

if not initialized yet

See also
process

process

Added in 1.0.0
fun process(
    charSequence: CharSequence,
    start: @IntRange(from = 0) Int,
    end: @IntRange(from = 0) 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: @IntRange(from = 0) Int

start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than or equal to charSequence.length()

end: @IntRange(from = 0) Int

end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than or equal to charSequence.length()

Throws
java.lang.IllegalStateException

if not initialized yet

java.lang.IllegalArgumentException

in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length()

process

Added in 1.0.0
fun process(
    charSequence: CharSequence,
    start: @IntRange(from = 0) Int,
    end: @IntRange(from = 0) Int,
    maxEmojiCount: @IntRange(from = 0) 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: @IntRange(from = 0) Int

start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than or equal to charSequence.length()

end: @IntRange(from = 0) Int

end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than or equal to charSequence.length()

maxEmojiCount: @IntRange(from = 0) Int

maximum number of emojis in the charSequence, should be greater than or equal to 0

Throws
java.lang.IllegalStateException

if not initialized yet

java.lang.IllegalArgumentException

in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length()maxEmojiCount < 0

process

Added in 1.0.0
fun process(
    charSequence: CharSequence,
    start: @IntRange(from = 0) Int,
    end: @IntRange(from = 0) Int,
    maxEmojiCount: @IntRange(from = 0) 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: @IntRange(from = 0) Int

start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than or equal to charSequence.length()

end: @IntRange(from = 0) Int

end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than or equal to charSequence.length()

maxEmojiCount: @IntRange(from = 0) Int

maximum number of emojis in the charSequence, should be greater than or equal to 0

replaceStrategy: Int

whether to replace all emoji with EmojiSpans, should be one of REPLACE_STRATEGY_DEFAULT, REPLACE_STRATEGY_NON_EXISTENT, REPLACE_STRATEGY_ALL

Throws
java.lang.IllegalStateException

if not initialized yet

java.lang.IllegalArgumentException

in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length()maxEmojiCount < 0

registerInitCallback

Added in 1.0.0
fun registerInitCallback(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, onInitialized is called without loading any metadata. In such cases onFailed is never called.
Parameters
initCallback: EmojiCompat.InitCallback

the initialization callback to register, cannot be null

unregisterInitCallback

Added in 1.0.0
fun unregisterInitCallback(initCallback: EmojiCompat.InitCallback): Unit

Unregisters a callback that was added before.

Parameters
initCallback: EmojiCompat.InitCallback

the callback to be removed, cannot be null