From 36b05790aa4ae7b47de5cffa3e79cd1e4e53f392 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 1 Feb 2026 19:53:31 -0700 Subject: [PATCH] docs(style API): add API documentation to `style_api_gen.py` (#9637) Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../styles/style-properties.rst | 262 +- scripts/style_api_gen.py | 706 +++-- src/core/lv_obj_style_gen.c | 7 +- src/core/lv_obj_style_gen.h | 2602 ++++++++++++++++- src/misc/lv_style.h | 51 + src/misc/lv_style_gen.c | 7 +- src/misc/lv_style_gen.h | 1739 ++++++++++- 7 files changed, 5037 insertions(+), 337 deletions(-) diff --git a/docs/src/common-widget-features/styles/style-properties.rst b/docs/src/common-widget-features/styles/style-properties.rst index a166cdf9ec..24f151e4bf 100644 --- a/docs/src/common-widget-features/styles/style-properties.rst +++ b/docs/src/common-widget-features/styles/style-properties.rst @@ -1,10 +1,14 @@ +.. ********************************************************************** +.. DO NOT EDIT +.. This file is automatically generated by "style_api_gen.py" +.. ********************************************************************** .. _style_properties: ================ Style Properties ================ -Size and position +Size and Position ----------------- Properties related to size, position, alignment and layout of Widgets. @@ -12,7 +16,8 @@ Properties related to size, position, alignment and layout of Widgets. width ~~~~~ -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 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. .. raw:: html @@ -26,7 +31,8 @@ Sets width of Widget. Pixel, percentage and `LV_SIZE_CONTENT` values can be used min_width ~~~~~~~~~ -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 minimal width. Pixel and percentage values can be used. Percentage values +are relative to the width of the parent's content area. .. raw:: html @@ -40,7 +46,8 @@ Sets a minimal width. Pixel and percentage values can be used. Percentage values max_width ~~~~~~~~~ -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 a maximal width. Pixel and percentage values can be used. Percentage values +are relative to the width of the parent's content area. .. raw:: html @@ -54,7 +61,8 @@ Sets a maximal width. Pixel and percentage values can be used. Percentage values height ~~~~~~ -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 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. .. raw:: html @@ -68,7 +76,8 @@ Sets height of Widget. Pixel, percentage and `LV_SIZE_CONTENT` can be used. Perc min_height ~~~~~~~~~~ -Sets a minimal height. Pixel and percentage values can be used. Percentage values are relative to the width 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. .. raw:: html @@ -82,7 +91,8 @@ Sets a minimal height. Pixel and percentage values can be used. Percentage value max_height ~~~~~~~~~~ -Sets a maximal 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. .. raw:: html @@ -96,7 +106,8 @@ Sets a maximal height. Pixel and percentage values can be used. Percentage value length ~~~~~~ -Its meaning depends on the type of Widget. For example in case of lv_scale it means the length of the ticks. +Its meaning depends on the type of Widget. For example in case of lv_scale it means +the length of the ticks. .. raw:: html @@ -110,7 +121,9 @@ Its meaning depends on the type of Widget. For example in case of lv_scale it me x ~ -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 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. .. raw:: html @@ -124,7 +137,9 @@ Set X coordinate of Widget considering the ``align`` setting. Pixel and percenta y ~ -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 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. .. raw:: html @@ -138,7 +153,12 @@ Set Y coordinate of Widget considering the ``align`` setting. Pixel and percenta align ~~~~~ -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. +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. .. raw:: html @@ -152,7 +172,8 @@ Set the alignment which tells from which point of the parent the X and Y coordin transform_width ~~~~~~~~~~~~~~~ -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 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. .. raw:: html @@ -166,7 +187,8 @@ Make Widget wider on both sides with this value. Pixel and percentage (with `lv_ transform_height ~~~~~~~~~~~~~~~~ -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. +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. .. raw:: html @@ -180,7 +202,9 @@ Make Widget higher on both sides with this value. Pixel and percentage (with `lv translate_x ~~~~~~~~~~~ -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 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. .. raw:: html @@ -194,7 +218,9 @@ Move Widget with this value in X direction. Applied after layouts, aligns and ot translate_y ~~~~~~~~~~~ -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 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. .. raw:: html @@ -208,7 +234,8 @@ Move Widget with this value in Y direction. Applied after layouts, aligns and ot translate_radial ~~~~~~~~~~~~~~~~ -Move object around the centre of the parent object (e.g. around the circumference of a scale) +Move object around the centre of the parent object (e.g. around the circumference +of a scale). .. raw:: html @@ -222,7 +249,8 @@ Move object around the centre of the parent object (e.g. around the circumferenc transform_scale_x ~~~~~~~~~~~~~~~~~ -Zoom Widget horizontally. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 half size, 512 double size, and so on +Zoom Widget horizontally. The value 256 (or `LV_SCALE_NONE`) means normal size, 128 +half size, 512 double size, and so on. .. raw:: html @@ -236,7 +264,8 @@ Zoom Widget horizontally. The value 256 (or `LV_SCALE_NONE`) means normal size, transform_scale_y ~~~~~~~~~~~~~~~~~ -Zoom Widget vertically. 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. .. raw:: html @@ -264,7 +293,7 @@ Rotate Widget. The value is interpreted in 0.1 degree units. E.g. 450 means 45 d transform_pivot_x ~~~~~~~~~~~~~~~~~ -Set pivot point's X coordinate for transformations. Relative to Widget's top left corner' +Set pivot point's X coordinate for transformations. Relative to Widget's top left corner. .. raw:: html @@ -278,7 +307,7 @@ Set pivot point's X coordinate for transformations. Relative to Widget's top lef transform_pivot_y ~~~~~~~~~~~~~~~~~ -Set pivot point's Y 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. .. raw:: html @@ -292,7 +321,8 @@ Set pivot point's Y coordinate for transformations. Relative to Widget's top lef transform_skew_x ~~~~~~~~~~~~~~~~ -Skew Widget horizontally. The value is interpreted in 0.1 degree units. E.g. 450 means 45 deg. +Skew Widget horizontally. The value is interpreted in 0.1 degree units. E.g. 450 +means 45 deg. .. raw:: html @@ -409,7 +439,7 @@ Sets the padding between the columns. Used by the layouts. pad_radial ~~~~~~~~~~ -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_``. .. raw:: html @@ -503,7 +533,9 @@ Set background color of Widget. bg_opa ~~~~~~ -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 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. .. raw:: html @@ -517,7 +549,7 @@ Set opacity of the background. Value 0, `LV_OPA_0` or `LV_OPA_TRANSP` means full bg_grad_color ~~~~~~~~~~~~~ -Set gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DIR_NONE` +Set gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DIR_NONE`. .. raw:: html @@ -531,7 +563,8 @@ Set gradient color of the background. Used only if `grad_dir` is not `LV_GRAD_DI bg_grad_dir ~~~~~~~~~~~ -Set direction of the gradient of the background. Possible values are `LV_GRAD_DIR_NONE/HOR/VER`. +Set direction of the gradient of the background. Possible values are +`LV_GRAD_DIR_NONE/HOR/VER`. .. raw:: html @@ -545,7 +578,8 @@ Set direction of the gradient of the background. Possible values are `LV_GRAD_DI bg_main_stop ~~~~~~~~~~~~ -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 color should start for gradients. 0 means to +top/left side, 255 the bottom/right side, 128 the center, and so on. .. raw:: html @@ -559,7 +593,8 @@ Set point from which background color should start for gradients. 0 means to top bg_grad_stop ~~~~~~~~~~~~ -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 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. .. raw:: html @@ -573,7 +608,7 @@ Set point from which background's gradient color should start. 0 means to top/le bg_main_opa ~~~~~~~~~~~ -Set opacity of the first gradient color +Set opacity of the first gradient color. .. raw:: html @@ -587,7 +622,7 @@ Set opacity of the first gradient color bg_grad_opa ~~~~~~~~~~~ -Set opacity of the second gradient color +Set opacity of the second gradient color. .. raw:: html @@ -601,7 +636,10 @@ Set opacity of the second gradient color bg_grad ~~~~~~~ -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 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. .. raw:: html @@ -615,7 +653,8 @@ Set gradient definition. The pointed instance must exist while Widget is alive. bg_image_src ~~~~~~~~~~~~ -Set a background image. Can be a pointer to `lv_image_dsc_t`, a path to a file or an `LV_SYMBOL_...` +Set a background image. Can be a pointer to `lv_image_dsc_t`, a path to a file or +an `LV_SYMBOL_...`. .. raw:: html @@ -629,7 +668,9 @@ Set a background image. Can be a pointer to `lv_image_dsc_t`, a path to a file o bg_image_opa ~~~~~~~~~~~~ -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 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. .. raw:: html @@ -657,7 +698,10 @@ Set a color to mix to the background image. bg_image_recolor_opa ~~~~~~~~~~~~~~~~~~~~ -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. +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. .. raw:: html @@ -690,7 +734,7 @@ Properties to describe the borders border_color ~~~~~~~~~~~~ -Set color of the border +Set color of the border. .. raw:: html @@ -704,7 +748,9 @@ Set color of the border border_opa ~~~~~~~~~~ -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 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. .. raw:: html @@ -732,12 +778,14 @@ Set width of the border. Only pixel values can be used. border_side ~~~~~~~~~~~ -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`. +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`. .. raw:: html -Drop shadow +Drop Shadow ----------- Take an A8 snapshot of the given part and blur it. @@ -1332,7 +1406,8 @@ Take an A8 snapshot of the given part and blur it. drop_shadow_radius ~~~~~~~~~~~~~~~~~~ -Sets the intensity of blurring. Applied on each lv_part separately before the children are rendered. +Sets the intensity of blurring. Applied on each lv_part separately before the +children are rendered. .. raw:: html @@ -1402,12 +1477,14 @@ Set the opacity of the shadow. drop_shadow_quality ~~~~~~~~~~~~~~~~~~~ -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. +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. .. raw:: html