文本 (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() 来设置类型。类型为bin文件的地址。

文本内容

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

文本编码

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

文本转换为图片

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

备注

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

文本输入设置

开发者可以使用函数 gui_text_input_set() 设置文本的输入。

文本模式

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

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

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

滚动排版模式（4种）：适合文本超出显示区域时，以滚动方式显示内容（如水平自动滚动、垂直滚动等）。

竖向排版模式（2种）：支持文本从上到下的竖排显示方式。

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

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

排版模式如下：

文本模式
类型	行类型	X 方向	Y 方向	控件
LEFT	单行	左对齐	顶部	文本控件(默认)
CENTER	单行	居中	顶部	文本控件
RIGHT	单行	右对齐	顶部	文本控件
MULTI_LEFT	多行	左对齐	顶部	文本控件
MULTI_CENTER	多行	居中	顶部	文本控件
MULTI_RIGHT	多行	右对齐	顶部	文本控件
MID_LEFT	多行	左对齐	中部	文本控件
MID_CENTER	多行	居中	中部	文本控件
MID_RIGHT	多行	右对齐	中部	文本控件
SCROLL_X	单行	由右向左滚动	顶部	滚动文本控件
SCROLL_Y	多行	左对齐	由下向上滚动	滚动文本控件
SCROLL_X_REVERSE	多行	由左向右滚动	顶部	滚动文本控件
SCROLL_Y_REVERSE	多行	右对齐	由上向下滚动	滚动文本控件
VERTICAL_LEFT	多行	左对齐	由上向下	文本控件
VERTICAL_RIGHT	多行	右对齐	由下向上	文本控件
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,
    /* SCROLL */
    SCROLL_X           = 0x30,
    SCROLL_Y           = 0x31,
    SCROLL_Y_REVERSE   = 0x32,
    SCROLL_X_REVERSE   = 0x33,
    /* 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 SCROLL_X

enumerator SCROLL_Y

enumerator SCROLL_Y_REVERSE

enumerator SCROLL_X_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_STB

enumerator GUI_FONT_SRC_IMG

enumerator GUI_FONT_SRC_MAT

enumerator GUI_FONT_SRC_FT

enumerator GUI_FONT_SRC_TTF

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 – The text box widget pointer.
text – The text string.
text_type – Text type.
color – The text’s color.
length – The text string’s length.
font_size – The 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 – The 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 – The 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 – The text box widget pointer.
color – The font color.

void gui_text_wordwrap_set(gui_text_t *this_widget, bool wordwrap)

By setting wordwrap to enable English word wrapping.

参数:

this_widget – The 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 – The 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 – The 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 – 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 – The 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 – The 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 – The text box widget pointer.
x – The X-axis coordinate of the text box.
y – The 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 – The 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 – The 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 – The text widget pointer.
font_source – The 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 – The 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 – The text widget pointer.
encoding_type – Encoding type.

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

Set text matrix.

备注

参数:

this_widget – The text widget pointer.
encoding_type – Encoding type.

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

Set text content.

参数:

this_widget – The text widget pointer.
text – The text string.
length – The 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 – The 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 – The parent widget in which the text is nested.
filename – The widget’s name.
x – The X-axis coordinate of the text box.
y – The Y-axis coordinate of the text box.
w – The width of the text box.
h – The height of the text box.

返回:

Returns the widget object pointer.

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