blob: 1618096d69108f5dc0275e6948ed3472b895890c [file] [log] [blame]
Seigo Nonakacb88a652019-03-29 14:22:49 -07001/*
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 Albertc0416092019-04-16 13:20:26 -070018 * @addtogroup Font
Dan Alberte4a1cab2019-06-14 14:01:20 -070019 * @{
Dan Albertc0416092019-04-16 13:20:26 -070020 */
21
22/**
Seigo Nonakacb88a652019-03-29 14:22:49 -070023 * @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
56enum {
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 */
94struct AFont;
95
96/**
97 * Close an AFont.
98 *
Elliott Hughes3d70e532019-10-29 08:59:39 -070099 * Available since API level 29.
100 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700101 * \param font a font returned by ASystemFontIterator_next or AFontMatchert_match.
102 * Do nothing if NULL is passed.
103 */
104void 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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700121 * Available since API level 29.
122 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700123 * \param font a font object. Passing NULL is not allowed.
124 * \return a string of the font file path.
125 */
126const 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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700191 * Available since API level 29.
192 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700193 * \param font a font object. Passing NULL is not allowed.
194 * \return a positive integer less than or equal to {@link ASYSTEM_FONT_MAX_WEIGHT} is returned.
195 */
196uint16_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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700201 * Available since API level 29.
202 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700203 * \param font a font object. Passing NULL is not allowed.
204 * \return true if italic, otherwise false.
205 */
206bool 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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700215 * Available since API level 29.
216 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700217 * \param font a font object. Passing NULL is not allowed.
218 * \return a IETF BCP47 compliant language tag or nullptr if not available.
219 */
220const 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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700229 * Available since API level 29.
230 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700231 * \param font a font object. Passing NULL is not allowed.
232 * \return a font collection index.
233 */
234size_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 = AFontIterator_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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700262 * Available since API level 29.
263 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700264 * \param font a font object. Passing NULL is not allowed.
265 * \return a number of font variation settings.
266 */
267size_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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700275 * Available since API level 29.
276 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700277 * \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 */
282uint32_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 *
Elliott Hughes3d70e532019-10-29 08:59:39 -0700290 * Available since API level 29.
291 *
Seigo Nonakacb88a652019-03-29 14:22:49 -0700292 * \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 ASYstemFont_getAxisCount} is not allwed.
295 * \return a float value for the given font variation setting.
296 */
297float AFont_getAxisValue(const AFont* _Nonnull font, uint32_t axisIndex)
298 __INTRODUCED_IN(29);
299
300#endif // __ANDROID_API__ >= 29
301
302__END_DECLS
303
304#endif // ANDROID_FONT_H
Dan Albertc0416092019-04-16 13:20:26 -0700305
306/** @} */