acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

lv_obj.h (14275B)

      1 /**
      2  * @file lv_obj.h
      3  *
      4  */
      5 
      6 #ifndef LV_OBJ_H
      7 #define LV_OBJ_H
      8 
      9 #ifdef __cplusplus
     10 extern "C" {
     11 #endif
     12 
     13 /*********************
     14  *      INCLUDES
     15  *********************/
     16 #include "../lv_conf_internal.h"
     17 
     18 #include <stddef.h>
     19 #include <stdbool.h>
     20 #include "../misc/lv_style.h"
     21 #include "../misc/lv_types.h"
     22 #include "../misc/lv_area.h"
     23 #include "../misc/lv_color.h"
     24 #include "../misc/lv_assert.h"
     25 #include "../hal/lv_hal.h"
     26 
     27 /*********************
     28  *      DEFINES
     29  *********************/
     30 
     31 /**********************
     32  *      TYPEDEFS
     33  **********************/
     34 
     35 struct _lv_obj_t;
     36 
     37 /**
     38  * Possible states of a widget.
     39  * OR-ed values are possible
     40  */
     41 enum {
     42     LV_STATE_DEFAULT     =  0x0000,
     43     LV_STATE_CHECKED     =  0x0001,
     44     LV_STATE_FOCUSED     =  0x0002,
     45     LV_STATE_FOCUS_KEY   =  0x0004,
     46     LV_STATE_EDITED      =  0x0008,
     47     LV_STATE_HOVERED     =  0x0010,
     48     LV_STATE_PRESSED     =  0x0020,
     49     LV_STATE_SCROLLED    =  0x0040,
     50     LV_STATE_DISABLED    =  0x0080,
     51 
     52     LV_STATE_USER_1      =  0x1000,
     53     LV_STATE_USER_2      =  0x2000,
     54     LV_STATE_USER_3      =  0x4000,
     55     LV_STATE_USER_4      =  0x8000,
     56 
     57     LV_STATE_ANY = 0xFFFF,    /**< Special value can be used in some functions to target all states*/
     58 };
     59 
     60 typedef uint16_t lv_state_t;
     61 
     62 /**
     63  * The possible parts of widgets.
     64  * The parts can be considered as the internal building block of the widgets.
     65  * E.g. slider = background + indicator + knob
     66  * Not all parts are used by every widget
     67  */
     68 enum {
     69     LV_PART_MAIN         = 0x000000,   /**< A background like rectangle*/
     70     LV_PART_SCROLLBAR    = 0x010000,   /**< The scrollbar(s)*/
     71     LV_PART_INDICATOR    = 0x020000,   /**< Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox*/
     72     LV_PART_KNOB         = 0x030000,   /**< Like handle to grab to adjust the value*/
     73     LV_PART_SELECTED     = 0x040000,   /**< Indicate the currently selected option or section*/
     74     LV_PART_ITEMS        = 0x050000,   /**< Used if the widget has multiple similar elements (e.g. table cells)*/
     75     LV_PART_TICKS        = 0x060000,   /**< Ticks on scale e.g. for a chart or meter*/
     76     LV_PART_CURSOR       = 0x070000,   /**< Mark a specific place e.g. for text area's cursor or on a chart*/
     77 
     78     LV_PART_CUSTOM_FIRST = 0x080000,    /**< Extension point for custom widgets*/
     79 
     80     LV_PART_ANY          = 0x0F0000,    /**< Special value can be used in some functions to target all parts*/
     81 };
     82 
     83 typedef uint32_t lv_part_t;
     84 
     85 /**
     86  * On/Off features controlling the object's behavior.
     87  * OR-ed values are possible
     88  */
     89 enum {
     90     LV_OBJ_FLAG_HIDDEN          = (1L << 0),  /**< Make the object hidden. (Like it wasn't there at all)*/
     91     LV_OBJ_FLAG_CLICKABLE       = (1L << 1),  /**< Make the object clickable by the input devices*/
     92     LV_OBJ_FLAG_CLICK_FOCUSABLE = (1L << 2),  /**< Add focused state to the object when clicked*/
     93     LV_OBJ_FLAG_CHECKABLE       = (1L << 3),  /**< Toggle checked state when the object is clicked*/
     94     LV_OBJ_FLAG_SCROLLABLE      = (1L << 4),  /**< Make the object scrollable*/
     95     LV_OBJ_FLAG_SCROLL_ELASTIC  = (1L << 5),  /**< Allow scrolling inside but with slower speed*/
     96     LV_OBJ_FLAG_SCROLL_MOMENTUM = (1L << 6),  /**< Make the object scroll further when "thrown"*/
     97     LV_OBJ_FLAG_SCROLL_ONE      = (1L << 7),  /**< Allow scrolling only one snappable children*/
     98     LV_OBJ_FLAG_SCROLL_CHAIN_HOR = (1L << 8), /**< Allow propagating the horizontal scroll to a parent*/
     99     LV_OBJ_FLAG_SCROLL_CHAIN_VER = (1L << 9), /**< Allow propagating the vertical scroll to a parent*/
    100     LV_OBJ_FLAG_SCROLL_CHAIN     = (LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER),
    101     LV_OBJ_FLAG_SCROLL_ON_FOCUS = (1L << 10),  /**< Automatically scroll object to make it visible when focused*/
    102     LV_OBJ_FLAG_SCROLL_WITH_ARROW  = (1L << 11), /**< Allow scrolling the focused object with arrow keys*/
    103     LV_OBJ_FLAG_SNAPPABLE       = (1L << 12), /**< If scroll snap is enabled on the parent it can snap to this object*/
    104     LV_OBJ_FLAG_PRESS_LOCK      = (1L << 13), /**< Keep the object pressed even if the press slid from the object*/
    105     LV_OBJ_FLAG_EVENT_BUBBLE    = (1L << 14), /**< Propagate the events to the parent too*/
    106     LV_OBJ_FLAG_GESTURE_BUBBLE  = (1L << 15), /**< Propagate the gestures to the parent*/
    107     LV_OBJ_FLAG_ADV_HITTEST     = (1L << 16), /**< Allow performing more accurate hit (click) test. E.g. consider rounded corners.*/
    108     LV_OBJ_FLAG_IGNORE_LAYOUT   = (1L << 17), /**< Make the object position-able by the layouts*/
    109     LV_OBJ_FLAG_FLOATING        = (1L << 18), /**< Do not scroll the object when the parent scrolls and ignore layout*/
    110     LV_OBJ_FLAG_OVERFLOW_VISIBLE = (1L << 19), /**< Do not clip the children's content to the parent's boundary*/
    111 
    112     LV_OBJ_FLAG_LAYOUT_1        = (1L << 23), /**< Custom flag, free to use by layouts*/
    113     LV_OBJ_FLAG_LAYOUT_2        = (1L << 24), /**< Custom flag, free to use by layouts*/
    114 
    115     LV_OBJ_FLAG_WIDGET_1        = (1L << 25), /**< Custom flag, free to use by widget*/
    116     LV_OBJ_FLAG_WIDGET_2        = (1L << 26), /**< Custom flag, free to use by widget*/
    117     LV_OBJ_FLAG_USER_1          = (1L << 27), /**< Custom flag, free to use by user*/
    118     LV_OBJ_FLAG_USER_2          = (1L << 28), /**< Custom flag, free to use by user*/
    119     LV_OBJ_FLAG_USER_3          = (1L << 29), /**< Custom flag, free to use by user*/
    120     LV_OBJ_FLAG_USER_4          = (1L << 30), /**< Custom flag, free to use by user*/
    121 
    122 };
    123 
    124 
    125 typedef uint32_t lv_obj_flag_t;
    126 
    127 /**
    128  * `type` field in `lv_obj_draw_part_dsc_t` if `class_p = lv_obj_class`
    129  * Used in `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END`
    130  */
    131 typedef enum {
    132     LV_OBJ_DRAW_PART_RECTANGLE,  /**< The main rectangle*/
    133     LV_OBJ_DRAW_PART_BORDER_POST,/**< The border if style_border_post = true*/
    134     LV_OBJ_DRAW_PART_SCROLLBAR,  /**< The scrollbar*/
    135 } lv_obj_draw_part_type_t;
    136 
    137 #include "lv_obj_tree.h"
    138 #include "lv_obj_pos.h"
    139 #include "lv_obj_scroll.h"
    140 #include "lv_obj_style.h"
    141 #include "lv_obj_draw.h"
    142 #include "lv_obj_class.h"
    143 #include "lv_event.h"
    144 #include "lv_group.h"
    145 
    146 /**
    147  * Make the base object's class publicly available.
    148  */
    149 extern const lv_obj_class_t lv_obj_class;
    150 
    151 /**
    152  * Special, rarely used attributes.
    153  * They are allocated automatically if any elements is set.
    154  */
    155 typedef struct {
    156     struct _lv_obj_t ** children;       /**< Store the pointer of the children in an array.*/
    157     uint32_t child_cnt;                 /**< Number of children*/
    158     lv_group_t * group_p;
    159 
    160     struct _lv_event_dsc_t * event_dsc; /**< Dynamically allocated event callback and user data array*/
    161     lv_point_t scroll;                  /**< The current X/Y scroll offset*/
    162 
    163     lv_coord_t ext_click_pad;           /**< Extra click padding in all direction*/
    164     lv_coord_t ext_draw_size;           /**< EXTend the size in every direction for drawing.*/
    165 
    166     lv_scrollbar_mode_t scrollbar_mode : 2; /**< How to display scrollbars*/
    167     lv_scroll_snap_t scroll_snap_x : 2;     /**< Where to align the snappable children horizontally*/
    168     lv_scroll_snap_t scroll_snap_y : 2;     /**< Where to align the snappable children vertically*/
    169     lv_dir_t scroll_dir : 4;                /**< The allowed scroll direction(s)*/
    170     uint8_t event_dsc_cnt;                  /**< Number of event callbacks stored in `event_dsc` array*/
    171 } _lv_obj_spec_attr_t;
    172 
    173 typedef struct _lv_obj_t {
    174     const lv_obj_class_t * class_p;
    175     struct _lv_obj_t * parent;
    176     _lv_obj_spec_attr_t * spec_attr;
    177     _lv_obj_style_t * styles;
    178 #if LV_USE_USER_DATA
    179     void * user_data;
    180 #endif
    181     lv_area_t coords;
    182     lv_obj_flag_t flags;
    183     lv_state_t state;
    184     uint16_t layout_inv : 1;
    185     uint16_t scr_layout_inv : 1;
    186     uint16_t skip_trans : 1;
    187     uint16_t style_cnt  : 6;
    188     uint16_t h_layout   : 1;
    189     uint16_t w_layout   : 1;
    190 } lv_obj_t;
    191 
    192 
    193 /**********************
    194  * GLOBAL PROTOTYPES
    195  **********************/
    196 
    197 /**
    198  * Initialize LVGL library.
    199  * Should be called before any other LVGL related function.
    200  */
    201 void lv_init(void);
    202 
    203 #if LV_ENABLE_GC || !LV_MEM_CUSTOM
    204 
    205 /**
    206  * Deinit the 'lv' library
    207  * Currently only implemented when not using custom allocators, or GC is enabled.
    208  */
    209 void lv_deinit(void);
    210 
    211 #endif
    212 
    213 /**
    214  * Returns whether the 'lv' library is currently initialized
    215  */
    216 bool lv_is_initialized(void);
    217 
    218 /**
    219  * Create a base object (a rectangle)
    220  * @param parent    pointer to a parent object. If NULL then a screen will be created.
    221  * @return          pointer to the new object
    222  */
    223 lv_obj_t * lv_obj_create(lv_obj_t * parent);
    224 
    225 
    226 /*=====================
    227  * Setter functions
    228  *====================*/
    229 
    230 /**
    231  * Set one or more flags
    232  * @param obj   pointer to an object
    233  * @param f     R-ed values from `lv_obj_flag_t` to set.
    234  */
    235 void lv_obj_add_flag(lv_obj_t * obj, lv_obj_flag_t f);
    236 
    237 /**
    238  * Clear one or more flags
    239  * @param obj   pointer to an object
    240  * @param f     OR-ed values from `lv_obj_flag_t` to set.
    241  */
    242 void lv_obj_clear_flag(lv_obj_t * obj, lv_obj_flag_t f);
    243 
    244 
    245 /**
    246  * Add one or more states to the object. The other state bits will remain unchanged.
    247  * If specified in the styles, transition animation will be started from the previous state to the current.
    248  * @param obj       pointer to an object
    249  * @param state     the states to add. E.g `LV_STATE_PRESSED | LV_STATE_FOCUSED`
    250  */
    251 void lv_obj_add_state(lv_obj_t * obj, lv_state_t state);
    252 
    253 /**
    254  * Remove one or more states to the object. The other state bits will remain unchanged.
    255  * If specified in the styles, transition animation will be started from the previous state to the current.
    256  * @param obj       pointer to an object
    257  * @param state     the states to add. E.g `LV_STATE_PRESSED | LV_STATE_FOCUSED`
    258  */
    259 void lv_obj_clear_state(lv_obj_t * obj, lv_state_t state);
    260 
    261 /**
    262  * Set the user_data field of the object
    263  * @param obj   pointer to an object
    264  * @param user_data   pointer to the new user_data.
    265  */
    266 #if LV_USE_USER_DATA
    267 static inline void lv_obj_set_user_data(lv_obj_t * obj, void * user_data)
    268 {
    269     obj->user_data = user_data;
    270 }
    271 #endif
    272 
    273 /*=======================
    274  * Getter functions
    275  *======================*/
    276 
    277 /**
    278  * Check if a given flag or all the given flags are set on an object.
    279  * @param obj   pointer to an object
    280  * @param f     the flag(s) to check (OR-ed values can be used)
    281  * @return      true: all flags are set; false: not all flags are set
    282  */
    283 bool lv_obj_has_flag(const lv_obj_t * obj, lv_obj_flag_t f);
    284 
    285 /**
    286  * Check if a given flag or any of the flags are set on an object.
    287  * @param obj   pointer to an object
    288  * @param f     the flag(s) to check (OR-ed values can be used)
    289  * @return      true: at lest one flag flag is set; false: none of the flags are set
    290  */
    291 bool lv_obj_has_flag_any(const lv_obj_t * obj, lv_obj_flag_t f);
    292 
    293 /**
    294  * Get the state of an object
    295  * @param obj   pointer to an object
    296  * @return      the state (OR-ed values from `lv_state_t`)
    297  */
    298 lv_state_t lv_obj_get_state(const lv_obj_t * obj);
    299 
    300 /**
    301  * Check if the object is in a given state or not.
    302  * @param obj       pointer to an object
    303  * @param state     a state or combination of states to check
    304  * @return          true: `obj` is in `state`; false: `obj` is not in `state`
    305  */
    306 bool lv_obj_has_state(const lv_obj_t * obj, lv_state_t state);
    307 
    308 /**
    309  * Get the group of the object
    310  * @param       obj pointer to an object
    311  * @return      the pointer to group of the object
    312  */
    313 void * lv_obj_get_group(const lv_obj_t * obj);
    314 
    315 /**
    316  * Get the user_data field of the object
    317  * @param obj   pointer to an object
    318  * @return      the pointer to the user_data of the object
    319  */
    320 #if LV_USE_USER_DATA
    321 static inline void * lv_obj_get_user_data(lv_obj_t * obj)
    322 {
    323     return obj->user_data;
    324 }
    325 #endif
    326 
    327 /*=======================
    328  * Other functions
    329  *======================*/
    330 
    331 /**
    332  * Allocate special data for an object if not allocated yet.
    333  * @param obj   pointer to an object
    334  */
    335 void lv_obj_allocate_spec_attr(lv_obj_t * obj);
    336 
    337 /**
    338  * Check the type of obj.
    339  * @param obj       pointer to an object
    340  * @param class_p   a class to check (e.g. `lv_slider_class`)
    341  * @return          true: `class_p` is the `obj` class.
    342  */
    343 bool lv_obj_check_type(const lv_obj_t * obj, const lv_obj_class_t * class_p);
    344 
    345 /**
    346  * Check if any object has a given class (type).
    347  * It checks the ancestor classes too.
    348  * @param obj       pointer to an object
    349  * @param class_p   a class to check (e.g. `lv_slider_class`)
    350  * @return          true: `obj` has the given class
    351  */
    352 bool lv_obj_has_class(const lv_obj_t * obj, const lv_obj_class_t * class_p);
    353 
    354 /**
    355  * Get the class (type) of the object
    356  * @param obj   pointer to an object
    357  * @return      the class (type) of the object
    358  */
    359 const lv_obj_class_t * lv_obj_get_class(const lv_obj_t * obj);
    360 
    361 /**
    362  * Check if any object is still "alive".
    363  * @param obj       pointer to an object
    364  * @return          true: valid
    365  */
    366 bool lv_obj_is_valid(const lv_obj_t * obj);
    367 
    368 /**
    369  * Scale the given number of pixels (a distance or size) relative to a 160 DPI display
    370  * considering the DPI of the `obj`'s display.
    371  * It ensures that e.g. `lv_dpx(100)` will have the same physical size regardless to the
    372  * DPI of the display.
    373  * @param obj   an object whose display's dpi should be considered
    374  * @param n     the number of pixels to scale
    375  * @return      `n x current_dpi/160`
    376  */
    377 static inline lv_coord_t lv_obj_dpx(const lv_obj_t * obj, lv_coord_t n)
    378 {
    379     return _LV_DPX_CALC(lv_disp_get_dpi(lv_obj_get_disp(obj)), n);
    380 }
    381 
    382 /**********************
    383  *      MACROS
    384  **********************/
    385 
    386 #if LV_USE_ASSERT_OBJ
    387 #  define LV_ASSERT_OBJ(obj_p, obj_class)                                                               \
    388     do {                                                                                                \
    389         LV_ASSERT_MSG(obj_p != NULL, "The object is NULL");                                             \
    390         LV_ASSERT_MSG(lv_obj_has_class(obj_p, obj_class) == true, "Incompatible object type.");         \
    391         LV_ASSERT_MSG(lv_obj_is_valid(obj_p)  == true, "The object is invalid, deleted or corrupted?"); \
    392     } while(0)
    393 # else
    394 #  define LV_ASSERT_OBJ(obj_p, obj_class) do{}while(0)
    395 #endif
    396 
    397 #if LV_USE_LOG && LV_LOG_TRACE_OBJ_CREATE
    398 #  define LV_TRACE_OBJ_CREATE(...) LV_LOG_TRACE(__VA_ARGS__)
    399 #else
    400 #  define LV_TRACE_OBJ_CREATE(...)
    401 #endif
    402 
    403 
    404 #ifdef __cplusplus
    405 } /*extern "C"*/
    406 #endif
    407 
    408 #endif /*LV_OBJ_H*/