Obtaining and Using System Fonts (C/C++)

Overview

System fonts are built-in fonts of the operating system. They show text when no other font is chosen, maintaining clear and uniform text presentation. The default system font is "HarmonyOS Sans".

System fonts can be enabled when an application does not register custom fonts or does not explicitly specify the text style. There are multiple system fonts. You can obtain the configuration information about system fonts and switch and use system fonts based on the font family name in the information.

System fonts can be disabled when you want to ensure that only custom fonts are used in your application, without being affected by the default fonts of the operating system. If the system font is enabled when there is no custom font, the system uses the default font. You can disable system fonts to ensure that the text rendering conforms to the design expectation and the visual style of the application is consistent.

Available APIs

The following table lists the common APIs and structs related to system fonts. For details about the APIs, see Drawing.

Name	Description
OH_Drawing_FontConfigInfo* OH_Drawing_GetSystemFontConfigInfo(OH_Drawing_FontConfigInfoErrorCode*)	Obtains the configuration about system fonts and returns the OH_Drawing_FontConfigInfo struct.
void OH_Drawing_DestroySystemFontConfigInfo(OH_Drawing_FontConfigInfo*)	Reclaims the memory occupied by the system font configuration.
OH_Drawing_FontCollection* OH_Drawing_CreateSharedFontCollection(void)	Creates an OH_Drawing_FontCollection object that is shareable.
OH_Drawing_TextStyle* OH_Drawing_CreateTextStyle(void)	Creates a pointer to an OH_Drawing_TextStyle object to set the text style.
OH_Drawing_SetTextStyleFontFamilies (OH_Drawing_TextStyle , int, const char fontFamilies[])	Sets the font families for a text style.
void OH_Drawing_DisableFontCollectionSystemFont(OH_Drawing_FontCollection* fontCollection)	Disables the system fonts.

Struct	Description
OH_Drawing_FontConfigInfo	Describes the information about a system font configuration.
OH_Drawing_FontGenericInfo	Describes the information about generic fonts supported by the system.
OH_Drawing_FontFallbackGroup	Describes the information about a font fallback group.

Obtaining System Font Information

Add the following library to the src/main/cpp/CMakeLists.txt file of the project.
```
libnative_drawing.so
```

Import the required header files.

#include <native_drawing/drawing_font_collection.h>
#include <native_drawing/drawing_text_typography.h>
#include <native_drawing/drawing_register_font.h>
#include <hilog/log.h>

Obtain the system font configuration. Check whether your attempt is successful according to the result code. For details, see OH_Drawing_FontConfigInfoErrorCode.

OH_Drawing_FontConfigInfoErrorCode fontConfigInfoErrorCode;  // Used to receive the error code.
OH_Drawing_FontConfigInfo* fontConfigInfo = OH_Drawing_GetSystemFontConfigInfo(&fontConfigInfoErrorCode);
if(fontConfigInfoErrorCode != SUCCESS_FONT_CONFIG_INFO) {
    OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_DOMAIN, "PrintSysFontMetrics", "Failed to obtain the system information. The error code is %{public}d", fontConfigInfoErrorCode);
}

sample_bitmap.cpp

Obtain the following information from OH_Drawing_FontConfigInfo:

Number of system font file paths.
Number of generic font sets.
Number of font fallbacks.
Double pointer to the system font file paths.
List of generic font sets. For details, see OH_Drawing_FontGenericInfo.
List of font fallbacks. For details, see OH_Drawing_FontFallbackGroup.

The following example shows how to obtain certain configuration information about system fonts:

// Obtaining system font configuration
if (fontConfigInfo != nullptr) {
    // Obtain the number of font file paths and print logs.
    size_t fontDirCount = fontConfigInfo->fontDirSize;
    OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "PrintSysFontMetrics", "Font file path count: %{public}zu\n", fontDirCount);
    // Iterate through the font file path list and print logs.
    for (size_t i = 0; i < fontDirCount; ++i) {
        OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "PrintSysFontMetrics", "Font file path: %{public}s\n",
                     fontConfigInfo->fontDirSet[i]);
    }
    // Obtain the number of generic font sets and print logs.
    size_t genericCount = fontConfigInfo->fontGenericInfoSize;
    OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "PrintSysFontMetrics", "Generic font set count: %{public}zu\n", genericCount);
    // Obtain the font family name (for example, HarmonyOS Sans) in each generic font set and print logs.
    for (size_t i = 0; i < genericCount; ++i) {
        OH_Drawing_FontGenericInfo &genericInfo = fontConfigInfo->fontGenericInfoSet[i];
        OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "PrintSysFontMetrics",
                     "Obtain the font family name %{public}s", i, genericInfo.familyName in the No.%{public}zu generic font set);
    }
}

sample_bitmap.cpp

The following figure shows some system font configuration information of the application device system. The configuration information varies according to devices.

Release the memory occupied by the configuration information if it is no longer needed.
```
OH_Drawing_DestroySystemFontConfigInfo(fontConfigInfo);
```

Using or Switching System Fonts

There are multiple system fonts. You can obtain the configuration information about system fonts and switch and use system fonts based on the font family name.

If no font is specified, the default system font "HarmonyOS Sans" is used to display text.

Add the following library to the src/main/cpp/CMakeLists.txt file of the project.
```
libnative_drawing.so
```

Import the required header files.

#include <native_drawing/drawing_font_collection.h>
#include <native_drawing/drawing_text_typography.h>
#include <native_drawing/drawing_register_font.h>
#include <hilog/log.h>

Create a font manager. You are advised to use OH_Drawing_CreateSharedFontCollection to create a sharable font set object.

NOTE

OH_Drawing_CreateFontCollection and OH_Drawing_CreateSharedFontCollection both create an OH_Drawing_FontCollection object. However, OH_Drawing_CreateFontCollection creates font set pointers that cannot be shared across OH_Drawing_TypographyCreate objects. Therefore, you are advised to use OH_Drawing_CreateSharedFontCollection to create a sharable font set object.
```
OH_Drawing_FontCollection *fontCollection = OH_Drawing_CreateSharedFontCollection();
```
sample_bitmap.cpp
Create an OH_Drawing_TextStyle object to set the text style.
```
OH_Drawing_TextStyle *textStyle = OH_Drawing_CreateTextStyle();
```
sample_bitmap.cpp

Obtaining system font information: Obtain the font family name and set the system font in the text style.

// Case 1: Set the system font to "HarmonyOS Sans Condensed".
const char *myFontFamilies[] = {"HarmonyOS Sans Condensed"};
OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies);

// Case 2: Use the default system font "HarmonyOS Sans".
// const char* myFontFamilies[] = {"HarmonyOS Sans Condensed"};
// OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies);

sample_bitmap.cpp

Generate the final paragraph to implement text drawing and display.

// Set other text styles.
OH_Drawing_SetTextStyleColor(textStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
// Set the font size to 70.0.
OH_Drawing_SetTextStyleFontSize(textStyle, 70.0);
// Create a paragraph style object to set the typography style.
OH_Drawing_TypographyStyle *typographyStyle = OH_Drawing_CreateTypographyStyle();
OH_Drawing_SetTypographyTextAlign(typographyStyle, TEXT_ALIGN_LEFT); // Set the typography to left alignment.
// Create a paragraph generator.
OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typographyStyle, fontCollection);
// Set the text style in the paragraph generator.
OH_Drawing_TypographyHandlerPushTextStyle(handler, textStyle);
// Set the text content in the paragraph generator.
const char *text = "Hello World. \nThe preceding text uses the system font.";
OH_Drawing_TypographyHandlerAddText(handler, text);
// Generate a paragraph using the paragraph generator.
OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
// Set the maximum width.
double maxWidth = width_;
OH_Drawing_TypographyLayout(typography, maxWidth);
// Draw the text on the canvas (0,height_/2.0).
OH_Drawing_TypographyPaint(typography, cCanvas_, 0, height_ / 2.0);

sample_bitmap.cpp

Disabling System Fonts

If the system font is enabled when there is no custom font, the system uses the default font. You can disable system fonts to ensure that the text rendering conforms to the design expectation and the visual style of the application is consistent.

In some use cases, you may want to use only custom fonts to ensure font consistency or provide a more personalized user experience. In this case, you can disable the system fonts.

NOTE

After disabling the system fonts, ensure that the custom font is registered. Otherwise, the text cannot be properly displayed.

Register a custom font. For details, see Registering and Using Custom Fonts.
Add the following library to the src/main/cpp/CMakeLists.txt file of the project.
```
libnative_drawing.so
```

Import the required header files.

#include <native_drawing/drawing_font_collection.h>
#include <native_drawing/drawing_text_typography.h>
#include <native_drawing/drawing_register_font.h>
#include <hilog/log.h>

Create a font manager. You are advised to use OH_Drawing_CreateSharedFontCollection to create a sharable font set object.
```
OH_Drawing_FontCollection *fontCollection = OH_Drawing_CreateSharedFontCollection();
```
sample_bitmap.cpp

Disable the system fonts.

OH_Drawing_DisableFontCollectionSystemFont(fontCollection);

sample_bitmap.cpp

Create a text style object and use the registered custom font.

NOTE

If no font is set, the system font is used by default. If the system font is disabled and no custom font is set, the text cannot be displayed properly.

OH_Drawing_TextStyle *textStyle = OH_Drawing_CreateTextStyle();
// Possible cases when the system fonts are disabled:
// Case 1: If the custom font is used, the text is displayed properly.
// This path is the path of the custom font file to be registered on the application device. Ensure that the custom font file is properly placed in this path.
// The font family name is required when the custom font is used.
const char* fontFamily = "HarmonyOS_Sans"; 
const char* fontPath = "/system/fonts/HarmonyOS_Sans.ttf"; 
// Returns **0** if the font is registered; returns **1** if the file does not exist; returns **2** if opening the file fails; returns **3** if reading the file fails; returns **4** if the file is not found; returns **5** if the file size is not obtained; returns **9** if the file is damaged.
int errorCode = OH_Drawing_RegisterFont(fontCollection, fontFamily, fontPath);
DRAWING_LOGI("errorCode = %{public}d", errorCode);
const char *myFontFamilies[] = {"HarmonyOS_Sans"}; // Ensure that the custom font has been successfully registered and enter the family name of the custom font.
OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies);

// Case 2: If the system font is used, the text cannot be displayed.
// const char *myFontFamilies[] = {"HarmonyOS_Sans"};
// OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies);

// Case 3: If no font is set, the default system font is used by default. However, the system fonts have been disabled. As a result, the text cannot be displayed.
// const char *myFontFamilies[] = {"HarmonyOS_Sans"};
// OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies);

sample_bitmap.cpp

Generate the final paragraph to implement text drawing and display.

// Set other text styles.
OH_Drawing_SetTextStyleColor(textStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
// Set the font size to 30.0.
OH_Drawing_SetTextStyleFontSize(textStyle, 30.0);
// Create a paragraph style object to set the typography style.
OH_Drawing_TypographyStyle *typographyStyle = OH_Drawing_CreateTypographyStyle();
OH_Drawing_SetTypographyTextAlign(typographyStyle, TEXT_ALIGN_LEFT); // Set the typography to left alignment.
// Create a paragraph generator.
OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typographyStyle, fontCollection);
// Set the text style in the paragraph generator.
OH_Drawing_TypographyHandlerPushTextStyle(handler, textStyle);
// Set the text content in the paragraph generator.
const char *text = "Hello World.\nThe preceding text uses the custom font.";
OH_Drawing_TypographyHandlerAddText(handler, text);
// Generate a paragraph using the paragraph generator.
OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    
// Set the maximum width.
double maxWidth = width_;
OH_Drawing_TypographyLayout(typography, maxWidth);
// Draw the text on the canvas (width_/5.0,height_/2.0).
OH_Drawing_TypographyPaint(typography, cCanvas_, width_ / 5.0, height_ / 2.0);

sample_bitmap.cpp