Seigo Nonaka | cb88a65 | 2019-03-29 14:22:49 -0700 | [diff] [blame] | 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 | /** |
Dan Albert | c041609 | 2019-04-16 13:20:26 -0700 | [diff] [blame^] | 18 | * @addtogroup Font |
| 19 | * { |
| 20 | */ |
| 21 | |
| 22 | /** |
Seigo Nonaka | cb88a65 | 2019-03-29 14:22:49 -0700 | [diff] [blame] | 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 | * ASystemFont* 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 | * ASystemFont* 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 | * ASystemFont* 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 | * ASystemFont* 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 | * ASystemFont* 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 | #if __ANDROID_API__ >= 29 |
| 101 | |
| 102 | enum { |
| 103 | /** A family variant value for the system default variant. */ |
| 104 | AFAMILY_VARIANT_DEFAULT = 0, |
| 105 | |
| 106 | /** |
| 107 | * A family variant value for the compact font family variant. |
| 108 | * |
| 109 | * The compact font family has Latin-based vertical metrics. |
| 110 | */ |
| 111 | AFAMILY_VARIANT_COMPACT = 1, |
| 112 | |
| 113 | /** |
| 114 | * A family variant value for the elegant font family variant. |
| 115 | * |
| 116 | * The elegant font family may have larger vertical metrics than Latin font. |
| 117 | */ |
| 118 | AFAMILY_VARIANT_ELEGANT = 2, |
| 119 | }; |
| 120 | |
| 121 | /** |
| 122 | * AFontMatcher performs match operation on given parameters and available font files. |
| 123 | * This matcher is not a thread-safe object. Do not pass this matcher to other threads. |
| 124 | */ |
| 125 | struct AFontMatcher; |
| 126 | |
| 127 | /** |
| 128 | * Select the best font from given parameters. |
| 129 | * |
| 130 | */ |
| 131 | |
| 132 | /** |
| 133 | * Creates a new AFontMatcher object |
| 134 | */ |
| 135 | AFontMatcher* _Nonnull AFontMatcher_create() __INTRODUCED_IN(29); |
| 136 | |
| 137 | /** |
| 138 | * Destroy the matcher object. |
| 139 | * |
| 140 | * \param matcher a matcher object. Passing NULL is not allowed. |
| 141 | */ |
| 142 | void AFontMatcher_destroy(AFontMatcher* _Nonnull matcher) __INTRODUCED_IN(29); |
| 143 | |
| 144 | /** |
| 145 | * Set font style to matcher. |
| 146 | * |
| 147 | * If this function is not called, the matcher performs with {@link ASYSTEM_FONT_WEIGHT_NORMAL} |
| 148 | * with non-italic style. |
| 149 | * |
| 150 | * \param matcher a matcher object. Passing NULL is not allowed. |
| 151 | * \param weight a font weight value. Only from 0 to 1000 value is valid |
| 152 | * \param italic true if italic, otherwise false. |
| 153 | */ |
| 154 | void AFontMatcher_setStyle( |
| 155 | AFontMatcher* _Nonnull matcher, |
| 156 | uint16_t weight, |
| 157 | bool italic) __INTRODUCED_IN(29); |
| 158 | |
| 159 | /** |
| 160 | * Set font locales to matcher. |
| 161 | * |
| 162 | * If this function is not called, the matcher performs with empty locale list. |
| 163 | * |
| 164 | * \param matcher a matcher object. Passing NULL is not allowed. |
| 165 | * \param languageTags a null character terminated comma separated IETF BCP47 compliant language |
| 166 | * tags. |
| 167 | */ |
| 168 | void AFontMatcher_setLocales( |
| 169 | AFontMatcher* _Nonnull matcher, |
| 170 | const char* _Nonnull languageTags) __INTRODUCED_IN(29); |
| 171 | |
| 172 | /** |
| 173 | * Set family variant to matcher. |
| 174 | * |
| 175 | * If this function is not called, the matcher performs with {@link AFAMILY_VARIANT_DEFAULT}. |
| 176 | * |
| 177 | * \param matcher a matcher object. Passing NULL is not allowed. |
| 178 | * \param familyVariant Must be one of {@link AFAMILY_VARIANT_DEFAULT}, |
| 179 | * {@link AFAMILY_VARIANT_COMPACT} or {@link AFAMILY_VARIANT_ELEGANT} is valid. |
| 180 | */ |
| 181 | void AFontMatcher_setFamilyVariant( |
| 182 | AFontMatcher* _Nonnull matcher, |
| 183 | uint32_t familyVariant) __INTRODUCED_IN(29); |
| 184 | |
| 185 | /** |
| 186 | * Performs the matching from the generic font family for the text and select one font. |
| 187 | * |
| 188 | * For more information about generic font families, read [W3C spec](https://www.w3.org/TR/css-fonts-4/#generic-font-families) |
| 189 | * |
| 190 | * Even if no font can render the given text, this function will return a non-null result for |
| 191 | * drawing Tofu character. |
| 192 | * |
| 193 | * \param matcher a matcher object. Passing NULL is not allowed. |
| 194 | * \param familyName a null character terminated font family name |
| 195 | * \param text a UTF-16 encoded text buffer to be rendered. Do not pass empty string. |
| 196 | * \param textLength a length of the given text buffer. This must not be zero. |
| 197 | * \param runLengthOut if not null, the font run length will be filled. |
| 198 | * \return a font to be used for given text and params. You need to release the returned font by |
| 199 | * ASystemFont_close when it is no longer needed. |
| 200 | */ |
| 201 | AFont* _Nonnull AFontMatcher_match( |
| 202 | const AFontMatcher* _Nonnull matcher, |
| 203 | const char* _Nonnull familyName, |
| 204 | const uint16_t* _Nonnull text, |
| 205 | const uint32_t textLength, |
| 206 | uint32_t* _Nullable runLengthOut) __INTRODUCED_IN(29); |
| 207 | |
| 208 | #endif // __ANDROID_API__ >= 29 |
| 209 | |
| 210 | __END_DECLS |
| 211 | |
| 212 | #endif // ANDROID_FONT_MATCHER_H |
Dan Albert | c041609 | 2019-04-16 13:20:26 -0700 | [diff] [blame^] | 213 | |
| 214 | /** @} */ |