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