1 /**
2 * @file lv_txt.h
3 *
4 */
5
6 #ifndef LV_TXT_H
7 #define LV_TXT_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #include "../lv_conf_internal.h"
17
18 #include <stdbool.h>
19 #include <stdarg.h>
20 #include "lv_area.h"
21 #include "../font/lv_font.h"
22 #include "lv_printf.h"
23 #include "lv_types.h"
24
25 /*********************
26 * DEFINES
27 *********************/
28 #ifndef LV_TXT_COLOR_CMD
29 #define LV_TXT_COLOR_CMD "#"
30 #endif
31
32 #define LV_TXT_ENC_UTF8 1
33 #define LV_TXT_ENC_ASCII 2
34
35 /**********************
36 * TYPEDEFS
37 **********************/
38
39 /**
40 * Options for text rendering.
41 */
42 enum {
43 LV_TEXT_FLAG_NONE = 0x00,
44 LV_TEXT_FLAG_RECOLOR = 0x01, /**< Enable parsing of recolor command*/
45 LV_TEXT_FLAG_EXPAND = 0x02, /**< Ignore max-width to avoid automatic word wrapping*/
46 LV_TEXT_FLAG_FIT = 0x04, /**< Max-width is already equal to the longest line. (Used to skip some calculation)*/
47 };
48 typedef uint8_t lv_text_flag_t;
49
50 /**
51 * State machine for text renderer.*/
52 enum {
53 LV_TEXT_CMD_STATE_WAIT, /**< Waiting for command*/
54 LV_TEXT_CMD_STATE_PAR, /**< Processing the parameter*/
55 LV_TEXT_CMD_STATE_IN, /**< Processing the command*/
56 };
57 typedef uint8_t lv_text_cmd_state_t;
58
59 /** Label align policy*/
60 enum {
61 LV_TEXT_ALIGN_AUTO, /**< Align text auto*/
62 LV_TEXT_ALIGN_LEFT, /**< Align text to left*/
63 LV_TEXT_ALIGN_CENTER, /**< Align text to center*/
64 LV_TEXT_ALIGN_RIGHT, /**< Align text to right*/
65 };
66 typedef uint8_t lv_text_align_t;
67
68 /**********************
69 * GLOBAL PROTOTYPES
70 **********************/
71
72 /**
73 * Get size of a text
74 * @param size_res pointer to a 'point_t' variable to store the result
75 * @param text pointer to a text
76 * @param font pointer to font of the text
77 * @param letter_space letter space of the text
78 * @param line_space line space of the text
79 * @param flags settings for the text from ::lv_text_flag_t
80 * @param max_width max width of the text (break the lines to fit this size). Set COORD_MAX to avoid
81 * line breaks
82 */
83 void lv_txt_get_size(lv_point_t * size_res, const char * text, const lv_font_t * font, lv_coord_t letter_space,
84 lv_coord_t line_space, lv_coord_t max_width, lv_text_flag_t flag);
85
86 /**
87 * Get the next line of text. Check line length and break chars too.
88 * @param txt a '\0' terminated string
89 * @param font pointer to a font
90 * @param letter_space letter space
91 * @param max_width max width of the text (break the lines to fit this size). Set COORD_MAX to avoid
92 * line breaks
93 * @param used_width When used_width != NULL, save the width of this line if
94 * flag == LV_TEXT_FLAG_NONE, otherwise save -1.
95 * @param flags settings for the text from 'txt_flag_type' enum
96 * @return the index of the first char of the new line (in byte index not letter index. With UTF-8
97 * they are different)
98 */
99 uint32_t _lv_txt_get_next_line(const char * txt, const lv_font_t * font, lv_coord_t letter_space,
100 lv_coord_t max_width, lv_coord_t * used_width, lv_text_flag_t flag);
101
102 /**
103 * Give the length of a text with a given font
104 * @param txt a '\0' terminate string
105 * @param length length of 'txt' in byte count and not characters (Á is 1 character but 2 bytes in
106 * UTF-8)
107 * @param font pointer to a font
108 * @param letter_space letter space
109 * @param flags settings for the text from 'txt_flag_t' enum
110 * @return length of a char_num long text
111 */
112 lv_coord_t lv_txt_get_width(const char * txt, uint32_t length, const lv_font_t * font, lv_coord_t letter_space,
113 lv_text_flag_t flag);
114
115 /**
116 * Check next character in a string and decide if the character is part of the command or not
117 * @param state pointer to a txt_cmd_state_t variable which stores the current state of command
118 * processing
119 * @param c the current character
120 * @return true: the character is part of a command and should not be written,
121 * false: the character should be written
122 */
123 bool _lv_txt_is_cmd(lv_text_cmd_state_t * state, uint32_t c);
124
125 /**
126 * Insert a string into an other
127 * @param txt_buf the original text (must be big enough for the result text and NULL terminated)
128 * @param pos position to insert (0: before the original text, 1: after the first char etc.)
129 * @param ins_txt text to insert, must be '\0' terminated
130 */
131 void _lv_txt_ins(char * txt_buf, uint32_t pos, const char * ins_txt);
132
133 /**
134 * Delete a part of a string
135 * @param txt string to modify, must be '\0' terminated and should point to a heap or stack frame, not read-only memory.
136 * @param pos position where to start the deleting (0: before the first char, 1: after the first
137 * char etc.)
138 * @param len number of characters to delete
139 */
140 void _lv_txt_cut(char * txt, uint32_t pos, uint32_t len);
141
142 /**
143 * return a new formatted text. Memory will be allocated to store the text.
144 * @param fmt `printf`-like format
145 * @return pointer to the allocated text string.
146 */
147 char * _lv_txt_set_text_vfmt(const char * fmt, va_list ap) LV_FORMAT_ATTRIBUTE(1, 0);
148
149 /**
150 * Decode two encoded character from a string.
151 * @param txt pointer to '\0' terminated string
152 * @param letter the first decoded Unicode character or 0 on invalid data code
153 * @param letter_next the second decoded Unicode character or 0 on invalid data code
154 * @param ofs start index in 'txt' where to start.
155 * After the call it will point to the next encoded char in 'txt'.
156 * NULL to use txt[0] as index
157 */
158 void _lv_txt_encoded_letter_next_2(const char * txt, uint32_t * letter, uint32_t * letter_next, uint32_t * ofs);
159
160 /**
161 * Test if char is break char or not (a text can broken here or not)
162 * @param letter a letter
163 * @return false: 'letter' is not break char
164 */
_lv_txt_is_break_char(uint32_t letter)165 static inline bool _lv_txt_is_break_char(uint32_t letter)
166 {
167 uint8_t i;
168 bool ret = false;
169
170 /* each chinese character can be break */
171 if(letter >= 0x4E00 && letter <= 0x9FA5) {
172 return true;
173 }
174
175 /*Compare the letter to TXT_BREAK_CHARS*/
176 for(i = 0; LV_TXT_BREAK_CHARS[i] != '\0'; i++) {
177 if(letter == (uint32_t)LV_TXT_BREAK_CHARS[i]) {
178 ret = true; /*If match then it is break char*/
179 break;
180 }
181 }
182
183 return ret;
184 }
185
186 /***************************************************************
187 * GLOBAL FUNCTION POINTERS FOR CHARACTER ENCODING INTERFACE
188 ***************************************************************/
189
190 /**
191 * Give the size of an encoded character
192 * @param str pointer to a character in a string
193 * @return length of the encoded character (1,2,3 ...). O in invalid
194 */
195 extern uint8_t (*_lv_txt_encoded_size)(const char *);
196
197 /**
198 * Convert a Unicode letter to encoded
199 * @param letter_uni a Unicode letter
200 * @return Encoded character in Little Endian to be compatible with C chars (e.g. 'Á', 'Ü')
201 */
202 extern uint32_t (*_lv_txt_unicode_to_encoded)(uint32_t);
203
204 /**
205 * Convert a wide character, e.g. 'Á' little endian to be compatible with the encoded format.
206 * @param c a wide character
207 * @return `c` in the encoded format
208 */
209 extern uint32_t (*_lv_txt_encoded_conv_wc)(uint32_t c);
210
211 /**
212 * Decode the next encoded character from a string.
213 * @param txt pointer to '\0' terminated string
214 * @param i start index in 'txt' where to start.
215 * After the call it will point to the next encoded char in 'txt'.
216 * NULL to use txt[0] as index
217 * @return the decoded Unicode character or 0 on invalid data code
218 */
219 extern uint32_t (*_lv_txt_encoded_next)(const char *, uint32_t *);
220
221 /**
222 * Get the previous encoded character form a string.
223 * @param txt pointer to '\0' terminated string
224 * @param i_start index in 'txt' where to start. After the call it will point to the previous
225 * encoded char in 'txt'.
226 * @return the decoded Unicode character or 0 on invalid data
227 */
228 extern uint32_t (*_lv_txt_encoded_prev)(const char *, uint32_t *);
229
230 /**
231 * Convert a letter index (in the encoded text) to byte index.
232 * E.g. in UTF-8 "AÁRT" index of 'R' is 2 but start at byte 3 because 'Á' is 2 bytes long
233 * @param txt a '\0' terminated UTF-8 string
234 * @param enc_id letter index
235 * @return byte index of the 'enc_id'th letter
236 */
237 extern uint32_t (*_lv_txt_encoded_get_byte_id)(const char *, uint32_t);
238
239 /**
240 * Convert a byte index (in an encoded text) to character index.
241 * E.g. in UTF-8 "AÁRT" index of 'R' is 2 but start at byte 3 because 'Á' is 2 bytes long
242 * @param txt a '\0' terminated UTF-8 string
243 * @param byte_id byte index
244 * @return character index of the letter at 'byte_id'th position
245 */
246 extern uint32_t (*_lv_txt_encoded_get_char_id)(const char *, uint32_t);
247
248 /**
249 * Get the number of characters (and NOT bytes) in a string.
250 * E.g. in UTF-8 "ÁBC" is 3 characters (but 4 bytes)
251 * @param txt a '\0' terminated char string
252 * @return number of characters
253 */
254 extern uint32_t (*_lv_txt_get_encoded_length)(const char *);
255
256 /**********************
257 * MACROS
258 **********************/
259
260 #ifdef __cplusplus
261 } /*extern "C"*/
262 #endif
263
264 #endif /*LV_TXT_H*/
265
