文本 (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 图像文件的路径和大小。需要配合文件系统使用。

文本模式

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

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

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

单行中部排版模式（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	多行	右对齐	中部	文本控件
BOT_LEFT	单行	左对齐	底部	文本控件
BOT_CENTER	单行	居中	底部	文本控件
BOT_RIGHT	单行	右对齐	底部	文本控件
MULTI_BOT_LEFT	多行	左对齐	底部	文本控件
MULTI_BOT_CENTER	多行	居中	底部	文本控件
MULTI_BOT_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,
    /* BOT */
    BOT_LEFT             = 0x20,
    BOT_CENTER           = 0x21,
    BOT_RIGHT            = 0x22,
    MULTI_BOT_LEFT       = 0x23,
    MULTI_BOT_CENTER     = 0x24,
    MULTI_BOT_RIGHT      = 0x25,
    /* 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

Defines

GUI_TEXT_GRADIENT_MAX_STOPS 8

GUI_TEXT_GRADIENT_LUT_SIZE 256

GUI_TEXT_SUBSTITUTE_CHAIN_MAX 4: Maximum number of substitute code points in the chain.

Enums

enum gui_text_gradient_dir_t

Gradient direction, matching the rect widget's directions.

Values:

enumerator GUI_TEXT_GRADIENT_HORIZONTAL: Left to right.

enumerator GUI_TEXT_GRADIENT_VERTICAL: Top to bottom.

enumerator GUI_TEXT_GRADIENT_DIAGONAL_TL_BR: Top-left to bottom-right.

enumerator GUI_TEXT_GRADIENT_DIAGONAL_TR_BL: Top-right to bottom-left.

enum gui_text_gradient_box_t

Box the gradient handles are normalized against.

Values:

enumerator GUI_TEXT_GRADIENT_BOX_INK: Union of the glyph outlines.

enumerator GUI_TEXT_GRADIENT_BOX_LAYOUT: Pen advances x line boxes, like a Figma auto-size text.

enumerator GUI_TEXT_GRADIENT_BOX_WIDGET: Widget rectangle, like a Figma fixed-size text.

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 BOT_LEFT

enumerator BOT_CENTER

enumerator BOT_RIGHT

enumerator MULTI_BOT_LEFT

enumerator MULTI_BOT_CENTER

enumerator MULTI_BOT_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, BOT_LEFT, MULTI_BOT_CENTER, 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_set_space_width(gui_text_t *this_widget, uint16_t space_width)

Set the fallback space width for legacy TTF fonts.

参数:

this_widget -- Text box widget pointer.
space_width -- Space width in pixels. 0 = use the default approximation.

void gui_text_set_missing_glyph_mode_global(gui_missing_glyph_mode_t mode)

Set the global behavior for code points with no glyph anywhere.

参数:: mode -- GUI_MISSING_GLYPH_SKIP or GUI_MISSING_GLYPH_SUBSTITUTE. GUI_MISSING_GLYPH_INHERIT is ignored, it is per-widget only.

void gui_text_set_missing_glyph_mode(gui_text_t *this_widget, gui_missing_glyph_mode_t mode)

Set this widget's behavior for characters missing from every font.

Overrides the global mode set by gui_text_set_missing_glyph_mode_global().

参数:

this_widget -- Text box widget pointer.
mode -- Missing-glyph mode; INHERIT follows the global mode.

bool gui_text_substitute_enabled(const gui_text_t *text)

Whether a text widget should substitute glyphs for missing characters.

参数:: text -- Text widget, may be NULL to query the global mode.
返回:: true if substitution is enabled.

void gui_text_substitute_chain_set(const uint32_t *cps, uint8_t n)

Override the substitute code point chain.

Candidates are tried in order; the first one with a glyph wins. Takes effect when glyphs are loaded, so set it during init rather than per frame.

参数:

cps -- Candidate code points; ignored when NULL.
n -- Number of candidates, clamped to GUI_TEXT_SUBSTITUTE_CHAIN_MAX.

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.

备注

With FONT_SRC_FILESYS on an XIP-capable VFS backend (romfs, ramfs) the font is read in place and the widget switches to FONT_SRC_MEMADDR. The file must stay mounted and unmodified while any widget uses the font.

参数:

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_set_cache(gui_text_t *this_widget, bool enable)

Enable cross-frame glyph bitmap cache for TTF text.

When enabled, rasterized glyph bitmaps are kept alive across frames instead of being freed each frame, eliminating re-rasterization for static or purely translating/scrolling text. Only effective for identity / pure-translate transforms; scale/rotate always re-rasterizes per frame. Trades memory (resident glyph bitmaps until content change or destroy) for CPU.

参数:

this_widget -- Text widget pointer.
enable -- true to keep glyph bitmaps across frames, false (default) to free them each frame.

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

void gui_text_set_gradient(gui_text_t *this_widget, gui_text_gradient_dir_t dir, const gui_text_gradient_stop_t *stops, uint8_t count)

Fill the text with a linear gradient.

Replaces the text color's RGB; its alpha and the widget opacity still apply. Only vector (TTF) text drawn without scale or rotation on an RGB565 or ARGB8888 display shows the gradient; other cases keep the flat color. Resets the handles to the preset of dir; the box mode is kept.

参数:

this_widget -- Text widget pointer.
dir -- Gradient direction preset.
stops -- Color stops, positions in 0.0 to 1.0; at most GUI_TEXT_GRADIENT_MAX_STOPS are used.
count -- Number of stops. NULL stops or count < 2 clears the gradient.

void gui_text_set_gradient_box(gui_text_t *this_widget, gui_text_gradient_box_t box)

Select the box the gradient handles are normalized against.

Default is GUI_TEXT_GRADIENT_BOX_INK. No effect before gui_text_set_gradient().

参数:

this_widget -- Text widget pointer.
box -- Box mode.

void gui_text_set_gradient_handles(gui_text_t *this_widget, float x0, float y0, float x1, float y1)

Place the gradient start and end handles, overriding the dir preset.

Coordinates are normalized to the box: (0, 0) top-left, (1, 1) bottom-right, matching Figma's gradientHandlePositions. Each value is clamped to -1.0..2.0. Handles closer than 1/16 of the box draw the first stop's color. No effect before gui_text_set_gradient().

参数:

this_widget -- Text widget pointer.
x0 -- Start handle X, stop position 0.0.
y0 -- Start handle Y.
x1 -- End handle X, stop position 1.0.
y1 -- End handle Y.

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)

Variables

uint32_t gui_text_substitute_chain[GUI_TEXT_SUBSTITUTE_CHAIN_MAX + 1]

Substitute candidates for missing glyphs, 0x0000-terminated.

Default order: U+FFFD replacement char, U+25A1 white square, U+0020 space. The space is the last resort: nearly every font has it, so a missing character degrades to a blank of the font's own width instead of vanishing.

struct gui_text_gradient_stop_t

Gradient color stop.

Public Members

float position: Position from the start handle (0.0) to the end handle (1.0).

gui_color_t color: Color at this position, alpha included.

struct gui_text_gradient_t

Text gradient state, allocated by gui_text_set_gradient().

Public Members

gui_text_gradient_dir_t dir

gui_text_gradient_box_t box

float handle_x0: Start handle, normalized to the box.

float handle_y0

float handle_x1: End handle, normalized to the box.

float handle_y1

font_gradient_t view: Rebound by the font draw each time.

bool bounds_valid

uint32_t bounds_frame: Frame the box was measured in.

int16_t bounds_x0: Box in screen coordinates, inclusive.

int16_t bounds_y0

int16_t bounds_x1

int16_t bounds_y1

int16_t shift_x: Offset of the copy being drawn from the measured box.

int16_t shift_y: Set by scroll text for its loop copy; 0 otherwise.

uint32_t lut[GUI_TEXT_GRADIENT_LUT_SIZE]: ARGB8888 colors.

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

gui_text_gradient_t *gradient: Optional gradient fill, NULL = flat color.

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)

uint16_t space_width: fallback space width (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

bool font_cache_enable: cross-frame glyph bitmap cache (identity/translate only)

bool font_cache_static: internal: chr[].buf currently holds a cross-frame static cache

uint8_t missing_glyph_mode: gui_missing_glyph_mode_t, 0 = inherit global

struct gui_text_line_t

Text line structure.

Public Members

int16_t index

int16_t offset