AniTrend / android-emojify

An android project to convert short codes, emoticons, html entities, emoticons to emoji and vice-versa
https://anitrend.github.io/android-emojify
Apache License 2.0
25 stars 12 forks source link
android android-emojify androidx emoji emoji-objects emojify emoticons fitzpatrick-modifier html-entities kotlin kotlin-coroutines

Android Emojify     Release   Codacy Badge   gradle-unit-test

FOSSA Status

This project is an android port of vdurmont/emoji-java which is a lightweight java library that helps you use Emojis in your java applications re-written in Kotlin, with some extra tweaks.

This project is already being used in AniTrend and only aims to provide emojis from emojipedia

Known Issues

Suggestions

Use Case

Trying to get emoji support in your application in a way that is both compatible with a browser and mobile, you might even be trying to create a github client with reaction support? Then this library is for you, your backend stores is the html entities or aliases in text and this library will take care of everything for you.

Getting Started

Step 1. Add this to your root build.gradle:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Step 2. Add the dependencies:

You must use one of our artifacts kotlinx, gson or moshi for deserialization, this should match whatever library you want to use. e.g.

dependencies {
    implementation 'com.github.anitrend.android-emojify:emojify:{latest_version}'
    implementation 'com.github.anitrend.android-emojify:contract:{latest_version}'
    implementation 'com.github.anitrend.android-emojify:kotlinx:{latest_version}'
}

Step 3. Create an application class in your android project and add:

Don't know how to do that?? Take a look at the application class example

class App : Application() {

  /**
   * Application scope bound emojiManager, you could keep a reference to this object in a
   * dependency injector framework like as a singleton in `Hilt`, `Dagger` or `Koin`
   */
    internal val emojiManager: EmojiManager by lazy {
        EmojiManager.create(this, KotlinxDeserializer())
    }
}

Step4. Optional - Init EmojiManager with androidx-startup

class EmojiInitializer : Initializer<EmojiManager> {
  private val serializer: IEmojiDeserializer = KotlinxDeserializer()

  /**
   * Initializes and a component given the application [Context]
   *
   * @param context The application context.
   */
  override fun create(context: Context) = EmojiManager.create(context, serializer)

  /**
   * @return A list of dependencies that this [Initializer] depends on. This is
   * used to determine initialization order of [Initializer]s.
   *
   * For e.g. if a [Initializer] `B` defines another
   * [Initializer] `A` as its dependency, then `A` gets initialized before `B`.
   */
  override fun dependencies() = emptyList<Class<out Initializer<*>>>()
}

class App : Application() {

  /**
   * Application scope bound emojiManager, you could keep a reference to this object in a
   * dependency injector framework like as a singleton in `Hilt`, `Dagger` or `Koin`
   */
  internal val startupEmojiManager: EmojiManager by lazy {
    // should already be initialized if we haven't disabled initialization in manifest
    // see: https://developer.android.com/topic/libraries/app-startup#disable-individual
    AppInitializer.getInstance(this)
      .initializeComponent(EmojiInitializer::class.java)
  }
}

AndroidManifest.xml

<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <meta-data
        android:name="{some_package_name_of_your_choosing}.EmojiInitializer"
        android:value="androidx.startup" />
</provider>

Screenshots

Examples:

EmojiManager

The EmojiManager provides several instance methods to search through the emojis database:

You can also query the metadata:

Or get everything:

Emoji model

An Emoji is a data class, which provides the following methods:

Fitzpatrick modifiers

Some emojis now support the use of Fitzpatrick modifiers that gives the choice between 5 shades of skin tones:

Modifier Type
🏻 type_1_2
🏼 type_3
🏽 type_4
🏾 type_5
🏿 type_6

We defined the format of the aliases including a Fitzpatrick modifier as:

:ALIAS|TYPE:

A few examples:

:boy|type_1_2:
:swimmer|type_4:
:santa|type_6:

EmojiParser

Is a set of extension methods to act on EmojiManager, so given an instance of EmojiManger we can achieve the following:

val emojiManager: EmojiManger = ...

To unicode

To replace all the aliases and the html representations found in a string by their unicode, use EmojiParser#parseToUnicode(String).

For example:

val str = "An :+1:awesome :smiley:string " + "😄with a few :wink:emojis!"
val result = emojiManager.parseToUnicode(str)
// An 😀awesome 😃string 😄with a few 😉emojis!

To aliases

To replace all the emoji's unicodes found in a string by their aliases, use EmojiParser#parseToAliases(String).

For example:

val str = "An 😀awesome 😃string with a few 😉emojis!"
val result = emojiManager.parseToAliases(str)
// "An :grinning:awesome :smiley:string with a few :wink:emojis!"

By default, the aliases will parse and include any Fitzpatrick modifier that would be provided. If you want to remove or ignore the Fitzpatrick modifiers, use EmojiParser#parseToAliases(String, FitzpatrickAction). Examples:

val str = "Here is a boy: \uD83D\uDC66\uD83C\uDFFF!"
emojiManager.parseToAliases(str, FitzpatrickAction.PARSE)
// Returns twice: "Here is a boy: :boy|type_6:!"
emojiManager.parseToAliases(str, FitzpatrickAction.REMOVE)
// Returns: "Here is a boy: :boy:!"
emojiManager.parseToAliases(str, FitzpatrickAction.IGNORE)
// Returns: "Here is a boy: :boy:🏿!"

To html

To replace all the emoji's unicodes found in a string by their html representation, use EmojiParser#parseToHtmlDecimal(String) or EmojiParser#parseToHtmlHexadecimal(String).

For example:

val str = "An 😀awesome 😃string with a few 😉emojis!"
val resultHtmlDecimal = emojiManager.parseToHtmlDecimal(str)
// Returns:
// "An &#128512;awesome &#128515;string with a few &#128521;emojis!"

val resultHexadecimal = emojiManager.parseToHtmlHexadecimal(str)
// Returns:
// "An 😀awesome 😃string with a few 😉emojis!"

By default, any Fitzpatrick modifier will be removed. If you want to ignore the Fitzpatrick modifiers, use emojiManager.parseToAliases(String, FitzpatrickAction). Examples:

val str = "Here is a boy: \uD83D\uDC66\uD83C\uDFFF!"

emojiManager.parseToHtmlDecimal(str, FitzpatrickAction.PARSE)
emojiManager.parseToHtmlDecimal(str, FitzpatrickAction.REMOVE)
// Returns: "Here is a boy: 👦!"
emojiManager.parseToHtmlDecimal(str, FitzpatrickAction.IGNORE)
// Returns: "Here is a boy: 👦🏿!"

The same applies for the methods emojiManager.parseToHtmlHexadecimal(String) and emojiManager.parseToHtmlHexadecimal(String, FitzpatrickAction).

Remove emojis

You can easily remove emojis from a string using one of the following methods:

For example:

val str = "An 😀awesome 😃string with a few 😉emojis!"
val collection = ArrayList<Emoji>()
collection.add(emojiManager.getForAlias("wink")); // This is 😉

emojiManager.removeAllEmojis(str);
emojiManager.removeAllEmojisExcept(str, collection);
emojiManager.removeEmojis(str, collection);

// Returns:
// "An awesome string with a few emojis!"
// "An awesome string with a few 😉emojis!"
// "An 😀awesome 😃string with a few emojis!"

Extract Emojis from a string

You can search a string of mixed emoji/non-emoji characters and have all of the emoji characters returned as a Collection.

Credits

emoji-java originally used the data provided by the github/gemoji project. It is still based on it but has evolved since.

License

Copyright 2018 AniTrend

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.