文本 (Text)

文本控件是用于显示文本的基本控件，可用于将多样化的文本渲染到屏幕上，支持矢量字体和点阵字体两种渲染方式。

特性

文本控件能支持下面的特性。

支持 UTF-8 / UTF16 / UTF-32
支持多语言
支持文本排版
自动换行和文本滚动
抗锯齿
支持多种字体
支持多种字号
支持 32 位真彩色
支持 Emoji
支持自定义动画效果
支持点阵字体和矢量字体
支持自行开发的字体文件

备注

多语言支持覆盖标准拉丁字符语言（如英文、法语），亚洲主要语言（如中文、日文、韩文），以及需要复杂字符渲染的语言（如阿拉伯语、波斯语、泰语等，包含变形、组合或者修饰字符文本）。

备注

只有部分芯片支持矢量字体。

用法

调用对应的函数加载字体文件并显示文本。

字体文件

为了绘制文本，包含字体信息的字体文件需要加载到系统中。

字体文件可以通过 Realtek 字体转换器生成，有点阵字体和矢量字体两种类型。字体文件可以提前初始化，由控件字号自动检索字体进行渲染，也可以单独为文本控件设置独特的字体。

初始化自定义bin字体文件，需要根据系统的文件读取方式选择调用 gui_font_mem_init_mem() 或者 gui_font_mem_init_ftl() 。

创建文本控件

开发者可以调用 gui_text_create() 来创建文本控件。创建后，控件的坐标和文本框的大小已经确定。这些属性也可以随时修改。

备注

文本控件的大小应大于要显示的字符串，超出范围的文本将被隐藏。

设置文本属性

设置文本

开发者可以调用 gui_text_set() 来设置文本控件文本、文本类型、颜色、长度和文本字体大小。

备注

文本长度必须小于等于设置的字符长度。对于点阵字体，文本字体大小必须与加载的字体文件的大小相同；对于矢量字体，可以动态设置字体大小。

字体类型

文本控件支持字体类型设置。开发者可以调用 gui_text_type_set() 来设置字体源。可以设置字体文件的地址，并指定字体源模式。

文本内容

开发者可以调用 gui_text_content_set() 来设置文本控件需要显示的内容。

文本编码

文本控件同时支持 UTF-8 编码、UTF-16 编码和 UTF-32 编码输入格式，开发者可以使用 gui_text_encoding_set() 更改编码方式。

文本转换为图片

使用 gui_text_convert_to_img() 可以将文本控件中的文本将被转换为图像，存储在内存中，并使用该图像进行呈现。它还支持图像转换，如缩放和旋转。这只适用于点阵字体。

备注

因为需要文本控件的内容和字体大小信息，所以应该在设置文本之后调用它。如果修改了文本的内容、字体大小、位置和其他属性，则需要重用此接口进行转换。

文本颜色

开发者可以使用函数 gui_text_color_set() 设置文本的颜色。

字体大小

开发者可以使用函数 gui_text_size_set() 设置字体的大小。对于使用 FreeType 的矢量字体，可以分别设置宽度和高度；对于点阵字体，仅高度参数作为字号生效。

自动换行

开发者可以使用函数 gui_text_wordwrap_set() 启用或禁用英文单词的自动换行功能。

字符间距和行间距

开发者可以使用函数 gui_text_extra_letter_spacing_set() 设置额外的字符间距，使用 gui_text_extra_line_spacing_set() 设置额外的行间距。

矩阵变换

开发者可以使用函数 gui_text_set_matrix() 为文本控件设置变换矩阵，实现旋转、缩放等效果。使用 gui_text_use_matrix_by_img() 可以启用基于图像的矩阵渲染，适用于复杂变换。

最小缩放比例

开发者可以使用函数 gui_text_set_min_scale() 设置文本的最小缩放比例。

字体渲染模式

对于 TTF 矢量字体，开发者可以使用函数 gui_text_rendermode_set() 设置光栅化渲染模式（1/2/4/8）。

字体源模式

开发者可以使用函数 gui_text_font_mode_set() 设置字体的源模式，例如从内存地址、FTL 或文件系统加载字体。

粗体设置

开发者可以使用函数 gui_text_bold_set() 设置文本的粗体权重和粗体模式。粗体权重范围为 0（正常）到 8（最粗），粗体模式支持水平加粗（快速）和全方向加粗两种方式。

备注

粗体功能仅对 TTF 矢量字体有效，点阵字体不支持此设置。

Emoji

开发者可以使用函数 gui_text_emoji_set() 设置 Emoji 图像文件的路径和大小。需要配合文件系统使用。

文本模式

文本控件当前支持30种排版模式，包括以下几类：

单行排版模式（3种）：适用于仅显示一行文本的场景，如单行居中、左对齐、右对齐等。

多行排版模式（3种）：用于显示多行文本，支持多行居中、多行左对齐、多行右对齐等多种排列方式。

单行中部排版模式（3种）：单行文本在垂直方向居中显示，支持左对齐、居中、右对齐。

多行中部排版模式（3种）：多行文本在垂直方向居中显示，支持左对齐、居中、右对齐。

滚动排版模式（6种）：适合文本超出显示区域时，以滚动方式显示内容，包括水平滚动（顶部和中部）和垂直滚动。

竖向排版模式（6种）：支持文本从上到下的竖排显示方式，也可作为旋转文本的通用排版方式，包括顶端对齐、中部对齐、底端对齐等。

从右至左（ RTL ）排版模式（6种）：针对如阿拉伯语、希伯来语等从右至左书写的语言，支持相应的排版模式。

每种排版模式都可根据实际应用场景选择，满足多样化的文本显示需求。通过 gui_text_mode_set() 来设置文本排版模式。

排版模式如下：

文本模式
类型	行类型	X 方向	Y 方向	控件
LEFT	单行	左对齐	顶部	文本控件(默认)
CENTER	单行	居中	顶部	文本控件
RIGHT	单行	右对齐	顶部	文本控件
MULTI_LEFT	多行	左对齐	顶部	文本控件
MULTI_CENTER	多行	居中	顶部	文本控件
MULTI_RIGHT	多行	右对齐	顶部	文本控件
MID_LEFT	单行	左对齐	中部	文本控件
MID_CENTER	单行	居中	中部	文本控件
MID_RIGHT	单行	右对齐	中部	文本控件
MULTI_MID_LEFT	多行	左对齐	中部	文本控件
MULTI_MID_CENTER	多行	居中	中部	文本控件
MULTI_MID_RIGHT	多行	右对齐	中部	文本控件
SCROLL_X	单行	由右向左滚动	顶部	滚动文本控件
SCROLL_X_REVERSE	单行	由左向右滚动	顶部	滚动文本控件
SCROLL_X_MID	单行	由右向左滚动	中部	滚动文本控件
SCROLL_X_MID_REVERSE	单行	由左向右滚动	中部	滚动文本控件
SCROLL_Y	多行	左对齐	由下向上滚动	滚动文本控件
SCROLL_Y_REVERSE	多行	右对齐	由上向下滚动	滚动文本控件
VERTICAL_LEFT_TOP	多行	左对齐	由上向下，顶端对齐	文本控件
VERTICAL_LEFT_MID	多行	左对齐	由上向下，中部对齐	文本控件
VERTICAL_LEFT_BOT	多行	左对齐	由上向下，底端对齐	文本控件
VERTICAL_RIGHT_TOP	多行	右对齐	由下向上，顶端对齐	文本控件
VERTICAL_RIGHT_MID	多行	右对齐	由下向上，中部对齐	文本控件
VERTICAL_RIGHT_BOT	多行	右对齐	由下向上，底端对齐	文本控件
RTL_RIGHT	多行	右对齐	顶部	文本控件
RTL_CENTER	多行	居中	顶部	文本控件
RTL_LEFT	多行	左对齐	顶部	文本控件
RTL_MULTI_RIGHT	多行	右对齐	顶部	文本控件
RTL_MULTI_CENTER	多行	居中	顶部	文本控件
RTL_MULTI_LEFT	多行	左对齐	顶部	文本控件

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;

文本移动

开发者可以调用函数 gui_text_move() 将文本控件移动到指定位置。

文本排版测量

开发者可以调用 gui_text_layout_measure() 在渲染之前获取文本的排版信息。该函数会触发完整的字体加载和排版流程，将结果写入控件的以下字段：

char_width_sum ：文本内容的像素总宽度（单行模式为文本宽度，多行模式为所有字符宽度之和）
char_height_sum ：排版后所有行的像素总高度
char_line_sum ：排版后的行数
active_font_len ：在文本框范围内可见的字符数
font_len ：总字符数（包括被裁剪的）

该函数支持所有字体类型（BMP/TTF/STB/MAT）和所有排版模式，并且正确处理自动换行、断词保护、字符间距、行间距以及阿拉伯语、泰语、希伯来语等复杂文本的排版。

备注

必须在设置文本内容和字体属性（如 gui_text_set 、 gui_text_mode_set 等）之后调用。

裁剪区域

开发者可以使用函数 gui_text_set_scope() 为文本控件设置裁剪区域。只有裁剪矩形内的文本部分会被绘制，坐标相对于文本控件自身的左上角。

此外，可以使用 gui_text_set_scope_absolute() 以屏幕绝对坐标设置裁剪区域。

示例

文本控件提供了多个示例和测试用例，位于 example/widget/text/ 目录下，在 example_text.c 的 app_init 中选择启用。

示例列表
#	函数	说明
1	`text_widget_example()`	基础文本控件，包含点击事件和定时器回调
2	`scroll_text_widget_example()`	水平（SCROLL_X）和垂直（SCROLL_Y）自动滚动文本
3	`custom_font_rendering_demo()`	自定义字体引擎，用户自定义加载/绘制/卸载/销毁
4	`text_font_rendering_test()`	滑动视图：点阵（1/2/4/8位）、矢量、粗体、矩阵、图片、性能
5	`text_font_layout_test()`	滑动视图：单行、多行、滚动、竖排、RTL 排版模式
6	`text_multi_language_test()`	多语言列表渲染（阿拉伯语、英语、中文、泰语、希伯来语）
7	`text_font_scroll_function_test()`	滚动 X/Y/反向控制：停止/重置/暂停/恢复及对齐模式
8	`text_font_scroll_loop_test()`	滚动循环（跑马灯）：X/Y 正向和反向
9	`text_font_source_mode_test()`	3x4 网格：源模式（MEMADDR/FTL/FILESYS）× 类型（BMP/IMG/MAT/TTF）
10	`text_wordwrap_test()`	自动换行与超长单词断词保护
11	`text_measure_test()`	排版测量：BMP/TTF 字体的单行和多行排版信息获取
12	`text_clip_test()`	使用窗口裁剪实现文本局部显示（上/下/右/居中）
13	`text_font_typo_rendering_test()`	排版渲染：点阵 + 矢量基线/行高（滑动视图）
14	`text_font_fallback_test()`	混合语言回退：CJK+英文混排，优先级链

简单文本控件（示例 1：text_widget_example）

基础文本控件示例，包含点击事件和定时器回调。

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.

参数:

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.

参数:

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.

备注

The font size must match the font file.

参数:

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.

备注

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

参数:

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.

参数:

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.

参数:

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.

参数:

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.

参数:

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.

参数:

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).

参数:

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.

参数:

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.

参数:

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).

参数:

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.

参数:

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.

参数:

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.

备注

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

参数:

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.

参数:

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.

备注

The type must match the font size.

参数:

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.

备注

Requires ROMFS.

备注

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

参数:

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.

备注

UTF-8 or Unicode.

参数:

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.

备注

参数:

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.

参数:

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.

参数:

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.

备注

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.

参数:

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.

返回:

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.

参数:: 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.

参数:

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).

参数:

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.

参数:

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