emojica: A Swift repository from xoudini

^{Emojica – a Swift framework for using custom emoji in strings.}

What does it do?

Emojica allows you to replace the standard emoji in your iOS apps with custom emoji. Works on UILabel and UITextView.

Just follow the instructions below, import your custom image set, and you're ready to go.

Features

Compatible with all iOS 13 emoji
Works with any image set¹
Safe to use even with incomplete image sets²
Convert input directly on textViewDidChange(_:)
Revert converted strings to their original representation

^{1. The naming should follow a similar pattern as the compatible image sets.}
^{2. The original emoji are used as fallback.}

Requirements

Xcode 11
iOS 13.0+
- Lower versions haven't been tested, although the framework may run without issues on a lower version.
Swift 5
- Using the framework in an Objective-C project may require some modifications to the source. Support for Objective-C will possibly be added at some point in the future.

Installation

CocoaPods

Add the pod to your Podfile:

target '...' do
    pod 'Emojica'
end

Navigate into your project directory and install/update:

$ cd /Path/To/Your/Project/ && pod install

Carthage

Add this to your Cartfile:

github "xoudini/emojica"

Navigate into your project directory and install/update:

$ cd /Path/To/Your/Project/ && carthage update

Swift Package Manager

Open your project use Xcode. Click File -> Add Packages, enter repository url.

https://github.com/xoudini/emojica

Manual installation

Clone the repository, and drag Emojica.xcodeproj into your project hierarchy in Xcode.
Select your project, then select your application's target under Targets.
Under the General tab, click the + under Embedded Binaries.
Select Emojica.frameworkiOS and finish by pressing Add.

If Xcode gives you a No such module 'Emojica' compiler error at your import statement, just build your application (or the framework) once. Also, each time you Clean (⇧⌘K) the project Xcode will give you the same error, and the solution is the same.

Usage

import Emojica

Instantiation

let emojica = Emojica()

// Creates an instance with a font.
let emojica = Emojica(font: UIFont.systemFont(ofSize: 17.0))

Configure instance

Set font:

emojica.font = UIFont.systemFont(ofSize: 17.0)

If no font is set, the system font is used.

Set size:
```
emojica.pointSize = 17.0
```

If you're satisfied with the default font, you can just set the size. The value for pointSize is 17.0 by default.

Set minimum code point width:

NOTE: Use this only when using a custom image set that isn't handled by Emojica.

emojica.minimumCodePointWidth = 4

A value between 0 and 8 that sets the minimum width for code point strings in order to correctly find the images for the custom emoji. The character 0 is used for padding.

To find a suitable value, find the image for e.g. © (U+00A9 COPYRIGHT SIGN), and use the length of that image's name – a9.png has a width of 2, 00a9.png has a width of 4, etc.

Set separator:

NOTE: Use this only when using a custom image set that isn't handled by Emojica.

emojica.separator = "~"

The separator used in the image names of combined code points.

Set image set used in the project:
```
emojica.imageSet = .default
```

Automatically configures settings specific to the image set.

Disable modifier symbols:
```
emojica.useModifiers = false
```

Strips out all modifier symbols from complete modifier sequences.

Enable emoji to be reverted:

NOTE: Keep the instance non-revertible if the original strings aren't needed after conversion.

emojica.revertible = true

Enables strings with custom emoji to be reverted to original state.

Convert string

let sample: String = "Sample text 😎"

let converted: NSAttributedString = emojica.convert(string: sample)

Revert string

NOTE: The instance must have revertible set to true.

let reverted: String = emojica.revert(attributedString: converted)

Using converted strings

let textView = UITextView()

...

let flag: String = "🇫🇮 "

textView.attributedText = emojica.convert(string: flag)

Directly converting text input

You can directly convert text input by implementing the UITextViewDelegate method textViewDidChange(_:) and passing the changed UITextView to the Emojica method by the same name:

func textViewDidChange(_ textView: UITextView) {
    emojica.textViewDidChange(textView)
}

Compatible Image Sets

The below image sets are tested, but other image sets may work just as well. If you have an image set that should be added to Emojica, please create an Issue.

Set	Version	Notes
Twemoji	v13.0	Prepare
EmojiOne	2.2.7	Missing code points¹
Noto Emoji	1.05	Prepare

NOTE: The newest EmojiOne and Noto sets haven't been checked in a while.

^{1. U+2640, U+2642 and U+2695 and sequences containing these characters are
unsupported.}

Example Project

The example EmojicaExample.xcodeproj is set up but does not contain images. To test the project, add your emoji images to the Images group and Run.

Preparations

WARNING: Running the script will overwrite the image names, so do not run the script over a unique image set!

Some image sets may have to be slightly modified before usage. Check the table in Compatible Image Sets if you're using a set marked Prepare, and if you are, follow these instructions:

1. Copy/move the contained file `rename.sh` into the folder containing your image set.

2. Open your preferred terminal.

3. Navigate into the directory:

$ cd /Path/To/Your/ImageSet/

4. Run the script:

$ sh rename.sh

Contact

Feedback and questions are welcome, create an Issue for bugs, problems, and potential feature requests.

If you end up using this framework in one of your projects, feel free to let me know, e.g. on Twitter.

Contributions

The list of contributors to this project can be found here.

If you would like to contribute, don't hesitate to open an issue or a pull request.

License

Emojica is released under the Apache License 2.0.

xoudini/emojica