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
Standards TTF file support^①
Self-developed font files support

^①: Only part of the chip support this feature.

Usage

Using functions to load font files and display text.

Initialize the Font File

In order to draw text, font files containing glyph information need to be loaded into the system.

The font file can be a standard .ttf file or a customized .bin file. The font file can be initialized ahead of time to avoid having to set the font type for each text widget.

To initialize the new version customized bin font file, use gui_font_mem_init(uint8_t *font_bin_addr).
To initialize the standard TTF file to draw text, use gui_font_stb_init(void *font_ttf_addr).

All customized bin font files are available from RTK technicians.

FONT_BIN, FONT_TTF are all addresses of the files stored in flash.

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 the same as the set character length, and the font size of the text must be the same as 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 Click

Text widget supports click. You can use this function to add the click event for text gui_text_click().

Text Mode

Text widget supports seven typesetting modes. To set text typesetting mode, use: gui_text_mode_set().

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_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

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 */
    VERTICAL_LEFT      = 0x40,
    VERTICAL_RIGHT     = 0x41,
} TEXT_MODE;

Text Move

It is possible to use this function gui_text_move() to move text to a specified location, but x and y cannot be larger than w and h of the text.

Set Animate

Using this function gui_text_set_animate() to set the animation and implement the animation effect in the corresponding callback function.

Example

Multiple Text Widget

#include "string.h"
#include "gui_obj.h"
#include "guidef.h"
#include "gui_text.h"
#include "draw_font.h"
#include "gui_app.h"
#include "rtk_gui_resource.h"

static char chinese[6] =
{
    0xE4, 0xB8, 0xAD,
    0xE6, 0x96, 0x87
};
static void app_launcher_ui_design(gui_app_t *app)
{
    gui_font_mem_init(HARMONYOS_SIZE24_BITS1_FONT_BIN);
    gui_font_mem_init(HARMONYOS_SIZE16_BITS4_FONT_BIN);
    gui_font_mem_init(HARMONYOS_SIZE32_BITS1_FONT_BIN);
    gui_font_mem_init(SIMKAI_SIZE24_BITS4_FONT_BIN);

    void *screen = &app->screen;

    gui_text_t *text1 = gui_text_create(screen,  "text1",  10, 10, 100, 50);
    gui_text_set(text1, chinese, GUI_FONT_SRC_BMP, APP_COLOR_WHITE, strlen(chinese), 24);
    gui_text_type_set(text1, HARMONYOS_SIZE24_BITS1_FONT_BIN, FONT_SRC_MEMADDR);
    gui_text_mode_set(text1, LEFT);

    gui_text_t *text2 = gui_text_create(screen,  "text2",  0, 50, 300, 50);
    gui_text_set(text2, "english", GUI_FONT_SRC_BMP, APP_COLOR_RED, 7, 16);
    gui_text_type_set(text2, HARMONYOS_SIZE16_BITS4_FONT_BIN, FONT_SRC_MEMADDR);
    gui_text_mode_set(text2, LEFT);

    char *string = "TEXT_WIDGET";
    gui_text_t *text3 = gui_text_create(screen,  "text3",  0, 90, 300, 50);
    gui_text_set(text3, string, GUI_FONT_SRC_BMP, APP_COLOR_BLUE, strlen(string), 32);
    gui_text_type_set(text3, HARMONYOS_SIZE32_BITS1_FONT_BIN, FONT_SRC_MEMADDR);
    gui_text_mode_set(text3, CENTER);

    gui_text_t *text4 = gui_text_create(screen,  "text4",  0, 150, 100, 200);
    gui_text_set(text4, "ABCDEFGHIJKLMNOPQRSTUVWXYZ", GUI_FONT_SRC_BMP, gui_rgb(0, 0xff, 0xff), 24, 24);
    gui_text_type_set(text4, SIMKAI_SIZE24_BITS4_FONT_BIN, FONT_SRC_MEMADDR);
    gui_text_mode_set(text4, MULTI_CENTER);
}

Animate Text Widget

#include "root_image_hongkong/ui_resource.h"
#include "string.h"
#include "gui_obj.h"
#include "guidef.h"
#include "gui_text.h"
#include "draw_font.h"

void change_text_cb(gui_text_t *obj)
{
    if (obj->animate->current_frame > 0 && obj->animate->current_frame < 50)
    {
        gui_text_move(obj, 50, 150);
        gui_text_content_set(obj, "123456789", 9);
    }
    else if (obj->animate->current_frame > 50 && obj->animate->current_frame < 100)
    {
        gui_text_move(obj, 200, 150);
        gui_text_content_set(obj, "987654321", 9);

    }
    else
    {
        gui_text_move(obj, 125, 50);
        gui_text_content_set(obj, "abcdefghi", 9);
    }
}

void page_tb_activity(void *parent)
{
    gui_font_mem_init(SIMKAI_SIZE24_BITS4_FONT_BIN);

    gui_text_t *text = gui_text_create(parent,  "text",  0, 0, 100, 200);
    gui_text_set(text, "ABCDEFGHI", GUI_FONT_SRC_BMP, APP_COLOR_RED, 9, 24);
    gui_text_type_set(text, SIMKAI_SIZE24_BITS4_FONT_BIN, FONT_SRC_MEMADDR);
    gui_text_mode_set(text, MULTI_CENTER);
    gui_text_set_animate(text, 5000, 15, change_text_cb, text);
}

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

enumerator VERTICAL_RIGHT

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

Parameters:

this_widget – text widget.
event_cb – cb function.
parameter – cb parameter.

void gui_text_pswd_done(gui_text_t *this_widget, gui_event_cb_t event_cb, void *parameter)

set textbox password done event cb, to handle password.

Parameters:

this_widget – text widget.
event_cb – cb function.
parameter – cb 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.

Returns:

void

void gui_text_set_animate(void *o, uint32_t dur, int repeat_count, void *callback, void *p)

set animate.

Parameters:

o – text widget.
dur – durtion. 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 lft or right.

Parameters:

this_widget – the text widget pointer.
mode – there was three mode: 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_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_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 – rendermode.1/2/4/8

void gui_text_set_min_scale(gui_text_t *this_widget, float min_scale)

set text min 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 use freetype, width and height is effective, else height will be applied as font size.

Parameters:

this_widget – the text widget pointer.
height – font height or font size.
width – font width(only be effective when freetype was 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 addr 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

Need romfs.

Note

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

Parameters:

this – The text widget pointer.
path – Path contain folder path and file name prefix. Path eg:”font/emoji/emoji_u”. Folder path is emoji image file folder path, eg:”font/emoji/”. File name prefix is prefix before the filename for Unicode sorting, eg:”emoji_u”.
size – Emoji image file size. eg 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)

to draw text by img, 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 father widget which the text nested in.
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 hight of the text box.

Returns:

return the widget object pointer.

struct gui_text_t

text widget structure

Public Members

gui_obj_t base

gui_color_t color

gui_animate_t *animate

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

bool layout_refresh

bool content_refresh

bool use_img_blit

uint8_t inputable

uint8_t ispasswd

uint8_t wordwrap

uint8_t scope

uint8_t rendermode

struct gui_text_line_t

text line structure

Public Members

uint16_t line_char

uint16_t line_dx

Text

Features

Usage

Initialize the Font File

Create Text Widget

Set Text Attributes

Set Text

Font Type

Text Content

Text Encoding

Convert to Img

Text Input

Text Click

Text Mode

Text Move

Set Animate

Example

Multiple Text Widget

Animate Text Widget

API