added in version 26.1.0
belongs to Maven artifact com.android.support:support-emoji:28.0.0-alpha1

Summary: Nested Classes | Constants | Methods | Inherited Methods | [Expand All]

EmojiCompat

This package is part of the Android support library which is no longer maintained. The support library has been superseded by AndroidX which is part of Jetpack. We recommend using the AndroidX libraries in all new projects. You should also consider migrating existing projects to AndroidX. To find the AndroidX class that maps to this deprecated class, see the AndroidX support library class mappings.

public class EmojiCompat
extends Object

java.lang.Object
↳	android.support.text.emoji.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 EmojiCompat.Config instance.

EmojiCompat has to be initialized using init(EmojiCompat.Config) 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 EmojiCompat.Config for more configuration parameters.

During initialization information about emojis is loaded on a background thread. Before the EmojiCompat instance is initialized, calls to functions such as process(CharSequence) will throw an exception. You can use the EmojiCompat.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.

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

Summary

Nested classes
class	EmojiCompat.Config Configuration class for EmojiCompat.
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 extras that represents the emoji metadata version used by the widget.
String	EDITOR_INFO_REPLACE_ALL_KEY Key in extras that represents setReplaceAll(boolean) configuration parameter.
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	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 KEYCODE_DEL or 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.
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.

Inherited methods
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait(long arg0, int arg1) final void wait(long arg0) final void wait()

Constants

EDITOR_INFO_METAVERSION_KEY

added in version 26.1.0

String EDITOR_INFO_METAVERSION_KEY

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(CharSequence, int).

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

EDITOR_INFO_REPLACE_ALL_KEY

added in version 26.1.0

String EDITOR_INFO_REPLACE_ALL_KEY

Key in extras that represents 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_FAILED

added in version 26.1.0

int LOAD_STATE_FAILED

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

Constant Value: 2 (0x00000002)

LOAD_STATE_LOADING

added in version 26.1.0

int LOAD_STATE_LOADING

EmojiCompat is initializing.

Constant Value: 0 (0x00000000)

LOAD_STATE_SUCCEEDED

added in version 26.1.0

int LOAD_STATE_SUCCEEDED

EmojiCompat successfully initialized.

Constant Value: 1 (0x00000001)

REPLACE_STRATEGY_ALL

added in version 26.1.0

int REPLACE_STRATEGY_ALL

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

Constant Value: 1 (0x00000001)

REPLACE_STRATEGY_DEFAULT

added in version 26.1.0

int REPLACE_STRATEGY_DEFAULT

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

Constant Value: 0 (0x00000000)

REPLACE_STRATEGY_NON_EXISTENT

added in version 26.1.0

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

added in version 26.1.0

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

added in version 26.1.0

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

added in version 26.1.0

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_LOADING, LOAD_STATE_SUCCEEDED, LOAD_STATE_FAILED

handleDeleteSurroundingText

added in version 26.1.0

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

added in version 26.1.0

boolean handleOnKeyDown (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
editable	Editable: Editable instance passed to onKeyDown(android.view.View, Editable, int, KeyEvent)
keyCode	int: keyCode passed to onKeyDown(android.view.View, Editable, int, KeyEvent)
event	KeyEvent: KeyEvent passed to onKeyDown(android.view.View, Editable, int, KeyEvent)

Returns
boolean	true if an EmojiSpan is deleted

hasEmojiGlyph

added in version 26.1.0

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

added in version 26.1.0

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

added in version 26.1.0

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 moved into LOAD_STATE_SUCCEEDED state without loading any metadata.

Parameters
config	EmojiCompat.Config

Returns
EmojiCompat

See also:

• EmojiCompat.Config

process

added in version 26.1.0

CharSequence process (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

Returns
CharSequence

Throws
IllegalStateException	if not initialized yet

See also:

• process(CharSequence, int, int)

process

added in version 26.1.0

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.

• 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 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	int: start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than charSequence.length()
end	int: end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than charSequence.length()
maxEmojiCount	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

Returns
CharSequence

Throws
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

added in version 26.1.0

CharSequence process (CharSequence charSequence, 
                int start, 
                int end, 
                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 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	int: start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than charSequence.length()
end	int: end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than charSequence.length()
maxEmojiCount	int: maximum number of emojis in the charSequence, should be greater than or equal to 0

Returns
CharSequence

Throws
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

added in version 26.1.0

CharSequence process (CharSequence charSequence, 
                int start, 
                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 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	int: start index in the charSequence to look for emojis, should be greater than or equal to 0, also less than charSequence.length()
end	int: end index in the charSequence to look for emojis, should be greater than or equal to start parameter, also less than charSequence.length()

Returns
CharSequence

Throws
IllegalStateException	if not initialized yet
IllegalArgumentException	in the following cases: start < 0, end < 0, end < start, start > charSequence.length(), end > charSequence.length()

registerInitCallback

added in version 26.1.0

void registerInitCallback (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(Throwable) is never called.

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

See also:

• unregisterInitCallback(InitCallback)

unregisterInitCallback

added in version 26.1.0

void unregisterInitCallback (EmojiCompat.InitCallback initCallback)

Unregisters a callback that was added before.

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

• Interfaces

  • EmojiCompat.MetadataRepoLoader

• Classes

  • EmojiCompat
  • EmojiCompat.Config
  • EmojiCompat.InitCallback
  • EmojiCompat.MetadataRepoLoaderCallback
  • EmojiSpan
  • FontRequestEmojiCompatConfig
  • FontRequestEmojiCompatConfig.ExponentialBackoffRetryPolicy
  • FontRequestEmojiCompatConfig.RetryPolicy
  • MetadataRepo
  • R
  • R.attr
  • R.bool
  • R.color
  • R.dimen
  • R.drawable
  • R.id
  • R.integer
  • R.layout
  • R.string
  • R.style
  • R.styleable