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