1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 Copyright 2017 The Android Open Source Project
4
5 Licensed under the Apache License, Version 2.0 (the "License");
6 you may not use this file except in compliance with the License.
7 You may obtain a copy of the License at
8
9     http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<sample>
18    <name>EmojiCompat</name>
19    <group>Views</group>
20    <package>com.example.android.emojicompat</package>
21    <minSdk>"android-O"</minSdk>
22    <targetSdkVersion>"android-O"</targetSdkVersion>
23
24    <strings>
25        <intro>
26            This sample demonstrates usage of EmojiCompat support library. You can use this library
27            to prevent your app from showing missing emoji characters in the form of tofu (□). You
28            can use either bundled or downloadable emoji fonts. This sample shows both usages.
29        </intro>
30    </strings>
31
32    <template src="base-build"/>
33
34    <metadata>
35        <status>PUBLISHED</status>
36        <categories>UI, Android O Preview</categories>
37        <technologies>Android</technologies>
38        <languages>Java</languages>
39        <solutions>Mobile</solutions>
40        <level>INTERMEDIATE</level>
41        <icon>screenshots/icon-web.png</icon>
42        <screenshots>
43            <img>screenshots/1-main.png</img>
44        </screenshots>
45        <api_refs>
46            <android>android.support.text.emoji.EmojiCompat</android>
47            <android>android.support.text.emoji.bundled.BundledEmojiCompatConfig</android>
48            <android>android.support.text.emoji.FontRequestEmojiCompatConfig</android>
49            <android>android.support.v4.provider.FontRequest</android>
50            <android>android.support.text.emoji.widget.EmojiAppCompatTextView</android>
51            <android>android.support.text.emoji.widget.EmojiAppCompatEditText</android>
52            <android>android.support.text.emoji.widget.EmojiAppCompatButton</android>
53            <android>android.support.text.emoji.widget.EmojiTextViewHelper</android>
54        </api_refs>
55
56        <description>
57            <![CDATA[
58This sample demonstrates usage of EmojiCompat support library. You can use this library
59to prevent your app from showing missing emoji characters in the form of tofu (□). You
60can use either bundled or downloadable emoji fonts. This sample shows both usages.
61]]>
62        </description>
63
64        <intro>
65            <![CDATA[
66The EmojiCompat support library aims to keep Android devices up to date with the latest emoji. It
67prevents your app from showing missing emoji characters in the form of ☐, which indicates that your
68device does not have a font to display the text. By using the EmojiCompat support library, your app
69users do not need to wait for Android OS updates to get the latest emoji.
70
71For further detail, read [Emoji Compatibility][1] documentation.
72
73### Configuration
74
75You need to first initialize EmojiCompat to load the metadata and the typeface. You can use either
76bundled or downloadable fonts.
77
78#### Use downloadable fonts
79
80***You need the beta version of Google Play Services to use this feature.*** Join
81[Google Play Services Public Beta Program][4] and make sure you have v11 installed on your device
82running Android O Developer Preview 2.
83
84For the downloadable font configuration, you need to create an instance of the [FontRequest][5]
85class, and provide the font provider authority, the font provider package, the font query, and a
86list of set of hashes for the certificates. For more information about FontRequest, refer to the
87Downloadable Fonts documentation. You can then create an instance of
88[FontRequestEmojiCompatConfig][6] and pass it to EmojiCompat.init().
89
90```java
91final FontRequest fontRequest = new FontRequest(
92                    "com.google.android.gms.fonts",
93                    "com.google.android.gms",
94                    "Noto Color Emoji Compat",
95                    R.array.com_google_android_gms_fonts_certs);
96EmojiCompat.init(new FontRequestEmojiCompatConfig(getApplicationContext(), fontRequest)
97                    .setReplaceAll(true)
98                    .registerInitCallback(new EmojiCompat.InitCallback() {
99                        @Override
100                        public void onInitialized() {
101                            Log.i(TAG, "EmojiCompat initialized");
102                        }
103
104                        @Override
105                        public void onFailed(@Nullable Throwable throwable) {
106                            Log.e(TAG, "EmojiCompat initialization failed", throwable);
107                        }
108                    });)
109```
110
111#### Use bundled font
112
113In order the use the bundled font, call init() method of [EmojiCompat][2] with an instance of
114[BundledEmojiCompatConfig][3].
115
116### Use EmojiCompat
117
118#### Built-in views
119
120The easiest way to use EmojiCompat in your layout, is to use [EmojiAppCompatTextView][7],
121[EmojiAppCompatEditText][8], or [EmojiAppCompatButton][9]. You can use them in your layout XMLs or
122code. You can just set any text containing emoji and the widgets handle the rest.
123
124#### With regular TextViews
125
126If you want to use EmojiCompat with a regular TextView, retrieve an instance of EmojiCompat by
127calling EmojiCompat.get() and call registerInitCallback method. You can pass an
128EmojiCompat.InitCallback and use the EmojiCompat#process() method there to transform emoji text into
129a backward-compatible format.
130
131#### With custom TextViews
132
133If you want to use EmojiCompat in your custom TextView, you can create an instance of
134[EmojiTextViewHelper][10] and use it in some overridden methods, namely setFilters and setAllCaps.
135[CustomTextView.java][11] shows what to do inside them.
136
137[1]: https://developer.android.com/preview/features/emoji-compat.html
138[2]: https://developer.android.com/reference/android/support/text/emoji/EmojiCompat.html
139[3]: https://developer.android.com/reference/android/support/text/emoji/bundled/BundledEmojiCompatConfig.html
140[4]: https://developers.google.com/android/guides/beta-program
141[5]: https://developer.android.com/reference/android/support/v4/provider/FontRequest.html
142[6]: https://developer.android.com/reference/android/support/text/emoji/FontRequestEmojiCompatConfig.html
143[7]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiAppCompatTextView.html
144[8]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiAppCompatEditText.html
145[9]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiAppCompatButton.html
146[10]: https://developer.android.com/reference/android/support/text/emoji/widget/EmojiCompatViewHelper.html
147[11]: https://github.com/googlesamples/android-EmojiCompat/blog/master/app/src/main/java/com/example/android/emojicompat/CustomTextView.java
148]]>
149        </intro>
150    </metadata>
151
152</sample>
153