Merge branch 'feat/support_bar_show_flex' into 'master'

Release v0.2.0

Closes AEG-1824

See merge request ae_group/esp-ui!6

.build-rules.yml

@@ -9,10 +9,22 @@ test_apps:
     - if: IDF_TARGET in ["esp32s2", "esp32s3", "esp32p4", "esp32c3", "esp32c6"]
 
 # Examples
+examples/esp_ui_phone_m5stace_core_s3:
+  enable:
+    - if: IDF_TARGET in ["esp32s3"]
+
 examples/esp_ui_phone_p4_function_ev_board:
   enable:
     - if: IDF_TARGET in ["esp32p4"]
 
+examples/esp_ui_phone_s3_box:
+  enable:
+    - if: IDF_TARGET in ["esp32s3"]
+
+examples/esp_ui_phone_s3_box_3:
+  enable:
+    - if: IDF_TARGET in ["esp32s3"]
+
 examples/esp_ui_phone_s3_lcd_ev_board:
   enable:
     - if: IDF_TARGET in ["esp32s3"]

.gitlab/ci/build.yml

@@ -73,6 +73,14 @@ build_component_test_apps:
     EXAMPLE_DIR: test_apps
 
 # Examples
+build_example_esp_ui_phone_m5stace_core_s3:
+  extends:
+    - .build_examples_template
+    - .build_esp32_s3_idf_release_version
+    - .rules:build:example_esp_ui_phone_m5stace_core_s3
+  variables:
+    EXAMPLE_DIR: examples/esp_idf/esp_ui_phone_m5stace_core_s3
+
 build_example_esp_ui_phone_p4_function_ev_board:
   extends:
     - .build_examples_template
@@ -81,6 +89,22 @@ build_example_esp_ui_phone_p4_function_ev_board:
   variables:
     EXAMPLE_DIR: examples/esp_idf/esp_ui_phone_p4_function_ev_board
 
+build_example_esp_ui_phone_s3_box:
+  extends:
+    - .build_examples_template
+    - .build_esp32_s3_idf_release_version
+    - .rules:build:example_esp_ui_phone_s3_box
+  variables:
+    EXAMPLE_DIR: examples/esp_idf/esp_ui_phone_s3_box
+
+build_example_esp_ui_phone_s3_box_3:
+  extends:
+    - .build_examples_template
+    - .build_esp32_s3_idf_release_version
+    - .rules:build:example_esp_ui_phone_s3_box_3
+  variables:
+    EXAMPLE_DIR: examples/esp_idf/esp_ui_phone_s3_box_3
+
 build_example_esp_ui_phone_s3_lcd_ev_board:
   extends:
     - .build_examples_template

.gitlab/ci/rules.yml

@@ -22,9 +22,18 @@
   - "**/*.md"
 
 # examples folder
+.patterns-example_esp_ui_phone_m5stace_core_s3: &patterns-example_esp_ui_phone_m5stace_core_s3
+  - "examples/esp_idf/esp_ui_phone_m5stace_core_s3/**/*"
+
 .patterns-example_esp_ui_phone_p4_function_ev_board: &patterns-example_esp_ui_phone_p4_function_ev_board
   - "examples/esp_idf/esp_ui_phone_p4_function_ev_board/**/*"
 
+.patterns-example_esp_ui_phone_s3_box: &patterns-example_esp_ui_phone_s3_box
+  - "examples/esp_idf/esp_ui_phone_s3_box/**/*"
+
+.patterns-example_esp_ui_phone_s3_box_3: &patterns-example_esp_ui_phone_s3_box_3
+  - "examples/esp_idf/esp_ui_phone_s3_box_3/**/*"
+
 .patterns-example_esp_ui_phone_s3_lcd_ev_board: &patterns-example_esp_ui_phone_s3_lcd_ev_board
   - "examples/esp_idf/esp_ui_phone_s3_lcd_ev_board/**/*"
 
@@ -68,6 +77,19 @@
       changes: *patterns-build_system
 
 # rules for examples
+.rules:build:example_esp_ui_phone_m5stace_core_s3:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-label-target_test
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-component
+    - <<: *if-dev-push
+      changes: *patterns-example_esp_ui_phone_m5stace_core_s3
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+
 .rules:build:example_esp_ui_phone_p4_function_ev_board:
   rules:
     - <<: *if-protected
@@ -81,6 +103,32 @@
     - <<: *if-dev-push
       changes: *patterns-build_system
 
+.rules:build:example_esp_ui_phone_s3_box:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-label-target_test
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-component
+    - <<: *if-dev-push
+      changes: *patterns-example_esp_ui_phone_s3_box
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+
+.rules:build:example_esp_ui_phone_s3_box_3:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-label-target_test
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-component
+    - <<: *if-dev-push
+      changes: *patterns-example_esp_ui_phone_s3_box_3
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+
 .rules:build:example_esp_ui_phone_s3_lcd_ev_board:
   rules:
     - <<: *if-protected

CHANGELOG.md

@@ -1,5 +1,18 @@
 # ChangeLog
 
+## v0.2.0 - 2024-08-20
+
+### Enhancements:
+
+* feat(examples): 'ESP_UI_Phone' add partition requirement
+* feat(examples): 'esp-idf' update stylesheet
+* feat(examples): 'esp-idf' add esp_ui_phone_s3_box
+* feat(examples): 'esp-idf' add esp_ui_phone_s3_box_3
+* feat(examples): 'esp-idf' add esp_ui_phone_m5stace_core_s3
+* feat(widgets): 'Navigation Bar' support flex visual mode
+* feat(widgets): 'Gesture' support indicator bar and avoid accidental touch
+* feat(core_app): improve resource clean and screen resize operations
+
 ## v0.1.1~1 - 2024-08-16
 
 ### Bugfixes:

README.md

@@ -1,7 +1,8 @@
-[![GitHub Release](https://img.shields.io/github/v/release/espressif/esp-ui)](https://github.com/espressif/esp-ui/releases) [![Espressif Release](https://components.espressif.com/components/espressif/esp-ui/badge.svg)](https://components.espressif.com/components/espressif/esp-ui)
-
 [![Arduino Lint](https://github.com/espressif/esp-ui/actions/workflows/arduino_lint.yml/badge.svg)](https://github.com/espressif/esp-ui/actions/workflows/arduino_lint.yml) [![Version Consistency](https://github.com/espressif/esp-ui/actions/workflows/check_lib_versions.yml/badge.svg)](https://github.com/espressif/esp-ui/actions/workflows/check_lib_versions.yml)
 
+**Latest Arduino Library Version**: [![GitHub Release](https://img.shields.io/github/v/release/espressif/esp-ui)](https://github.com/espressif/esp-ui/releases)
+**Latest Espressif Component Version**: [![Espressif Release](https://components.espressif.com/components/espressif/esp-ui/badge.svg)](https://components.espressif.com/components/espressif/esp-ui)
+
 # ESP-UI
 
 * [中文版本](./README_CN.md)
@@ -19,9 +20,12 @@ Key features include:
 
 The system UI functionality demonstration is as follows:
 
-<div align="center"><img src="https://dl.espressif.com/AE/esp-dev-kits/esp_ui_phone_demo_2.gif" alt="phone_demo" width="600"></div>
-<p align="center">
-<a href="./docs/system_ui_phone.md"> System UI - Phone </a>
+<p align="middle">
+<video controls src="https://dl.espressif.com/AE/esp-dev-kits/esp_ui_phone_demo_1024_600_compress.mp4" muted="true"></video>
+</p>
+
+<p align="middle">
+<a href="https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32p4/esp32-p4-function-ev-board/index.html">ESP32-P4-Function-EV-Board</a> running system UI - <a href="./docs/system_ui_phone_CN.md">Phone</a>
 </p>
 <br>
 

README_CN.md

@@ -1,7 +1,8 @@
-[![GitHub Release](https://img.shields.io/github/v/release/espressif/esp-ui)](https://github.com/espressif/esp-ui/releases) [![Espressif Release](https://components.espressif.com/components/espressif/esp-ui/badge.svg)](https://components.espressif.com/components/espressif/esp-ui)
-
 [![Arduino Lint](https://github.com/espressif/esp-ui/actions/workflows/arduino_lint.yml/badge.svg)](https://github.com/espressif/esp-ui/actions/workflows/arduino_lint.yml) [![Version Consistency](https://github.com/espressif/esp-ui/actions/workflows/check_lib_versions.yml/badge.svg)](https://github.com/espressif/esp-ui/actions/workflows/check_lib_versions.yml)
 
+**最新 Arduino 库版本**: [![GitHub Release](https://img.shields.io/github/v/release/espressif/esp-ui)](https://github.com/espressif/esp-ui/releases)
+**最新 Espressif 组件版本**: [![Espressif Release](https://components.espressif.com/components/espressif/esp-ui/badge.svg)](https://components.espressif.com/components/espressif/esp-ui)
+
 # ESP-UI
 
 * [English Version](./README.md)
@@ -17,11 +18,14 @@ esp-ui 是一个基于 [LVGL](https://github.com/lvgl/lvgl) 的 UI 运行框架
 - 采用 app 的应用管理方式，实现多个 app 的 UI 隔离与共存，使用户专注于各自 app 内的 UI 实现。
 - 应用 UI 兼容 "[Squareline](https://squareline.io/) 导出代码" 的开发方式。
 
-系统 UI 的功能演示如下：
+各系统 UI 的功能演示如下：
+
+<p align="middle">
+<video controls src="https://dl.espressif.com/AE/esp-dev-kits/esp_ui_phone_demo_1024_600_compress.mp4" muted="true"></video>
+</p>
 
-<div align="center"><img src="https://dl.espressif.com/AE/esp-dev-kits/esp_ui_phone_demo_2.gif" alt ="phone_demo" width="600"></div>
-<p align="center">
-<a href="./docs/system_ui_phone_CN.md"> 系统 UI - Phone </a>
+<p align="middle">
+<a href="https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32p4/esp32-p4-function-ev-board/index.html">ESP32-P4-Function-EV-Board</a> 运行系统 UI - <a href="./docs/system_ui_phone_CN.md">Phone</a>
 </p>
 <br>
 

docs/how_to_use.md

@@ -101,24 +101,27 @@ Here are examples of using esp-ui on the Arduino development platform:
 
 ## App Examples
 
-esp-ui provides general app examples for the following system UIs. Users can modify these examples based on their actual needs to quickly develop custom apps.
+esp-ui provides general app examples for the following system UIs. Users can modify the appropriate examples based on their actual needs to quickly develop custom apps.
 
 - [Phone](../src/app_examples/phone/)
-  - [Simple Conf](../src/app_examples/phone/simple_conf/): This example uses a simple app configuration with most parameters set to default values, requiring only a few necessary parameters to be configured by the user. It is suitable for GUI development using "handwritten code"<sup>[Note 1]</sup>.
-  - [Complex Conf](../src/app_examples/phone/complex_conf/): This example uses a complex app configuration where all parameters need to be configured by the user. It is suitable for GUI development using "handwritten code"<sup>[Note 1]</sup>.
-  - [Squareline](../src/app_examples/phone/squareline/): This example uses a simple app configuration with most parameters set to default values, requiring only a few necessary parameters to be configured by the user. It is suitable for GUI development using "Squareline exported code"<sup>[Note 2]</sup>.
+  - [Simple Conf](../src/app_examples/phone/simple_conf/): This example uses a simple app configuration method, where most parameters have default values and only a few essential ones need to be configured by the user. It is suitable for GUI development using the "handwritten code"<sup>[Note 1]</sup> approach.
+  - [Complex Conf](../src/app_examples/phone/complex_conf/): This example uses a complex app configuration method, where all parameters need to be configured by the user. It is suitable for GUI development using the "handwritten code"<sup>[Note 1]</sup> approach.
+  - [Squareline](../src/app_examples/phone/squareline/): This example uses a simple app configuration method, where most parameters have default values and only a few essential ones need to be configured by the user. It is suitable for GUI development using the "Squareline exported code"<sup>[Note 2]</sup> approach. This example also demonstrates how to modify the code exported by Squareline to automatically clean up animation resources when the app exits.
 
 > [!NOTE]
-> 1. "Handwritten code" refers to manually writing code to implement the GUI, usually using `lv_scr_act()` to get the current screen object and adding all GUI elements to this screen object.
-> 2. "Squareline exported code" refers to using [Squareline Studio](https://squareline.io/) to design the GUI, exporting the code, and then adding the exported code to the app to implement the GUI.
-> 3. The app provides an automatic resource cleanup function (`enable_recycle_resource`), which automatically cleans up resources such as **screens**, **animations**, and **timers** when the app exits. This function requires all resources to be created in the `run()` function; otherwise, memory leaks may occur. If you need to create resources outside the `run()` function, disable this function and redefine the `cleanResource()` function to implement manual cleanup.
-> 4. The app provides an automatic default screen creation function (`enable_default_screen`), which automatically creates and loads a default screen when the app runs. Users can obtain the current screen object through `lv_scr_act()`. If you need to create and load the screen object manually, disable this function.
+> 1. "Handwritten code" refers to manually writing code to develop the GUI, typically using `lv_scr_act()` to get the current screen object and adding all GUI elements to that screen object.
+> 2. "Squareline exported code" refers to designing the GUI using [Squareline Studio](https://squareline.io/), exporting the code, and then adding the exported code to the app to develop the GUI.
+> 3. The app provides an automatic default screen creation feature (`enable_default_screen`). When enabled, the system will automatically create and load a default screen when the app's `run()` is executed. Users can get the current screen object via `lv_scr_act()`. If users need to manually create and load screen objects, this feature should be disabled.
+> 4. The app provides an automatic resource cleanup feature (`enable_recycle_resource`). When enabled, the system will automatically clean up resources, including **screens** (`lv_obj_create(NULL)`), **animations** (`lv_anim_start()`), and **timers** (`lv_timer_create()`), when the app exits. This feature requires users to complete the creation of all resources within the `run()/resume()` function or between `startRecordResource()` and `stopRecordResource()`.
+> 5. The app provides an automatic screen size adjustment feature (`enable_resize_visual_area`). When enabled, the system will automatically resize the screen to the visual area when the screen is created. This feature requires users to complete the creation of all screens (such as `lv_obj_create(NULL)`, `lv_timer_create()`, `lv_anim_start()`) within the `run()/resume()` function or between `startRecordResource()` and `stopRecordResource()`. If this feature is not enabled, the app's screen will be displayed in full screen by default, but some areas might be obscured when displaying floating UIs (such as a status bar). The app can call the `getVisualArea()` function to retrieve the final visual area.
 
 > [!WARNING]
-> * When using the "handwritten code" method in the app, to avoid variable and function name conflicts between multiple apps, it is recommended that global variables and functions in the app use the "<app_name>_" prefix.
+> * If users adopt the "handwritten code" approach in their app, it's recommended to enable the `enable_default_screen` feature.
+> * To avoid naming conflicts between variables and functions across multiple apps, it's recommended to prefix global variables and functions in the app with "<app_name>_".
 
 > [!WARNING]
-> * When using the "Squareline exported code" method in the app, it is recommended to use Squareline Studio version `v1.4.0` or above.
-> * It is strongly recommended not to use animations in Squareline, as these animation objects cannot be accessed by the user or esp-ui, and therefore cannot be cleaned up automatically or manually, potentially leading to crashes or memory leaks when the app exits.
-> * To avoid variable and function name conflicts between multiple apps, it is recommended to name all screens with the "<app_name>_" prefix and set "Project Settings" > "Properties" > "Object Naming" to "[Screen_Widget]_Name" in Squareline Studio (this feature requires version >= `v1.4.0`).
-> * Since each set of Squareline exported code includes *ui_helpers.c* and *ui_helpers.h* files, to avoid function name conflicts between multiple apps, delete these two files and use the *ui_helpers* files provided internally by esp-ui. After deletion, modify the `#include "ui_helpers.h"` in the *ui.h* file to `#include "esp_ui.h"`.
+> * If users adopt the "Squareline exported code" approach in their app, it's recommended to use Squareline Studio version `v1.4.0` or above and disable the `enable_default_screen` feature.
+> * To avoid naming conflicts between variables and functions across multiple apps, it's recommended to prefix the names of all screens with "<app_name>_" and set "Object Naming" in Squareline Studio's "Project Settings" > "Properties" to "[Screen_Widget]_Name" (this feature requires version >= `v1.4.0`).
+> * Since each code exported by Squareline includes *ui_helpers.c* and *ui_helpers.h* files, to avoid function name conflicts across multiple apps, it's recommended to delete these two files and use the *ui_helpers* file provided by esp-ui instead. After deletion, modify the *ui.h* file by replacing `#include "ui_helpers.h"` with `#include "esp_ui.h"`.
+> * It's advised not to create and use animations in Squareline, as these animation resources cannot be directly accessed by the user or esp-ui and therefore cannot be automatically or manually cleaned up, which may lead to program crashes or memory leaks when the app exits. If you must use them, you need to modify the part of the exported code where the animation resources are created. Please refer to the implementation in the [Squareline Example](../src/app_examples/phone/squareline/), which manually records animation resources by adding `startRecordResource()` and `stopRecordResource()` functions before and after `lv_anim_start()` so that they can be automatically cleaned up when the app closes.
+> * Additionally, when using the code exported by Squareline, users still need to make some additional modifications based on the actual situation, such as renaming the `ui_init()` function to `<app_name>_ui_init()` to ensure the code can be compiled and run correctly.