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