From 03ac0284ae0363c97047496263d8690850b9e6cb Mon Sep 17 00:00:00 2001 From: Amir Gonnen Date: Thu, 27 Jun 2019 21:44:20 +0300 Subject: [PATCH 1/6] Fix uninitialized var warning --- src/lv_draw/lv_img_decoder.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lv_draw/lv_img_decoder.c b/src/lv_draw/lv_img_decoder.c index 1c64daf0b..c9f5448f6 100644 --- a/src/lv_draw/lv_img_decoder.c +++ b/src/lv_draw/lv_img_decoder.c @@ -126,7 +126,7 @@ lv_res_t lv_img_decoder_open(lv_img_decoder_dsc_t * dsc, const void * src, const dsc->src_type = lv_img_src_get_type(src); dsc->user_data = NULL; - lv_res_t res; + lv_res_t res = LV_RES_INV; lv_img_decoder_t * d; LV_LL_READ(LV_GC_ROOT(_lv_img_defoder_ll), d) From bbc9c886c6edf8891232683923323e503905a940 Mon Sep 17 00:00:00 2001 From: Themba Dube Date: Thu, 27 Jun 2019 18:07:26 -0400 Subject: [PATCH 2/6] Update Doxygen comments --- src/lv_core/lv_disp.h | 6 ++ src/lv_core/lv_group.h | 26 +++--- src/lv_core/lv_obj.h | 161 +++++++++++++++++++--------------- src/lv_core/lv_style.h | 59 ++++++++----- src/lv_draw/lv_draw_label.h | 8 +- src/lv_draw/lv_img_cache.h | 14 ++- src/lv_draw/lv_img_decoder.h | 46 +++++----- src/lv_font/lv_font.h | 26 +++--- src/lv_font/lv_font_fmt_txt.h | 33 +++---- src/lv_font/lv_symbol_def.h | 4 +- src/lv_hal/lv_hal_disp.h | 62 +++++++------ src/lv_hal/lv_hal_indev.h | 73 +++++++-------- src/lv_misc/lv_anim.h | 44 +++++----- src/lv_misc/lv_area.h | 4 + src/lv_misc/lv_color.h | 3 + src/lv_misc/lv_fs.h | 8 +- src/lv_misc/lv_ll.h | 4 +- src/lv_misc/lv_log.h | 10 +-- src/lv_misc/lv_math.h | 6 +- src/lv_misc/lv_mem.h | 11 ++- src/lv_misc/lv_task.h | 12 +-- src/lv_misc/lv_txt.h | 19 ++-- src/lv_misc/lv_types.h | 3 + src/lv_objx/lv_bar.h | 5 +- src/lv_objx/lv_btnm.h | 14 +-- src/lv_objx/lv_calendar.h | 21 +++-- src/lv_objx/lv_cb.h | 13 +-- src/lv_objx/lv_chart.h | 26 +++--- src/lv_objx/lv_cont.h | 35 ++++---- src/lv_objx/lv_imgbtn.h | 2 +- src/lv_objx/lv_kb.h | 1 + src/lv_objx/lv_label.h | 26 +++--- src/lv_objx/lv_list.h | 11 +-- src/lv_objx/lv_mbox.h | 3 +- src/lv_objx/lv_page.h | 16 ++-- src/lv_objx/lv_preload.h | 6 ++ src/lv_objx/lv_roller.h | 6 +- src/lv_objx/lv_slider.h | 8 +- src/lv_objx/lv_sw.h | 15 ++-- src/lv_objx/lv_ta.h | 24 ++--- src/lv_objx/lv_table.h | 5 ++ src/lv_objx/lv_tabview.h | 1 + src/lv_objx/lv_win.h | 11 +-- src/lv_themes/lv_theme.h | 6 ++ src/lv_version.h | 2 +- 45 files changed, 508 insertions(+), 391 deletions(-) diff --git a/src/lv_core/lv_disp.h b/src/lv_core/lv_disp.h index 14e18759f..e9802f9fc 100644 --- a/src/lv_core/lv_disp.h +++ b/src/lv_core/lv_disp.h @@ -132,10 +132,16 @@ static inline void lv_scr_load(lv_obj_t * scr) *------------------------------------------------*/ #ifndef LV_HOR_RES +/** + * The horizontal resolution of the currently active display. + */ #define LV_HOR_RES lv_disp_get_hor_res(lv_disp_get_default()) #endif #ifndef LV_VER_RES +/** + * The vertical resolution of the currently active display. + */ #define LV_VER_RES lv_disp_get_ver_res(lv_disp_get_default()) #endif diff --git a/src/lv_core/lv_group.h b/src/lv_core/lv_group.h index 58b258d6d..c27f76939 100644 --- a/src/lv_core/lv_group.h +++ b/src/lv_core/lv_group.h @@ -52,26 +52,30 @@ struct _lv_group_t; typedef void (*lv_group_style_mod_cb_t)(struct _lv_group_t *, lv_style_t *); typedef void (*lv_group_focus_cb_t)(struct _lv_group_t *); +/** + * Groups can be used to logically hold objects so that they can be individually focused. + * They are NOT for laying out objects on a screen (try `lv_cont` for that). + */ typedef struct _lv_group_t { - lv_ll_t obj_ll; /*Linked list to store the objects in the group */ - lv_obj_t ** obj_focus; /*The object in focus*/ + lv_ll_t obj_ll; /**< Linked list to store the objects in the group */ + lv_obj_t ** obj_focus; /**< The object in focus*/ - lv_group_style_mod_cb_t style_mod_cb; /*A function to modifies the style of the focused object*/ - lv_group_style_mod_cb_t style_mod_edit_cb; /*A function which modifies the style of the edited object*/ - lv_group_focus_cb_t focus_cb; /*A function to call when a new object is focused (optional)*/ - lv_style_t style_tmp; /*Stores the modified style of the focused object */ + lv_group_style_mod_cb_t style_mod_cb; /**< A function to modifies the style of the focused object*/ + lv_group_style_mod_cb_t style_mod_edit_cb; /**< A function which modifies the style of the edited object*/ + lv_group_focus_cb_t focus_cb; /**< A function to call when a new object is focused (optional)*/ + lv_style_t style_tmp; /**< Stores the modified style of the focused object */ #if LV_USE_USER_DATA lv_group_user_data_t user_data; #endif - uint8_t frozen : 1; /*1: can't focus to new object*/ - uint8_t editing : 1; /*1: Edit mode, 0: Navigate mode*/ - uint8_t click_focus : 1; /*1: If an object in a group is clicked by an indev then it will be + uint8_t frozen : 1; /**< 1: can't focus to new object*/ + uint8_t editing : 1; /**< 1: Edit mode, 0: Navigate mode*/ + uint8_t click_focus : 1; /**< 1: If an object in a group is clicked by an indev then it will be focused */ - uint8_t refocus_policy : 1; /*1: Focus prev if focused on deletion. 0: Focus next if focused on + uint8_t refocus_policy : 1; /**< 1: Focus prev if focused on deletion. 0: Focus next if focused on deletion.*/ - uint8_t wrap : 1; /*1: Focus next/prev can wrap at end of list. 0: Focus next/prev stops at end + uint8_t wrap : 1; /**< 1: Focus next/prev can wrap at end of list. 0: Focus next/prev stops at end of list.*/ } lv_group_t; diff --git a/src/lv_core/lv_obj.h b/src/lv_core/lv_obj.h index d6bc3fc19..07ada0826 100644 --- a/src/lv_core/lv_obj.h +++ b/src/lv_core/lv_obj.h @@ -55,62 +55,76 @@ extern "C" { struct _lv_obj_t; + +/** Design modes */ enum { - LV_DESIGN_DRAW_MAIN, - LV_DESIGN_DRAW_POST, - LV_DESIGN_COVER_CHK, + LV_DESIGN_DRAW_MAIN, /**< Draw the main portion of the object */ + LV_DESIGN_DRAW_POST, /**< Draw extras on the object */ + LV_DESIGN_COVER_CHK, /**< Check if the object fully covers the 'mask_p' area */ }; typedef uint8_t lv_design_mode_t; +/** + * The design callback is used to draw the object on the screen. + * It accepts the object, a mask area, and the mode in which to draw the object. + */ typedef bool (*lv_design_cb_t)(struct _lv_obj_t * obj, const lv_area_t * mask_p, lv_design_mode_t mode); enum { - LV_EVENT_PRESSED, /*The object has been pressed*/ - LV_EVENT_PRESSING, /*The object is being pressed (called continuously while pressing)*/ - LV_EVENT_PRESS_LOST, /*Still pressing but slid from the objects*/ - LV_EVENT_SHORT_CLICKED, /*Released before long press time. Not called if dragged.*/ - LV_EVENT_LONG_PRESSED, /*Pressing for `LV_INDEV_LONG_PRESS_TIME` time. Not called if dragged.*/ - LV_EVENT_LONG_PRESSED_REPEAT, /*Called after `LV_INDEV_LONG_PRESS_TIME` in every - `LV_INDEV_LONG_PRESS_REP_TIME` ms. Not called if dragged.*/ - LV_EVENT_CLICKED, /*Called on release if not dragged (regardless to long press)*/ - LV_EVENT_RELEASED, /*Called in every cases when the object has been released*/ - LV_EVENT_DRAG_BEGIN, + LV_EVENT_PRESSED, /**< The object has been pressed*/ + LV_EVENT_PRESSING, /**< The object is being pressed (called continuously while pressing)*/ + LV_EVENT_PRESS_LOST, /**< User is still pressing but slid cursor/finger off of the object */ + LV_EVENT_SHORT_CLICKED, /**< User pressed object for a short period of time, then released it. Not called if dragged. */ + LV_EVENT_LONG_PRESSED, /**< Object has been pressed for at least `LV_INDEV_LONG_PRESS_TIME`. Not called if dragged.*/ + LV_EVENT_LONG_PRESSED_REPEAT, /**< Called after `LV_INDEV_LONG_PRESS_TIME` in every + `LV_INDEV_LONG_PRESS_REP_TIME` ms. Not called if dragged.*/ + LV_EVENT_CLICKED, /**< Called on release if not dragged (regardless to long press)*/ + LV_EVENT_RELEASED, /**< Called in every cases when the object has been released*/ + LV_EVENT_DRAG_BEGIN, LV_EVENT_DRAG_END, LV_EVENT_DRAG_THROW_BEGIN, LV_EVENT_KEY, LV_EVENT_FOCUSED, LV_EVENT_DEFOCUSED, - LV_EVENT_VALUE_CHANGED, + LV_EVENT_VALUE_CHANGED, /**< The object's value has changed (i.e. slider moved) */ LV_EVENT_INSERT, LV_EVENT_REFRESH, - LV_EVENT_APPLY, /*"Ok", "Apply" or similar specific button has clicked*/ - LV_EVENT_CANCEL, /*"Close", "Cancel" or similar specific button has clicked*/ - LV_EVENT_DELETE, + LV_EVENT_APPLY, /**< "Ok", "Apply" or similar specific button has clicked*/ + LV_EVENT_CANCEL, /**< "Close", "Cancel" or similar specific button has clicked*/ + LV_EVENT_DELETE, /**< Object is being deleted */ }; -typedef uint8_t lv_event_t; +typedef uint8_t lv_event_t; /**< Type of event being sent to the object. */ +/** + * @brief Event callback. + * Events are used to notify the user of some action being taken on the object. + * For details, see ::lv_event_t. + */ typedef void (*lv_event_cb_t)(struct _lv_obj_t * obj, lv_event_t event); +/** Signals are for use by the object itself or to extend the object's functionality. + * Applications should use ::lv_obj_set_event_cb to be notified of events that occur + * on the object. */ enum { /*General signals*/ - LV_SIGNAL_CLEANUP, - LV_SIGNAL_CHILD_CHG, - LV_SIGNAL_CORD_CHG, - LV_SIGNAL_PARENT_SIZE_CHG, - LV_SIGNAL_STYLE_CHG, - LV_SIGNAL_REFR_EXT_DRAW_PAD, - LV_SIGNAL_GET_TYPE, + LV_SIGNAL_CLEANUP, /**< Object is being deleted */ + LV_SIGNAL_CHILD_CHG, /**< Child was removed/added */ + LV_SIGNAL_CORD_CHG, /**< Object coordinates/size have changed */ + LV_SIGNAL_PARENT_SIZE_CHG, /**< Parent's size has changed */ + LV_SIGNAL_STYLE_CHG, /**< Object's style has changed */ + LV_SIGNAL_REFR_EXT_DRAW_PAD, /**< Object's extra padding has changed */ + LV_SIGNAL_GET_TYPE, /**< LittlevGL needs to retrieve the object's type */ /*Input device related*/ - LV_SIGNAL_PRESSED, - LV_SIGNAL_PRESSING, - LV_SIGNAL_PRESS_LOST, - LV_SIGNAL_RELEASED, - LV_SIGNAL_LONG_PRESS, - LV_SIGNAL_LONG_PRESS_REP, - LV_SIGNAL_DRAG_BEGIN, - LV_SIGNAL_DRAG_END, - + LV_SIGNAL_PRESSED, /**< The object has been pressed*/ + LV_SIGNAL_PRESSING, /**< The object is being pressed (called continuously while pressing)*/ + LV_SIGNAL_PRESS_LOST, /**< User is still pressing but slid cursor/finger off of the object */ + LV_SIGNAL_RELEASED, /**< User pressed object for a short period of time, then released it. Not called if dragged. */ + LV_SIGNAL_LONG_PRESS, /**< Object has been pressed for at least `LV_INDEV_LONG_PRESS_TIME`. Not called if dragged.*/ + LV_SIGNAL_LONG_PRESS_REP, /**< Called after `LV_INDEV_LONG_PRESS_TIME` in every + LV_SIGNAL_DRAG_BEGIN, `LV_INDEV_LONG_PRESS_REP_TIME` ms. Not called if dragged.*/ + LV_SIGNAL_DRAG_END, /**< Called on release if not dragged (regardless to long press)*/ + /**< Called in every cases when the object has been released*/ /*Group related*/ LV_SIGNAL_FOCUS, LV_SIGNAL_DEFOCUS, @@ -121,6 +135,7 @@ typedef uint8_t lv_signal_t; typedef lv_res_t (*lv_signal_cb_t)(struct _lv_obj_t * obj, lv_signal_t sign, void * param); +/** Object alignment. */ enum { LV_ALIGN_CENTER = 0, LV_ALIGN_IN_TOP_LEFT, @@ -154,69 +169,69 @@ typedef struct lv_coord_t yofs; lv_align_t align; uint8_t auto_realign : 1; - uint8_t origo_align : 1; /*1: the oigo (center of the object) was aligned with + uint8_t origo_align : 1; /**< 1: the origo (center of the object) was aligned with `lv_obj_align_origo`*/ } lv_reailgn_t; #endif enum { - LV_DRAG_DIR_HOR = 0x1, - LV_DRAG_DIR_VER = 0x2, - LV_DRAG_DIR_ALL = 0x3, /* Should be the bitwise OR of the above */ + LV_DRAG_DIR_HOR = 0x1, /**< Object can be dragged horizontally. */ + LV_DRAG_DIR_VER = 0x2, /**< Object can be dragged vertically. */ + LV_DRAG_DIR_ALL = 0x3, /**< Object can be dragged in all directions. */ }; typedef uint8_t lv_drag_dir_t; typedef struct _lv_obj_t { - struct _lv_obj_t * par; /*Pointer to the parent object*/ - lv_ll_t child_ll; /*Linked list to store the children objects*/ + struct _lv_obj_t * par; /**< Pointer to the parent object*/ + lv_ll_t child_ll; /**< Linked list to store the children objects*/ - lv_area_t coords; /*Coordinates of the object (x1, y1, x2, y2)*/ + lv_area_t coords; /**< Coordinates of the object (x1, y1, x2, y2)*/ - lv_event_cb_t event_cb; - lv_signal_cb_t signal_cb; /*Object type specific signal function*/ - lv_design_cb_t design_cb; /*Object type specific design function*/ + lv_event_cb_t event_cb; /**< Event callback function */ + lv_signal_cb_t signal_cb; /**< Object type specific signal function*/ + lv_design_cb_t design_cb; /**< Object type specific design function*/ - void * ext_attr; /*Object type specific extended data*/ - const lv_style_t * style_p; /*Pointer to the object's style*/ + void * ext_attr; /**< Object type specific extended data*/ + const lv_style_t * style_p; /**< Pointer to the object's style*/ #if LV_USE_GROUP != 0 - void * group_p; /*Pointer to the group of the object*/ + void * group_p; /**< Pointer to the group of the object*/ #endif #if LV_USE_EXT_CLICK_AREA == LV_EXT_CLICK_AREA_TINY - uint8_t ext_click_pad_hor; - uint8_t ext_click_pad_ver; + uint8_t ext_click_pad_hor; /**< Extra click padding in horizontal direction */ + uint8_t ext_click_pad_ver; /**< Extra click padding in vertical direction */ #endif #if LV_USE_EXT_CLICK_AREA == LV_EXT_CLICK_AREA_FULL - lv_area_t ext_click_pad; + lv_area_t ext_click_pad; /**< Extra click padding area. */ #endif /*Attributes and states*/ - uint8_t click : 1; /*1: Can be pressed by an input device*/ - uint8_t drag : 1; /*1: Enable the dragging*/ - uint8_t drag_throw : 1; /*1: Enable throwing with drag*/ - uint8_t drag_parent : 1; /*1: Parent will be dragged instead*/ - uint8_t hidden : 1; /*1: Object is hidden*/ - uint8_t top : 1; /*1: If the object or its children is clicked it goes to the foreground*/ - uint8_t opa_scale_en : 1; /*1: opa_scale is set*/ - uint8_t parent_event : 1; /*1: Send the object's events to the parent too. */ - lv_drag_dir_t drag_dir : 2; /* Which directions the object can be dragged in */ - uint8_t reserved : 6; /*Reserved for future use*/ - uint8_t protect; /*Automatically happening actions can be prevented. 'OR'ed values from + uint8_t click : 1; /**< 1: Can be pressed by an input device*/ + uint8_t drag : 1; /**< 1: Enable the dragging*/ + uint8_t drag_throw : 1; /**< 1: Enable throwing with drag*/ + uint8_t drag_parent : 1; /**< 1: Parent will be dragged instead*/ + uint8_t hidden : 1; /**< 1: Object is hidden*/ + uint8_t top : 1; /**< 1: If the object or its children is clicked it goes to the foreground*/ + uint8_t opa_scale_en : 1; /**< 1: opa_scale is set*/ + uint8_t parent_event : 1; /**< 1: Send the object's events to the parent too. */ + lv_drag_dir_t drag_dir : 2; /**< Which directions the object can be dragged in */ + uint8_t reserved : 6; /**< Reserved for future use*/ + uint8_t protect; /**< Automatically happening actions can be prevented. 'OR'ed values from `lv_protect_t`*/ - lv_opa_t opa_scale; /*Scale down the opacity by this factor. Effects all children as well*/ + lv_opa_t opa_scale; /**< Scale down the opacity by this factor. Effects all children as well*/ - lv_coord_t ext_draw_pad; /*EXTtend the size in every direction for drawing. */ + lv_coord_t ext_draw_pad; /**< EXTtend the size in every direction for drawing. */ #if LV_USE_OBJ_REALIGN - lv_reailgn_t realign; + lv_reailgn_t realign; /**< Information about the last call to ::lv_obj_align. */ #endif #if LV_USE_USER_DATA - lv_obj_user_data_t user_data; + lv_obj_user_data_t user_data; /**< Custom user data for object. */ #endif } lv_obj_t; @@ -224,21 +239,21 @@ typedef struct _lv_obj_t /*Protect some attributes (max. 8 bit)*/ enum { LV_PROTECT_NONE = 0x00, - LV_PROTECT_CHILD_CHG = 0x01, /*Disable the child change signal. Used by the library*/ - LV_PROTECT_PARENT = 0x02, /*Prevent automatic parent change (e.g. in lv_page)*/ - LV_PROTECT_POS = 0x04, /*Prevent automatic positioning (e.g. in lv_cont layout)*/ - LV_PROTECT_FOLLOW = 0x08, /*Prevent the object be followed in automatic ordering (e.g. in + LV_PROTECT_CHILD_CHG = 0x01, /**< Disable the child change signal. Used by the library*/ + LV_PROTECT_PARENT = 0x02, /**< Prevent automatic parent change (e.g. in lv_page)*/ + LV_PROTECT_POS = 0x04, /**< Prevent automatic positioning (e.g. in lv_cont layout)*/ + LV_PROTECT_FOLLOW = 0x08, /**< Prevent the object be followed in automatic ordering (e.g. in lv_cont PRETTY layout)*/ - LV_PROTECT_PRESS_LOST = 0x10, /*If the `indev` was pressing this object but swiped out while + LV_PROTECT_PRESS_LOST = 0x10, /**< If the `indev` was pressing this object but swiped out while pressing do not search other object.*/ - LV_PROTECT_CLICK_FOCUS = 0x20, /*Prevent focusing the object by clicking on it*/ + LV_PROTECT_CLICK_FOCUS = 0x20, /**< Prevent focusing the object by clicking on it*/ }; typedef uint8_t lv_protect_t; -/*Used by `lv_obj_get_type()`. The object's and its ancestor types are stored here*/ +/** Used by `lv_obj_get_type()`. The object's and its ancestor types are stored here*/ typedef struct { - const char * type[LV_MAX_ANCESTOR_NUM]; /*[0]: the actual type, [1]: ancestor, [2] #1's ancestor + const char * type[LV_MAX_ANCESTOR_NUM]; /**< [0]: the actual type, [1]: ancestor, [2] #1's ancestor ... [x]: "lv_obj" */ } lv_obj_type_t; diff --git a/src/lv_core/lv_style.h b/src/lv_core/lv_style.h index b1a13e9ac..f8eb79b10 100644 --- a/src/lv_core/lv_style.h +++ b/src/lv_core/lv_style.h @@ -22,7 +22,7 @@ extern "C" { /********************* * DEFINES *********************/ -#define LV_RADIUS_CIRCLE (LV_COORD_MAX) /*A very big radius to always draw as circle*/ +#define LV_RADIUS_CIRCLE (LV_COORD_MAX) /**< A very big radius to always draw as circle*/ /********************** * TYPEDEFS @@ -36,41 +36,50 @@ enum { LV_BORDER_LEFT = 0x04, LV_BORDER_RIGHT = 0x08, LV_BORDER_FULL = 0x0F, - LV_BORDER_INTERNAL = 0x10, /*FOR matrix-like objects (e.g. Button matrix)*/ + LV_BORDER_INTERNAL = 0x10, /**< FOR matrix-like objects (e.g. Button matrix)*/ }; typedef uint8_t lv_border_part_t; /*Shadow types*/ enum { - LV_SHADOW_BOTTOM = 0, - LV_SHADOW_FULL, + LV_SHADOW_BOTTOM = 0, /**< Only draw bottom shadow */ + LV_SHADOW_FULL, /**< Draw shadow on all sides */ }; typedef uint8_t lv_shadow_type_t; +/** + * Objects in LittlevGL can be assigned a style - which holds information about + * how the object should be drawn. + * + * This allows for easy customization without having to modify the object's design + * function. + */ typedef struct { - uint8_t glass : 1; /*1: Do not inherit this style*/ + uint8_t glass : 1; /**< 1: Do not inherit this style*/ + /** Object background. */ struct { - lv_color_t main_color; - lv_color_t grad_color; /*`grad_color` will be removed in v6.0, use `aux_color` instead*/ - lv_coord_t radius; - lv_opa_t opa; + lv_color_t main_color; /**< Object's main background color. */ + lv_color_t grad_color; /**< Second color. If not equal to `main_color` a gradient will be drawn for the background. */ + lv_coord_t radius; /**< Object's corner radius. You can use #LV_RADIUS_CIRCLE if you want to draw a circle. */ + lv_opa_t opa; /**< Object's opacity (0-255). */ struct { - lv_color_t color; - lv_coord_t width; - lv_border_part_t part; - lv_opa_t opa; + lv_color_t color; /**< Border color */ + lv_coord_t width; /**< Border width */ + lv_border_part_t part; /**< Which borders to draw */ + lv_opa_t opa; /**< Border opacity. */ } border; + struct { lv_color_t color; lv_coord_t width; - lv_shadow_type_t type; + lv_shadow_type_t type; /**< Which parts of the shadow to draw */ } shadow; struct @@ -83,33 +92,37 @@ typedef struct } padding; } body; + /** Style for text drawn by this object. */ struct { - lv_color_t color; - lv_color_t sel_color; + lv_color_t color; /**< Text color */ + lv_color_t sel_color; /**< Text selection background color. */ const lv_font_t * font; - lv_coord_t letter_space; - lv_coord_t line_space; - lv_opa_t opa; + lv_coord_t letter_space; /**< Space between letters */ + lv_coord_t line_space; /**< Space between lines (vertical) */ + lv_opa_t opa; /**< Text opacity */ } text; + /**< Style of images. */ struct { - lv_color_t color; - lv_opa_t intense; - lv_opa_t opa; + lv_color_t color; /**< Color to recolor the image with */ + lv_opa_t intense; /**< Opacity of recoloring (0 means no recoloring) */ + lv_opa_t opa; /**< Opacity of whole image */ } image; + /**< Style of lines (not borders). */ struct { lv_color_t color; lv_coord_t width; lv_opa_t opa; - uint8_t rounded : 1; /*1: rounded line endings*/ + uint8_t rounded : 1; /**< 1: rounded line endings*/ } line; } lv_style_t; #if LV_USE_ANIMATION +/** Data structure for style animations. */ typedef struct { lv_style_t style_start; /*Save not only pointers because can be same as 'style_anim' then it diff --git a/src/lv_draw/lv_draw_label.h b/src/lv_draw/lv_draw_label.h index ebc66d430..44eb2fa99 100644 --- a/src/lv_draw/lv_draw_label.h +++ b/src/lv_draw/lv_draw_label.h @@ -23,19 +23,19 @@ extern "C" { * TYPEDEFS **********************/ -/* Store some info to speed up drawing of very large texts +/** Store some info to speed up drawing of very large texts * It takes a lot of time to get the first visible character because * all the previous characters needs to be checked to calculate the positions. * This structure stores an earlier (e.g. at -1000 px) coordinate and the index of that line. * Therefore the calculations can start from here.*/ typedef struct { - /*Index of the line at `y` coordinate*/ + /** Index of the line at `y` coordinate*/ int32_t line_start; - /*Give the `y` coordinate of the first letter at `line start` index. Relative to the label's coordinates*/ + /** Give the `y` coordinate of the first letter at `line start` index. Relative to the label's coordinates*/ int32_t y; - /*The 'y1' coordinate of the label when the hint was saved. + /** The 'y1' coordinate of the label when the hint was saved. * Used to invalidate the hint if the label has moved too much. */ int32_t coord_y; }lv_draw_label_hint_t; diff --git a/src/lv_draw/lv_img_cache.h b/src/lv_draw/lv_img_cache.h index 112724764..2cfa4d49d 100644 --- a/src/lv_draw/lv_img_cache.h +++ b/src/lv_draw/lv_img_cache.h @@ -22,13 +22,19 @@ extern "C" { /********************** * TYPEDEFS **********************/ + +/** + * When loading images from the network it can take a long time to download and decode the image. + * + * To avoid repeating this heavy load images can be cached. + */ typedef struct { - lv_img_decoder_dsc_t dec_dsc; + lv_img_decoder_dsc_t dec_dsc; /**< Image information */ - /* Count the cache entries's life. Add `time_tio_open` to `life` when the entry is used. - * Decrement all lifes by one every in every `lv_img_cache_open`. - * If life == 0 the entry can be reused,*/ + /** Count the cache entries's life. Add `time_tio_open` to `life` when the entry is used. + * Decrement all lifes by one every in every ::lv_img_cache_open. + * If life == 0 the entry can be reused */ int32_t life; }lv_img_cache_entry_t; diff --git a/src/lv_draw/lv_img_decoder.h b/src/lv_draw/lv_img_decoder.h index 9e4045fd9..4f64005d2 100644 --- a/src/lv_draw/lv_img_decoder.h +++ b/src/lv_draw/lv_img_decoder.h @@ -41,15 +41,19 @@ extern "C" { * TYPEDEFS **********************/ +/** + * Source of image. */ enum { - LV_IMG_SRC_VARIABLE, - LV_IMG_SRC_FILE, - LV_IMG_SRC_SYMBOL, - LV_IMG_SRC_UNKNOWN, + LV_IMG_SRC_VARIABLE, /** Binary/C variable */ + LV_IMG_SRC_FILE, /** File in filesystem */ + LV_IMG_SRC_SYMBOL, /** Symbol (@ref lv_symbol_def.h) */ + LV_IMG_SRC_UNKNOWN, /** Unknown source */ }; typedef uint8_t lv_img_src_t; - +/** + * LittlevGL image header + */ typedef struct { @@ -69,31 +73,31 @@ typedef struct enum { LV_IMG_CF_UNKNOWN = 0, - LV_IMG_CF_RAW, /*Contains the file as it is. Needs custom decoder function*/ - LV_IMG_CF_RAW_ALPHA, /*Contains the file as it is. The image has alpha. Needs custom decoder + LV_IMG_CF_RAW, /**< Contains the file as it is. Needs custom decoder function*/ + LV_IMG_CF_RAW_ALPHA, /**< Contains the file as it is. The image has alpha. Needs custom decoder function*/ - LV_IMG_CF_RAW_CHROMA_KEYED, /*Contains the file as it is. The image is chroma keyed. Needs + LV_IMG_CF_RAW_CHROMA_KEYED, /**< Contains the file as it is. The image is chroma keyed. Needs custom decoder function*/ - LV_IMG_CF_TRUE_COLOR, /*Color format and depth should match with LV_COLOR settings*/ - LV_IMG_CF_TRUE_COLOR_ALPHA, /*Same as `LV_IMG_CF_TRUE_COLOR` but every pixel has an alpha byte*/ - LV_IMG_CF_TRUE_COLOR_CHROMA_KEYED, /*Same as `LV_IMG_CF_TRUE_COLOR` but LV_COLOR_TRANSP pixels + LV_IMG_CF_TRUE_COLOR, /**< Color format and depth should match with LV_COLOR settings*/ + LV_IMG_CF_TRUE_COLOR_ALPHA, /**< Same as `LV_IMG_CF_TRUE_COLOR` but every pixel has an alpha byte*/ + LV_IMG_CF_TRUE_COLOR_CHROMA_KEYED, /**< Same as `LV_IMG_CF_TRUE_COLOR` but LV_COLOR_TRANSP pixels will be transparent*/ - LV_IMG_CF_INDEXED_1BIT, /*Can have 2 different colors in a palette (always chroma keyed)*/ - LV_IMG_CF_INDEXED_2BIT, /*Can have 4 different colors in a palette (always chroma keyed)*/ - LV_IMG_CF_INDEXED_4BIT, /*Can have 16 different colors in a palette (always chroma keyed)*/ - LV_IMG_CF_INDEXED_8BIT, /*Can have 256 different colors in a palette (always chroma keyed)*/ + LV_IMG_CF_INDEXED_1BIT, /**< Can have 2 different colors in a palette (always chroma keyed)*/ + LV_IMG_CF_INDEXED_2BIT, /**< Can have 4 different colors in a palette (always chroma keyed)*/ + LV_IMG_CF_INDEXED_4BIT, /**< Can have 16 different colors in a palette (always chroma keyed)*/ + LV_IMG_CF_INDEXED_8BIT, /**< Can have 256 different colors in a palette (always chroma keyed)*/ - LV_IMG_CF_ALPHA_1BIT, /*Can have one color and it can be drawn or not*/ - LV_IMG_CF_ALPHA_2BIT, /*Can have one color but 4 different alpha value*/ - LV_IMG_CF_ALPHA_4BIT, /*Can have one color but 16 different alpha value*/ - LV_IMG_CF_ALPHA_8BIT, /*Can have one color but 256 different alpha value*/ + LV_IMG_CF_ALPHA_1BIT, /**< Can have one color and it can be drawn or not*/ + LV_IMG_CF_ALPHA_2BIT, /**< Can have one color but 4 different alpha value*/ + LV_IMG_CF_ALPHA_4BIT, /**< Can have one color but 16 different alpha value*/ + LV_IMG_CF_ALPHA_8BIT, /**< Can have one color but 256 different alpha value*/ }; typedef uint8_t lv_img_cf_t; -/* Image header it is compatible with - * the result image converter utility*/ +/** Image header it is compatible with + * the result from image converter utility*/ typedef struct { lv_img_header_t header; diff --git a/src/lv_font/lv_font.h b/src/lv_font/lv_font.h index 53c3ada41..e639a54a3 100644 --- a/src/lv_font/lv_font.h +++ b/src/lv_font/lv_font.h @@ -42,32 +42,32 @@ extern "C" { * General types *-----------------*/ -/*Describe the properties of a glyph*/ +/** Describes the properties of a glyph. */ typedef struct { - uint16_t adv_w; /*The glyph needs this space. Draw the next glyph after this width. 8 bit integer, 4 bit fractional */ - uint8_t box_w; /*Width of the glyph's bounding box*/ - uint8_t box_h; /*Height of the glyph's bounding box*/ - int8_t ofs_x; /*x offset of the bounding box*/ - int8_t ofs_y; /*y offset of the bounding box*/ - uint8_t bpp; /*Bit-per-pixel: 1, 2, 4, 8*/ + uint16_t adv_w; /**< The glyph needs this space. Draw the next glyph after this width. 8 bit integer, 4 bit fractional */ + uint8_t box_w; /**< Width of the glyph's bounding box*/ + uint8_t box_h; /**< Height of the glyph's bounding box*/ + int8_t ofs_x; /**< x offset of the bounding box*/ + int8_t ofs_y; /**< y offset of the bounding box*/ + uint8_t bpp; /**< Bit-per-pixel: 1, 2, 4, 8*/ }lv_font_glyph_dsc_t; /*Describe the properties of a font*/ typedef struct _lv_font_struct { - /*Get a glyph's descriptor from a font*/ + /** Get a glyph's descriptor from a font*/ bool (*get_glyph_dsc)(const struct _lv_font_struct *, lv_font_glyph_dsc_t *, uint32_t letter, uint32_t letter_next); - /*Get a glyph's bitmap from a font*/ + /** Get a glyph's bitmap from a font*/ const uint8_t * (*get_glyph_bitmap)(const struct _lv_font_struct *, uint32_t); /*Pointer to the font in a font pack (must have the same line height)*/ - uint8_t line_height; /*The real line height where any text fits*/ - uint8_t base_line; /*Base line measured from the top of the line_height*/ - void * dsc; /*Store implementation specific data here*/ + uint8_t line_height; /**< The real line height where any text fits*/ + uint8_t base_line; /**< Base line measured from the top of the line_height*/ + void * dsc; /**< Store implementation specific data here*/ #if LV_USE_USER_DATA - lv_font_user_data_t user_data; + lv_font_user_data_t user_data; /**< Custom user data for font. */ #endif } lv_font_t; diff --git a/src/lv_font/lv_font_fmt_txt.h b/src/lv_font/lv_font_fmt_txt.h index 34678bdb5..d166e934c 100644 --- a/src/lv_font/lv_font_fmt_txt.h +++ b/src/lv_font/lv_font_fmt_txt.h @@ -32,19 +32,20 @@ extern "C" { * TYPEDEFS **********************/ -/*Describe a glyph*/ +/** This describes a glyph. */ typedef struct { - uint32_t bitmap_index : 20; /* Start index of the bitmap. A font can be max 1 MB. */ - uint32_t adv_w :12; /*Draw the next glyph after this width. 12.4 format (real_value * 16 is stored). */ + uint32_t bitmap_index : 20; /**< Start index of the bitmap. A font can be max 1 MB. */ + uint32_t adv_w :12; /**< Draw the next glyph after this width. 12.4 format (real_value * 16 is stored). */ - uint8_t box_w; /*Width of the glyph's bounding box*/ - uint8_t box_h; /*Height of the glyph's bounding box*/ - int8_t ofs_x; /*x offset of the bounding box*/ - uint8_t ofs_y; /*y offset of the bounding box. Measured from the top of the line*/ + uint8_t box_w; /**< Width of the glyph's bounding box*/ + uint8_t box_h; /**< Height of the glyph's bounding box*/ + int8_t ofs_x; /**< x offset of the bounding box*/ + uint8_t ofs_y; /**< y offset of the bounding box. Measured from the top of the line*/ }lv_font_fmt_txt_glyph_dsc_t; +/** Format of font character map. */ typedef enum { LV_FONT_FMT_TXT_CMAP_FORMAT0_TINY, LV_FONT_FMT_TXT_CMAP_FORMAT0_FULL, @@ -58,14 +59,14 @@ typedef enum { * See https://github.com/littlevgl/lv_font_conv/blob/master/doc/font_spec.md */ typedef struct { - /* First Unicode character for this range */ + /** First Unicode character for this range */ uint32_t range_start; - /* Number of Unicode characters related to this range. + /** Number of Unicode characters related to this range. * Last Unicode character = range_start + range_length - 1*/ uint16_t range_length; - /* First glyph ID (array index of `glyph_dsc`) for this range */ + /** First glyph ID (array index of `glyph_dsc`) for this range */ uint16_t glyph_id_start; /* @@ -97,19 +98,19 @@ typedef struct { uint16_t * unicode_list; - /* if(type == LV_FONT_FMT_TXT_CMAP_FORMAT0_...) it's `uint8_t *` + /** if(type == LV_FONT_FMT_TXT_CMAP_FORMAT0_...) it's `uint8_t *` * if(type == LV_FONT_FMT_TXT_CMAP_SPARSE_...) it's `uint16_t *` */ const void * glyph_id_ofs_list; - /*Length of `unicode_list` and/or `glyph_id_ofs_list`*/ + /** Length of `unicode_list` and/or `glyph_id_ofs_list`*/ uint16_t list_length; - /*Type of this character map*/ + /** Type of this character map*/ lv_font_fmt_txt_cmap_type_t type :2; }lv_font_fmt_txt_cmap_t; -/*A simple mapping of kern values from pairs*/ +/** A simple mapping of kern values from pairs*/ typedef struct { /*To get a kern value of two code points: 1. Get the `glyph_id_left` and `glyph_id_right` from `lv_font_fmt_txt_cmap_t @@ -124,7 +125,7 @@ typedef struct { uint32_t glyph_ids_size :2; /*0: `glyph_ids` is stored as `uint8_t`; 1: as `uint16_t`*/ }lv_font_fmt_txt_kern_pair_t; -/*More complex but more optimal class based kern value storage*/ +/** More complex but more optimal class based kern value storage*/ typedef struct { /*To get a kern value of two code points: 1. Get the `glyph_id_left` and `glyph_id_right` from `lv_font_fmt_txt_cmap_t @@ -142,7 +143,7 @@ typedef struct { }lv_font_fmt_txt_kern_classes_t; -/*Bitmap formats*/ +/** Bitmap formats*/ typedef enum { LV_FONT_FMT_TXT_PLAIN = 0, LV_FONT_FMT_TXT_COMPRESSED = 1, diff --git a/src/lv_font/lv_symbol_def.h b/src/lv_font/lv_symbol_def.h index 8555f0139..338705e58 100644 --- a/src/lv_font/lv_symbol_def.h +++ b/src/lv_font/lv_symbol_def.h @@ -63,11 +63,11 @@ extern "C" { #define LV_SYMBOL_BATTERY_EMPTY "\xef\x89\x84" #define LV_SYMBOL_BLUETOOTH "\xef\x8a\x93" -/*Invalid symbol at (U+F8FF). If written before a string then `lv_img` will show it as a label*/ +/** Invalid symbol at (U+F8FF). If written before a string then `lv_img` will show it as a label*/ #define LV_SYMBOL_DUMMY "\xEF\xA3\xBF" /* - * following list is generated using + * The following list is generated using * cat src/lv_misc/lv_symbol_def.h | sed -E -n 's/^#define\s+(LV_SYMBOL_\w+).*"$/ _LV_STR_\1,/p' */ enum { diff --git a/src/lv_hal/lv_hal_disp.h b/src/lv_hal/lv_hal_disp.h index a399958b7..8db692a09 100644 --- a/src/lv_hal/lv_hal_disp.h +++ b/src/lv_hal/lv_hal_disp.h @@ -41,12 +41,15 @@ extern "C" { struct _disp_t; struct _disp_drv_t; +/** + * Structure for holding display buffer information. + */ typedef struct { - void * buf1; - void * buf2; + void * buf1; /**< First display buffer. */ + void * buf2; /**< Second display buffer. */ - /*Used by the library*/ + /*Internal, used by the library*/ void * buf_act; uint32_t size; /*In pixel count*/ lv_area_t area; @@ -59,18 +62,17 @@ typedef struct typedef struct _disp_drv_t { - /*Horizontal and vertical resolution*/ - lv_coord_t hor_res; - lv_coord_t ver_res; + lv_coord_t hor_res; /**< Horizontal resolution. */ + lv_coord_t ver_res; /**< Vertical resolution. */ - /* Pointer to a buffer initialized with `lv_disp_buf_init()`. + /** Pointer to a buffer initialized with `lv_disp_buf_init()`. * LittlevGL will use this buffer(s) to draw the screens contents */ lv_disp_buf_t * buffer; #if LV_ANTIALIAS - uint32_t antialiasing : 1; + uint32_t antialiasing : 1; /**< 1: antialiasing is enabled on this display. */ #endif - uint32_t rotated : 1; /*1: turn the display by 90 degree.*/ + uint32_t rotated : 1; /**< 1: turn the display by 90 degree. @warning Does not update coordinates for you!*/ #if LV_COLOR_SCREEN_TRANSP /**Handle if the the screen doesn't have a solid (opa == LV_OPA_COVER) background. @@ -78,67 +80,71 @@ typedef struct _disp_drv_t uint32_t screen_transp : 1; #endif - /* MANDATORY: Write the internal buffer (VDB) to the display. 'lv_disp_flush_ready()' has to be + /** MANDATORY: Write the internal buffer (VDB) to the display. 'lv_disp_flush_ready()' has to be * called when finished */ void (*flush_cb)(struct _disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p); - /* OPTIONAL: Extend the invalidated areas to match with the display drivers requirements + /** OPTIONAL: Extend the invalidated areas to match with the display drivers requirements * E.g. round `y` to, 8, 16 ..) on a monochrome display*/ void (*rounder_cb)(struct _disp_drv_t * disp_drv, lv_area_t * area); - /* OPTIONAL: Set a pixel in a buffer according to the special requirements of the display + /** OPTIONAL: Set a pixel in a buffer according to the special requirements of the display * Can be used for color format not supported in LittelvGL. E.g. 2 bit -> 4 gray scales - * Note: Much slower then drawing with supported color formats. */ + * @note Much slower then drawing with supported color formats. */ void (*set_px_cb)(struct _disp_drv_t * disp_drv, uint8_t * buf, lv_coord_t buf_w, lv_coord_t x, lv_coord_t y, lv_color_t color, lv_opa_t opa); - /* OPTIONAL: Called after every refresh cycle to tell the rendering and flushing time + the + /** OPTIONAL: Called after every refresh cycle to tell the rendering and flushing time + the * number of flushed pixels */ void (*monitor_cb)(struct _disp_drv_t * disp_drv, uint32_t time, uint32_t px); #if LV_USE_GPU - /*OPTIONAL: Blend two memories using opacity (GPU only)*/ + /** OPTIONAL: Blend two memories using opacity (GPU only)*/ void (*gpu_blend_cb)(struct _disp_drv_t * disp_drv, lv_color_t * dest, const lv_color_t * src, uint32_t length, lv_opa_t opa); - /*OPTIONAL: Fill a memory with a color (GPU only)*/ + /** OPTIONAL: Fill a memory with a color (GPU only)*/ void (*gpu_fill_cb)(struct _disp_drv_t * disp_drv, lv_color_t * dest_buf, lv_coord_t dest_width, const lv_area_t * fill_area, lv_color_t color); #endif - /*On CHROMA_KEYED images this color will be transparent. + /** On CHROMA_KEYED images this color will be transparent. * `LV_COLOR_TRANSP` by default. (lv_conf.h)*/ lv_color_t color_chroma_key; #if LV_USE_USER_DATA - lv_disp_drv_user_data_t user_data; + lv_disp_drv_user_data_t user_data; /**< Custom display driver user data */ #endif } lv_disp_drv_t; struct _lv_obj_t; +/** + * Display structure. + * ::lv_disp_drv_t is the first member of the structure. + */ typedef struct _disp_t { - /*Driver to the display*/ + /**< Driver to the display*/ lv_disp_drv_t driver; - /*A task which periodically checks the dirty areas and refreshes them*/ + /**< A task which periodically checks the dirty areas and refreshes them*/ lv_task_t * refr_task; - /*Screens of the display*/ + /** Screens of the display*/ lv_ll_t scr_ll; - struct _lv_obj_t * act_scr; - struct _lv_obj_t * top_layer; - struct _lv_obj_t * sys_layer; + struct _lv_obj_t * act_scr; /**< Currently active screen on this display */ + struct _lv_obj_t * top_layer; /**< @see lv_disp_get_layer_top */ + struct _lv_obj_t * sys_layer; /**< @see lv_disp_get_layer_sys */ - /*Invalidated (marked to redraw) areas*/ + /** Invalidated (marked to redraw) areas*/ lv_area_t inv_areas[LV_INV_BUF_SIZE]; uint8_t inv_area_joined[LV_INV_BUF_SIZE]; uint32_t inv_p : 10; /*Miscellaneous data*/ - uint32_t last_activity_time; + uint32_t last_activity_time; /**< Last time there was activity on this display */ } lv_disp_t; /********************** @@ -147,8 +153,8 @@ typedef struct _disp_t /** * Initialize a display driver with default values. - * It is used to surly have known values in the fields ant not memory junk. - * After it you can set the fields. + * It is used to have known values in the fields and not junk in memory. + * After it you can safely set only the fields you need. * @param driver pointer to driver variable to initialize */ void lv_disp_drv_init(lv_disp_drv_t * driver); diff --git a/src/lv_hal/lv_hal_indev.h b/src/lv_hal/lv_hal_indev.h index fa0e2ad5f..ef1a55596 100644 --- a/src/lv_hal/lv_hal_indev.h +++ b/src/lv_hal/lv_hal_indev.h @@ -39,44 +39,45 @@ struct _disp_t; struct _lv_indev_t; struct _lv_indev_drv_t; -/*Possible input device types*/ +/** Possible input device types*/ enum { - LV_INDEV_TYPE_NONE, /*Show uninitialized state*/ - LV_INDEV_TYPE_POINTER, /*Touch pad, mouse, external button*/ - LV_INDEV_TYPE_KEYPAD, /*Keypad or keyboard*/ - LV_INDEV_TYPE_BUTTON, /*External (hardware button) which is assigned to a specific point of the + LV_INDEV_TYPE_NONE, /**< Uninitialized state*/ + LV_INDEV_TYPE_POINTER, /**< Touch pad, mouse, external button*/ + LV_INDEV_TYPE_KEYPAD, /**< Keypad or keyboard*/ + LV_INDEV_TYPE_BUTTON, /**< External (hardware button) which is assigned to a specific point of the screen*/ - LV_INDEV_TYPE_ENCODER, /*Encoder with only Left, Right turn and a Button*/ + LV_INDEV_TYPE_ENCODER, /**< Encoder with only Left, Right turn and a Button*/ }; typedef uint8_t lv_indev_type_t; -/*States for input devices*/ +/** States for input devices*/ enum { LV_INDEV_STATE_REL = 0, LV_INDEV_STATE_PR }; typedef uint8_t lv_indev_state_t; -/*Data type when an input device is read */ +/** Data structure passed to an input driver to fill */ typedef struct { - lv_point_t point; /*For LV_INDEV_TYPE_POINTER the currently pressed point*/ - uint32_t key; /*For LV_INDEV_TYPE_KEYPAD the currently pressed key*/ - uint32_t btn_id; /*For LV_INDEV_TYPE_BUTTON the currently pressed button*/ - int16_t enc_diff; /*For LV_INDEV_TYPE_ENCODER number of steps since the previous read*/ + lv_point_t point; /**< For LV_INDEV_TYPE_POINTER the currently pressed point*/ + uint32_t key; /**< For LV_INDEV_TYPE_KEYPAD the currently pressed key*/ + uint32_t btn_id; /**< For LV_INDEV_TYPE_BUTTON the currently pressed button*/ + int16_t enc_diff; /**< For LV_INDEV_TYPE_ENCODER number of steps since the previous read*/ - lv_indev_state_t state; /*LV_INDEV_STATE_REL or LV_INDEV_STATE_PR*/ + lv_indev_state_t state; /**< LV_INDEV_STATE_REL or LV_INDEV_STATE_PR*/ } lv_indev_data_t; -/*Initialized by the user and registered by 'lv_indev_add()'*/ +/** Initialized by the user and registered by 'lv_indev_add()'*/ typedef struct _lv_indev_drv_t { - /*Input device type*/ + /**< Input device type*/ lv_indev_type_t type; - /*Function pointer to read input device data. - * Return 'true' if there is still data to be read (buffered)*/ + /**< Function pointer to read input device data. + * Return 'true' if there is more data to be read (buffered). + * Most drivers can safely return 'false' */ bool (*read_cb)(struct _lv_indev_drv_t * indev_drv, lv_indev_data_t * data); - /* Called when an action happened on the input device. + /** Called when an action happened on the input device. * The second parameter is the event from `lv_event_t`*/ void (*feedback_cb)(struct _lv_indev_drv_t *, uint8_t); @@ -84,36 +85,38 @@ typedef struct _lv_indev_drv_t lv_indev_drv_user_data_t user_data; #endif - /*Pointer to the assigned display*/ + /**< Pointer to the assigned display*/ struct _disp_t * disp; - /*Task to read the periodically read the input device*/ + /**< Task to read the periodically read the input device*/ lv_task_t * read_task; - /*Number of pixels to slide before actually drag the object*/ + /**< Number of pixels to slide before actually drag the object*/ uint8_t drag_limit; - /*Drag throw slow-down in [%]. Greater value means faster slow-down */ + /**< Drag throw slow-down in [%]. Greater value means faster slow-down */ uint8_t drag_throw; - /*Long press time in milliseconds*/ + /**< Long press time in milliseconds*/ uint16_t long_press_time; - /*Repeated trigger period in long press [ms] */ + /**< Repeated trigger period in long press [ms] */ uint16_t long_press_rep_time; } lv_indev_drv_t; -/*Run time data of input devices*/ +/** Run time data of input devices + * Internally used by the library, you should not need to touch it. + */ typedef struct _lv_indev_proc_t { - lv_indev_state_t state; + lv_indev_state_t state; /**< Current state of the input device. */ union { struct { /*Pointer and button data*/ - lv_point_t act_point; - lv_point_t last_point; - lv_point_t vect; + lv_point_t act_point; /**< Current point of input device. */ + lv_point_t last_point; /**< Last point of input device. */ + lv_point_t vect; /**< Difference between `act_point` and `last_point`. */ lv_point_t drag_sum; /*Count the dragged pixels to check LV_INDEV_DEF_DRAG_LIMIT*/ lv_point_t drag_throw_vect; struct _lv_obj_t * act_obj; /*The object being pressed*/ @@ -132,8 +135,8 @@ typedef struct _lv_indev_proc_t } keypad; } types; - uint32_t pr_timestamp; /*Pressed time stamp*/ - uint32_t longpr_rep_timestamp; /*Long press repeat time stamp*/ + uint32_t pr_timestamp; /**< Pressed time stamp*/ + uint32_t longpr_rep_timestamp; /**< Long press repeat time stamp*/ /*Flags*/ uint8_t long_pr_sent : 1; @@ -145,15 +148,15 @@ typedef struct _lv_indev_proc_t struct _lv_obj_t; struct _lv_group_t; -/*The main input device descriptor with driver, runtime data ('proc') and some additional +/** The main input device descriptor with driver, runtime data ('proc') and some additional * information*/ typedef struct _lv_indev_t { lv_indev_drv_t driver; lv_indev_proc_t proc; - struct _lv_obj_t * cursor; /*Cursor for LV_INPUT_TYPE_POINTER*/ - struct _lv_group_t * group; /*Keypad destination group*/ - const lv_point_t * btn_points; /*Array points assigned to the button ()screen will be pressed + struct _lv_obj_t * cursor; /**< Cursor for LV_INPUT_TYPE_POINTER*/ + struct _lv_group_t * group; /**< Keypad destination group*/ + const lv_point_t * btn_points; /**< Array points assigned to the button ()screen will be pressed here by the buttons*/ } lv_indev_t; diff --git a/src/lv_misc/lv_anim.h b/src/lv_misc/lv_anim.h index a816bc0fc..645138cb0 100644 --- a/src/lv_misc/lv_anim.h +++ b/src/lv_misc/lv_anim.h @@ -31,7 +31,7 @@ extern "C" { * TYPEDEFS **********************/ -/*Can be used to indicate if animations are enabled or disabled in a case*/ +/** Can be used to indicate if animations are enabled or disabled in a case*/ enum { LV_ANIM_OFF, LV_ANIM_ON, @@ -39,14 +39,14 @@ enum { typedef uint8_t lv_anim_enable_t; -/*Type of the animated value*/ +/** Type of the animated value*/ typedef lv_coord_t lv_anim_value_t; #if LV_USE_ANIMATION struct _lv_anim_t; -/* Generic prototype of "animator" functions. +/** Generic prototype of "animator" functions. * First parameter is the variable to animate. * Second parameter is the value to set. * Compatible with `lv_xxx_set_yyy(obj, value)` functions @@ -54,38 +54,38 @@ struct _lv_anim_t; * it doesn't receive `lv_anim_t *` as its first argument*/ typedef void (*lv_anim_exec_xcb_t)(void *, lv_anim_value_t); -/* Same as `lv_anim_exec_cb_t` but receives `lv_anim_t *` as the first parameter. +/** Same as `lv_anim_exec_xcb_t` but receives `lv_anim_t *` as the first parameter. * It's more consistent but less convenient. Might be used by binding generator functions.*/ typedef void (*lv_anim_custom_exec_cb_t)(struct _lv_anim_t *, lv_anim_value_t); -/*Get the current value during an animation*/ +/** Get the current value during an animation*/ typedef lv_anim_value_t (*lv_anim_path_cb_t)(const struct _lv_anim_t *); -/*Callback to call when the animation is ready*/ +/** Callback to call when the animation is ready*/ typedef void (*lv_anim_ready_cb_t)(struct _lv_anim_t *); -/*Describe an animation*/ +/** Describes an animation*/ typedef struct _lv_anim_t { - void * var; /*Variable to animate*/ - lv_anim_exec_xcb_t exec_cb; /*Function to execute to animate*/ - lv_anim_path_cb_t path_cb; /*An array with the steps of animations*/ - lv_anim_ready_cb_t ready_cb; /*Call it when the animation is ready*/ - int32_t start; /*Start value*/ - int32_t end; /*End value*/ - uint16_t time; /*Animation time in ms*/ - int16_t act_time; /*Current time in animation. Set to negative to make delay.*/ - uint16_t playback_pause; /*Wait before play back*/ - uint16_t repeat_pause; /*Wait before repeat*/ + void * var; /** 0 ? (x) : (-(x))) #define LV_TRIGO_SIN_MAX 32767 -#define LV_TRIGO_SHIFT 15 /* >> LV_TRIGO_SHIFT to normalize*/ +#define LV_TRIGO_SHIFT 15 /**< >> LV_TRIGO_SHIFT to normalize*/ -#define LV_BEZIER_VAL_MAX 1024 /*Max time in Bezier functions (not [0..1] to use integers) */ -#define LV_BEZIER_VAL_SHIFT 10 /*log2(LV_BEZIER_VAL_MAX): used to normalize up scaled values*/ +#define LV_BEZIER_VAL_MAX 1024 /**< Max time in Bezier functions (not [0..1] to use integers) */ +#define LV_BEZIER_VAL_SHIFT 10 /**< log2(LV_BEZIER_VAL_MAX): used to normalize up scaled values*/ /********************** * TYPEDEFS diff --git a/src/lv_misc/lv_mem.h b/src/lv_misc/lv_mem.h index 5b4efbe6f..81a3e7a2f 100644 --- a/src/lv_misc/lv_mem.h +++ b/src/lv_misc/lv_mem.h @@ -42,15 +42,18 @@ extern "C" { * TYPEDEFS **********************/ +/** + * Heap information structure. + */ typedef struct { - uint32_t total_size; + uint32_t total_size; /**< Total heap size */ uint32_t free_cnt; - uint32_t free_size; + uint32_t free_size; /**< Size of available memory */ uint32_t free_biggest_size; uint32_t used_cnt; - uint8_t used_pct; - uint8_t frag_pct; + uint8_t used_pct; /**< Percentage used */ + uint8_t frag_pct; /**< Amount of fragmentation */ } lv_mem_monitor_t; /********************** diff --git a/src/lv_misc/lv_task.h b/src/lv_misc/lv_task.h index f5d5ce9a2..0d5696aa2 100644 --- a/src/lv_misc/lv_task.h +++ b/src/lv_misc/lv_task.h @@ -61,14 +61,14 @@ typedef uint8_t lv_task_prio_t; */ typedef struct _lv_task_t { - uint32_t period; - uint32_t last_run; - lv_task_cb_t task_cb; + uint32_t period; /**< How often the task should run */ + uint32_t last_run; /**< Last time the task ran */ + lv_task_cb_t task_cb; /**< Task function */ - void * user_data; + void * user_data; /**< Custom user data */ - uint8_t prio : 3; - uint8_t once : 1; + uint8_t prio : 3; /**< Task priority */ + uint8_t once : 1; /**< 1: one shot task */ } lv_task_t; /********************** diff --git a/src/lv_misc/lv_txt.h b/src/lv_misc/lv_txt.h index 3e60fcf61..6fc6e4a63 100644 --- a/src/lv_misc/lv_txt.h +++ b/src/lv_misc/lv_txt.h @@ -35,19 +35,24 @@ extern "C" { /********************** * TYPEDEFS **********************/ +/** + * Options for text rendering. + */ enum { LV_TXT_FLAG_NONE = 0x00, - LV_TXT_FLAG_RECOLOR = 0x01, /*Enable parsing of recolor command*/ - LV_TXT_FLAG_EXPAND = 0x02, /*Ignore width to avoid automatic word wrapping*/ - LV_TXT_FLAG_CENTER = 0x04, /*Align the text to the middle*/ - LV_TXT_FLAG_RIGHT = 0x08, /*Align the text to the right*/ + LV_TXT_FLAG_RECOLOR = 0x01, /**< Enable parsing of recolor command*/ + LV_TXT_FLAG_EXPAND = 0x02, /**< Ignore width to avoid automatic word wrapping*/ + LV_TXT_FLAG_CENTER = 0x04, /**< Align the text to the middle*/ + LV_TXT_FLAG_RIGHT = 0x08, /**< Align the text to the right*/ }; typedef uint8_t lv_txt_flag_t; +/** + * State machine for text renderer. */ enum { - LV_TXT_CMD_STATE_WAIT, /*Waiting for command*/ - LV_TXT_CMD_STATE_PAR, /*Processing the parameter*/ - LV_TXT_CMD_STATE_IN, /*Processing the command*/ + LV_TXT_CMD_STATE_WAIT, /**< Waiting for command*/ + LV_TXT_CMD_STATE_PAR, /**< Processing the parameter*/ + LV_TXT_CMD_STATE_IN, /**< Processing the command*/ }; typedef uint8_t lv_txt_cmd_state_t; diff --git a/src/lv_misc/lv_types.h b/src/lv_misc/lv_types.h index bdd860f56..41b04c0d1 100644 --- a/src/lv_misc/lv_types.h +++ b/src/lv_misc/lv_types.h @@ -22,6 +22,9 @@ extern "C" { * TYPEDEFS **********************/ +/** + * LittlevGL error codes. + */ enum { LV_RES_INV = 0, /*Typically indicates that the object is deleted (become invalid) in the action function or an operation was failed*/ diff --git a/src/lv_objx/lv_bar.h b/src/lv_objx/lv_bar.h index ec558bf42..14c558e7a 100644 --- a/src/lv_objx/lv_bar.h +++ b/src/lv_objx/lv_bar.h @@ -66,9 +66,10 @@ typedef struct const lv_style_t * style_indic; /*Style of the indicator*/ } lv_bar_ext_t; +/** Bar styles. */ enum { - LV_BAR_STYLE_BG, - LV_BAR_STYLE_INDIC, + LV_BAR_STYLE_BG, /** Bar background style. */ + LV_BAR_STYLE_INDIC, /** Bar fill area style. */ }; typedef uint8_t lv_bar_style_t; diff --git a/src/lv_objx/lv_btnm.h b/src/lv_objx/lv_btnm.h index bcbc494ea..90b2de393 100644 --- a/src/lv_objx/lv_btnm.h +++ b/src/lv_objx/lv_btnm.h @@ -35,14 +35,14 @@ extern "C" { * TYPEDEFS **********************/ -/* Type to store button control bits (disabled, hidden etc.) */ +/** Type to store button control bits (disabled, hidden etc.) */ enum { - LV_BTNM_CTRL_HIDDEN = 0x0008, - LV_BTNM_CTRL_NO_REPEAT = 0x0010, - LV_BTNM_CTRL_INACTIVE = 0x0020, - LV_BTNM_CTRL_TGL_ENABLE = 0x0040, - LV_BTNM_CTRL_TGL_STATE = 0x0080, - LV_BTNM_CTRL_CLICK_TRIG = 0x0100, /*1: Send LV_EVENT_SELECTED on CLICK, 0: Send LV_EVENT_SELECTED on PRESS*/ + LV_BTNM_CTRL_HIDDEN = 0x0008, /**< Button hidden */ + LV_BTNM_CTRL_NO_REPEAT = 0x0010, /**< Do not repeat press this button. */ + LV_BTNM_CTRL_INACTIVE = 0x0020, /**< Disable this button. */ + LV_BTNM_CTRL_TGL_ENABLE = 0x0040, /**< Button *can* be toggled. */ + LV_BTNM_CTRL_TGL_STATE = 0x0080, /**< Button is currently toggled (e.g. checked). */ + LV_BTNM_CTRL_CLICK_TRIG = 0x0100, /**< 1: Send LV_EVENT_SELECTED on CLICK, 0: Send LV_EVENT_SELECTED on PRESS*/ }; typedef uint16_t lv_btnm_ctrl_t; diff --git a/src/lv_objx/lv_calendar.h b/src/lv_objx/lv_calendar.h index ad7dda2a7..83e489cc1 100644 --- a/src/lv_objx/lv_calendar.h +++ b/src/lv_objx/lv_calendar.h @@ -31,6 +31,9 @@ extern "C" { * TYPEDEFS **********************/ +/** + * Represents a date on the calendar object (platform-agnostic). + */ typedef struct { uint16_t year; @@ -63,16 +66,16 @@ typedef struct const lv_style_t * style_today_box; } lv_calendar_ext_t; -/*Styles*/ +/** Calendar styles*/ enum { - LV_CALENDAR_STYLE_BG, /*Also the style of the "normal" date numbers*/ - LV_CALENDAR_STYLE_HEADER, - LV_CALENDAR_STYLE_HEADER_PR, - LV_CALENDAR_STYLE_DAY_NAMES, - LV_CALENDAR_STYLE_HIGHLIGHTED_DAYS, - LV_CALENDAR_STYLE_INACTIVE_DAYS, - LV_CALENDAR_STYLE_WEEK_BOX, - LV_CALENDAR_STYLE_TODAY_BOX, + LV_CALENDAR_STYLE_BG, /**< Background and "normal" date numbers style */ + LV_CALENDAR_STYLE_HEADER, /** Calendar header style */ + LV_CALENDAR_STYLE_HEADER_PR, /** Calendar header style (when pressed) */ + LV_CALENDAR_STYLE_DAY_NAMES, /** Day name style */ + LV_CALENDAR_STYLE_HIGHLIGHTED_DAYS, /** Highlighted day style */ + LV_CALENDAR_STYLE_INACTIVE_DAYS, /** Inactive day style */ + LV_CALENDAR_STYLE_WEEK_BOX, /** Week highlight style */ + LV_CALENDAR_STYLE_TODAY_BOX, /** Today highlight style */ }; typedef uint8_t lv_calendar_style_t; diff --git a/src/lv_objx/lv_cb.h b/src/lv_objx/lv_cb.h index f061cbd1a..5fa598b7b 100644 --- a/src/lv_objx/lv_cb.h +++ b/src/lv_objx/lv_cb.h @@ -51,13 +51,14 @@ typedef struct lv_obj_t * label; /*Pointer to label*/ } lv_cb_ext_t; +/** Checkbox styles. */ enum { - LV_CB_STYLE_BG, - LV_CB_STYLE_BOX_REL, - LV_CB_STYLE_BOX_PR, - LV_CB_STYLE_BOX_TGL_REL, - LV_CB_STYLE_BOX_TGL_PR, - LV_CB_STYLE_BOX_INA, + LV_CB_STYLE_BG, /**< Style of object background. */ + LV_CB_STYLE_BOX_REL, /**< Style of box (released). */ + LV_CB_STYLE_BOX_PR, /**< Style of box (pressed). */ + LV_CB_STYLE_BOX_TGL_REL, /**< Style of box (released but checked). */ + LV_CB_STYLE_BOX_TGL_PR, /**< Style of box (pressed and checked). */ + LV_CB_STYLE_BOX_INA, /**< Style of disabled box */ }; typedef uint8_t lv_cb_style_t; diff --git a/src/lv_objx/lv_chart.h b/src/lv_objx/lv_chart.h index ab68b4313..feb001593 100644 --- a/src/lv_objx/lv_chart.h +++ b/src/lv_objx/lv_chart.h @@ -38,21 +38,21 @@ extern "C" { * TYPEDEFS **********************/ -/*Chart types*/ +/** Chart types*/ enum { - LV_CHART_TYPE_NONE = 0x00, /*Don't draw the series*/ - LV_CHART_TYPE_LINE = 0x01, /*Connect the points with lines*/ - LV_CHART_TYPE_COLUMN = 0x02, /*Draw columns*/ - LV_CHART_TYPE_POINT = 0x04, /*Draw circles on the points*/ - LV_CHART_TYPE_VERTICAL_LINE = 0x08, /*Draw vertical lines on points (useful when chart width == point count)*/ - LV_CHART_TYPE_AREA = 0x10, /*Draw area chart*/ + LV_CHART_TYPE_NONE = 0x00, /**< Don't draw the series*/ + LV_CHART_TYPE_LINE = 0x01, /**< Connect the points with lines*/ + LV_CHART_TYPE_COLUMN = 0x02, /**< Draw columns*/ + LV_CHART_TYPE_POINT = 0x04, /**< Draw circles on the points*/ + LV_CHART_TYPE_VERTICAL_LINE = 0x08, /**< Draw vertical lines on points (useful when chart width == point count)*/ + LV_CHART_TYPE_AREA = 0x10, /**< Draw area chart*/ }; typedef uint8_t lv_chart_type_t; -/*Chart update mode for `lv_chart_set_next`*/ +/** Chart update mode for `lv_chart_set_next`*/ enum { - LV_CHART_UPDATE_MODE_SHIFT, /*Shift old data to the left and add the new one o the right*/ - LV_CHART_UPDATE_MODE_CIRCULAR, /*Add the new data in a circular way*/ + LV_CHART_UPDATE_MODE_SHIFT, /**< Shift old data to the left and add the new one o the right*/ + LV_CHART_UPDATE_MODE_CIRCULAR, /**< Add the new data in a circular way*/ }; typedef uint8_t lv_chart_update_mode_t; @@ -63,10 +63,10 @@ typedef struct uint16_t start_point; } lv_chart_series_t; -/*Data of axis */ +/** Data of axis */ enum { - LV_CHART_AXIS_SKIP_LAST_TICK = 0x00, /* don't draw the last tick */ - LV_CHART_AXIS_DRAW_LAST_TICK = 0x01 /* draw the last tick */ + LV_CHART_AXIS_SKIP_LAST_TICK = 0x00, /**< don't draw the last tick */ + LV_CHART_AXIS_DRAW_LAST_TICK = 0x01 /**< draw the last tick */ }; typedef uint8_t lv_chart_axis_options_t; diff --git a/src/lv_objx/lv_cont.h b/src/lv_objx/lv_cont.h index 22a3a1ff7..fea79396b 100644 --- a/src/lv_objx/lv_cont.h +++ b/src/lv_objx/lv_cont.h @@ -31,27 +31,30 @@ extern "C" { * TYPEDEFS **********************/ -/*Layout options*/ +/** Container layout options*/ enum { - LV_LAYOUT_OFF = 0, - LV_LAYOUT_CENTER, - LV_LAYOUT_COL_L, /*Column left align*/ - LV_LAYOUT_COL_M, /*Column middle align*/ - LV_LAYOUT_COL_R, /*Column right align*/ - LV_LAYOUT_ROW_T, /*Row top align*/ - LV_LAYOUT_ROW_M, /*Row middle align*/ - LV_LAYOUT_ROW_B, /*Row bottom align*/ - LV_LAYOUT_PRETTY, /*Put as many object as possible in row and begin a new row*/ - LV_LAYOUT_GRID, /*Align same-sized object into a grid*/ + LV_LAYOUT_OFF = 0, /**< No layout */ + LV_LAYOUT_CENTER, /**< Center objects */ + LV_LAYOUT_COL_L, /**< Column left align*/ + LV_LAYOUT_COL_M, /**< Column middle align*/ + LV_LAYOUT_COL_R, /**< Column right align*/ + LV_LAYOUT_ROW_T, /**< Row top align*/ + LV_LAYOUT_ROW_M, /**< Row middle align*/ + LV_LAYOUT_ROW_B, /**< Row bottom align*/ + LV_LAYOUT_PRETTY, /**< Put as many object as possible in row and begin a new row*/ + LV_LAYOUT_GRID, /**< Align same-sized object into a grid*/ }; typedef uint8_t lv_layout_t; +/** + * How to resize the container around the children. + */ enum { - LV_FIT_NONE, /*Do not change the size automatically*/ - LV_FIT_TIGHT, /*Involve the children*/ - LV_FIT_FLOOD, /*Align the size to the parent's edge*/ - LV_FIT_FILL, /*Align the size to the parent's edge first but if there is an object out of it - then involve it*/ + LV_FIT_NONE, /**< Do not change the size automatically*/ + LV_FIT_TIGHT, /**< Shrink wrap around the children */ + LV_FIT_FLOOD, /**< Align the size to the parent's edge*/ + LV_FIT_FILL, /**< Align the size to the parent's edge first but if there is an object out of it + then get larger */ }; typedef uint8_t lv_fit_t; diff --git a/src/lv_objx/lv_imgbtn.h b/src/lv_objx/lv_imgbtn.h index 850866335..842411b16 100644 --- a/src/lv_objx/lv_imgbtn.h +++ b/src/lv_objx/lv_imgbtn.h @@ -54,7 +54,7 @@ typedef struct /*Styles*/ enum { - LV_IMGBTN_STYLE_REL, + LV_IMGBTN_STYLE_REL, /**< Same meaning as ordinary button styles. */ LV_IMGBTN_STYLE_PR, LV_IMGBTN_STYLE_TGL_REL, LV_IMGBTN_STYLE_TGL_PR, diff --git a/src/lv_objx/lv_kb.h b/src/lv_objx/lv_kb.h index 8ea7c99a0..f08891f1b 100644 --- a/src/lv_objx/lv_kb.h +++ b/src/lv_objx/lv_kb.h @@ -41,6 +41,7 @@ extern "C" { * TYPEDEFS **********************/ +/** Current keyboard mode. */ enum { LV_KB_MODE_TEXT, LV_KB_MODE_NUM, diff --git a/src/lv_objx/lv_label.h b/src/lv_objx/lv_label.h index 8189734ee..133e4f6a7 100644 --- a/src/lv_objx/lv_label.h +++ b/src/lv_objx/lv_label.h @@ -38,27 +38,27 @@ extern "C" { * TYPEDEFS **********************/ -/*Long mode behaviors. Used in 'lv_label_ext_t' */ +/** Long mode behaviors. Used in 'lv_label_ext_t' */ enum { - LV_LABEL_LONG_EXPAND, /*Expand the object size to the text size*/ - LV_LABEL_LONG_BREAK, /*Keep the object width, break the too long lines and expand the object + LV_LABEL_LONG_EXPAND, /**< Expand the object size to the text size*/ + LV_LABEL_LONG_BREAK, /**< Keep the object width, break the too long lines and expand the object height*/ - LV_LABEL_LONG_DOT, /*Keep the size and write dots at the end if the text is too long*/ - LV_LABEL_LONG_SROLL, /*Keep the size and roll the text back and forth*/ - LV_LABEL_LONG_SROLL_CIRC, /*Keep the size and roll the text circularly*/ - LV_LABEL_LONG_CROP, /*Keep the size and crop the text out of it*/ + LV_LABEL_LONG_DOT, /**< Keep the size and write dots at the end if the text is too long*/ + LV_LABEL_LONG_SROLL, /**< Keep the size and roll the text back and forth*/ + LV_LABEL_LONG_SROLL_CIRC, /**< Keep the size and roll the text circularly*/ + LV_LABEL_LONG_CROP, /**< Keep the size and crop the text out of it*/ }; typedef uint8_t lv_label_long_mode_t; -/*Label align policy*/ +/** Label align policy*/ enum { - LV_LABEL_ALIGN_LEFT, - LV_LABEL_ALIGN_CENTER, - LV_LABEL_ALIGN_RIGHT, + LV_LABEL_ALIGN_LEFT, /**< Align text to left */ + LV_LABEL_ALIGN_CENTER, /**< Align text to center */ + LV_LABEL_ALIGN_RIGHT, /**< Align text to right */ }; typedef uint8_t lv_label_align_t; -/*Data of label*/ +/** Data of label*/ typedef struct { /*Inherited from 'base_obj' so no inherited ext.*/ /*Ext. of ancestor*/ @@ -93,7 +93,7 @@ typedef struct characters */ } lv_label_ext_t; -/*Styles*/ +/** Label styles*/ enum { LV_LABEL_STYLE_MAIN, }; diff --git a/src/lv_objx/lv_list.h b/src/lv_objx/lv_list.h index 0aed99f32..0da81bcf1 100644 --- a/src/lv_objx/lv_list.h +++ b/src/lv_objx/lv_list.h @@ -64,12 +64,13 @@ typedef struct #endif } lv_list_ext_t; +/** List styles. */ enum { - LV_LIST_STYLE_BG, - LV_LIST_STYLE_SCRL, - LV_LIST_STYLE_SB, - LV_LIST_STYLE_EDGE_FLASH, - LV_LIST_STYLE_BTN_REL, + LV_LIST_STYLE_BG, /**< List background style */ + LV_LIST_STYLE_SCRL, /**< List scrollable area style. */ + LV_LIST_STYLE_SB, /**< List scrollbar style. */ + LV_LIST_STYLE_EDGE_FLASH, /**< List edge flash style. */ + LV_LIST_STYLE_BTN_REL, /**< Same meaning as the ordinary button styles. */ LV_LIST_STYLE_BTN_PR, LV_LIST_STYLE_BTN_TGL_REL, LV_LIST_STYLE_BTN_TGL_PR, diff --git a/src/lv_objx/lv_mbox.h b/src/lv_objx/lv_mbox.h index 805bf190a..df504f851 100644 --- a/src/lv_objx/lv_mbox.h +++ b/src/lv_objx/lv_mbox.h @@ -59,9 +59,10 @@ typedef struct #endif } lv_mbox_ext_t; +/** Message box styles. */ enum { LV_MBOX_STYLE_BG, - LV_MBOX_STYLE_BTN_BG, + LV_MBOX_STYLE_BTN_BG, /**< Same meaning as ordinary button styles. */ LV_MBOX_STYLE_BTN_REL, LV_MBOX_STYLE_BTN_PR, LV_MBOX_STYLE_BTN_TGL_REL, diff --git a/src/lv_objx/lv_page.h b/src/lv_objx/lv_page.h index 59b62d5ec..49f4489b1 100644 --- a/src/lv_objx/lv_page.h +++ b/src/lv_objx/lv_page.h @@ -38,18 +38,18 @@ extern "C" { * TYPEDEFS **********************/ -/*Scrollbar modes: shows when should the scrollbars be visible*/ +/** Scrollbar modes: shows when should the scrollbars be visible*/ enum { - LV_SB_MODE_OFF = 0x0, /*Never show scrollbars*/ - LV_SB_MODE_ON = 0x1, /*Always show scrollbars*/ - LV_SB_MODE_DRAG = 0x2, /*Show scrollbars when page is being dragged*/ - LV_SB_MODE_AUTO = 0x3, /*Show scrollbars when the scrollable container is large enough to be scrolled*/ - LV_SB_MODE_HIDE = 0x4, /*Hide the scroll bar temporally*/ - LV_SB_MODE_UNHIDE = 0x5, /*Unhide the previously hidden scrollbar. Recover it's type too*/ + LV_SB_MODE_OFF = 0x0, /**< Never show scrollbars*/ + LV_SB_MODE_ON = 0x1, /**< Always show scrollbars*/ + LV_SB_MODE_DRAG = 0x2, /**< Show scrollbars when page is being dragged*/ + LV_SB_MODE_AUTO = 0x3, /**< Show scrollbars when the scrollable container is large enough to be scrolled*/ + LV_SB_MODE_HIDE = 0x4, /**< Hide the scroll bar temporally*/ + LV_SB_MODE_UNHIDE = 0x5, /**< Unhide the previously hidden scrollbar. Recover it's type too*/ }; typedef uint8_t lv_sb_mode_t; -/*Edges: describes the four edges of the page*/ +/** Edges: describes the four edges of the page*/ enum { LV_PAGE_EDGE_LEFT = 0x1, LV_PAGE_EDGE_TOP = 0x2, diff --git a/src/lv_objx/lv_preload.h b/src/lv_objx/lv_preload.h index 918960146..cbc7826a6 100644 --- a/src/lv_objx/lv_preload.h +++ b/src/lv_objx/lv_preload.h @@ -42,12 +42,18 @@ extern "C" { * TYPEDEFS **********************/ +/** + * Type of preloader. + */ enum { LV_PRELOAD_TYPE_SPINNING_ARC, LV_PRELOAD_TYPE_FILLSPIN_ARC, }; typedef uint8_t lv_preload_type_t; +/** + * Direction the preloader should spin. + */ enum { LV_PRELOAD_DIR_FORWARD, LV_PRELOAD_DIR_BACKWARD, diff --git a/src/lv_objx/lv_roller.h b/src/lv_objx/lv_roller.h index 677a7dd15..5303c3aa1 100644 --- a/src/lv_objx/lv_roller.h +++ b/src/lv_objx/lv_roller.h @@ -38,10 +38,10 @@ extern "C" { * TYPEDEFS **********************/ - +/** Roller mode. */ enum { - LV_ROLLER_MODE_NORMAL, - LV_ROLLER_MODE_INIFINITE, + LV_ROLLER_MODE_NORMAL, /**< Normal mode (roller ends at the end of the options). */ + LV_ROLLER_MODE_INIFINITE, /**< Infinite mode (roller can be scrolled forever). */ }; typedef uint8_t lv_roller_mode_t; diff --git a/src/lv_objx/lv_slider.h b/src/lv_objx/lv_slider.h index 5ca12903b..07086efe4 100644 --- a/src/lv_objx/lv_slider.h +++ b/src/lv_objx/lv_slider.h @@ -46,11 +46,11 @@ typedef struct uint8_t knob_in : 1; /*1: Draw the knob inside the bar*/ } lv_slider_ext_t; -/*Built-in styles of slider*/ +/** Built-in styles of slider*/ enum { - LV_SLIDER_STYLE_BG, - LV_SLIDER_STYLE_INDIC, - LV_SLIDER_STYLE_KNOB, + LV_SLIDER_STYLE_BG, /** Slider background style. */ + LV_SLIDER_STYLE_INDIC, /** Slider indicator (filled area) style. */ + LV_SLIDER_STYLE_KNOB, /** Slider knob style. */ }; typedef uint8_t lv_slider_style_t; diff --git a/src/lv_objx/lv_sw.h b/src/lv_objx/lv_sw.h index 91723e4df..f4b44aeb1 100644 --- a/src/lv_objx/lv_sw.h +++ b/src/lv_objx/lv_sw.h @@ -42,8 +42,8 @@ typedef struct { lv_slider_ext_t slider; /*Ext. of ancestor*/ /*New data for this type */ - const lv_style_t * style_knob_off; /*Style of the knob when the switch is OFF*/ - const lv_style_t * style_knob_on; /*Style of the knob when the switch is ON (NULL to use the same as OFF)*/ + const lv_style_t * style_knob_off; /**< Style of the knob when the switch is OFF*/ + const lv_style_t * style_knob_on; /**< Style of the knob when the switch is ON (NULL to use the same as OFF)*/ lv_coord_t start_x; uint8_t changed : 1; /*Indicates the switch state explicitly changed by drag*/ uint8_t slided : 1; @@ -52,11 +52,14 @@ typedef struct #endif } lv_sw_ext_t; +/** + * Switch styles. + */ enum { - LV_SW_STYLE_BG, - LV_SW_STYLE_INDIC, - LV_SW_STYLE_KNOB_OFF, - LV_SW_STYLE_KNOB_ON, + LV_SW_STYLE_BG, /**< Switch background. */ + LV_SW_STYLE_INDIC, /**< Switch fill area. */ + LV_SW_STYLE_KNOB_OFF, /**< Switch knob (when off). */ + LV_SW_STYLE_KNOB_ON, /**< Switch knob (when on). */ }; typedef uint8_t lv_sw_style_t; diff --git a/src/lv_objx/lv_ta.h b/src/lv_objx/lv_ta.h index c33ac8cf4..5f7881b65 100644 --- a/src/lv_objx/lv_ta.h +++ b/src/lv_objx/lv_ta.h @@ -43,13 +43,14 @@ extern "C" { * TYPEDEFS **********************/ +/** Style of text area's cursor. */ enum { - LV_CURSOR_NONE, - LV_CURSOR_LINE, - LV_CURSOR_BLOCK, - LV_CURSOR_OUTLINE, - LV_CURSOR_UNDERLINE, - LV_CURSOR_HIDDEN = 0x08, /*Or it to any value to hide the cursor temporally*/ + LV_CURSOR_NONE, /**< No cursor */ + LV_CURSOR_LINE, /**< Vertical line */ + LV_CURSOR_BLOCK, /**< Rectangle */ + LV_CURSOR_OUTLINE, /**< Outline around character */ + LV_CURSOR_UNDERLINE, /**< Horizontal line under character */ + LV_CURSOR_HIDDEN = 0x08, /**< This flag can be ORed to any of the other values to temporarily hide the cursor */ }; typedef uint8_t lv_cursor_type_t; @@ -88,12 +89,13 @@ typedef struct uint8_t one_line : 1; /*One line mode (ignore line breaks)*/ } lv_ta_ext_t; +/** Possible text areas tyles. */ enum { - LV_TA_STYLE_BG, - LV_TA_STYLE_SB, - LV_TA_STYLE_CURSOR, - LV_TA_STYLE_EDGE_FLASH, - LV_TA_STYLE_PLACEHOLDER, + LV_TA_STYLE_BG, /**< Text area background style */ + LV_TA_STYLE_SB, /**< Scrollbar style */ + LV_TA_STYLE_CURSOR, /**< Cursor style */ + LV_TA_STYLE_EDGE_FLASH, /**< Edge flash style */ + LV_TA_STYLE_PLACEHOLDER, /**< Placeholder style */ }; typedef uint8_t lv_ta_style_t; diff --git a/src/lv_objx/lv_table.h b/src/lv_objx/lv_table.h index 0ad63ebc1..d6a0be7d1 100644 --- a/src/lv_objx/lv_table.h +++ b/src/lv_objx/lv_table.h @@ -41,6 +41,11 @@ extern "C" { * TYPEDEFS **********************/ +/** + * Internal table cell format structure. + * + * Use the `lv_table` APIs instead. + */ typedef union { struct diff --git a/src/lv_objx/lv_tabview.h b/src/lv_objx/lv_tabview.h index 2c0b24e1d..419a0bb70 100644 --- a/src/lv_objx/lv_tabview.h +++ b/src/lv_objx/lv_tabview.h @@ -42,6 +42,7 @@ extern "C" { * TYPEDEFS **********************/ +/** Position of tabview buttons. */ enum { LV_TABVIEW_BTNS_POS_TOP, LV_TABVIEW_BTNS_POS_BOTTOM, LV_TABVIEW_BTNS_POS_LEFT, LV_TABVIEW_BTNS_POS_RIGHT }; typedef uint8_t lv_tabview_btns_pos_t; diff --git a/src/lv_objx/lv_win.h b/src/lv_objx/lv_win.h index 8f4599afc..8fe7d5ad5 100644 --- a/src/lv_objx/lv_win.h +++ b/src/lv_objx/lv_win.h @@ -66,12 +66,13 @@ typedef struct lv_coord_t btn_size; /*Size of the control buttons (square)*/ } lv_win_ext_t; +/** Window styles. */ enum { - LV_WIN_STYLE_BG, - LV_WIN_STYLE_CONTENT, - LV_WIN_STYLE_SB, - LV_WIN_STYLE_HEADER, - LV_WIN_STYLE_BTN_REL, + LV_WIN_STYLE_BG, /**< Window object background style. */ + LV_WIN_STYLE_CONTENT, /**< Window content style. */ + LV_WIN_STYLE_SB, /**< Window scrollbar style. */ + LV_WIN_STYLE_HEADER, /**< Window titlebar background style. */ + LV_WIN_STYLE_BTN_REL, /**< Same meaning as ordinary button styles. */ LV_WIN_STYLE_BTN_PR, }; typedef uint8_t lv_win_style_t; diff --git a/src/lv_themes/lv_theme.h b/src/lv_themes/lv_theme.h index cead2313a..4b4b8a39b 100644 --- a/src/lv_themes/lv_theme.h +++ b/src/lv_themes/lv_theme.h @@ -30,6 +30,12 @@ extern "C" { * TYPEDEFS **********************/ +/** + * A theme in LittlevGL consists of many styles bound together. + * + * There is a style for each object type, as well as a generic style for + * backgrounds and panels. + */ typedef struct { struct diff --git a/src/lv_version.h b/src/lv_version.h index b718be951..9dc3e26d6 100644 --- a/src/lv_version.h +++ b/src/lv_version.h @@ -35,7 +35,7 @@ extern "C" { /********************** * MACROS **********************/ -/* Gives 1 if the x.y.z version is supported in the current version +/** Gives 1 if the x.y.z version is supported in the current version * Usage: * * - Require v6 From 0e71a341284a5d65c01d90de98ce443c880b4d8b Mon Sep 17 00:00:00 2001 From: Themba Dube Date: Thu, 27 Jun 2019 18:32:35 -0400 Subject: [PATCH 3/6] Disable Doxygen preprocessing --- scripts/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/Doxyfile b/scripts/Doxyfile index df15bdb0c..2f93286b5 100644 --- a/scripts/Doxyfile +++ b/scripts/Doxyfile @@ -2011,7 +2011,7 @@ PERLMOD_MAKEVAR_PREFIX = # C-preprocessor directives found in the sources and include files. # The default value is: YES. -ENABLE_PREPROCESSING = YES +ENABLE_PREPROCESSING = NO # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names # in the source code. If set to NO, only conditional compilation will be From 72cf43a176fd94f209766420ac8b4b4d1cba8ecf Mon Sep 17 00:00:00 2001 From: Themba Dube Date: Fri, 28 Jun 2019 08:36:53 -0400 Subject: [PATCH 4/6] Fix inadvertant commenting of signal --- src/lv_core/lv_obj.h | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/lv_core/lv_obj.h b/src/lv_core/lv_obj.h index 047e417d5..f6cd7b2bb 100644 --- a/src/lv_core/lv_obj.h +++ b/src/lv_core/lv_obj.h @@ -121,10 +121,9 @@ enum { LV_SIGNAL_PRESS_LOST, /**< User is still pressing but slid cursor/finger off of the object */ LV_SIGNAL_RELEASED, /**< User pressed object for a short period of time, then released it. Not called if dragged. */ LV_SIGNAL_LONG_PRESS, /**< Object has been pressed for at least `LV_INDEV_LONG_PRESS_TIME`. Not called if dragged.*/ - LV_SIGNAL_LONG_PRESS_REP, /**< Called after `LV_INDEV_LONG_PRESS_TIME` in every - LV_SIGNAL_DRAG_BEGIN, `LV_INDEV_LONG_PRESS_REP_TIME` ms. Not called if dragged.*/ - LV_SIGNAL_DRAG_END, /**< Called on release if not dragged (regardless to long press)*/ - /**< Called in every cases when the object has been released*/ + LV_SIGNAL_LONG_PRESS_REP, /**< Called after `LV_INDEV_LONG_PRESS_TIME` in every `LV_INDEV_LONG_PRESS_REP_TIME` ms. Not called if dragged.*/ + LV_SIGNAL_DRAG_BEGIN, + LV_SIGNAL_DRAG_END, /*Group related*/ LV_SIGNAL_FOCUS, LV_SIGNAL_DEFOCUS, From c1072a62893ea5093b5050077c10ab22578f384c Mon Sep 17 00:00:00 2001 From: Gabor Kiss-Vamosi Date: Fri, 28 Jun 2019 22:15:11 +0200 Subject: [PATCH 5/6] lv_chart: fix axis tick postions --- src/lv_objx/lv_chart.c | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/src/lv_objx/lv_chart.c b/src/lv_objx/lv_chart.c index 7f92b1560..465244a4c 100644 --- a/src/lv_objx/lv_chart.c +++ b/src/lv_objx/lv_chart.c @@ -24,8 +24,6 @@ #define LV_CHART_AXIS_TO_LABEL_DISTANCE 4 #define LV_CHART_AXIS_MAJOR_TICK_LEN_COE 1 / 15 #define LV_CHART_AXIS_MINOR_TICK_LEN_COE 2 / 3 -#define LV_CHART_AXIS_X_TICK_OFFSET_FIX 1 -#define LV_CHART_AXIS_Y_TICK_OFFSET_FIX 0 /********************** * TYPEDEFS @@ -685,13 +683,13 @@ static void lv_chart_draw_div(lv_obj_t * chart, const lv_area_t * mask) uint8_t div_i_start; lv_point_t p1; lv_point_t p2; - lv_coord_t w = lv_obj_get_width(chart) - 1; - lv_coord_t h = lv_obj_get_height(chart) - 1; + lv_coord_t w = lv_obj_get_width(chart); + lv_coord_t h = lv_obj_get_height(chart); lv_coord_t x_ofs = chart->coords.x1; lv_coord_t y_ofs = chart->coords.y1; if(ext->hdiv_cnt != 0) { - /*Draw slide lines if no border*/ + /*Draw side lines if no border*/ if(style->body.border.width != 0) { div_i_start = 1; div_i_end = ext->hdiv_cnt; @@ -703,18 +701,15 @@ static void lv_chart_draw_div(lv_obj_t * chart, const lv_area_t * mask) p1.x = 0 + x_ofs; p2.x = w + x_ofs; for(div_i = div_i_start; div_i <= div_i_end; div_i++) { - p1.y = (int32_t)((int32_t)h * div_i) / (ext->hdiv_cnt + 1); + p1.y = (int32_t)((int32_t)(h - style->line.width) * div_i) / (ext->hdiv_cnt + 1); p1.y += y_ofs; - if(div_i == div_i_start) p1.y += (style->line.width >> 1) + 1; /*The first line might not be visible*/ - if(div_i == div_i_end) p1.y -= (style->line.width >> 1) + 1; /*The last line might not be visible*/ - p2.y = p1.y; lv_draw_line(&p1, &p2, mask, style, opa_scale); } } if(ext->vdiv_cnt != 0) { - /*Draw slide lines if no border*/ + /*Draw side lines if no border*/ if(style->body.border.width != 0) { div_i_start = 1; div_i_end = ext->vdiv_cnt; @@ -726,10 +721,8 @@ static void lv_chart_draw_div(lv_obj_t * chart, const lv_area_t * mask) p1.y = 0 + y_ofs; p2.y = h + y_ofs; for(div_i = div_i_start; div_i <= div_i_end; div_i++) { - p1.x = (int32_t)((int32_t)w * div_i) / (ext->vdiv_cnt + 1); + p1.x = (int32_t)((int32_t)(w - style->line.width) * div_i) / (ext->vdiv_cnt + 1); p1.x += x_ofs; - if(div_i == div_i_start) p1.x += (style->line.width >> 1) + 1; /*The first line might not be visible*/ - if(div_i == div_i_end) p1.x -= (style->line.width >> 1) + 1; /*The last line might not be visible*/ p2.x = p1.x; lv_draw_line(&p1, &p2, mask, style, opa_scale); } @@ -1109,7 +1102,7 @@ static void lv_chart_draw_y_ticks(lv_obj_t * chart, const lv_area_t * mask) /* draw a line at moving y position */ p2.y = p1.y = - y_ofs + h - (int32_t)(((int32_t)h * i) / num_scale_ticks + 1) - LV_CHART_AXIS_Y_TICK_OFFSET_FIX; + y_ofs + (int32_t)((int32_t)(h - style->line.width) * i) / num_scale_ticks; if(i != num_scale_ticks) lv_draw_line(&p1, &p2, mask, style, opa_scale); @@ -1148,6 +1141,7 @@ static void lv_chart_draw_y_ticks(lv_obj_t * chart, const lv_area_t * mask) lv_draw_label(&a, mask, style, opa_scale, buf, LV_TXT_FLAG_CENTER, NULL, -1, -1, NULL); } } + } } } @@ -1216,7 +1210,7 @@ static void lv_chart_draw_x_ticks(lv_obj_t * chart, const lv_area_t * mask) p2.y = p1.y + minor_tick_len; /* minor tick */ /* draw a line at moving x position */ - p2.x = p1.x = x_ofs + (int32_t)(((int32_t)w * i) / num_scale_ticks + 1) - LV_CHART_AXIS_X_TICK_OFFSET_FIX; + p2.x = p1.x = x_ofs + (int32_t)((int32_t)(w - style->line.width) * i) / num_scale_ticks; if(i != num_scale_ticks) lv_draw_line(&p1, &p2, mask, style, opa_scale); From f91479470b3e62a16ed1ce30e0ce872dfc1bca14 Mon Sep 17 00:00:00 2001 From: Gabor Kiss-Vamosi Date: Fri, 28 Jun 2019 22:16:11 +0200 Subject: [PATCH 6/6] lv_disp_get_hor/ver_res: fix if no disp yet --- src/lv_hal/lv_hal_disp.c | 4 ++-- src/lv_objx/lv_chart.c | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/lv_hal/lv_hal_disp.c b/src/lv_hal/lv_hal_disp.c index c8331e273..9e97e6b37 100644 --- a/src/lv_hal/lv_hal_disp.c +++ b/src/lv_hal/lv_hal_disp.c @@ -224,7 +224,7 @@ lv_coord_t lv_disp_get_hor_res(lv_disp_t * disp) if(disp == NULL) disp = lv_disp_get_default(); if(disp == NULL) - return disp->driver.rotated == 0 ? LV_HOR_RES_MAX : LV_VER_RES_MAX; + return LV_HOR_RES_MAX; else return disp->driver.rotated == 0 ? disp->driver.hor_res : disp->driver.ver_res; } @@ -239,7 +239,7 @@ lv_coord_t lv_disp_get_ver_res(lv_disp_t * disp) if(disp == NULL) disp = lv_disp_get_default(); if(disp == NULL) - return disp->driver.rotated == 0 ? LV_VER_RES_MAX : LV_HOR_RES_MAX; + return LV_VER_RES_MAX; else return disp->driver.rotated == 0 ? disp->driver.ver_res : disp->driver.hor_res; } diff --git a/src/lv_objx/lv_chart.c b/src/lv_objx/lv_chart.c index 465244a4c..482e30f64 100644 --- a/src/lv_objx/lv_chart.c +++ b/src/lv_objx/lv_chart.c @@ -94,12 +94,12 @@ lv_obj_t * lv_chart_create(lv_obj_t * par, const lv_obj_t * copy) ext->series.dark = LV_OPA_50; ext->series.width = 2; ext->margin = 0; + memset(&ext->x_axis, 0, sizeof(ext->x_axis)); + memset(&ext->y_axis, 0, sizeof(ext->y_axis)); ext->x_axis.major_tick_len = LV_CHART_TICK_LENGTH_AUTO; ext->x_axis.minor_tick_len = LV_CHART_TICK_LENGTH_AUTO; ext->y_axis.major_tick_len = LV_CHART_TICK_LENGTH_AUTO; ext->y_axis.minor_tick_len = LV_CHART_TICK_LENGTH_AUTO; - memset(&ext->x_axis, 0, sizeof(ext->x_axis)); - memset(&ext->y_axis, 0, sizeof(ext->y_axis)); if(ancestor_design_f == NULL) ancestor_design_f = lv_obj_get_design_cb(new_chart); if(ancestor_signal == NULL) ancestor_signal = lv_obj_get_signal_cb(new_chart); @@ -1092,7 +1092,7 @@ static void lv_chart_draw_y_ticks(lv_obj_t * chart, const lv_area_t * mask) for(i = 0; i < (num_scale_ticks + 1); i++) { /* one extra loop - it may not exist in the list, empty label */ /* first point of the tick */ - p1.x = 0 + x_ofs; + p1.x = 0 + x_ofs - 1; /* second point of the tick */ if((num_of_labels != 0) && (i == 0 || i % ext->y_axis.num_tick_marks == 0))