Registering and Using Custom Fonts (C/C++)

Overview

Custom fonts are fonts created or selected by developers based on application requirements. They are usually used to implement specific text styles or fulfill distinct design goals. To render specific text styles and characters, applications can register and use custom fonts.

Workflow

Registering custom fonts is to register font files (such as .ttf and .otf files) from application resources to the system so that applications can use these fonts for text rendering. The registration process is to register font files with the system font library through the font management API so that the font files can be called in the application.

Using custom fonts is to explicitly specify registered custom fonts for text drawing in an application. You can select a specific text style (such as regular, bold, and italic) as required and apply it to UI elements, text controls, or other text display areas to meet design requirements and provide consistent visual effect.

Available APIs

The following table lists the APIs for registering and using custom fonts. For details, see Drawing.

API	Description
OH_Drawing_CreateSharedFontCollection (void)	Creates an OH_Drawing_FontCollection object that is shareable.
OH_Drawing_RegisterFont (OH_Drawing_FontCollection* , const char* fontFamily, const char* familySrc )	Registers a custom font with the font manager. The supported font file formats are .ttf and .otf.
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.
OH_Drawing_UnregisterFont (OH_Drawing_FontCollection* , const char* fontFamily)	Unregisters a custom font by font family name.

How to Develop

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>

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();
```

Set the font family name and sandbox path of the custom font file.

NOTE

Ensure that the available custom font file to be registered is correctly placed in the /system/fonts/NotoSerifTamil[wdth,wght].ttf directory of the application device.

// The font family name is required when the custom font is used.
const char* fontFamily = "myFamilyName"; 
// 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.
const char* fontPath = "/system/fonts/NotoSerifTamil[wdth,wght].ttf";

Register the custom font with the font manager by calling OH_Drawing_RegisterFont().

You can check the return result of the API to determine whether the registration is successful.

The return results of OH_Drawing_RegisterFont are as follows:

0: The registration is successful. 1: The file does not exist. 2: Failed to open the file. 3: Failed to read the file. 4: Failed to find the file. 5: Failed to obtain the file size. 9: The file is damaged.
```
// 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);
```

After the custom font is successfully registered, call OH_Drawing_CreateTextStyle() to create a text style object and call OH_Drawing_SetTextStyleFontFamilies() to add the custom font.

// If the custom font has been successfully registered, enter the font family name of the custom font.
const char* myFontFamilies[] = {"myFamilyName"}; 
// Add the available custom font.
OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies);

Generate the final paragraph to implement text drawing and display using the custom font.

// Set other text styles.
OH_Drawing_SetTextStyleColor(textStyle , OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
// Set the font size to 60.0.
OH_Drawing_SetTextStyleFontSize(textStyle, 60.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, this 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 (0,100).
OH_Drawing_TypographyPaint(typography, cCanvas_, 0, 100);

To release a custom font, call the OH_Drawing_UnregisterFont API.

// Unregister the custom font.
OH_Drawing_UnregisterFont(fontCollection, fontFamily);
OH_Drawing_TypographyCreate* handler1 = OH_Drawing_CreateTypographyHandler(typographyStyle, fontCollection);
// Set the text style in the paragraph generator.
OH_Drawing_TypographyHandlerPushTextStyle(handler1, textStyle);
// Set the text content in the paragraph generator.
const char* text1 = "Hello, the custom font of this text is unregistered.";
OH_Drawing_TypographyHandlerAddText(handler1, text1);
// Generate a paragraph using the paragraph generator.
OH_Drawing_Typography* typography1 = OH_Drawing_CreateTypography(handler1);
OH_Drawing_TypographyLayout(typography1, maxWidth);
// Draw the text on the canvas (0, 300).
OH_Drawing_TypographyPaint(typography1, cCanvas_, 0, 300);