EmojiCompat

@AnyThread
public 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
public abstract class EmojiCompat.Config

Configuration class for EmojiCompat.
public interface EmojiCompat.GlyphChecker

Interface to check if a given emoji exists on the system.
public abstract class EmojiCompat.InitCallback

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
static final String
EDITOR_INFO_METAVERSION_KEY = "android.support.text.emoji.emojiCompat_metadataVersion"

Key in extras that represents the emoji metadata version used by the widget.
static final String
EDITOR_INFO_REPLACE_ALL_KEY = "android.support.text.emoji.emojiCompat_replaceAll"

Key in extras that represents setReplaceAll configuration parameter.
static final int

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

An unrecoverable error occurred during initialization of EmojiCompat.
static final int

EmojiCompat is initializing.
static final int

EmojiCompat successfully initialized.
static final int

EmojiCompat will start loading metadata when init is called.
static final int

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

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

Replace strategy that uses the value given in EmojiCompat.Config.
static final int

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

Public methods
static EmojiCompat
get()

Return singleton EmojiCompat instance.
@NonNull String

Returns signature for the currently loaded emoji assets.
int

Returns loading state of the EmojiCompat instance.
static boolean
handleDeleteSurroundingText(
    @NonNull InputConnection inputConnection,
    @NonNull Editable editable,
    @IntRange(from = 0) int beforeLength,
    @IntRange(from = 0) int afterLength,
    boolean inCodePoints
)

Handles deleteSurroundingText commands from InputConnection and tries to delete an EmojiSpan from an Editable.
static boolean
handleOnKeyDown(@NonNull Editable editable, int keyCode, KeyEvent event)

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(
    @NonNull CharSequence sequence,
    @IntRange(from = 0) int metadataVersion
)

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

Initialize the singleton instance with a configuration.
void

When setMetadataLoadStrategy is set to LOAD_STRATEGY_MANUAL, this function starts loading the metadata.
CharSequence
process(@NonNull CharSequence charSequence)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.
CharSequence
process(
    @NonNull CharSequence charSequence,
    @IntRange(from = 0) int start,
    @IntRange(from = 0) int end
)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.
CharSequence
process(
    @NonNull CharSequence charSequence,
    @IntRange(from = 0) int start,
    @IntRange(from = 0) int end,
    @IntRange(from = 0) int maxEmojiCount
)

Checks a given CharSequence for emojis, and adds EmojiSpans if any emojis are found.
CharSequence
process(
    @NonNull CharSequence charSequence,
    @IntRange(from = 0) int start,
    @IntRange(from = 0) int end,
    @IntRange(from = 0) int maxEmojiCount,
    int replaceStrategy
)

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

Registers an initialization callback.
void

Unregisters a callback that was added before.

Constants

EDITOR_INFO_METAVERSION_KEY

Added in 1.0.0
public static final String EDITOR_INFO_METAVERSION_KEY = "android.support.text.emoji.emojiCompat_metadataVersion"

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
public static final String EDITOR_INFO_REPLACE_ALL_KEY = "android.support.text.emoji.emojiCompat_replaceAll"

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
public static final int LOAD_STATE_DEFAULT = 3

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

See also
getLoadState

LOAD_STATE_FAILED

Added in 1.0.0
public static final int LOAD_STATE_FAILED = 2

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
public static final int LOAD_STATE_LOADING = 0

EmojiCompat is initializing.

See also
getLoadState

LOAD_STATE_SUCCEEDED

Added in 1.0.0
public static final int LOAD_STATE_SUCCEEDED = 1

EmojiCompat successfully initialized.

See also
getLoadState

LOAD_STRATEGY_DEFAULT

Added in 1.0.0
public static final int LOAD_STRATEGY_DEFAULT = 0

EmojiCompat will start loading metadata when init is called.

See also
setMetadataLoadStrategy

LOAD_STRATEGY_MANUAL

Added in 1.0.0
public static final int LOAD_STRATEGY_MANUAL = 1

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

See also
setMetadataLoadStrategy

REPLACE_STRATEGY_ALL

Added in 1.0.0
public static final int REPLACE_STRATEGY_ALL = 1

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

See also
process

REPLACE_STRATEGY_DEFAULT

Added in 1.0.0
public static final int REPLACE_STRATEGY_DEFAULT = 0

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

See also
process

REPLACE_STRATEGY_NON_EXISTENT

Added in 1.0.0
public static final int REPLACE_STRATEGY_NON_EXISTENT = 2

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

Public methods

get

Added in 1.0.0
public static EmojiCompat get()

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
public @NonNull 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.

Throws
java.lang.IllegalStateException

if not initialized yet

getLoadState

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

Added in 1.0.0
public static boolean handleDeleteSurroundingText(
    @NonNull InputConnection inputConnection,
    @NonNull Editable editable,
    @IntRange(from = 0) int beforeLength,
    @IntRange(from = 0) 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
@NonNull InputConnection inputConnection

InputConnection instance
@NonNull Editable editable

TextView.Editable instance
@IntRange(from = 0) int beforeLength

the number of characters before the cursor to be deleted
@IntRange(from = 0) int afterLength

the number of characters after the cursor to be deleted
boolean inCodePoints

true if length parameters are in codepoints
Returns
boolean

true if an EmojiSpan is deleted

handleOnKeyDown

Added in 1.0.0
public static boolean handleOnKeyDown(@NonNull Editable editable, int keyCode, KeyEvent event)

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
@NonNull Editable editable

Editable instance passed to onKeyDown
int keyCode

keyCode passed to onKeyDown
KeyEvent event

KeyEvent passed to onKeyDown
Returns
boolean

true if an EmojiSpan is deleted

hasEmojiGlyph

Added in 1.0.0
public boolean hasEmojiGlyph(@NonNull 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
@NonNull CharSequence sequence

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
public boolean hasEmojiGlyph(
    @NonNull CharSequence sequence,
    @IntRange(from = 0) 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
@NonNull CharSequence sequence

CharSequence representing the emoji
@IntRange(from = 0) int metadataVersion

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
public static EmojiCompat init(@NonNull EmojiCompat.Config config)

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.

See also
EmojiCompat.Config

load

Added in 1.0.0
public void load()

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:

Throws
java.lang.IllegalStateException

when setMetadataLoadStrategy is not set to LOAD_STRATEGY_MANUAL

process

Added in 1.0.0
public CharSequence process(@NonNull 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
@NonNull CharSequence charSequence

CharSequence to add the EmojiSpans
Throws
java.lang.IllegalStateException

if not initialized yet
See also
process

process

Added in 1.0.0
public CharSequence process(
    @NonNull CharSequence charSequence,
    @IntRange(from = 0) int start,
    @IntRange(from = 0) int end
)

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
@NonNull CharSequence charSequence

CharSequence to add the EmojiSpans, cannot be null
@IntRange(from = 0) int start

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()
@IntRange(from = 0) int end

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
public CharSequence process(
    @NonNull CharSequence charSequence,
    @IntRange(from = 0) int start,
    @IntRange(from = 0) int end,
    @IntRange(from = 0) int maxEmojiCount
)

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
@NonNull CharSequence charSequence

CharSequence to add the EmojiSpans, cannot be null
@IntRange(from = 0) int start

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()
@IntRange(from = 0) int end

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()
@IntRange(from = 0) int maxEmojiCount

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
public CharSequence process(
    @NonNull CharSequence charSequence,
    @IntRange(from = 0) int start,
    @IntRange(from = 0) int end,
    @IntRange(from = 0) int maxEmojiCount,
    int replaceStrategy
)

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
@NonNull CharSequence charSequence

CharSequence to add the EmojiSpans, cannot be null
@IntRange(from = 0) int start

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()
@IntRange(from = 0) int end

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()
@IntRange(from = 0) int maxEmojiCount

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

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
public void registerInitCallback(@NonNull EmojiCompat.InitCallback initCallback)

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
@NonNull EmojiCompat.InitCallback initCallback

the initialization callback to register, cannot be null
See also
unregisterInitCallback

unregisterInitCallback

Added in 1.0.0
public void unregisterInitCallback(@NonNull EmojiCompat.InitCallback initCallback)

Unregisters a callback that was added before.

Parameters
@NonNull EmojiCompat.InitCallback initCallback

the callback to be removed, cannot be null