1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup Font 19 * @{ 20 */ 21 22 /** 23 * @file font_matcher.h 24 * @brief Provides the font matching logic with various inputs. 25 * 26 * You can use this class for deciding what font is to be used for drawing text. 27 * 28 * A matcher is created from text style, locales and UI compatibility. The match function for 29 * matcher object can be called multiple times until close function is called. 30 * 31 * Even if no font can render the given text, the match function will return a non-null result for 32 * drawing Tofu character. 33 * 34 * Examples: 35 * \code{.cpp} 36 * // Simple font query for the ASCII character. 37 * std::vector<uint16_t> text = { 'A' }; 38 * AFontMatcher* matcher = AFontMatcher_create("sans-serif"); 39 * AFont* font = AFontMatcher_match(text.data(), text.length(), &runLength); 40 * // runLength will be 1 and the font will points a valid font file. 41 * AFontMatcher_destroy(matcher); 42 * 43 * // Querying font for CJK characters 44 * std::vector<uint16_t> text = { 0x9AA8 }; 45 * AFontMatcher* matcher = AFontMatcher_create("sans-serif"); 46 * AFontMatcher_setLocales(matcher, "zh-CN,ja-JP"); 47 * AFont* font = AFontMatcher_match(text.data(), text.length(), &runLength); 48 * // runLength will be 1 and the font will points a Simplified Chinese font. 49 * AFontMatcher_setLocales(matcher, "ja-JP,zh-CN"); 50 * AFont* font = AFontMatcher_match(text.data(), text.length(), &runLength); 51 * // runLength will be 1 and the font will points a Japanese font. 52 * AFontMatcher_destroy(matcher); 53 * 54 * // Querying font for text/color emoji 55 * std::vector<uint16_t> text = { 0xD83D, 0xDC68, 0x200D, 0x2764, 0xFE0F, 0x200D, 0xD83D, 0xDC68 }; 56 * AFontMatcher* matcher = AFontMatcher_create("sans-serif"); 57 * AFont* font = AFontMatcher_match(text.data(), text.length(), &runLength); 58 * // runLength will be 8 and the font will points a color emoji font. 59 * AFontMatcher_destroy(matcher); 60 * 61 * // Mixture of multiple script of characters. 62 * // 0x05D0 is a Hebrew character and 0x0E01 is a Thai character. 63 * std::vector<uint16_t> text = { 0x05D0, 0x0E01 }; 64 * AFontMatcher* matcher = AFontMatcher_create("sans-serif"); 65 * AFont* font = AFontMatcher_match(text.data(), text.length(), &runLength); 66 * // runLength will be 1 and the font will points a Hebrew font. 67 * AFontMatcher_destroy(matcher); 68 * \endcode 69 * 70 * Available since API level 29. 71 */ 72 73 #ifndef ANDROID_FONT_MATCHER_H 74 #define ANDROID_FONT_MATCHER_H 75 76 #include <stdbool.h> 77 #include <stddef.h> 78 #include <sys/cdefs.h> 79 80 #include <android/font.h> 81 82 /****************************************************************** 83 * 84 * IMPORTANT NOTICE: 85 * 86 * This file is part of Android's set of stable system headers 87 * exposed by the Android NDK (Native Development Kit). 88 * 89 * Third-party source AND binary code relies on the definitions 90 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 91 * 92 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 93 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 94 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 95 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 96 */ 97 98 __BEGIN_DECLS 99 100 enum { 101 /** A family variant value for the system default variant. */ 102 AFAMILY_VARIANT_DEFAULT = 0, 103 104 /** 105 * A family variant value for the compact font family variant. 106 * 107 * The compact font family has Latin-based vertical metrics. 108 */ 109 AFAMILY_VARIANT_COMPACT = 1, 110 111 /** 112 * A family variant value for the elegant font family variant. 113 * 114 * The elegant font family may have larger vertical metrics than Latin font. 115 */ 116 AFAMILY_VARIANT_ELEGANT = 2, 117 }; 118 119 /** 120 * AFontMatcher performs match operation on given parameters and available font files. 121 * This matcher is not a thread-safe object. Do not pass this matcher to other threads. 122 */ 123 struct AFontMatcher; 124 125 /** 126 * Select the best font from given parameters. 127 * 128 */ 129 130 /** 131 * Creates a new AFontMatcher object. 132 * 133 * Available since API level 29. 134 */ 135 AFontMatcher* _Nonnull AFontMatcher_create() __INTRODUCED_IN(29); 136 137 /** 138 * Destroy the matcher object. 139 * 140 * Available since API level 29. 141 * 142 * \param matcher a matcher object. Passing NULL is not allowed. 143 */ 144 void AFontMatcher_destroy(AFontMatcher* _Nonnull matcher) __INTRODUCED_IN(29); 145 146 /** 147 * Set font style to matcher. 148 * 149 * If this function is not called, the matcher performs with {@link AFONT_WEIGHT_NORMAL} 150 * with non-italic style. 151 * 152 * Available since API level 29. 153 * 154 * \param matcher a matcher object. Passing NULL is not allowed. 155 * \param weight a font weight value. Only from 0 to 1000 value is valid 156 * \param italic true if italic, otherwise false. 157 */ 158 void AFontMatcher_setStyle( 159 AFontMatcher* _Nonnull matcher, 160 uint16_t weight, 161 bool italic) __INTRODUCED_IN(29); 162 163 /** 164 * Set font locales to matcher. 165 * 166 * If this function is not called, the matcher performs with empty locale list. 167 * 168 * Available since API level 29. 169 * 170 * \param matcher a matcher object. Passing NULL is not allowed. 171 * \param languageTags a null character terminated comma separated IETF BCP47 compliant language 172 * tags. 173 */ 174 void AFontMatcher_setLocales( 175 AFontMatcher* _Nonnull matcher, 176 const char* _Nonnull languageTags) __INTRODUCED_IN(29); 177 178 /** 179 * Set family variant to matcher. 180 * 181 * If this function is not called, the matcher performs with {@link AFAMILY_VARIANT_DEFAULT}. 182 * 183 * Available since API level 29. 184 * 185 * \param matcher a matcher object. Passing NULL is not allowed. 186 * \param familyVariant Must be one of {@link AFAMILY_VARIANT_DEFAULT}, 187 * {@link AFAMILY_VARIANT_COMPACT} or {@link AFAMILY_VARIANT_ELEGANT} is valid. 188 */ 189 void AFontMatcher_setFamilyVariant( 190 AFontMatcher* _Nonnull matcher, 191 uint32_t familyVariant) __INTRODUCED_IN(29); 192 193 /** 194 * Performs the matching from the generic font family for the text and select one font. 195 * 196 * For more information about generic font families, read [W3C spec](https://www.w3.org/TR/css-fonts-4/#generic-font-families) 197 * 198 * Even if no font can render the given text, this function will return a non-null result for 199 * drawing Tofu character. 200 * 201 * Available since API level 29. 202 * 203 * \param matcher a matcher object. Passing NULL is not allowed. 204 * \param familyName a null character terminated font family name 205 * \param text a UTF-16 encoded text buffer to be rendered. Do not pass empty string. 206 * \param textLength a length of the given text buffer. This must not be zero. 207 * \param runLengthOut if not null, the font run length will be filled. 208 * \return a font to be used for given text and params. You need to release the returned font by 209 * AFont_close when it is no longer needed. 210 */ 211 AFont* _Nonnull AFontMatcher_match( 212 const AFontMatcher* _Nonnull matcher, 213 const char* _Nonnull familyName, 214 const uint16_t* _Nonnull text, 215 const uint32_t textLength, 216 uint32_t* _Nullable runLengthOut) __INTRODUCED_IN(29); 217 218 __END_DECLS 219 220 #endif // ANDROID_FONT_MATCHER_H 221 222 /** @} */ 223