1
2Android EmojiCompat Sample
3===================================
4
5This sample demonstrates usage of EmojiCompat support library. You can use this library
6to prevent your app from showing missing emoji characters in the form of tofu (□). You
7can use either bundled or downloadable emoji fonts. This sample shows both usages.
8
9Introduction
10------------
11
12The EmojiCompat support library aims to keep Android devices up to date with the latest emoji. It
13prevents your app from showing missing emoji characters in the form of ☐, which indicates that your
14device does not have a font to display the text. By using the EmojiCompat support library, your app
15users do not need to wait for Android OS updates to get the latest emoji.
16
17For further detail, read [Emoji Compatibility][1] documentation.
18
19### Configuration
20
21You need to first initialize EmojiCompat to load the metadata and the typeface. You can use either
22bundled or downloadable fonts.
23
24#### Use downloadable fonts
25
26***You need the beta version of Google Play Services to use this feature.*** Join
27[Google Play Services Public Beta Program][4] and make sure you have v11 installed on your device
28running Android O Developer Preview 2.
29
30For the downloadable font configuration, you need to create an instance of the [FontRequest][5]
31class, and provide the font provider authority, the font provider package, the font query, and a
32list of set of hashes for the certificates. For more information about FontRequest, refer to the
33Downloadable Fonts documentation. You can then create an instance of
34[FontRequestEmojiCompatConfig][6] and pass it to EmojiCompat.init().
35
36```java
37final FontRequest fontRequest = new FontRequest(
38                    "com.google.android.gms.fonts",
39                    "com.google.android.gms",
40                    "Noto Color Emoji Compat",
41                    R.array.com_google_android_gms_fonts_certs);
42EmojiCompat.init(new FontRequestEmojiCompatConfig(getApplicationContext(), fontRequest)
43                    .setReplaceAll(true)
44                    .registerInitCallback(new EmojiCompat.InitCallback() {
45                        @Override
46                        public void onInitialized() {
47                            Log.i(TAG, "EmojiCompat initialized");
48                        }
49
50                        @Override
51                        public void onFailed(@Nullable Throwable throwable) {
52                            Log.e(TAG, "EmojiCompat initialization failed", throwable);
53                        }
54                    });)
55```
56
57##### Preloading the font during application install
58You can add the following meta-data to your AndroidManifest.xml in order to download the font when
59your application is installed from Play Store.  This way the font will be downloaded and ready when
60your application starts for the first time.
61
62```xml
63    <meta-data android:name="fontProviderRequests" android:value="Noto Color Emoji Compat"/>
64```
65
66#### Use bundled font
67
68In order the use the bundled font, call init() method of [EmojiCompat][2] with an instance of
69[BundledEmojiCompatConfig][3].
70
71### Use EmojiCompat
72
73#### Built-in views
74
75The easiest way to use EmojiCompat in your layout, is to use [EmojiAppCompatTextView][7],
76[EmojiAppCompatEditText][8], or [EmojiAppCompatButton][9]. You can use them in your layout XMLs or
77code. You can just set any text containing emoji and the widgets handle the rest.
78
79#### With regular TextViews
80
81If you want to use EmojiCompat with a regular TextView, retrieve an instance of EmojiCompat by
82calling EmojiCompat.get() and call registerInitCallback method. You can pass an
83EmojiCompat.InitCallback and use the EmojiCompat#process() method there to transform emoji text into
84a backward-compatible format.
85
86#### With custom TextViews
87
88If you want to use EmojiCompat in your custom TextView, you can create an instance of
89[EmojiTextViewHelper][10] and use it in some overridden methods, namely setFilters and setAllCaps.
90[CustomTextView.java][11] shows what to do inside them.
91
92[1]: https://developer.android.com/preview/features/emoji-compat.html
93[2]: https://developer.android.com/reference/android/support/text/emoji/EmojiCompat.html
94[3]: https://developer.android.com/reference/android/support/text/emoji/bundled/BundledEmojiCompatConfig.html
95[4]: https://developers.google.com/android/guides/beta-program
96[5]: https://developer.android.com/reference/android/support/v4/provider/FontRequest.html
97[6]: https://developer.android.com/reference/android/support/text/emoji/FontRequestEmojiCompatConfig.html
98[7]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiAppCompatTextView.html
99[8]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiAppCompatEditText.html
100[9]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiAppCompatButton.html
101[10]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiCompatViewHelper.html
102[11]: https://github.com/googlesamples/android-EmojiCompat/blog/master/app/src/main/java/com/example/android/emojicompat/CustomTextView.java
103
104Pre-requisites
105--------------
106
107- Android SDK 27
108- Android Build Tools v27.0.3
109- Android Support Repository
110
111Screenshots
112-------------
113
114<img src="screenshots/1-main.png" height="400" alt="Screenshot"/>
115
116Getting Started
117---------------
118
119This sample uses the Gradle build system. To build this project, use the
120"gradlew build" command or use "Import Project" in Android Studio.
121
122Support
123-------
124
125- Google+ Community: https://plus.google.com/communities/105153134372062985968
126- Stack Overflow: http://stackoverflow.com/questions/tagged/android
127
128If you've found an error in this sample, please file an issue:
129https://github.com/googlesamples/android-EmojiCompat
130
131Patches are encouraged, and may be submitted by forking this project and
132submitting a pull request through GitHub. Please see CONTRIBUTING.md for more details.
133
134License
135-------
136
137Copyright 2017 The Android Open Source Project, Inc.
138
139Licensed to the Apache Software Foundation (ASF) under one or more contributor
140license agreements.  See the NOTICE file distributed with this work for
141additional information regarding copyright ownership.  The ASF licenses this
142file to you under the Apache License, Version 2.0 (the "License"); you may not
143use this file except in compliance with the License.  You may obtain a copy of
144the License at
145
146http://www.apache.org/licenses/LICENSE-2.0
147
148Unless required by applicable law or agreed to in writing, software
149distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
150WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
151License for the specific language governing permissions and limitations under
152the License.
153