文本 (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() 设置字体的大小。

自动换行

开发者可以使用函数 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）。

EMOJI 表情

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

文本模式

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

单行排版模式（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() 将文本控件移动到指定位置。

示例

简单文本控件

static void text_widget_example(void)
{
    gui_text_t *text = gui_text_create(gui_obj_get_root(), "text", 0, 0, 0, 0);
    gui_text_set(text, "HoneyGUI", GUI_FONT_SRC_BMP, APP_COLOR_WHITE, 8, 32);
    gui_text_type_set(text, font32b1, 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

enum FONT_SRC_TYPE

Font type enum.

Values:

enumerator GUI_FONT_SRC_BMP

enumerator GUI_FONT_SRC_IMG

enumerator GUI_FONT_SRC_MAT

enumerator GUI_FONT_SRC_TTF

enumerator GUI_FONT_SRC_STB

enumerator GUI_FONT_SRC_CUS

enum FONT_SRC_MODE

Values:

enumerator FONT_SRC_MEMADDR

enumerator FONT_SRC_FILESYS

enumerator FONT_SRC_FTL

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, uint8_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_set_animate(void *o, uint32_t dur, int repeat_count, void *callback, void *p)

Set animate.

参数:

o -- Text widget.
dur -- Duration. Time length of the animate.
repeat_count -- 0: One shoot, -1: Endless.
callback -- Happens at every frame.
p -- Callback's parameter.

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 -- There are three modes: LEFT, CENTER, and RIGHT.

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_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_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, uint8_t height, uint8_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.

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

gui_inline bool gui_scroll_text_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

TEXT_MODE mode

TEXT_CHARSET charset

FONT_SRC_TYPE font_type

FONT_SRC_MODE font_mode

uint8_t font_height

uint8_t emoji_size

uint8_t checksum

int8_t extra_letter_spacing

int8_t extra_line_spacing

bool layout_refresh

bool content_refresh

bool use_img_blit

bool inputable

bool ispasswd

bool wordwrap

bool scope

bool arabic

bool thai

bool hebrew

uint8_t rendermode

struct gui_text_line_t

Text line structure.

Public Members

int16_t index

int16_t offset