1 /*
2  * Copyright (C) 2018 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 system_fonts.h
24  * @brief Provides the system font configurations.
25  *
26  * These APIs provides the list of system installed font files with additional metadata about the
27  * font.
28  *
29  * The ASystemFontIterator_open method will give you an iterator which can iterate all system
30  * installed font files as shown in the following example.
31  *
32  * \code{.cpp}
33  *   ASystemFontIterator* iterator = ASystemFontIterator_open();
34  *   ASystemFont* font = NULL;
35  *
36  *   while ((font = ASystemFontIterator_next(iterator)) != nullptr) {
37  *       // Look if the font is your desired one.
38  *       if (ASystemFont_getWeight(font) == 400 && !ASystemFont_isItalic(font)
39  *           && ASystemFont_getLocale(font) == NULL) {
40  *           break;
41  *       }
42  *       ASystemFont_close(font);
43  *   }
44  *   ASystemFontIterator_close(iterator);
45  *
46  *   int fd = open(ASystemFont_getFontFilePath(font), O_RDONLY);
47  *   int collectionIndex = ASystemFont_getCollectionINdex(font);
48  *   std::vector<std::pair<uint32_t, float>> variationSettings;
49  *   for (size_t i = 0; i < ASystemFont_getAxisCount(font); ++i) {
50  *       variationSettings.push_back(std::make_pair(
51  *           ASystemFont_getAxisTag(font, i),
52  *           ASystemFont_getAxisValue(font, i)));
53  *   }
54  *   ASystemFont_close(font);
55  *
56  *   // Use this font for your text rendering engine.
57  *
58  * \endcode
59  *
60  * Available since API level 29.
61  */
62 
63 #ifndef ANDROID_SYSTEM_FONTS_H
64 #define ANDROID_SYSTEM_FONTS_H
65 
66 #include <stdbool.h>
67 #include <stddef.h>
68 #include <sys/cdefs.h>
69 
70 #include <android/font.h>
71 
72 /******************************************************************
73  *
74  * IMPORTANT NOTICE:
75  *
76  *   This file is part of Android's set of stable system headers
77  *   exposed by the Android NDK (Native Development Kit).
78  *
79  *   Third-party source AND binary code relies on the definitions
80  *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
81  *
82  *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
83  *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
84  *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
85  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
86  */
87 
88 __BEGIN_DECLS
89 
90 #if __ANDROID_API__ >= 29
91 
92 /**
93  * ASystemFontIterator provides access to the system font configuration.
94  *
95  * ASystemFontIterator is an iterator for all available system font settings.
96  * This iterator is not a thread-safe object. Do not pass this iterator to other threads.
97  */
98 struct ASystemFontIterator;
99 
100 /**
101  * Create a system font iterator.
102  *
103  * Use ASystemFont_close() to close the iterator.
104  *
105  * Available since API level 29.
106  *
107  * \return a pointer for a newly allocated iterator, nullptr on failure.
108  */
109 ASystemFontIterator* _Nullable ASystemFontIterator_open() __INTRODUCED_IN(29);
110 
111 /**
112  * Close an opened system font iterator, freeing any related resources.
113  *
114  * Available since API level 29.
115  *
116  * \param iterator a pointer of an iterator for the system fonts. Do nothing if NULL is passed.
117  */
118 void ASystemFontIterator_close(ASystemFontIterator* _Nullable iterator) __INTRODUCED_IN(29);
119 
120 /**
121  * Move to the next system font.
122  *
123  * Available since API level 29.
124  *
125  * \param iterator an iterator for the system fonts. Passing NULL is not allowed.
126  * \return a font. If no more font is available, returns nullptr. You need to release the returned
127  *         font by ASystemFont_close when it is no longer needed.
128  */
129 AFont* _Nullable ASystemFontIterator_next(ASystemFontIterator* _Nonnull iterator) __INTRODUCED_IN(29);
130 
131 #endif // __ANDROID_API__ >= 29
132 
133 __END_DECLS
134 
135 #endif // ANDROID_SYSTEM_FONTS_H
136 
137 /** @} */
138