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.h 24 * @brief Provides some constants used in system_fonts.h or fonts_matcher.h 25 * 26 * Available since API level 29. 27 */ 28 29 #ifndef ANDROID_FONT_H 30 #define ANDROID_FONT_H 31 32 #include <stdbool.h> 33 #include <stddef.h> 34 #include <sys/cdefs.h> 35 36 /****************************************************************** 37 * 38 * IMPORTANT NOTICE: 39 * 40 * This file is part of Android's set of stable system headers 41 * exposed by the Android NDK (Native Development Kit). 42 * 43 * Third-party source AND binary code relies on the definitions 44 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 45 * 46 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 47 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 48 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 49 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 50 */ 51 52 __BEGIN_DECLS 53 54 enum { 55 /** The minimum value fot the font weight value. */ 56 AFONT_WEIGHT_MIN = 0, 57 58 /** A font weight value for the thin weight. */ 59 AFONT_WEIGHT_THIN = 100, 60 61 /** A font weight value for the extra-light weight. */ 62 AFONT_WEIGHT_EXTRA_LIGHT = 200, 63 64 /** A font weight value for the light weight. */ 65 AFONT_WEIGHT_LIGHT = 300, 66 67 /** A font weight value for the normal weight. */ 68 AFONT_WEIGHT_NORMAL = 400, 69 70 /** A font weight value for the medium weight. */ 71 AFONT_WEIGHT_MEDIUM = 500, 72 73 /** A font weight value for the semi-bold weight. */ 74 AFONT_WEIGHT_SEMI_BOLD = 600, 75 76 /** A font weight value for the bold weight. */ 77 AFONT_WEIGHT_BOLD = 700, 78 79 /** A font weight value for the extra-bold weight. */ 80 AFONT_WEIGHT_EXTRA_BOLD = 800, 81 82 /** A font weight value for the black weight. */ 83 AFONT_WEIGHT_BLACK = 900, 84 85 /** The maximum value for the font weight value. */ 86 AFONT_WEIGHT_MAX = 1000 87 }; 88 89 /** 90 * AFont provides information of the single font configuration. 91 */ 92 struct AFont; 93 94 /** 95 * Close an AFont. 96 * 97 * Available since API level 29. 98 * 99 * \param font a font returned by ASystemFontIterator_next or AFontMatchert_match. 100 * Do nothing if NULL is passed. 101 */ 102 void AFont_close(AFont* _Nullable font) __INTRODUCED_IN(29); 103 104 /** 105 * Return an absolute path to the current font file. 106 * 107 * Here is a list of font formats returned by this method: 108 * <ul> 109 * <li>OpenType</li> 110 * <li>OpenType Font Collection</li> 111 * <li>TrueType</li> 112 * <li>TrueType Collection</li> 113 * </ul> 114 * The file extension could be one of *.otf, *.ttf, *.otc or *.ttc. 115 * 116 * The font file returned is guaranteed to be opend with O_RDONLY. 117 * Note that the returned pointer is valid until AFont_close() is called for the given font. 118 * 119 * Available since API level 29. 120 * 121 * \param font a font object. Passing NULL is not allowed. 122 * \return a string of the font file path. 123 */ 124 const char* _Nonnull AFont_getFontFilePath(const AFont* _Nonnull font) __INTRODUCED_IN(29); 125 126 /** 127 * Return a weight value associated with the current font. 128 * 129 * The weight values are positive and less than or equal to 1000. 130 * Here are pairs of the common names and their values. 131 * <p> 132 * <table> 133 * <tr> 134 * <th align="center">Value</th> 135 * <th align="center">Name</th> 136 * <th align="center">NDK Definition</th> 137 * </tr> 138 * <tr> 139 * <td align="center">100</td> 140 * <td align="center">Thin</td> 141 * <td align="center">{@link AFONT_WEIGHT_THIN}</td> 142 * </tr> 143 * <tr> 144 * <td align="center">200</td> 145 * <td align="center">Extra Light (Ultra Light)</td> 146 * <td align="center">{@link AFONT_WEIGHT_EXTRA_LIGHT}</td> 147 * </tr> 148 * <tr> 149 * <td align="center">300</td> 150 * <td align="center">Light</td> 151 * <td align="center">{@link AFONT_WEIGHT_LIGHT}</td> 152 * </tr> 153 * <tr> 154 * <td align="center">400</td> 155 * <td align="center">Normal (Regular)</td> 156 * <td align="center">{@link AFONT_WEIGHT_NORMAL}</td> 157 * </tr> 158 * <tr> 159 * <td align="center">500</td> 160 * <td align="center">Medium</td> 161 * <td align="center">{@link AFONT_WEIGHT_MEDIUM}</td> 162 * </tr> 163 * <tr> 164 * <td align="center">600</td> 165 * <td align="center">Semi Bold (Demi Bold)</td> 166 * <td align="center">{@link AFONT_WEIGHT_SEMI_BOLD}</td> 167 * </tr> 168 * <tr> 169 * <td align="center">700</td> 170 * <td align="center">Bold</td> 171 * <td align="center">{@link AFONT_WEIGHT_BOLD}</td> 172 * </tr> 173 * <tr> 174 * <td align="center">800</td> 175 * <td align="center">Extra Bold (Ultra Bold)</td> 176 * <td align="center">{@link AFONT_WEIGHT_EXTRA_BOLD}</td> 177 * </tr> 178 * <tr> 179 * <td align="center">900</td> 180 * <td align="center">Black (Heavy)</td> 181 * <td align="center">{@link AFONT_WEIGHT_BLACK}</td> 182 * </tr> 183 * </table> 184 * </p> 185 * Note that the weight value may fall in between above values, e.g. 250 weight. 186 * 187 * For more information about font weight, read [OpenType usWeightClass](https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass) 188 * 189 * Available since API level 29. 190 * 191 * \param font a font object. Passing NULL is not allowed. 192 * \return a positive integer less than or equal to {@link AFONT_WEIGHT_MAX} is returned. 193 */ 194 uint16_t AFont_getWeight(const AFont* _Nonnull font) __INTRODUCED_IN(29); 195 196 /** 197 * Return true if the current font is italic, otherwise returns false. 198 * 199 * Available since API level 29. 200 * 201 * \param font a font object. Passing NULL is not allowed. 202 * \return true if italic, otherwise false. 203 */ 204 bool AFont_isItalic(const AFont* _Nonnull font) __INTRODUCED_IN(29); 205 206 /** 207 * Return a IETF BCP47 compliant language tag associated with the current font. 208 * 209 * For information about IETF BCP47, read [Locale.forLanguageTag(java.lang.String)](https://developer.android.com/reference/java/util/Locale.html#forLanguageTag(java.lang.String)") 210 * 211 * Note that the returned pointer is valid until AFont_close() is called. 212 * 213 * Available since API level 29. 214 * 215 * \param font a font object. Passing NULL is not allowed. 216 * \return a IETF BCP47 compliant language tag or nullptr if not available. 217 */ 218 const char* _Nullable AFont_getLocale(const AFont* _Nonnull font) __INTRODUCED_IN(29); 219 220 /** 221 * Return a font collection index value associated with the current font. 222 * 223 * In case the target font file is a font collection (e.g. .ttc or .otc), this 224 * returns a non-negative value as an font offset in the collection. This 225 * always returns 0 if the target font file is a regular font. 226 * 227 * Available since API level 29. 228 * 229 * \param font a font object. Passing NULL is not allowed. 230 * \return a font collection index. 231 */ 232 size_t AFont_getCollectionIndex(const AFont* _Nonnull font) __INTRODUCED_IN(29); 233 234 /** 235 * Return a count of font variation settings associated with the current font 236 * 237 * The font variation settings are provided as multiple tag-values pairs. 238 * 239 * For example, bold italic font may have following font variation settings: 240 * 'wght' 700, 'slnt' -12 241 * In this case, AFont_getAxisCount returns 2 and AFont_getAxisTag 242 * and AFont_getAxisValue will return following values. 243 * \code{.cpp} 244 * AFont* font = ASystemFontIterator_next(ite); 245 * 246 * // Returns the number of axes 247 * AFont_getAxisCount(font); // Returns 2 248 * 249 * // Returns the tag-value pair for the first axis. 250 * AFont_getAxisTag(font, 0); // Returns 'wght'(0x77676874) 251 * AFont_getAxisValue(font, 0); // Returns 700.0 252 * 253 * // Returns the tag-value pair for the second axis. 254 * AFont_getAxisTag(font, 1); // Returns 'slnt'(0x736c6e74) 255 * AFont_getAxisValue(font, 1); // Returns -12.0 256 * \endcode 257 * 258 * For more information about font variation settings, read [Font Variations Table](https://docs.microsoft.com/en-us/typography/opentype/spec/fvar) 259 * 260 * Available since API level 29. 261 * 262 * \param font a font object. Passing NULL is not allowed. 263 * \return a number of font variation settings. 264 */ 265 size_t AFont_getAxisCount(const AFont* _Nonnull font) __INTRODUCED_IN(29); 266 267 268 /** 269 * Return an OpenType axis tag associated with the current font. 270 * 271 * See AFont_getAxisCount for more details. 272 * 273 * Available since API level 29. 274 * 275 * \param font a font object. Passing NULL is not allowed. 276 * \param axisIndex an index to the font variation settings. Passing value larger than or 277 * equal to {@link AFont_getAxisCount} is not allowed. 278 * \return an OpenType axis tag value for the given font variation setting. 279 */ 280 uint32_t AFont_getAxisTag(const AFont* _Nonnull font, uint32_t axisIndex) 281 __INTRODUCED_IN(29); 282 283 /** 284 * Return an OpenType axis value associated with the current font. 285 * 286 * See AFont_getAxisCount for more details. 287 * 288 * Available since API level 29. 289 * 290 * \param font a font object. Passing NULL is not allowed. 291 * \param axisIndex an index to the font variation settings. Passing value larger than or 292 * equal to {@link AFont_getAxisCount} is not allowed. 293 * \return a float value for the given font variation setting. 294 */ 295 float AFont_getAxisValue(const AFont* _Nonnull font, uint32_t axisIndex) 296 __INTRODUCED_IN(29); 297 298 __END_DECLS 299 300 #endif // ANDROID_FONT_H 301 302 /** @} */ 303