1 /** 2 * @file lv_group.h 3 * 4 */ 5 6 #ifndef LV_GROUP_H 7 #define LV_GROUP_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #ifdef LV_CONF_INCLUDE_SIMPLE 17 #include "lv_conf.h" 18 #else 19 #include "../../lv_conf.h" 20 #endif 21 22 #include "lv_obj.h" 23 24 /********************* 25 * DEFINES 26 *********************/ 27 /*Predefined keys to control the focused object via lv_group_send(group, c)*/ 28 /*For compatibility in signal function define the keys regardless to `LV_USE_GROUP`*/ 29 30 enum { 31 LV_KEY_UP = 17, /*0x11*/ 32 LV_KEY_DOWN = 18, /*0x12*/ 33 LV_KEY_RIGHT = 19, /*0x13*/ 34 LV_KEY_LEFT = 20, /*0x14*/ 35 LV_KEY_ESC = 27, /*0x1B*/ 36 LV_KEY_DEL = 127, /*0x7F*/ 37 LV_KEY_BACKSPACE = 8, /*0x08*/ 38 LV_KEY_ENTER = 10, /*0x0A, '\n'*/ 39 LV_KEY_NEXT = 9, /*0x09, '\t'*/ 40 LV_KEY_PREV = 11, /*0x0B, '*/ 41 LV_KEY_HOME = 2, /*0x02, STX*/ 42 LV_KEY_END = 3, /*0x03, ETX*/ 43 }; 44 typedef uint8_t lv_key_t; 45 46 #if LV_USE_GROUP != 0 47 /********************** 48 * TYPEDEFS 49 **********************/ 50 struct _lv_group_t; 51 52 typedef void (*lv_group_style_mod_cb_t)(struct _lv_group_t *, lv_style_t *); 53 typedef void (*lv_group_focus_cb_t)(struct _lv_group_t *); 54 55 /** 56 * Groups can be used to logically hold objects so that they can be individually focused. 57 * They are NOT for laying out objects on a screen (try `lv_cont` for that). 58 */ 59 typedef struct _lv_group_t 60 { 61 lv_ll_t obj_ll; /**< Linked list to store the objects in the group */ 62 lv_obj_t ** obj_focus; /**< The object in focus*/ 63 64 lv_group_style_mod_cb_t style_mod_cb; /**< A function to modifies the style of the focused object*/ 65 lv_group_style_mod_cb_t style_mod_edit_cb; /**< A function which modifies the style of the edited object*/ 66 lv_group_focus_cb_t focus_cb; /**< A function to call when a new object is focused (optional)*/ 67 lv_style_t style_tmp; /**< Stores the modified style of the focused object */ 68 #if LV_USE_USER_DATA 69 lv_group_user_data_t user_data; 70 #endif 71 72 uint8_t frozen : 1; /**< 1: can't focus to new object*/ 73 uint8_t editing : 1; /**< 1: Edit mode, 0: Navigate mode*/ 74 uint8_t click_focus : 1; /**< 1: If an object in a group is clicked by an indev then it will be 75 focused */ 76 uint8_t refocus_policy : 1; /**< 1: Focus prev if focused on deletion. 0: Focus next if focused on 77 deletion.*/ 78 uint8_t wrap : 1; /**< 1: Focus next/prev can wrap at end of list. 0: Focus next/prev stops at end 79 of list.*/ 80 } lv_group_t; 81 82 enum { LV_GROUP_REFOCUS_POLICY_NEXT = 0, LV_GROUP_REFOCUS_POLICY_PREV = 1 }; 83 typedef uint8_t lv_group_refocus_policy_t; 84 85 /********************** 86 * GLOBAL PROTOTYPES 87 **********************/ 88 89 /** 90 * Init. the group module 91 * @remarks Internal function, do not call directly. 92 */ 93 void lv_group_init(void); 94 95 /** 96 * Create a new object group 97 * @return pointer to the new object group 98 */ 99 lv_group_t * lv_group_create(void); 100 101 /** 102 * Delete a group object 103 * @param group pointer to a group 104 */ 105 void lv_group_del(lv_group_t * group); 106 107 /** 108 * Add an object to a group 109 * @param group pointer to a group 110 * @param obj pointer to an object to add 111 */ 112 void lv_group_add_obj(lv_group_t * group, lv_obj_t * obj); 113 114 /** 115 * Remove an object from its group 116 * @param obj pointer to an object to remove 117 */ 118 void lv_group_remove_obj(lv_obj_t * obj); 119 120 /** 121 * Remove all objects from a group 122 * @param group pointer to a group 123 */ 124 void lv_group_remove_all_objs(lv_group_t * group); 125 126 /** 127 * Focus on an object (defocus the current) 128 * @param obj pointer to an object to focus on 129 */ 130 void lv_group_focus_obj(lv_obj_t * obj); 131 132 /** 133 * Focus the next object in a group (defocus the current) 134 * @param group pointer to a group 135 */ 136 void lv_group_focus_next(lv_group_t * group); 137 138 /** 139 * Focus the previous object in a group (defocus the current) 140 * @param group pointer to a group 141 */ 142 void lv_group_focus_prev(lv_group_t * group); 143 144 /** 145 * Do not let to change the focus from the current object 146 * @param group pointer to a group 147 * @param en true: freeze, false: release freezing (normal mode) 148 */ 149 void lv_group_focus_freeze(lv_group_t * group, bool en); 150 151 /** 152 * Send a control character to the focuses object of a group 153 * @param group pointer to a group 154 * @param c a character (use LV_KEY_.. to navigate) 155 * @return result of focused object in group. 156 */ 157 lv_res_t lv_group_send_data(lv_group_t * group, uint32_t c); 158 159 /** 160 * Set a function for a group which will modify the object's style if it is in focus 161 * @param group pointer to a group 162 * @param style_mod_cb the style modifier function pointer 163 */ 164 void lv_group_set_style_mod_cb(lv_group_t * group, lv_group_style_mod_cb_t style_mod_cb); 165 166 /** 167 * Set a function for a group which will modify the object's style if it is in focus in edit mode 168 * @param group pointer to a group 169 * @param style_mod_edit_cb the style modifier function pointer 170 */ 171 void lv_group_set_style_mod_edit_cb(lv_group_t * group, lv_group_style_mod_cb_t style_mod_edit_cb); 172 173 /** 174 * Set a function for a group which will be called when a new object is focused 175 * @param group pointer to a group 176 * @param focus_cb the call back function or NULL if unused 177 */ 178 void lv_group_set_focus_cb(lv_group_t * group, lv_group_focus_cb_t focus_cb); 179 180 /** 181 * Set whether the next or previous item in a group is focused if the currently focussed obj is 182 * deleted. 183 * @param group pointer to a group 184 * @param new refocus policy enum 185 */ 186 void lv_group_set_refocus_policy(lv_group_t * group, lv_group_refocus_policy_t policy); 187 188 /** 189 * Manually set the current mode (edit or navigate). 190 * @param group pointer to group 191 * @param edit: true: edit mode; false: navigate mode 192 */ 193 void lv_group_set_editing(lv_group_t * group, bool edit); 194 195 /** 196 * Set the `click_focus` attribute. If enabled then the object will be focused then it is clicked. 197 * @param group pointer to group 198 * @param en: true: enable `click_focus` 199 */ 200 void lv_group_set_click_focus(lv_group_t * group, bool en); 201 202 /** 203 * Set whether focus next/prev will allow wrapping from first->last or last->first object. 204 * @param group pointer to group 205 * @param en: true: wrapping enabled; false: wrapping disabled 206 */ 207 void lv_group_set_wrap(lv_group_t * group, bool en); 208 209 /** 210 * Modify a style with the set 'style_mod' function. The input style remains unchanged. 211 * @param group pointer to group 212 * @param style pointer to a style to modify 213 * @return a copy of the input style but modified with the 'style_mod' function 214 */ 215 lv_style_t * lv_group_mod_style(lv_group_t * group, const lv_style_t * style); 216 217 /** 218 * Get the focused object or NULL if there isn't one 219 * @param group pointer to a group 220 * @return pointer to the focused object 221 */ 222 lv_obj_t * lv_group_get_focused(const lv_group_t * group); 223 224 #if LV_USE_USER_DATA 225 /** 226 * Get a pointer to the group's user data 227 * @param group pointer to an group 228 * @return pointer to the user data 229 */ 230 lv_group_user_data_t * lv_group_get_user_data(lv_group_t * group); 231 232 #endif 233 234 /** 235 * Get a the style modifier function of a group 236 * @param group pointer to a group 237 * @return pointer to the style modifier function 238 */ 239 lv_group_style_mod_cb_t lv_group_get_style_mod_cb(const lv_group_t * group); 240 241 /** 242 * Get a the style modifier function of a group in edit mode 243 * @param group pointer to a group 244 * @return pointer to the style modifier function 245 */ 246 lv_group_style_mod_cb_t lv_group_get_style_mod_edit_cb(const lv_group_t * group); 247 248 /** 249 * Get the focus callback function of a group 250 * @param group pointer to a group 251 * @return the call back function or NULL if not set 252 */ 253 lv_group_focus_cb_t lv_group_get_focus_cb(const lv_group_t * group); 254 255 /** 256 * Get the current mode (edit or navigate). 257 * @param group pointer to group 258 * @return true: edit mode; false: navigate mode 259 */ 260 bool lv_group_get_editing(const lv_group_t * group); 261 262 /** 263 * Get the `click_focus` attribute. 264 * @param group pointer to group 265 * @return true: `click_focus` is enabled; false: disabled 266 */ 267 bool lv_group_get_click_focus(const lv_group_t * group); 268 269 /** 270 * Get whether focus next/prev will allow wrapping from first->last or last->first object. 271 * @param group pointer to group 272 * @param en: true: wrapping enabled; false: wrapping disabled 273 */ 274 bool lv_group_get_wrap(lv_group_t * group); 275 276 /** 277 * Notify the group that current theme changed and style modification callbacks need to be 278 * refreshed. 279 * @param group pointer to group. If NULL then all groups are notified. 280 */ 281 void lv_group_report_style_mod(lv_group_t * group); 282 283 /********************** 284 * MACROS 285 **********************/ 286 287 #endif /*LV_USE_GROUP != 0*/ 288 289 #ifdef __cplusplus 290 } /* extern "C" */ 291 #endif 292 293 #endif /*LV_GROUP_H*/ 294