diff --git a/docs/src/common-widget-features/styles/style-properties.mdx b/docs/src/common-widget-features/styles/style-properties.mdx index 7d75123e07..09df571de9 100644 --- a/docs/src/common-widget-features/styles/style-properties.mdx +++ b/docs/src/common-widget-features/styles/style-properties.mdx @@ -2,6 +2,15 @@ title: Style Properties description: LVGL style property reference. --- +{/* ********************************************************************** + DO NOT EDIT + This file is automatically generated by "style_api_gen.py" + ********************************************************************** */} + + +## Size and Position + +Properties related to size, position, alignment and layout of Widgets. - Sets width of Widget. Pixel, percentage and `LV_SIZE_CONTENT` values can be used. Percentage values are relative to the width of the parent's content area. - - Sets a minimal width. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area. - - Sets a maximal width. Pixel and percentage values can be used. Percentage values are relative to the width of the parent's content area. - - Sets height of Widget. Pixel, percentage and `LV_SIZE_CONTENT` can be used. Percentage values are relative to the height of the parent's content area. - - Sets a minimal height. Pixel and percentage values can be used. Percentage values are relative to the height of the parent's content area. - - Sets a maximal height. Pixel and percentage values can be used. Percentage values are relative to the height of the parent's content area. - - Its meaning depends on the type of Widget. For example in case of lv_scale it means the length of the ticks. + + +Set X coordinate of Widget considering the ``align`` setting. Pixel and percentage +values can be used. Percentage values are relative to the width of the parent's +content area. + + + +Set Y coordinate of Widget considering the ``align`` setting. Pixel and percentage +values can be used. Percentage values are relative to the height of the parent's +content area. - Set the alignment which tells from which point of the parent the X and Y coordinates should be interpreted. Possible values are: `LV_ALIGN_DEFAULT`, `LV_ALIGN_TOP_LEFT/MID/RIGHT`, `LV_ALIGN_BOTTOM_LEFT/MID/RIGHT`, `LV_ALIGN_LEFT/RIGHT_MID`, `LV_ALIGN_CENTER`. `LV_ALIGN_DEFAULT` means `LV_ALIGN_TOP_LEFT` with LTR base direction and `LV_ALIGN_TOP_RIGHT` with RTL base direction. - - Make Widget wider on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's width. - - Make Widget higher on both sides with this value. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's height. - - Move Widget with this value in X direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's width. - - Move Widget with this value in Y direction. Applied after layouts, aligns and other positioning. Pixel and percentage (with `lv_pct(x)`) values can be used. Percentage values are relative to Widget's height. - - Move object around the centre of the parent object (e.g. around the circumference of a scale). - - Zoom Widget horizontally. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on. - - Zoom Widget vertically. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on. - - Rotate Widget. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg. - - Set pivot point's X coordinate for transformations. Relative to Widget's top left corner. - - Set pivot point's Y coordinate for transformations. Relative to Widget's top left corner. - - Skew Widget horizontally. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg. - - Skew Widget vertically. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg. - +## Padding + +Properties to describe spacing between the parent's sides and the children and among the children. Very similar to the padding properties in HTML. + - Sets the padding on the top. It makes the content area smaller in this direction. - - Sets the padding on the bottom. It makes the content area smaller in this direction. - - Sets the padding on the left. It makes the content area smaller in this direction. - - Sets the padding on the right. It makes the content area smaller in this direction. - - Sets the padding between the rows. Used by the layouts. - - Sets the padding between the columns. Used by the layouts. - - -Pad text labels away from the scale ticks/remainder of the `LV_PART_`. - +Pad text labels away from the scale ticks/remainder of the ``LV_PART_``. +## Margin + +Properties to describe spacing around a Widget. Very similar to the margin properties in HTML. + - Sets margin on the top. Widget will keep this space from its siblings in layouts. - - Sets margin on the bottom. Widget will keep this space from its siblings in layouts. - - Sets margin on the left. Widget will keep this space from its siblings in layouts. - - Sets margin on the right. Widget will keep this space from its siblings in layouts. - +## Background + +Properties to describe the background color and image of Widget. + - Set background color of Widget. - - Set opacity of the background. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DIR_NONE`. - - Set direction of the gradient of the background. Possible values are `LV_GRAD_DIR_NONE/HOR/VER`. - - Set point from which background color should start for gradients. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on. - - Set point from which background's gradient color should start. 0 means to top/left side, 255 the bottom/right side, 128 the center, and so on. - - Set opacity of the first gradient color. - - Set opacity of the second gradient color. - - Set gradient definition. The pointed instance must exist while Widget is alive. NULL to disable. It wraps `BG_GRAD_COLOR`, `BG_GRAD_DIR`, `BG_MAIN_STOP` and `BG_GRAD_STOP` into one descriptor and allows creating gradients with more colors as well. If it's set other gradient related properties will be ignored. - - Set a background image. Can be a pointer to `lv_image_dsc_t`, a path to a file or an `LV_SYMBOL_...`. - - Set opacity of the background image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set a color to mix to the background image. - - Set intensity of background image recoloring. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means no mixing, 255, `LV_OPA_100` or `LV_OPA_COVER` means full recoloring, other values or LV_OPA_10, LV_OPA_20, etc are interpreted proportionally. - - If enabled the background image will be tiled. Possible values are `true` or `false`. - +## Border + +Properties to describe the borders + - Set color of the border. - - Set opacity of the border. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set width of the border. Only pixel values can be used. - - Set only which side(s) the border should be drawn. Possible values are `LV_BORDER_SIDE_NONE/TOP/BOTTOM/LEFT/RIGHT/INTERNAL`. OR-ed values can be used as well, e.g. `LV_BORDER_SIDE_TOP | LV_BORDER_SIDE_LEFT`. - - Sets whether the border should be drawn before or after the children are drawn. `true`: after children, `false`: before children. - +## Outline + +Properties to describe the outline. It's like a border but drawn outside of the rectangles. + - Set width of outline in pixels. - - Set color of outline. - - Set opacity of outline. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set padding of outline, i.e. the gap between Widget and the outline. - +## Shadow + +Properties to describe the shadow drawn under the rectangles. + - Set width of the shadow in pixels. The value should be >= 0. - = 0. layout={false} extDraw={true} > - Set an offset on the shadow in pixels in X direction. - - Set an offset on the shadow in pixels in Y direction. - - Make shadow calculation to use a larger or smaller rectangle as base. The value can be in pixels to make the area larger/smaller. - - Set color of shadow. - - Set opacity of shadow. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - +## Image + +Properties to describe the images + - Set opacity of an image. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set color to mix with the image. - - Set intensity of color mixing. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set image colorkey definition. The lv_image_colorkey_t contains two color values: `high_color` and `low_color`. the color of pixels ranging from `low_color` to `high_color` will be transparent. - +## Line + +Properties to describe line-like Widgets + - Set width of lines in pixels. - - Set width of dashes in pixels. Note that dash works only on horizontal and vertical lines. - - Set gap between dashes in pixels. Note that dash works only on horizontal and vertical lines. - - Make end points of the lines rounded. `true`: rounded, `false`: perpendicular line ending. - - Set color of lines. - - Set opacity of lines. - +## Arc + +TODO + - Set width (thickness) of arcs in pixels. - - Make end points of arcs rounded. `true`: rounded, `false`: perpendicular line ending. - - Set color of arc. - - Set opacity of arcs. - - Set an image from which arc will be masked out. It's useful to display complex effects on the arcs. Can be a pointer to `lv_image_dsc_t` or a path to a file. - +## Text + +Properties to describe the properties of text. All these properties are inherited. + - Sets color of text. - - Set opacity of text. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set font of text (a pointer `lv_font_t *`). - - Set letter space in pixels. - - Set line space in pixels. - - Set decoration for the text. Possible values are `LV_TEXT_DECOR_NONE/UNDERLINE/STRIKETHROUGH`. OR-ed values can be used as well. - - Set how to align the lines of the text. Note that it doesn't align the Widget itself, only the lines inside the Widget. Possible values are `LV_TEXT_ALIGN_LEFT/CENTER/RIGHT/AUTO`. `LV_TEXT_ALIGN_AUTO` detect the text base direction and uses left or right alignment accordingly. - - Sets the color of letter outline stroke. - - Set the letter outline stroke width in pixels. - - Set the opacity of the letter outline stroke. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Set the text leading trim mode. Removes empty space above and/or below text based on font metrics (cap-height, x-height, baseline). Similar to CSS `text-box-trim`. Possible values are `LV_TEXT_LEADING_TRIM_NONE/CAPITAL_BASELINE/LOWER_BASELINE/CAPITAL/LOWER`. - +## Blur + +Blur the widget or its background + - Sets the intensity of blurring. Applied on each lv_part separately before the children are rendered. - - -If `true` the background of the widget will be blurred. The part should have < 100% -opacity to make it visible. If `false` the given part will be blurred when it's -rendered but before drawing the children. - +If `true` the background of the widget will be blurred. The part should have less +than 100% opacity to make it visible. If `false` the given part will be blurred +when it's rendered but before drawing the children. - Setting to `LV_BLUR_QUALITY_SPEED` the blurring algorithm will prefer speed over quality. `LV_BLUR_QUALITY_PRECISION` will force using higher quality but slower blur. With `LV_BLUR_QUALITY_AUTO` the quality will be selected automatically. - +## Drop Shadow + +Take an A8 snapshot of the given part and blur it. + - Sets the intensity of blurring. Applied on each lv_part separately before the children are rendered. - - Set an offset on the shadow in pixels in X direction. - - Set an offset on the shadow in pixels in Y direction. - - Set the color of the shadow. - - Set the opacity of the shadow. - - Setting to `LV_BLUR_QUALITY_SPEED` the blurring algorithm will prefer speed over quality. `LV_BLUR_QUALITY_PRECISION` will force using higher quality but slower blur. With `LV_BLUR_QUALITY_AUTO` the quality will be selected automatically. - +## Miscellaneous + +Mixed properties for various purposes. + - Set radius on every corner. The value is interpreted in pixels (>= 0) or `LV_RADIUS_CIRCLE` for max radius. - = 0) or layout={false} extDraw={false} > - Move start point of object (e.g. scale tick) radially. - - Enable clipping of content that overflows rounded corners of parent Widget. Can be `true` or `false`. - - Scale down all opacity values of the Widget by this factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - First draw Widget on the layer, then scale down layer opacity factor. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent, 255, `LV_OPA_100` or `LV_OPA_COVER` means fully covering, other values or LV_OPA_10, LV_OPA_20, etc means semi transparency. - - Mix a color with all colors of the Widget. - - The intensity of mixing of color filter. - - Set a color to mix to the obj. - - Sets the intensity of color mixing. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means fully transparent. A value of 255, `LV_OPA_100` or `LV_OPA_COVER` means fully opaque. Intermediate values like LV_OPA_10, LV_OPA_20, etc result in semi-transparency. - - Animation template for Widget's animation. Should be a pointer to `lv_anim_t`. The animation parameters are widget specific, e.g. animation time could be the E.g. blink time of the cursor on the Text Area or scroll time of a roller. See Widgets' documentation to learn more. - - Animation duration in milliseconds. Its meaning is widget specific. E.g. blink time of the cursor on the Text Area or scroll time of a roller. See Widgets' documentation to learn more. - - -An initialized `lv_style_transition_dsc_t` to describe a transition. - +An initialized ``lv_style_transition_dsc_t`` to describe a transition. - Describes how to blend the colors to the background. Possible values are `LV_BLEND_MODE_NORMAL/ADDITIVE/SUBTRACTIVE/MULTIPLY/DIFFERENCE`. - - Set layout of Widget. Children will be repositioned and resized according to policies set for the layout. For possible values see documentation of the layouts. - - Set base direction of Widget. Possible values are `LV_BIDI_DIR_LTR/RTL/AUTO`. - - If set, a layer will be created for the widget and the layer will be masked with this A8 bitmap mask. - - Adjust sensitivity for rotary encoders in 1/256 unit. It means, 128: slow down the rotary to half, 512: speeds up to double, 256: no change. - +## Flex + +Flex layout properties. + - Defines in which direction the flex layout should arrange the children. - - Defines how to align the children in the direction of flex flow. - - Defines how to align the children perpendicular to the direction of flex flow. - - Defines how to align the tracks of the flow. - - Defines how much space to take proportionally from the free space of the Widget's track. - +## Grid + +Grid layout properties. + - An array to describe the columns of the grid. Should be LV_GRID_TEMPLATE_LAST terminated. - - Defines how to distribute the columns. - - An array to describe the rows of the grid. Should be LV_GRID_TEMPLATE_LAST terminated. - - Defines how to distribute the rows. - - Set column in which Widget should be placed. - - Set how to align Widget horizontally. - - Set how many columns Widget should span. Needs to be >= 1. - = 1. layout={true} extDraw={false} > - Set row in which Widget should be placed. - - Set how to align Widget vertically. - - Set how many rows Widget should span. Needs to be >= 1. - diff --git a/include/lvgl/core/lv_obj_style_gen.h b/include/lvgl/core/lv_obj_style_gen.h index bfe9a47636..aaf6184f49 100644 --- a/include/lvgl/core/lv_obj_style_gen.h +++ b/include/lvgl/core/lv_obj_style_gen.h @@ -1291,9 +1291,9 @@ static inline int32_t lv_obj_get_style_blur_radius(const lv_obj_t * obj, lv_part } /** - * If `true` the background of the widget will be blurred. The part should have < 100% - * opacity to make it visible. If `false` the given part will be blurred when it's - * rendered but before drawing the children. + * If `true` the background of the widget will be blurred. The part should have less + * than 100% opacity to make it visible. If `false` the given part will be blurred + * when it's rendered but before drawing the children. * Default: `false`, inherited: No, layout: No, ext. draw: No. * @param obj Pointer to Widget * @param part One of the `LV_PART_...` enum values @@ -3042,9 +3042,9 @@ void lv_obj_set_style_text_leading_trim(lv_obj_t * obj, lv_text_leading_trim_t v void lv_obj_set_style_blur_radius(lv_obj_t * obj, int32_t value, lv_style_selector_t selector); /** - * If `true` the background of the widget will be blurred. The part should have < 100% - * opacity to make it visible. If `false` the given part will be blurred when it's - * rendered but before drawing the children. + * If `true` the background of the widget will be blurred. The part should have less + * than 100% opacity to make it visible. If `false` the given part will be blurred + * when it's rendered but before drawing the children. * Default: `false`, inherited: No, layout: No, ext. draw: No. * @param obj Pointer to Widget * @param value Value to submit diff --git a/include/lvgl/core/lv_style_gen.h b/include/lvgl/core/lv_style_gen.h index cea70036e1..8bb73a202d 100644 --- a/include/lvgl/core/lv_style_gen.h +++ b/include/lvgl/core/lv_style_gen.h @@ -798,9 +798,9 @@ void lv_style_set_text_leading_trim(lv_style_t * style, lv_text_leading_trim_t v void lv_style_set_blur_radius(lv_style_t * style, int32_t value); /** - * If `true` the background of the widget will be blurred. The part should have < 100% - * opacity to make it visible. If `false` the given part will be blurred when it's - * rendered but before drawing the children. + * If `true` the background of the widget will be blurred. The part should have less + * than 100% opacity to make it visible. If `false` the given part will be blurred + * when it's rendered but before drawing the children. * Default: `false`, inherited: No, layout: No, ext. draw: No. * @param style Pointer to style * @param value Value to submit @@ -2110,9 +2110,9 @@ void lv_style_set_grid_cell_row_span(lv_style_t * style, int32_t value); } /** - * If `true` the background of the widget will be blurred. The part should have < 100% - * opacity to make it visible. If `false` the given part will be blurred when it's - * rendered but before drawing the children. + * If `true` the background of the widget will be blurred. The part should have less + * than 100% opacity to make it visible. If `false` the given part will be blurred + * when it's rendered but before drawing the children. * Default: `false`, inherited: No, layout: No, ext. draw: No. * @param val Value to submit */ diff --git a/scripts/style_api_gen.py b/scripts/style_api_gen.py index 342fd731a6..8139eb7284 100755 --- a/scripts/style_api_gen.py +++ b/scripts/style_api_gen.py @@ -5,7 +5,7 @@ - lvgl/include/lvgl/core/lv_style_gen.h - lvgl/src/core/lv_obj_style_gen.c - lvgl/src/misc/lv_style_gen.c -- lvgl/docs/src/common-widget-features/styles/style-properties.rst +- lvgl/docs/src/common-widget-features/styles/style-properties.mdx This script effectively "factors out" what would be duplicate code and documentation in all 5 of the above files, into 1 place: below. @@ -315,7 +315,7 @@ props = [ 'style_type': 'num', 'var_type': 'lv_opa_t' , 'default':'`LV_OPA_COVER`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, 'dsc': "Set opacity of lines."}, -{'section': 'Arc', 'dsc':'TODO' }, +{'section': 'Arc', 'dsc':'Properties to describe the Arc Widget' }, {'name': 'ARC_WIDTH', 'style_type': 'num', 'var_type': 'int32_t' , 'default':0, 'inherited': 0, 'layout': 0, 'ext_draw': 1, 'dsc': "Set width (thickness) of arcs in pixels."}, @@ -388,7 +388,7 @@ props = [ {'name': 'BLUR_BACKDROP', 'style_type': 'num', 'var_type': 'bool', 'default':'`false`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, - 'dsc': "If `true` the background of the widget will be blurred. The part should have < 100% opacity to make it visible. If `false` the given part will be blurred when it's rendered but before drawing the children."}, + 'dsc': "If `true` the background of the widget will be blurred. The part should have less than 100% opacity to make it visible. If `false` the given part will be blurred when it's rendered but before drawing the children."}, {'name': 'BLUR_QUALITY', 'style_type': 'num', 'var_type': 'lv_blur_quality_t', 'default':'`LV_BLUR_QUALITY_AUTO`', 'inherited': 0, 'layout': 0, 'ext_draw': 0, @@ -585,11 +585,14 @@ HEADING = f'''\ ''' -RST_HEADING = f'''\ -.. ********************************************************************** -.. DO NOT EDIT -.. This file is automatically generated by "{_cfg_this_script}" -.. **********************************************************************''' +MDX_HEADING = f'''--- +title: Style Properties +description: LVGL style property reference. +--- +{{/* ********************************************************************** + DO NOT EDIT + This file is automatically generated by "{_cfg_this_script}" + ********************************************************************** */}}''' # ========================================================================= @@ -883,34 +886,36 @@ def local_style_set_h(p): def docs(p): if "section" in p: print() - print(p['section']) - print("-" * len(p['section'])) + print(f"## {p['section']}") print() print(p['dsc']) return - li_style = "style='display:inline-block; margin-right: 20px; margin-left: 0px" - dsc = word_wrapped_description(p['dsc'], in_a_comment=False) - - print() name = p["name"].lower() - print(name) - print("~" * len(name)) - print() - print(dsc) if 'default' in p: - d, i, L, e = extra_info(p) + d, i, l, e = extra_info(p) + # Convert the inherited/layout/extDraw strings to JSX booleans/values + inherited_val = "true" if i.strip().lower() == "yes" else "false" + layout_val = "true" if l.strip().lower() == "yes" else "false" + ext_draw_val = "true" if e.strip().lower() == "yes" else "false" print() - print(".. raw:: html") + print(f'') + print(dsc) + print(f'') + else: + # No default info — just emit the description as plain text under a heading print() - print(" ") + print(f"### {name}") + print() + print(dsc) def guard_proc(p): @@ -1042,16 +1047,12 @@ print('''\ print('#endif /* LV_STYLE_GEN_H */') # ------------------------------------------------------------------------- -# style-properties.rst +# style-properties.mdx # ------------------------------------------------------------------------- -sys.stdout = open(base_dir + '/../docs/src/common-widget-features/styles/style-properties.rst', 'w') +sys.stdout = open(base_dir + '/../docs/src/common-widget-features/styles/style-properties.mdx', 'w') -print(RST_HEADING) -print('.. _style_properties:') +print(MDX_HEADING) print() -print('================') -print('Style Properties') -print('================') for prop in props: docs(prop)