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.

Create Text Widget

To create a text widget, you can use gui_text_create(), The coordinates on the screen and text box size have been identified after create. These attributes also can be modified whenever you want.

Note

The size of the text box should be larger than the string to be shown; out-of-range text will be hidden.

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, and the text font size must match the size of the loaded font file.

Font Type

The text widget support type setting. This function can be used to set the type. The type is a bin/ttf file address gui_text_type_set().

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 Input

Text widget supports the input setting. You can use this function to set input gui_text_input_set().

Text Modes

The text control currently supports 21 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 (6 types): Used for displaying multiple lines of text, supporting various arrangements like multi-line centered, multi-line left-aligned, multi-line right-aligned, etc.

  • Scrolling layout modes (4 types): Ideal for displaying content that exceeds the display area by scrolling, such as horizontal auto-scrolling, vertical scrolling, etc.

  • Vertical layout modes (2 types): Supports vertical text display from top to bottom.

  • 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

Multi-line

Left

Mid

Text widget

MID_CENTER

Multi-line

Center

Mid

Text widget

MID_RIGHT

Multi-line

Right

Mid

Text widget

SCROLL_X

Single-line

Right to Left

Top

Scroll text widget

SCROLL_Y

Multi-line

Left

Bottom to Top

Scroll text widget

SCROLL_X_REVERSE

Multi-line

Left to Right

Top

Scroll text widget

SCROLL_Y_REVERSE

Multi-line

Right

Top to Bottom

Scroll text widget

VERTICAL_LEFT

Multi-line

Left

Top to Bottom

Text widget

VERTICAL_RIGHT

Multi-line

Right

Bottom to Top

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,
    /* 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;

Text Move

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

Example

Simple Text Widget 

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.

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, uint8_t font_size)

Set the string in a text box widget.

Note

The font size must match the font file.

Parameters:

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

Parameters:

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

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Note

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

Parameters:

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

Parameters:

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

Note

The type must match the font size.

Parameters:

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

Note

Requires ROMFS.

Note

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

Parameters:

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

Note

UTF-8 or Unicode.

Parameters:

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

Note

Parameters:

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

Parameters:

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

Parameters:

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

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 – 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:

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