blob: e286a4c812827ec403837263ce1ec98a6020e801 [file] [log] [blame]
/*
* Copyright (C) 2019 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @addtogroup Font
* {
*/
/**
* @file font_matcher.h
* @brief Provides the font matching logic with various inputs.
*
* You can use this class for deciding what font is to be used for drawing text.
*
* A matcher is created from text style, locales and UI compatibility. The match function for
* matcher object can be called multiple times until close function is called.
*
* Even if no font can render the given text, the match function will return a non-null result for
* drawing Tofu character.
*
* Examples:
* \code{.cpp}
* // Simple font query for the ASCII character.
* std::vector<uint16_t> text = { 'A' };
* AFontMatcher* matcher = AFontMatcher_create("sans-serif");
* ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);
* // runLength will be 1 and the font will points a valid font file.
* AFontMatcher_destroy(matcher);
*
* // Querying font for CJK characters
* std::vector<uint16_t> text = { 0x9AA8 };
* AFontMatcher* matcher = AFontMatcher_create("sans-serif");
* AFontMatcher_setLocales(matcher, "zh-CN,ja-JP");
* ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);
* // runLength will be 1 and the font will points a Simplified Chinese font.
* AFontMatcher_setLocales(matcher, "ja-JP,zh-CN");
* ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);
* // runLength will be 1 and the font will points a Japanese font.
* AFontMatcher_destroy(matcher);
*
* // Querying font for text/color emoji
* std::vector<uint16_t> text = { 0xD83D, 0xDC68, 0x200D, 0x2764, 0xFE0F, 0x200D, 0xD83D, 0xDC68 };
* AFontMatcher* matcher = AFontMatcher_create("sans-serif");
* ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);
* // runLength will be 8 and the font will points a color emoji font.
* AFontMatcher_destroy(matcher);
*
* // Mixture of multiple script of characters.
* // 0x05D0 is a Hebrew character and 0x0E01 is a Thai character.
* std::vector<uint16_t> text = { 0x05D0, 0x0E01 };
* AFontMatcher* matcher = AFontMatcher_create("sans-serif");
* ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);
* // runLength will be 1 and the font will points a Hebrew font.
* AFontMatcher_destroy(matcher);
* \endcode
*
* Available since API level 29.
*/
#ifndef ANDROID_FONT_MATCHER_H
#define ANDROID_FONT_MATCHER_H
#include <stdbool.h>
#include <stddef.h>
#include <sys/cdefs.h>
#include <android/font.h>
/******************************************************************
*
* IMPORTANT NOTICE:
*
* This file is part of Android's set of stable system headers
* exposed by the Android NDK (Native Development Kit).
*
* Third-party source AND binary code relies on the definitions
* here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
*
* - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
* - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
* - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
* - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
*/
__BEGIN_DECLS
#if __ANDROID_API__ >= 29
enum {
/** A family variant value for the system default variant. */
AFAMILY_VARIANT_DEFAULT = 0,
/**
* A family variant value for the compact font family variant.
*
* The compact font family has Latin-based vertical metrics.
*/
AFAMILY_VARIANT_COMPACT = 1,
/**
* A family variant value for the elegant font family variant.
*
* The elegant font family may have larger vertical metrics than Latin font.
*/
AFAMILY_VARIANT_ELEGANT = 2,
};
/**
* AFontMatcher performs match operation on given parameters and available font files.
* This matcher is not a thread-safe object. Do not pass this matcher to other threads.
*/
struct AFontMatcher;
/**
* Select the best font from given parameters.
*
*/
/**
* Creates a new AFontMatcher object
*/
AFontMatcher* _Nonnull AFontMatcher_create() __INTRODUCED_IN(29);
/**
* Destroy the matcher object.
*
* \param matcher a matcher object. Passing NULL is not allowed.
*/
void AFontMatcher_destroy(AFontMatcher* _Nonnull matcher) __INTRODUCED_IN(29);
/**
* Set font style to matcher.
*
* If this function is not called, the matcher performs with {@link ASYSTEM_FONT_WEIGHT_NORMAL}
* with non-italic style.
*
* \param matcher a matcher object. Passing NULL is not allowed.
* \param weight a font weight value. Only from 0 to 1000 value is valid
* \param italic true if italic, otherwise false.
*/
void AFontMatcher_setStyle(
AFontMatcher* _Nonnull matcher,
uint16_t weight,
bool italic) __INTRODUCED_IN(29);
/**
* Set font locales to matcher.
*
* If this function is not called, the matcher performs with empty locale list.
*
* \param matcher a matcher object. Passing NULL is not allowed.
* \param languageTags a null character terminated comma separated IETF BCP47 compliant language
* tags.
*/
void AFontMatcher_setLocales(
AFontMatcher* _Nonnull matcher,
const char* _Nonnull languageTags) __INTRODUCED_IN(29);
/**
* Set family variant to matcher.
*
* If this function is not called, the matcher performs with {@link AFAMILY_VARIANT_DEFAULT}.
*
* \param matcher a matcher object. Passing NULL is not allowed.
* \param familyVariant Must be one of {@link AFAMILY_VARIANT_DEFAULT},
* {@link AFAMILY_VARIANT_COMPACT} or {@link AFAMILY_VARIANT_ELEGANT} is valid.
*/
void AFontMatcher_setFamilyVariant(
AFontMatcher* _Nonnull matcher,
uint32_t familyVariant) __INTRODUCED_IN(29);
/**
* Performs the matching from the generic font family for the text and select one font.
*
* For more information about generic font families, read [W3C spec](https://www.w3.org/TR/css-fonts-4/#generic-font-families)
*
* Even if no font can render the given text, this function will return a non-null result for
* drawing Tofu character.
*
* \param matcher a matcher object. Passing NULL is not allowed.
* \param familyName a null character terminated font family name
* \param text a UTF-16 encoded text buffer to be rendered. Do not pass empty string.
* \param textLength a length of the given text buffer. This must not be zero.
* \param runLengthOut if not null, the font run length will be filled.
* \return a font to be used for given text and params. You need to release the returned font by
* ASystemFont_close when it is no longer needed.
*/
AFont* _Nonnull AFontMatcher_match(
const AFontMatcher* _Nonnull matcher,
const char* _Nonnull familyName,
const uint16_t* _Nonnull text,
const uint32_t textLength,
uint32_t* _Nullable runLengthOut) __INTRODUCED_IN(29);
#endif // __ANDROID_API__ >= 29
__END_DECLS
#endif // ANDROID_FONT_MATCHER_H
/** @} */