Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gluonhq/emoji

Emoji support
https://github.com/gluonhq/emoji

Last synced: 6 days ago
JSON representation

Emoji support

Host: GitHub
URL: https://github.com/gluonhq/emoji
Owner: gluonhq
License: gpl-3.0
Created: 2023-06-22T17:44:37.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-09-15T18:32:08.000Z (about 2 months ago)
Last Synced: 2024-09-15T19:51:34.545Z (about 2 months ago)
Language: Java
Size: 31.5 MB
Stars: 13
Watchers: 5
Forks: 5
Open Issues: 2
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

[![Gluon](.github/assets/gluon_logo.svg)](https://gluonhq.com)

[![Build](https://github.com/gluonhq/emoji/actions/workflows/build.yml/badge.svg)](https://github.com/gluonhq/emoji/actions/workflows/build.yml)
[![Maven Central](https://img.shields.io/maven-central/v/com.gluonhq/emoji)](https://search.maven.org/#search|ga|1|com.gluonhq.emoji)
[![License](https://img.shields.io/github/license/gluonhq/emoji)](https://opensource.org/licenses/GPL-3.0)
[![javadoc](https://javadoc.io/badge2/com.gluonhq/emoji/javadoc.svg?color=blue)](https://javadoc.io/doc/com.gluonhq/emoji)

Emoji library is a Java implementation of the [emoji-data](https://github.com/iamcal/emoji-data) project adding emoji support for JavaFX applications.

## What is an Emoji?

From [Wikipedia](https://en.wikipedia.org/wiki/Emoji):

> An emoji is a pictogram, logogram, ideogram or smiley embedded in text and used in electronic messages and web pages.
> The primary function of emoji is to fill in emotional cues otherwise missing from typed conversation.

## Emoji support in JavaFX

JavaFX can be used to create client applications that target desktop, embedded, mobiles and even web.
Given the wide variety of applications, it becomes very important to have emoji support in the platform.
This project aims to bridge this gap and add emoji support to JavaFX.

## Usage

As stated earlier, emojis can be represented in form of text or a picture.
This library can be used to represent an Emoji as one of the following and seamlessly interchange between these types:

* String, e.g. `wave`
* Unicode, e.g. `\uD83D\uDC4B`
* Hex code string, e.g. `1F44B-1F3FC`
* Image, e.g. `👋`

[Emoji](https://github.com/gluonhq/emoji/blob/main/emoji/src/main/java/com/gluonhq/emoji/Emoji.java) data class is used to represent each emoji.
For better understanding of the Emoji class, we suggest you to go through [Using the data](https://github.com/iamcal/emoji-data#using-the-data) in emoji-data or the Emoji [javadoc](https://javadoc.io/doc/com.gluonhq/emoji).

### API overview

`EmojiData` contains the public API which can be used to create `Emoji` objects from String and Unicode, and vice-versa.

Fetch `👋` emoji from text:

```
Optional emoji = EmojiData.emojiFromShortName("wave");
```

In case the exact text for emoji is not known, `search` API can be used to get a list of emojis which matches the text:

```
List emojis = EmojiData.search("wav");
```

Fetch `👋` emoji from unicode:

```
Optional emoji = EmojiData.emojiFromUnicodeString("\uD83D\uDC4B");
```

Fetch `👋` emoji from hex-code point string:

```
Optional emoji = EmojiData.emojiFromCodepoints("1F44B-1F3FC");
```

Fetch `👋` emoji's unicode from text:

```
Optional unicode = EmojiData.emojiForText("wave");
```

UTF-8 encoded text can be parsed into a list of emojis and regular text using `TextUtil`:

```
List nodes = TextUtil.convertToStringAndEmojiObjects("this is an emoji: \uD83D\uDC4B");
```

## Projects

The GitHub repository contains 3 projects: emoji, samples, emoji-updater.

### emoji
Raw emoji support with `Emoji` and `EmojiData` classes.
This module is to be used as a dependency in your JavaFX application.

Use the emoji dependency in a Maven project:

```

com.gluonhq.emoji
emoji
${version}

```

Manually build the emoji artifact:

```
mvn clean install -f emoji
```

### Offline
Emojis are extracted from sprites which are downloaded and stored in local file system to reduce the size of the application.
In cases where downloading of these sprites is not possible, the offline module can be added as a dependency.

```

com.gluonhq.emoji
offline
${version}

```

Manually build the offline artifact:

```
mvn clean install -f offline
```

### Samples

#### Nodes App
Simple JavaFX application that displays all emojis.
This application can be considered as a playground to test emoji and its APIs.

![emoji-sample.png](.github/assets/emoji-sample.png)

Each emoji is an ImageView and shows the description of the emoji on hover:

![emoji-sample-hover.png](.github/assets/emoji-sample-hover.png)

Run the sample nodes application:

```
mvn javafx:run -f samples/nodes
```

Run the sample introduction application:

```
mvn javafx:run -f samples/introduction
```

### Updater
Utility to manually update Emoji to the latest emoji data, whenever a new version is released.
Normally, this will be used by the library developers, but in case we are falling behind, you can use it too ;)

To update the emoji list, set the [commit number](https://github.com/gluonhq/emoji/blob/main/emoji-updater/src/main/java/com/gluonhq/emoji/tools/Main.java#L39)
from [emoji-data](https://github.com/iamcal/emoji-data) and run:

```
mvn javafx:run -f updater
```

## Contribution

All contributions are welcome!

There are two common ways to contribute:

- Submit [issues](https://github.com/gluonhq/emoji/issues) for bug reports, questions, or requests for enhancements.
- Contributions can be submitted via [pull request](https://github.com/gluonhq/emoji/pulls), provided you have signed the [Gluon Individual Contributor License Agreement (CLA)](https://cla.gluonhq.com).

Follow [contributing rules](https://github.com/gluonhq/emoji/blob/main/CONTRIBUTING.md) for this repository.