Home | History | Annotate | Download | only in android 
      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  * \return a pointer for a newly allocated iterator, nullptr on failure.
    106  */
    107 ASystemFontIterator* _Nullable ASystemFontIterator_open() __INTRODUCED_IN(29);
    108 
    109 /**
    110  * Close an opened system font iterator, freeing any related resources.
    111  *
    112  * \param iterator a pointer of an iterator for the system fonts. Do nothing if NULL is passed.
    113  */
    114 void ASystemFontIterator_close(ASystemFontIterator* _Nullable iterator) __INTRODUCED_IN(29);
    115 
    116 /**
    117  * Move to the next system font.
    118  *
    119  * \param iterator an iterator for the system fonts. Passing NULL is not allowed.
    120  * \return a font. If no more font is available, returns nullptr. You need to release the returned
    121  *         font by ASystemFont_close when it is no longer needed.
    122  */
    123 AFont* _Nullable ASystemFontIterator_next(ASystemFontIterator* _Nonnull iterator) __INTRODUCED_IN(29);
    124 
    125 #endif // __ANDROID_API__ >= 29
    126 
    127 __END_DECLS
    128 
    129 #endif // ANDROID_SYSTEM_FONTS_H
    130 
    131 /** @} */
    132