feat(repo): update docs and library properties

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 
-exclude: '(.*/assets/.*|app_examples/phone/squareline/src/ui/.*|.*src/squareline/SQ.*/.*|.*src/fonts/.*/.*|docs/|.*py)'
+exclude: '(.*/assets/.*|app_examples/phone/squareline/src/ui/.*|.*src/squareline/ui_comp/.*|.*src/squareline/ui_helpers/.*|.*src/fonts/.*/.*|docs/|.*py)'
 repos:
   - repo: https://github.com/igrr/astyle_py.git
     rev: v1.0.5

CHANGELOG.md

@@ -1,5 +1,24 @@
 # ChangeLog
 
+## v0.4.0 - 2024-10-23
+
+### Enhancements:
+
+* feat(core): support compilation on non-Unix/Linux systems
+* feat(core): add event module
+* feat(core): add lvgl lock & unlock
+* feat(core): add stylesheet template
+* feat(phone): public app function 'getPhone()'
+* feat(phone): only change the app's visible area size when the status bar is completely opaque
+* feat(phone): cancel navigation bar and enable gesture-based navigation by default
+* feat(phone): add stylesheet 320x480, 800x1280, 1280x800
+* feat(squareline): add ui_comp
+
+### Bugfixes:
+
+* fix(cmake): remove unused code
+* fix(conf): fix missing macros definition
+
 ## v0.3.1 - 2024-09-25
 
 ### Enhancements:

docs/how_to_use.md

@@ -15,7 +15,10 @@
     - [Installing the Library](#installing-the-library)
     - [Configuration Instructions](#configuration-instructions-1)
     - [Project Examples](#project-examples-1)
-  - [App Examples](#app-examples)
+  - [App Development](#app-development)
+    - [Principles and Features](#principles-and-features)
+    - [General Examples](#general-examples)
+    - [Considerations](#considerations)
 
 ## Dependencies
 
@@ -99,29 +102,62 @@ Here are examples of using esp-brookesia on the Arduino development platform:
 
 - [ESP_Brookesia_Phone](../examples/arduino/ESP_Brookesia_Phone): This example demonstrates how to run the Phone UI using the [ESP32_Display_Panel](https://github.com/esp-arduino-libs/ESP32_Display_Panel) library.
 
-## App Examples
+## App Development
 
-esp-brookesia 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.
+### Principles and Features
+
+esp-brookesia provides the capability to develop apps through C++ inheritance, allowing users to inherit from the appropriate system app base class (e.g., the [ESP_Brookesia_PhoneApp](../src/systems/phone/esp_brookesia_phone_app.hpp) class for Phone) and implement the necessary pure virtual functions (`run()` and `back()`). Users can also redefine other virtual functions as needed (e.g., `close()`, `init()`, and `pause()`), which are derived from the core app base class [ESP_Brookesia_CoreApp](../src/core/esp_brookesia_core_app.hpp).
+
+The system app base class in esp-brookesia inherits from the core app base class `ESP_Brookesia_CoreApp`, which provides the following user-configurable features:
+
+- **Name**: Set the app's name by configuring the `name` field in `ESP_Brookesia_CoreAppData_t`.
+- **Icon**: Set the app's icon by configuring the `launcher_icon` field in `ESP_Brookesia_CoreAppData_t`.
+- **Screen Size**: Set the app's screen size by configuring the `screen_size` field in `ESP_Brookesia_CoreAppData_t`. It is recommended that the screen size equals the actual screen size (i.e., `screen_size = ESP_BROOKESIA_STYLE_SIZE_RECT_PERCENT(100, 100)`) to avoid display anomalies in unused screen areas when the app's screen size is smaller.
+- **Automatic Default Screen Creation**: Enable this feature by setting `enable_default_screen = 1` in `ESP_Brookesia_CoreAppData_t`. The system will automatically create and load a default screen when the app executes `run()`, and users can retrieve the current screen object using `lv_scr_act()`. If users wish to create and load screen objects manually, this feature should be disabled.
+- **Automatic Resource Cleanup**: Enable this feature by setting `enable_recycle_resource = 1` in `ESP_Brookesia_CoreAppData_t`. 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 requires users to complete all resource creation within the `run()/resume()` function or between `startRecordResource()` and `stopRecordResource()`.
+- **Automatic Screen Size Adjustment**: Enable this feature by setting `enable_resize_visual_area = 1` in `ESP_Brookesia_CoreAppData_t`. The system will automatically adjust the screen size to the visual area size when the app creates a screen. This also requires users to complete all screen creation within the `run()/resume()` function or between `startRecordResource()` and `stopRecordResource()`. If the screen displays floating UI elements (e.g., status bar) and this feature is not enabled, the app's screen will default to full-screen size, which may obscure some areas. The app can call the `getVisualArea()` function to retrieve the final visual area.
+
+Additionally, the system app base class in esp-brookesia provides extra user-configurable features, exemplified by the Phone app base class `ESP_Brookesia_PhoneApp`:
+
+- **Icon Page Index**: Set the app icon's page index on the home screen by configuring the `app_launcher_page_index` field in `ESP_Brookesia_PhoneAppData_t` (usually divided into three pages).
+- **Status Icon Area Index**: Set the status icon's area index in the status bar by configuring the `status_icon_area_index` field in `ESP_Brookesia_PhoneAppData_t` (usually divided into `left-middle-right` or `left-right` areas).
+- **Status Icon**: Set the app's status icon by configuring the `status_icon` field in `ESP_Brookesia_PhoneAppData_t`.
+- **Status Bar Visual Mode**: Set the app's status bar visual mode by configuring the `status_bar_visual_mode` field in `ESP_Brookesia_PhoneAppData_t`, supporting `fixed` and `hidden` modes.
+- **Navigation Bar Visual Mode**: Set the app's navigation bar visual mode by configuring the `navigation_bar_visual_mode` field in `ESP_Brookesia_PhoneAppData_t`, supporting `fixed`, `hidden`, and `flexible` modes.
+- **Gesture Navigation**: Enable or disable gesture navigation for the app by configuring the `enable_navigation_gesture` field in `ESP_Brookesia_PhoneAppData_t`.
+
+### General Examples
+
+esp-brookesia provides general app examples for the following system UIs, allowing users to modify suitable examples based on actual needs for rapid custom app development:
 
 - [Phone](../src/app_examples/phone/)
-  - [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.
+  - [Simple Conf](../src/app_examples/phone/simple_conf/): This example uses a simple app configuration, with most parameters set to default values and only a few necessary parameters requiring user configuration. It is suitable for the "handwritten code"<sup>[Note 1]</sup> approach to GUI development.
+  - [Complex Conf](../src/app_examples/phone/complex_conf/): This example utilizes a complex app configuration where all parameters require user configuration. It is suitable for the "handwritten code"<sup>[Note 1]</sup> approach to GUI development.
+  - [Squareline](../src/app_examples/phone/squareline/): This example employs a simple app configuration, with most parameters set to default values and only a few necessary parameters requiring user configuration. It is suitable for the "Squareline exported code"<sup>[Note 2]</sup> approach to GUI development. This example also demonstrates how to modify Squareline exported code to automatically clean up animation resources upon app exit.
 
 > [!NOTE]
-> 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.
+> 1. "Handwritten code" refers to the approach where users manually write code to implement GUI development, 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 the method where users design GUIs using [Squareline Studio](https://squareline.io/), export the code, and then add the exported code to the app for GUI development.
 
-> [!WARNING]
-> * 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>_".
+### Considerations
 
-> [!WARNING]
-> * 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-brookesia instead. After deletion, modify the *ui.h* file by replacing `#include "ui_helpers.h"` with `#include "esp_brookesia.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-brookesia 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.
+If users adopt the "handwritten code" approach, they should enable **Automatic Default Screen Creation** (`enable_default_screen`) and consider the following:
+
+- **Function Name Conflicts**: To avoid variable and function name conflicts between multiple apps, it is recommended that global variables and functions within the app use the "<app_name>_" prefix for naming.
+
+If users adopt the "Squareline exported code" approach, they should disable **Automatic Default Screen Creation** (`enable_default_screen`) and use Squareline Studio version `v1.4.0` or higher, considering the following:
+
+- **Function Name Conflicts**: To prevent variable and function name conflicts between multiple apps, it is recommended that all screen names use the "<app_name>_" prefix and set "Project Settings" > "Properties" > "Object Naming" in Squareline Studio to "[Screen_Widget]_Name" (this feature requires version >= `v1.4.0`).
+- **Duplicate UI Helpers Files**: Since each Squareline exported code contains *ui_helpers.c* and *ui_helpers.h* files, users should delete these two files and use the internal *ui_helpers* file provided by esp-brookesia. After deletion, they need to modify `#include "ui_helpers.h"` in *ui.h* to `#include "esp_brookesia.h"`.
+- **Duplicate UI Components Files**: When a Squareline project uses `components` controls, the exported code will contain *ui_comp.c* and *ui_comp.h* files. To avoid function name conflicts, users should delete the *ui_comp.c* file and use the internal *ui_comp.c* file provided by esp-brookesia, and then delete the following content from *ui_comp.h*:
+
+  ```c
+  void get_component_child_event_cb(lv_event_t * e);
+  void del_component_child_event_cb(lv_event_t * e);
+
+  lv_obj_t * ui_comp_get_child(lv_obj_t * comp, uint32_t child_idx);
+  extern uint32_t LV_EVENT_GET_COMP_CHILD;
+  ```
+
+- **Animation Usage Not Recommended**: It is advised not to create and use animations in Squareline, as these animation resources cannot be directly accessed or cleaned up automatically or manually by users or esp-brookesia, which may lead to crashes or memory leaks when the app exits. If animations must be used, users need to modify the animation resource creation part of the exported code, as shown in the [Squareline example](../src/app_examples/phone/squareline/), which manually records animation resources using `startRecordResource()` and `stopRecordResource()` to ensure they can be cleaned up automatically when the app closes.
+- **Ensure Proper Compilation**: Furthermore, when using Squareline exported code, users may need to make additional modifications based on actual circumstances, such as renaming the `ui_init()` function to `<app_name>_ui_init()` to ensure the code compiles and runs correctly.