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 #if __ANDROID_API__ >= 29 55 56 enum { 57 /** The minimum value fot the font weight value. */ 58 AFONT_WEIGHT_MIN = 0, 59 60 /** A font weight value for the thin weight. */ 61 AFONT_WEIGHT_THIN = 100, 62 63 /** A font weight value for the extra-light weight. */ 64 AFONT_WEIGHT_EXTRA_LIGHT = 200, 65 66 /** A font weight value for the light weight. */ 67 AFONT_WEIGHT_LIGHT = 300, 68 69 /** A font weight value for the normal weight. */ 70 AFONT_WEIGHT_NORMAL = 400, 71 72 /** A font weight value for the medium weight. */ 73 AFONT_WEIGHT_MEDIUM = 500, 74 75 /** A font weight value for the semi-bold weight. */ 76 AFONT_WEIGHT_SEMI_BOLD = 600, 77 78 /** A font weight value for the bold weight. */ 79 AFONT_WEIGHT_BOLD = 700, 80 81 /** A font weight value for the extra-bold weight. */ 82 AFONT_WEIGHT_EXTRA_BOLD = 800, 83 84 /** A font weight value for the black weight. */ 85 AFONT_WEIGHT_BLACK = 900, 86 87 /** The maximum value for the font weight value. */ 88 AFONT_WEIGHT_MAX = 1000 89 }; 90 91 /** 92 * AFont provides information of the single font configuration. 93 */ 94 struct AFont; 95 96 /** 97 * Close an AFont. 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 * \param font a font object. Passing NULL is not allowed. 120 * \return a string of the font file path. 121 */ 122 const char* _Nonnull AFont_getFontFilePath(const AFont* _Nonnull font) __INTRODUCED_IN(29); 123 124 /** 125 * Return a weight value associated with the current font. 126 * 127 * The weight values are positive and less than or equal to 1000. 128 * Here are pairs of the common names and their values. 129 * <p> 130 * <table> 131 * <tr> 132 * <th align="center">Value</th> 133 * <th align="center">Name</th> 134 * <th align="center">NDK Definition</th> 135 * </tr> 136 * <tr> 137 * <td align="center">100</td> 138 * <td align="center">Thin</td> 139 * <td align="center">{@link AFONT_WEIGHT_THIN}</td> 140 * </tr> 141 * <tr> 142 * <td align="center">200</td> 143 * <td align="center">Extra Light (Ultra Light)</td> 144 * <td align="center">{@link AFONT_WEIGHT_EXTRA_LIGHT}</td> 145 * </tr> 146 * <tr> 147 * <td align="center">300</td> 148 * <td align="center">Light</td> 149 * <td align="center">{@link AFONT_WEIGHT_LIGHT}</td> 150 * </tr> 151 * <tr> 152 * <td align="center">400</td> 153 * <td align="center">Normal (Regular)</td> 154 * <td align="center">{@link AFONT_WEIGHT_NORMAL}</td> 155 * </tr> 156 * <tr> 157 * <td align="center">500</td> 158 * <td align="center">Medium</td> 159 * <td align="center">{@link AFONT_WEIGHT_MEDIUM}</td> 160 * </tr> 161 * <tr> 162 * <td align="center">600</td> 163 * <td align="center">Semi Bold (Demi Bold)</td> 164 * <td align="center">{@link AFONT_WEIGHT_SEMI_BOLD}</td> 165 * </tr> 166 * <tr> 167 * <td align="center">700</td> 168 * <td align="center">Bold</td> 169 * <td align="center">{@link AFONT_WEIGHT_BOLD}</td> 170 * </tr> 171 * <tr> 172 * <td align="center">800</td> 173 * <td align="center">Extra Bold (Ultra Bold)</td> 174 * <td align="center">{@link AFONT_WEIGHT_EXTRA_BOLD}</td> 175 * </tr> 176 * <tr> 177 * <td align="center">900</td> 178 * <td align="center">Black (Heavy)</td> 179 * <td align="center">{@link AFONT_WEIGHT_BLACK}</td> 180 * </tr> 181 * </table> 182 * </p> 183 * Note that the weight value may fall in between above values, e.g. 250 weight. 184 * 185 * For more information about font weight, read [OpenType usWeightClass](https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass) 186 * 187 * \param font a font object. Passing NULL is not allowed. 188 * \return a positive integer less than or equal to {@link ASYSTEM_FONT_MAX_WEIGHT} is returned. 189 */ 190 uint16_t AFont_getWeight(const AFont* _Nonnull font) __INTRODUCED_IN(29); 191 192 /** 193 * Return true if the current font is italic, otherwise returns false. 194 * 195 * \param font a font object. Passing NULL is not allowed. 196 * \return true if italic, otherwise false. 197 */ 198 bool AFont_isItalic(const AFont* _Nonnull font) __INTRODUCED_IN(29); 199 200 /** 201 * Return a IETF BCP47 compliant language tag associated with the current font. 202 * 203 * For information about IETF BCP47, read [Locale.forLanguageTag(java.lang.String)](https://developer.android.com/reference/java/util/Locale.html#forLanguageTag(java.lang.String)") 204 * 205 * Note that the returned pointer is valid until AFont_close() is called. 206 * 207 * \param font a font object. Passing NULL is not allowed. 208 * \return a IETF BCP47 compliant language tag or nullptr if not available. 209 */ 210 const char* _Nullable AFont_getLocale(const AFont* _Nonnull font) __INTRODUCED_IN(29); 211 212 /** 213 * Return a font collection index value associated with the current font. 214 * 215 * In case the target font file is a font collection (e.g. .ttc or .otc), this 216 * returns a non-negative value as an font offset in the collection. This 217 * always returns 0 if the target font file is a regular font. 218 * 219 * \param font a font object. Passing NULL is not allowed. 220 * \return a font collection index. 221 */ 222 size_t AFont_getCollectionIndex(const AFont* _Nonnull font) __INTRODUCED_IN(29); 223 224 /** 225 * Return a count of font variation settings associated with the current font 226 * 227 * The font variation settings are provided as multiple tag-values pairs. 228 * 229 * For example, bold italic font may have following font variation settings: 230 * 'wght' 700, 'slnt' -12 231 * In this case, AFont_getAxisCount returns 2 and AFont_getAxisTag 232 * and AFont_getAxisValue will return following values. 233 * \code{.cpp} 234 * AFont* font = AFontIterator_next(ite); 235 * 236 * // Returns the number of axes 237 * AFont_getAxisCount(font); // Returns 2 238 * 239 * // Returns the tag-value pair for the first axis. 240 * AFont_getAxisTag(font, 0); // Returns 'wght'(0x77676874) 241 * AFont_getAxisValue(font, 0); // Returns 700.0 242 * 243 * // Returns the tag-value pair for the second axis. 244 * AFont_getAxisTag(font, 1); // Returns 'slnt'(0x736c6e74) 245 * AFont_getAxisValue(font, 1); // Returns -12.0 246 * \endcode 247 * 248 * For more information about font variation settings, read [Font Variations Table](https://docs.microsoft.com/en-us/typography/opentype/spec/fvar) 249 * 250 * \param font a font object. Passing NULL is not allowed. 251 * \return a number of font variation settings. 252 */ 253 size_t AFont_getAxisCount(const AFont* _Nonnull font) __INTRODUCED_IN(29); 254 255 256 /** 257 * Return an OpenType axis tag associated with the current font. 258 * 259 * See AFont_getAxisCount for more details. 260 * 261 * \param font a font object. Passing NULL is not allowed. 262 * \param axisIndex an index to the font variation settings. Passing value larger than or 263 * equal to {@link AFont_getAxisCount} is not allowed. 264 * \return an OpenType axis tag value for the given font variation setting. 265 */ 266 uint32_t AFont_getAxisTag(const AFont* _Nonnull font, uint32_t axisIndex) 267 __INTRODUCED_IN(29); 268 269 /** 270 * Return an OpenType axis value associated with the current font. 271 * 272 * See AFont_getAxisCount for more details. 273 * 274 * \param font a font object. Passing NULL is not allowed. 275 * \param axisIndex an index to the font variation settings. Passing value larger than or 276 * equal to {@link ASYstemFont_getAxisCount} is not allwed. 277 * \return a float value for the given font variation setting. 278 */ 279 float AFont_getAxisValue(const AFont* _Nonnull font, uint32_t axisIndex) 280 __INTRODUCED_IN(29); 281 282 #endif // __ANDROID_API__ >= 29 283 284 __END_DECLS 285 286 #endif // ANDROID_FONT_H 287 288 /** @} */ 289