Text

The text widget is the basic widget used to display text, which can be used to output text in different fonts, different colors, and different sizes to the screen. In order to draw text, the font file can be a standard .ttf file or a customized .bin file.

Features

Text widgets can support the following features.

UTF-8/UTF16/UTF-32 support
Multi language support
Text typesetting support
Word wrap and texts scrolling
Anti-aliasing
Multi fonts support
Multi font sizes support
Thirty-two bit true color support
Emoji support
Custom animation effects support
Supports bitmap fonts and vector fonts
Self-developed font files support

Note

Multilingual support covers standard Latin character languages (such as English, French), major Asian languages (such as Chinese, Japanese, Korean), and languages requiring complex character rendering (such as Arabic, Persian, Thai, etc., including transformed, combined, or modified character texts).

Note

Only certain chips support vector fonts.

Usage

Using functions to load font files and display text.

Font Files

To render text, font files containing font information need to be loaded into the system.

Font files can be generated using the Realtek font converter, and there are two types: bitmap fonts and vector fonts. Font files can be pre-initialized, allowing the font to be automatically retrieved by the control's font size for rendering, or unique fonts can be set individually for text controls.

To initialize custom bin font files, you need to choose to call either gui_font_mem_init_mem() or gui_font_mem_init_ftl() based on the system's file reading method.

Set Text Attributes

Set Text

To add some texts or characters to a text widget and set text attributes with gui_text_set().

Note

The text length must be less than or equal to the set character length. For bitmap fonts, the text font size must match the size of the loaded font file; for vector fonts, the font size can be set dynamically.

Font Type

The text widget supports font type setting. Developers can call gui_text_type_set() to set the font source. You can set the address of font files and specify the font source mode.

Text Content

This interface can be used to set the content that needs to be displayed by the text widget gui_text_content_set().

Text Encoding

The text widget supports input formats in UTF-8, UTF-16, and UTF-32 encodings simultaneously. Developers can use gui_text_encoding_set() to change the encoding format.

Convert to Img

By using this function gui_text_convert_to_img(), the text in the text widget will be converted into an image, stored in memory, and rendered using the image. It also supports image transformations such as scaling and rotation. This only applies to bitmap fonts.

Note

Because the content and font size information of the text widget is needed, it should be called after set text. If the content, font size, position, and other attributes of the text have been modified, you need to reuse this interface for conversion.

Text Color

Developers can use the function gui_text_color_set() to set the text color.

Font Size

Developers can use the function gui_text_size_set() to set the font size. For vector fonts using FreeType, width and height can be set separately; for bitmap fonts, only the height parameter is effective as the font size.

Word Wrap

Developers can use the function gui_text_wordwrap_set() to enable or disable automatic word wrapping for English words.

Letter and Line Spacing

Developers can use the function gui_text_extra_letter_spacing_set() to set extra letter spacing, and gui_text_extra_line_spacing_set() to set extra line spacing.

Matrix Transformation

Developers can use the function gui_text_set_matrix() to set a transformation matrix for the text widget, enabling effects like rotation and scaling. Using gui_text_use_matrix_by_img() enables image-based matrix rendering, suitable for complex transformations.

Minimum Scale

Developers can use the function gui_text_set_min_scale() to set the minimum scale ratio for text.

Font Render Mode

For vector fonts, developers can use the function gui_text_rendermode_set() to set the rasterization render mode (1/2/4/8).

Font Source Mode

Developers can use the function gui_text_font_mode_set() to set the font source mode, such as loading fonts from memory address, FTL, or file system.

Bold Setting

Developers can use the function gui_text_bold_set() to set the bold weight and bold mode for text. Bold weight ranges from 0 (normal) to 8 (boldest), and bold mode supports horizontal bold (fast) and omnidirectional bold.

Note

Bold functionality is only effective for TTF vector fonts; bitmap fonts do not support this setting.

Emoji

Developers can use the function gui_text_emoji_set() to set the path and size of emoji image files. Requires use with a file system.

Text Modes

The text control currently supports 30 types of layout modes, including the following categories:

Single-line layout modes (3 types): Suitable for scenarios displaying only one line of text, such as single-line centered, left-aligned, right-aligned, etc.

Multi-line layout modes (3 types): Used for displaying multiple lines of text, supporting various arrangements like multi-line centered, multi-line left-aligned, multi-line right-aligned, etc.

Single-line middle layout modes (3 types): Single-line text vertically centered, supporting left-aligned, centered, and right-aligned.

Multi-line middle layout modes (3 types): Multi-line text vertically centered, supporting left-aligned, centered, and right-aligned.

Scrolling layout modes (6 types): Ideal for displaying content that exceeds the display area by scrolling, including horizontal scrolling (top and middle) and vertical scrolling.

Vertical layout modes (6 types): Supports vertical text display from top to bottom, and can also be used as a general layout method for rotated text, including top alignment, middle alignment, and bottom alignment.

RTL (right-to-left) layout modes (6 types): Designed for languages written from right to left, such as Arabic and Hebrew, supporting corresponding layout modes.

Each layout mode can be selected based on the actual application scenario to meet diverse text display needs. Use gui_text_mode_set() to set the text layout mode.

All type setting modes are as follows.

Text Mode
Type	Line Type	X Direction	Y Direction	Widget
LEFT	Single-line	Left	Top	Text widget (Default)
CENTER	Single-line	Center	Top	Text widget
RIGHT	Single-line	Right	Top	Text widget
MULTI_LEFT	Multi-line	Left	Top	Text widget
MULTI_CENTER	Multi-line	Center	Top	Text widget
MULTI_RIGHT	Multi-line	Right	Top	Text widget
MID_LEFT	Single-line	Left	Mid	Text widget
MID_CENTER	Single-line	Center	Mid	Text widget
MID_RIGHT	Single-line	Right	Mid	Text widget
MULTI_MID_LEFT	Multi-line	Left	Mid	Text widget
MULTI_MID_CENTER	Multi-line	Center	Mid	Text widget
MULTI_MID_RIGHT	Multi-line	Right	Mid	Text widget
SCROLL_X	Single-line	Right to Left	Top	Scroll text widget
SCROLL_X_REVERSE	Single-line	Left to Right	Top	Scroll text widget
SCROLL_X_MID	Single-line	Right to Left	Mid	Scroll text widget
SCROLL_X_MID_REVERSE	Single-line	Left to Right	Mid	Scroll text widget
SCROLL_Y	Multi-line	Left	Bottom to Top	Scroll text widget
SCROLL_Y_REVERSE	Multi-line	Right	Top to Bottom	Scroll text widget
VERTICAL_LEFT_TOP	Multi-line	Left	Top to Bottom, top aligned	Text widget
VERTICAL_LEFT_MID	Multi-line	Left	Top to Bottom, middle aligned	Text widget
VERTICAL_LEFT_BOT	Multi-line	Left	Top to Bottom, bottom aligned	Text widget
VERTICAL_RIGHT_TOP	Multi-line	Right	Bottom to Top, top aligned	Text widget
VERTICAL_RIGHT_MID	Multi-line	Right	Bottom to Top, middle aligned	Text widget
VERTICAL_RIGHT_BOT	Multi-line	Right	Bottom to Top, bottom aligned	Text widget
RTL_RIGHT	Multi-line	Right	Top	Text widget
RTL_CENTER	Multi-line	Center	Top	Text widget
RTL_LEFT	Multi-line	Left	Top	Text widget
RTL_MULTI_RIGHT	Multi-line	Right	Top	Text widget
RTL_MULTI_CENTER	Multi-line	Center	Top	Text widget
RTL_MULTI_LEFT	Multi-line	Left	Top	Text widget

typedef enum
{
    /* TOP */
    LEFT                 = 0x00,
    CENTER               = 0x01,
    RIGHT                = 0x02,
    MULTI_LEFT           = 0x03,
    MULTI_CENTER         = 0x04,
    MULTI_RIGHT          = 0x05,
    /* MID */
    MID_LEFT             = 0x10,
    MID_CENTER           = 0x11,
    MID_RIGHT            = 0x12,
    MULTI_MID_LEFT       = 0x13,
    MULTI_MID_CENTER     = 0x14,
    MULTI_MID_RIGHT      = 0x15,
    /* SCROLL */
    SCROLL_X             = 0x30,
    SCROLL_X_REVERSE     = 0x31,
    SCROLL_X_MID         = 0X32,
    SCROLL_X_MID_REVERSE = 0x33,

    SCROLL_Y             = 0x38,
    SCROLL_Y_REVERSE     = 0x39,
    /* VERTICAL LEFT
    &  CLOCKWISE*/
    VERTICAL_LEFT_TOP    = 0x40,
    VERTICAL_LEFT_MID    = 0x41,
    VERTICAL_LEFT_BOT    = 0x42,
    /* VERTICAL RIGHT
    &  COUNTERCLOCKWISE*/
    VERTICAL_RIGHT_TOP   = 0x50,
    VERTICAL_RIGHT_MID   = 0x51,
    VERTICAL_RIGHT_BOT   = 0x52,
    /* RTL */
    RTL_RIGHT            = 0x60,
    RTL_CENTER           = 0x61,
    RTL_LEFT             = 0x62,
    RTL_MULTI_RIGHT      = 0x63,
    RTL_MULTI_CENTER     = 0x64,
    RTL_MULTI_LEFT       = 0x65,
} TEXT_MODE;

Text Move

It is possible to use this function gui_text_move() to move text to a specified location.

Text Layout Measurement

Developers can call gui_text_layout_measure() to obtain text layout information before rendering. This function triggers the full font loading and layout pipeline, writing results back to the following widget fields:

char_width_sum: Total pixel width of text content (single-line width or sum of all character widths in multi-line mode)
char_height_sum: Total pixel height of all laid-out lines
char_line_sum: Number of lines after layout
active_font_len: Number of characters visible within the bounding box
font_len: Total character count (including clipped ones)

This function supports all font types (BMP/TTF/STB/MAT) and all layout modes, correctly handling word wrap, word break protection, letter spacing, line spacing, and complex text shaping for Arabic, Thai, Hebrew, etc.

Note

Must be called after setting text content and font attributes (e.g., gui_text_set, gui_text_mode_set, etc.).

Scope Clipping

Developers can use the function gui_text_set_scope() to set a clip scope on the text widget. Only the portion of text inside the scope rectangle will be drawn. The coordinates are relative to the text widget's own top-left corner.

Additionally, gui_text_set_scope_absolute() can be used to set the clip scope using absolute screen coordinates.

Example

The text widget provides multiple examples and test cases located in example/widget/text/. Enable the desired test in app_init of example_text.c.

Example List
#	Function	Description
1	`text_widget_example()`	Basic text widget with click event and timer callback
2	`scroll_text_widget_example()`	Horizontal (SCROLL_X) and vertical (SCROLL_Y) auto-scroll
3	`custom_font_rendering_demo()`	Custom font engine with user-defined load/draw/unload/destroy
4	`text_font_rendering_test()`	Swipeable views: bitmap (1/2/4/8-bit), vector, bold, matrix, img, bench
5	`text_font_layout_test()`	Swipeable views: single-line, multi-line, scroll, vertical, RTL
6	`text_multi_language_test()`	Language list with per-language rendering (AR, EN, ZH, TH, HE)
7	`text_font_scroll_function_test()`	Scroll X/Y/reverse with stop/reset/pause/resume and alignment modes
8	`text_font_scroll_loop_test()`	Scroll loop (marquee) for X/Y forward and reverse directions
9	`text_font_source_mode_test()`	3x4 grid: source (MEMADDR/FTL/FILESYS) x type (BMP/IMG/MAT/TTF)
10	`text_wordwrap_test()`	Word wrap with oversized word break protection
11	`text_measure_test()`	Layout measure: BMP/TTF single-line and multi-line metrics
12	`text_clip_test()`	Partial text display using win clip (top/bottom/right/center)
13	`text_font_typo_rendering_test()`	Typography rendering: bitmap + vector baseline/line-height (swipeable)
14	`text_font_fallback_test()`	Mixed-language fallback: CJK+EN in one string with priority chain

Simple Text Widget (Example 1: text_widget_example)

Basic text widget with click event and periodic timer callback.

void text_widget_example(void)
{
    char *text_string = "HoneyGUI";
    gui_text_t *text = gui_text_create(gui_obj_get_root(), "text", 0, 0, 0, 0);
    gui_text_set(text, text_string, GUI_FONT_SRC_BMP, APP_COLOR_WHITE, strlen(text_string), 32);
    gui_text_type_set(text, font32b2, FONT_SRC_MEMADDR);

    gui_obj_add_event_cb(text, (gui_event_cb_t)test_event_cb, GUI_EVENT_TOUCH_CLICKED, NULL);

    gui_obj_create_timer(&(text->base), 1000, true, test_timer_cb);
    gui_obj_start_timer(&(text->base));
}

API

Enums

enum TEXT_MODE

Values:

enumerator LEFT

enumerator CENTER

enumerator RIGHT

enumerator MULTI_LEFT

enumerator MULTI_CENTER

enumerator MULTI_RIGHT

enumerator MID_LEFT

enumerator MID_CENTER

enumerator MID_RIGHT

enumerator MULTI_MID_LEFT

enumerator MULTI_MID_CENTER

enumerator MULTI_MID_RIGHT

enumerator SCROLL_X

enumerator SCROLL_X_REVERSE

enumerator SCROLL_X_MID

enumerator SCROLL_X_MID_REVERSE

enumerator SCROLL_Y

enumerator SCROLL_Y_REVERSE

enumerator VERTICAL_LEFT_TOP

enumerator VERTICAL_LEFT_MID

enumerator VERTICAL_LEFT_BOT

enumerator VERTICAL_RIGHT_TOP

enumerator VERTICAL_RIGHT_MID

enumerator VERTICAL_RIGHT_BOT

enumerator RTL_RIGHT

enumerator RTL_CENTER

enumerator RTL_LEFT

enumerator RTL_MULTI_RIGHT

enumerator RTL_MULTI_CENTER

enumerator RTL_MULTI_LEFT

Functions

void gui_text_click(gui_text_t *this_widget, gui_event_cb_t event_cb, void *parameter)

Set textbox click event callback.

Parameters:

this_widget -- Text widget.
event_cb -- Callback function.
parameter -- Callback parameter.

void gui_text_pswd_done(gui_text_t *this_widget, gui_event_cb_t event_cb, void *parameter)

Set textbox password done event callback to handle password.

Parameters:

this_widget -- Text widget.
event_cb -- Callback function.
parameter -- Callback parameter.

void gui_text_set(gui_text_t *this_widget, void *text, FONT_SRC_TYPE text_type, gui_color_t color, uint16_t length, uint16_t font_size)

Set the string in a text box widget.

Note

The font size must match the font file.

Parameters:

this_widget -- Text box widget pointer.
text -- Text string.
text_type -- Text type.
color -- Text's color.
length -- Text string's length.
font_size -- Text string's font size.

void gui_text_mode_set(gui_text_t *this_widget, TEXT_MODE mode)

Set text mode of this_widget text widget.

Note

If text line count was more than one, it will display on the left even if it was set left or right.

Parameters:

this_widget -- Text widget pointer.
mode -- Text layout mode (e.g., LEFT, CENTER, RIGHT, MULTI_LEFT, SCROLL_X, VERTICAL_LEFT_TOP, RTL_RIGHT, etc.).

void gui_text_input_set(gui_text_t *this_widget, bool inputable)

Set inputable.

Parameters:

this_widget -- Text box widget pointer.
inputable -- Inputable.

void gui_text_color_set(gui_text_t *this_widget, gui_color_t color)

Set font color.

Parameters:

this_widget -- Text box widget pointer.
color -- Font color.

void gui_text_wordwrap_set(gui_text_t *this_widget, bool wordwrap)

By setting wordwrap to enable English word wrapping.

Parameters:

this_widget -- Text box widget pointer.
wordwrap -- Wordwrap.

void gui_text_extra_letter_spacing_set(gui_text_t *this_widget, int8_t extra_letter_spacing)

Set extra letter spacing.

Parameters:

this_widget -- Text box widget pointer.
extra_letter_spacing -- Extra letter spacing.

void gui_text_extra_line_spacing_set(gui_text_t *this_widget, int8_t extra_line_spacing)

Set extra line spacing.

Parameters:

this_widget -- Text box widget pointer.
extra_line_spacing -- Extra line spacing.

void gui_text_set_line_height(gui_text_t *this_widget, int16_t line_height)

Set explicit line height for multi-line layout (Figma "Line height" property).

Parameters:

this_widget -- Text box widget pointer.
line_height -- Line height in pixels. 0 = use default calculated line height.

void gui_text_use_matrix_by_img(gui_text_t *this_widget, bool use_img_blit)

Enable/disable matrix-based image rendering for text.

Parameters:

this_widget -- Pointer to the text widget.
use_img_blit -- True = Use image matrix blitting (for complex transformations), False = Use standard rendering.

void gui_text_rendermode_set(gui_text_t *this_widget, uint8_t rendermode)

Set TTF raster render mode.

Parameters:

this_widget -- Text box widget pointer.
rendermode -- Render mode. 1/2/4/8.

void gui_text_bold_set(gui_text_t *this_widget, uint8_t bold_weight, BOLD_MODE bold_mode)

Set text bold weight and mode (only effective for vector fonts).

Parameters:

this_widget -- Text box widget pointer.
bold_weight -- Bold weight. 0 = normal, 1-8 = bold levels.
bold_mode -- Bold mode: BOLD_HORIZONTAL (fast) or BOLD_FULL.

void gui_text_set_min_scale(gui_text_t *this_widget, float min_scale)

Set text minimum scale.

Parameters:

this_widget -- Text box widget pointer.
min_scale -- Minimum scale.

void gui_text_move(gui_text_t *this_widget, int16_t x, int16_t y)

Move the text widget.

Parameters:

this_widget -- Text box widget pointer.
x -- X-axis coordinate of the text box.
y -- Y-axis coordinate of the text box.

void gui_text_size_set(gui_text_t *this_widget, uint16_t height, uint16_t width)

Set font size or width and height.

Note

If using FreeType, width and height are effective; otherwise, height will be applied as font size.

Parameters:

this_widget -- Text widget pointer.
height -- Font height or font size.
width -- Font width (only effective when FreeType is used).

void gui_text_font_mode_set(gui_text_t *this_widget, FONT_SRC_MODE font_mode)

Set text font mode.

Parameters:

this_widget -- Text widget pointer.
font_mode -- Font source mode.

void gui_text_type_set(gui_text_t *this_widget, void *font_source, FONT_SRC_MODE font_mode)

Set font type.

Note

The type must match the font size.

Parameters:

this_widget -- Text widget pointer.
font_source -- Address of .ttf or .bin.
font_mode -- Font source mode.

void gui_text_emoji_set(gui_text_t *this_widget, uint8_t *path, uint8_t size)

Set emoji file path and emoji size.

Note

Requires ROMFS.

Note

Example of a full emoji image file path: 'font/emoji/emoji_u1f30d.bin'.

Parameters:

this_widget -- Text widget pointer.
path -- Path containing folder path and file name prefix. Path example: 'font/emoji/emoji_u'. Folder path is the emoji image file folder path, e.g., 'font/emoji/'. File name prefix is the prefix before the filename for Unicode sorting, e.g., 'emoji_u'.
size -- Emoji image file size, e.g., 32.

void gui_text_encoding_set(gui_text_t *this_widget, TEXT_CHARSET charset)

Set font encoding.

Note

UTF-8 or Unicode.

Parameters:

this_widget -- Text widget pointer.
charset -- Encoding type.

void gui_text_set_matrix(gui_text_t *this_widget, gui_matrix_t *matrix)

Set text matrix.

Note

Parameters:

this_widget -- Text widget pointer.
matrix -- Matrix pointer.

void gui_text_content_set(gui_text_t *this_widget, void *text, uint16_t length)

Set text content.

Parameters:

this_widget -- Text widget pointer.
text -- Text string.
length -- Text string's length.

void gui_text_convert_to_img(gui_text_t *this_widget, GUI_FormatType font_img_type)

Draw text by image so that text can be scaled.

Parameters:

this_widget -- Text widget pointer.
font_img_type -- Color format.

gui_text_t *gui_text_create(void *parent, const char *name, int16_t x, int16_t y, int16_t w, int16_t h)

Create a text box widget.

Note

The area of the text box should be larger than that of the string to be shown; otherwise, part of the text will be hidden.

Parameters:

parent -- Parent widget in which the text is nested.
name -- Widget's name.
x -- X-axis coordinate of the text box.
y -- Y-axis coordinate of the text box.
w -- Width of the text box.
h -- Height of the text box.

Returns:

Widget object pointer.

void gui_text_layout_measure(gui_text_t *this_widget)

Perform text layout measurement without rendering.

Triggers the full font loading and layout pipeline using the widget's current properties, then writes results back to the widget's fields: char_width_sum, char_height_sum, char_line_sum, active_font_len, font_len.

Can be called right after gui_text_set() / gui_text_mode_set() etc., before any draw cycle.

Parameters:: this_widget -- Text widget pointer (must have content and font set).

void gui_text_set_scope(gui_text_t *this_widget, int16_t x, int16_t y, int16_t w, int16_t h)

Set a clip scope on the text widget (relative to text position).

Only the portion of text inside the scope rectangle will be drawn. Coordinates are relative to the text widget's own top-left corner.

Parameters:

this_widget -- Text widget pointer.
x -- X offset of the visible area relative to text.
y -- Y offset of the visible area relative to text.
w -- Width of the visible area.
h -- Height of the visible area.

void gui_text_set_scope_absolute(gui_text_t *this_widget, int16_t x, int16_t y, int16_t w, int16_t h)

Set an absolute clip scope on the text widget (screen coordinates).

Parameters:

this_widget -- Text widget pointer.
x -- X coordinate on screen.
y -- Y coordinate on screen.
w -- Width of the visible area.
h -- Height of the visible area.

void gui_text_set_font_blend_mode(gui_text_t *this_widget, BLEND_MODE_TYPE blend_mode)

Set font blend mode for text rendering.

Parameters:

this_widget -- Text widget pointer.
blend_mode -- Blend mode (e.g., IMG_PLUS_DARKER for darken blend).

gui_inline bool gui_text_rect_hit (gui_text_rect_t *a, gui_rect_t *b)

gui_inline bool gui_text_scope_rect_hit (gui_text_rect_t *a, gui_rect_t *b)

struct gui_text_t

Text widget structure.

Public Members

gui_obj_t base

gui_color_t color

gui_img_t *scale_img

uint8_t *emoji_path

float min_scale

void *content

void *data

void *path

gui_matrix_t *matrix

uint16_t len

uint16_t font_len

uint16_t active_font_len

int16_t char_width_sum

int16_t char_height_sum

int16_t char_line_sum

int16_t offset_x

int16_t offset_y

uint16_t font_height

gui_rect_t scope_rect: self scope clip area (relative to text)

TEXT_MODE mode

TEXT_CHARSET charset

FONT_SRC_TYPE font_type

FONT_SRC_MODE font_mode

BLEND_MODE_TYPE font_blend_mode: blend mode for font rendering

uint8_t emoji_size

uint8_t checksum

int8_t extra_letter_spacing

int8_t extra_line_spacing

int16_t line_height: explicit line height (0 = use default)

uint8_t bold_weight

bool layout_refresh

bool content_refresh

bool use_img_blit

bool inputable

bool ispasswd

bool wordwrap

bool scope

bool scope_self: scope set by gui_text_set_scope

bool scope_absolute: 0=relative to text, 1=absolute screen coords

bool arabic

bool thai

bool hebrew

uint8_t rendermode

uint8_t bold_mode: 0=BOLD_HORIZONTAL (fast), 1=BOLD_FULL

struct gui_text_line_t

Text line structure.

Public Members

int16_t index

int16_t offset

Text

Features

Usage

Font Files

Create Text Widget

Set Text Attributes

Set Text

Font Type

Text Content

Text Encoding

Convert to Img

Text Color

Font Size

Word Wrap

Letter and Line Spacing

Matrix Transformation

Minimum Scale

Font Render Mode

Font Source Mode

Bold Setting

Emoji

Text Modes

Text Move

Text Layout Measurement

Scope Clipping

Example

Simple Text Widget (Example 1: text_widget_example)

API