belongs to Maven artifact com.android.support:support-emoji:28.0.0-alpha1
EmojiCompat
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 EmojiSpan
s
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 EmojiSpan
s 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 EmojiSpan
s 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.
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 EmojiSpan
s 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 EmojiSpan
s 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:
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
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 EmojiSpan
s, 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
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
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