1 /**
2  * @file lv_table.h
3  *
4  */
5 
6 #ifndef LV_TABLE_H
7 #define LV_TABLE_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 
17 #include "../label/lv_label.h"
18 
19 #if LV_USE_TABLE != 0
20 
21 /*Testing of dependencies*/
22 #if LV_USE_LABEL == 0
23 #error "lv_table: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1)"
24 #endif
25 
26 /*********************
27  *      DEFINES
28  *********************/
29 #define LV_TABLE_CELL_NONE 0XFFFF
30 LV_EXPORT_CONST_INT(LV_TABLE_CELL_NONE);
31 
32 /**********************
33  *      TYPEDEFS
34  **********************/
35 
36 typedef enum {
37     LV_TABLE_CELL_CTRL_NONE        = 0 << 0,
38     LV_TABLE_CELL_CTRL_MERGE_RIGHT = 1 << 0,
39     LV_TABLE_CELL_CTRL_TEXT_CROP   = 1 << 1,
40     LV_TABLE_CELL_CTRL_CUSTOM_1    = 1 << 4,
41     LV_TABLE_CELL_CTRL_CUSTOM_2    = 1 << 5,
42     LV_TABLE_CELL_CTRL_CUSTOM_3    = 1 << 6,
43     LV_TABLE_CELL_CTRL_CUSTOM_4    = 1 << 7,
44 } lv_table_cell_ctrl_t;
45 
46 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_table_class;
47 
48 /**********************
49  * GLOBAL PROTOTYPES
50  **********************/
51 
52 /**
53  * Create a table object
54  * @param parent        pointer to an object, it will be the parent of the new table
55  * @return              pointer to the created table
56  */
57 lv_obj_t * lv_table_create(lv_obj_t * parent);
58 
59 /*=====================
60  * Setter functions
61  *====================*/
62 
63 /**
64  * Set the value of a cell.
65  * @param obj           pointer to a Table object
66  * @param row           id of the row [0 .. row_cnt -1]
67  * @param col           id of the column [0 .. col_cnt -1]
68  * @param txt           text to display in the cell. It will be copied and saved so this variable is not required after this function call.
69  * @note                New roes/columns are added automatically if required
70  */
71 void lv_table_set_cell_value(lv_obj_t * obj, uint32_t row, uint32_t col, const char * txt);
72 
73 /**
74  * Set the value of a cell.  Memory will be allocated to store the text by the table.
75  * @param obj           pointer to a Table object
76  * @param row           id of the row [0 .. row_cnt -1]
77  * @param col           id of the column [0 .. col_cnt -1]
78  * @param fmt           `printf`-like format
79  * @note                New roes/columns are added automatically if required
80  */
81 void lv_table_set_cell_value_fmt(lv_obj_t * obj, uint32_t row, uint32_t col, const char * fmt,
82                                  ...) LV_FORMAT_ATTRIBUTE(4, 5);
83 
84 /**
85  * Set the number of rows
86  * @param obj           table pointer to a Table object
87  * @param row_cnt       number of rows
88  */
89 void lv_table_set_row_count(lv_obj_t * obj, uint32_t row_cnt);
90 
91 /**
92  * Set the number of columns
93  * @param obj       table pointer to a Table object
94  * @param col_cnt   number of columns.
95  */
96 void lv_table_set_column_count(lv_obj_t * obj, uint32_t col_cnt);
97 
98 /**
99  * Set the width of a column
100  * @param obj       table pointer to a Table object
101  * @param col_id    id of the column [0 .. LV_TABLE_COL_MAX -1]
102  * @param w         width of the column
103  */
104 void lv_table_set_column_width(lv_obj_t * obj, uint32_t col_id, int32_t w);
105 
106 /**
107  * Add control bits to the cell.
108  * @param obj       pointer to a Table object
109  * @param row       id of the row [0 .. row_cnt -1]
110  * @param col       id of the column [0 .. col_cnt -1]
111  * @param ctrl      OR-ed values from ::lv_table_cell_ctrl_t
112  */
113 void lv_table_add_cell_ctrl(lv_obj_t * obj, uint32_t row, uint32_t col, lv_table_cell_ctrl_t ctrl);
114 
115 /**
116  * Clear control bits of the cell.
117  * @param obj       pointer to a Table object
118  * @param row       id of the row [0 .. row_cnt -1]
119  * @param col       id of the column [0 .. col_cnt -1]
120  * @param ctrl      OR-ed values from ::lv_table_cell_ctrl_t
121  */
122 void lv_table_clear_cell_ctrl(lv_obj_t * obj, uint32_t row, uint32_t col, lv_table_cell_ctrl_t ctrl);
123 
124 /**
125  * Add custom user data to the cell.
126  * @param obj       pointer to a Table object
127  * @param row       id of the row [0 .. row_cnt -1]
128  * @param col       id of the column [0 .. col_cnt -1]
129  * @param user_data pointer to the new user_data.
130  *                  Should be allocated by `lv_malloc`,
131  *                  and it will be freed automatically when the table is deleted or
132  *                  when the cell is dropped due to lower row or column count.
133  */
134 void lv_table_set_cell_user_data(lv_obj_t * obj, uint16_t row, uint16_t col, void * user_data);
135 
136 /**
137  * Set the selected cell
138  * @param obj       pointer to a table object
139  * @param row       id of the cell row to select
140  * @param col       id of the cell column to select
141  */
142 void lv_table_set_selected_cell(lv_obj_t * obj, uint16_t row, uint16_t col);
143 
144 /*=====================
145  * Getter functions
146  *====================*/
147 
148 /**
149  * Get the value of a cell.
150  * @param obj       pointer to a Table object
151  * @param row       id of the row [0 .. row_cnt -1]
152  * @param col       id of the column [0 .. col_cnt -1]
153  * @return          text in the cell
154  */
155 const char * lv_table_get_cell_value(lv_obj_t * obj, uint32_t row, uint32_t col);
156 
157 /**
158  * Get the number of rows.
159  * @param obj       table pointer to a Table object
160  * @return          number of rows.
161  */
162 uint32_t lv_table_get_row_count(lv_obj_t * obj);
163 
164 /**
165  * Get the number of columns.
166  * @param obj       table pointer to a Table object
167  * @return          number of columns.
168  */
169 uint32_t lv_table_get_column_count(lv_obj_t * obj);
170 
171 /**
172  * Get the width of a column
173  * @param obj       table pointer to a Table object
174  * @param col       id of the column [0 .. LV_TABLE_COL_MAX -1]
175  * @return          width of the column
176  */
177 int32_t lv_table_get_column_width(lv_obj_t * obj, uint32_t col);
178 
179 /**
180  * Get whether a cell has the control bits
181  * @param obj       pointer to a Table object
182  * @param row       id of the row [0 .. row_cnt -1]
183  * @param col       id of the column [0 .. col_cnt -1]
184  * @param ctrl      OR-ed values from ::lv_table_cell_ctrl_t
185  * @return          true: all control bits are set; false: not all control bits are set
186  */
187 bool lv_table_has_cell_ctrl(lv_obj_t * obj, uint32_t row, uint32_t col, lv_table_cell_ctrl_t ctrl);
188 
189 /**
190  * Get the selected cell (pressed and or focused)
191  * @param obj       pointer to a table object
192  * @param row       pointer to variable to store the selected row (LV_TABLE_CELL_NONE: if no cell selected)
193  * @param col       pointer to variable to store the selected column  (LV_TABLE_CELL_NONE: if no cell selected)
194  */
195 void lv_table_get_selected_cell(lv_obj_t * obj, uint32_t * row, uint32_t * col);
196 
197 /**
198  * Get custom user data to the cell.
199  * @param obj       pointer to a Table object
200  * @param row       id of the row [0 .. row_cnt -1]
201  * @param col       id of the column [0 .. col_cnt -1]
202  */
203 void * lv_table_get_cell_user_data(lv_obj_t * obj, uint16_t row, uint16_t col);
204 
205 /**********************
206  *      MACROS
207  **********************/
208 
209 #endif /*LV_USE_TABLE*/
210 
211 #ifdef __cplusplus
212 } /*extern "C"*/
213 #endif
214 
215 #endif /*LV_TABLE_H*/
216