diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2bc86ef..7c5cae5 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 217e145..616d00e 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/docs/how_to_use.md b/docs/how_to_use.md index 8724c17..a20abe7 100644 --- a/docs/how_to_use.md +++ b/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"[Note 1] 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"[Note 1] 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"[Note 2] 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"[Note 1] 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"[Note 1] 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"[Note 2] 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 "_". +### 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 "_" 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 `_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 "_" 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 "_" 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 `_ui_init()` to ensure the code compiles and runs correctly. diff --git a/docs/how_to_use_CN.md b/docs/how_to_use_CN.md index 30e3279..924b52a 100644 --- a/docs/how_to_use_CN.md +++ b/docs/how_to_use_CN.md @@ -15,7 +15,10 @@ - [安装库](#安装库) - [配置说明](#配置说明-1) - [工程示例](#工程示例-1) - - [App 示例](#app-示例) + - [App 开发](#app-开发) + - [原理及功能](#原理及功能) + - [通用示例](#通用示例) + - [注意事项](#注意事项) ## 依赖 @@ -99,7 +102,31 @@ idf.py add-dependency "espressif/esp-brookesia" - [ESP_Brookesia_Phone](../examples/arduino/ESP_Brookesia_Phone): 此示例演示了如何使用 [ESP32_Display_Panel](https://github.com/esp-arduino-libs/ESP32_Display_Panel) 库运行 Phone UI。 -## App 示例 +## App 开发 + +### 原理及功能 + +esp-brookesia 提供了通过 C++ 继承的方式来开发 app 的功能,用户可以根据目标系统 UI 继承相应的系统 app 基类(如 Phone 中的 [ESP_Brookesia_PhoneApp](../src/systems/phone/esp_brookesia_phone_app.hpp) 类),然后实现必要的纯虚函数(`run()` 和 `back()`),还可以根据需求重定义其他虚函数(如 `close()`、`init()` 和 `pause()` 等),这些虚函数源自内核 app 基类 [ESP_Brookesia_CoreApp](../src/core/esp_brookesia_core_app.hpp)。 + +esp-brookesia 的系统 app 基类是继承自内核 app 基类 `ESP_Brookesia_CoreApp`,它提供了以下用户可静态配置的功能: + +- **名称**:通过设置 `ESP_Brookesia_CoreAppData_t` 中 `name` 字段来设置 app 的名称。 +- **图标**:通过设置 `ESP_Brookesia_CoreAppData_t` 中 `launcher_icon` 字段来设置 app 的图标。 +- **屏幕大小**:通过设置 `ESP_Brookesia_CoreAppData_t` 中 `screen_size` 字段来设置 app 的屏幕大小。由于当 app 屏幕大小小于实际屏幕大小时,空闲屏幕区域的显示会出现异常,因此建议用户设置的屏幕大小等于实际屏幕大小,即 `screen_size = ESP_BROOKESIA_STYLE_SIZE_RECT_PERCENT(100, 100)`。 +- **自动创建默认屏幕**:通过设置 `ESP_Brookesia_CoreAppData_t` 中 `enable_default_screen = 1` 开启,开启后系统会在 app 执行 `run()` 时自动创建并加载一个默认屏幕,用户可以通过 `lv_scr_act()` 获取当前屏幕对象。如果用户需要自行创建和加载屏幕对象,请关闭此功能。 +- 自动清理资源的功能:通过设置 `ESP_Brookesia_CoreAppData_t` 中 `enable_recycle_resource = 1` 开启,开启后系统会在 app 退出时会自动清理包括 **屏幕**(`lv_obj_create(NULL)`)、 **动画**(`lv_anim_start()`) 和 **定时器**(`lv_timer_create()`)在内的资源,此功能要求用户在 `run()/resume()` 函数内或者 `startRecordResource()` 与 `stopRecordResource()` 之间完成所有资源的创建。 +- **自动调整屏幕大小的功能**:通过设置 `ESP_Brookesia_CoreAppData_t` 中 `enable_resize_visual_area = 1` 开启,开启后系统会在 app 创建屏幕时自动调整屏幕的大小为可视区域的大小,此功能要求用户在 `run()/resume()` 函数内或者 `startRecordResource()` 与 `stopRecordResource()` 函数之间完成所有屏幕的创建(`lv_obj_create(NULL)`, `lv_timer_create()`, `lv_anim_start()`)。当屏幕显示悬浮 UI(如状态栏)时,如果未开启此功能,app 的屏幕将默认以全屏大小显示,但某些区域可能被遮挡。app 可以调用 `getVisualArea()` 函数来获取最终的可视区域。 + +除此之外,esp-brookesia 的系统 app 基类也提供了一些额外的用户可静态配置的功能,以 Phone 的 app 基类 `ESP_Brookesia_PhoneApp` 为例: + +- **图标页索引**:通过设置 `ESP_Brookesia_PhoneAppData_t` 中 `app_launcher_page_index` 字段来设置 app 图标显示在主页的第几页(通常分为 3 页)。 +- **状态图标区域索引**:通过设置 `ESP_Brookesia_PhoneAppData_t` 中 `status_icon_area_index` 字段来设置 app 状态图标显示在状态栏的第几个区域(通常分为 `左-中-右` 三个区域或 `左-右` 两个区域)。 +- **状态图标**:通过设置 `ESP_Brookesia_PhoneAppData_t` 中 `status_icon` 字段来设置 app 的状态图标。 +- **状态栏显示模式**:通过设置 `ESP_Brookesia_PhoneAppData_t` 中 `status_bar_visual_mode` 字段来设置 app 的状态栏显示模式,支持 `固定` 和 `隐藏` 两种模式。 +- **导航栏显示模式**:通过设置 `ESP_Brookesia_PhoneAppData_t` 中 `navigation_bar_visual_mode` 字段来设置 app 的导航栏显示模式,支持 `固定`、`隐藏` 和 `动态` 三种模式。 +- **手势导航**:通过设置 `ESP_Brookesia_PhoneAppData_t` 中 enable_navigation_gesture` 字段来设置 app 是否支持通过手势进行导航。 + +### 通用示例 esp-brookesia 针对以下系统 UI 提供了通用的 app 示例,用户可以根据实际需求基于适合的示例进行修改,快速实现自定义 app 的开发。 @@ -111,17 +138,26 @@ esp-brookesia 针对以下系统 UI 提供了通用的 app 示例,用户可以 > [!NOTE] > 1. "手写代码" 是指用户需要手动编写代码来实现 GUI 的开发,通常使用 `lv_scr_act()` 获取当前屏幕对象,并将所有的 GUI 元素添加到该屏幕对象上。 > 2. "Squareline 导出代码" 是指用户使用 [Squareline Studio](https://squareline.io/) 设计 GUI,并导出代码,然后将导出的代码添加到 app 中,即可实现 GUI 的开发。 -> 3. app 提供了自动创建默认屏幕的功能(`enable_default_screen`),开启后系统会在 app 执行 `run()` 时自动创建并加载一个默认屏幕,用户可以通过 `lv_scr_act()` 获取当前屏幕对象。如果用户需要自行创建和加载屏幕对象,请关闭此功能。 -> 4. app 提供了自动清理资源的功能(`enable_recycle_resource`),开启后系统会在 app 退出时会自动清理包括 **屏幕**(`lv_obj_create(NULL)`)、 **动画**(`lv_anim_start()`) 和 **定时器**(`lv_timer_create()`)在内的资源,此功能要求用户在 `run()/resume()` 函数内或者 `startRecordResource()` 与 `stopRecordResource()` 之间完成所有资源的创建。 -> 5. app 提供了自动调整屏幕大小的功能(`enable_resize_visual_area`),开启后系统会在 app 创建屏幕时自动调整屏幕的大小为可视区域的大小,此功能要求用户在 `run()/resume()` 函数内或者 `startRecordResource()` 与 `stopRecordResource()` 函数之间完成所有屏幕的创建(`lv_obj_create(NULL)`, `lv_timer_create()`, `lv_anim_start()`)。当屏幕显示悬浮 UI(如状态栏)时,如果未开启此功能,app 的屏幕将默认以全屏显示,但某些区域可能被遮挡。app 可以调用 `getVisualArea()` 函数来获取最终的可视区域。 -> [!WARNING] -> * 如果用户在 app 中采用 "手写代码" 的方式,请开启 `enable_default_screen` 功能。 -> * 为了避免多个 app 之间出现变量和函数重名的问题,推荐 app 内的全局变量和函数采用 "_" 前缀的命名方式。 +### 注意事项 -> [!WARNING] -> * 如果用户在 app 中采用 "Squareline 导出代码" 的方式,推荐 Squareline Stduio 的版本为 `v1.4.0` 及以上,并关闭 `enable_default_screen` 功能。 -> * 为了避免多个 app 之间出现变量和函数重名的问题,推荐所有屏幕的名称采用 "_" 前缀的命名方式,并设置 Squareline Studio 中的 "Project Settings" > "Properties" > "Object Naming" 为 "[Screen_Widget]_Name"(此功能要求版本 >= `v1.4.0`)。 -> * 由于每个 Squareline 导出的代码中都会有 *ui_helpers.c* 和 *ui_helpers.h* 文件,为了避免多个 app 之间出现函数重名的问题,请删除这两个文件,并统一使用 esp-brookesia 内部提供的 *ui_helpers* 文件,删除后需要修改 *ui.h* 文件中的 `#include "ui_helpers.h"` 为 `#include "esp_brookesia.h"`。 -> * 建议用户不要在 Squareline 创建和使用动画,因为这些动画资源无法被用户或者 esp-brookesia 直接获取,从而无法被自动或者手动清理,可能会在 app 退出时导致程序崩溃或内存泄漏问题。如果一定要使用,需要对导出代码中动画资源的创建部分进行修改,具体请参考 [Squareline 示例](../src/app_examples/phone/squareline/) 中的实现,该示例通过在 `lv_anim_start()` 前后添加 `startRecordResource()` 和 `stopRecordResource()` 函数来手动记录动画资源,使其能够在 app 关闭时被自动清理。 -> * 除此之外,使用 Squareline 导出的代码时,用户仍需根据实际情况进行一些额外的修改,如修改 `ui_init()` 函数名为 `_ui_init()`,以确保代码能够被正常编译与运行。 +如果用户采用 "手写代码" 的方式,请开启 **自动创建默认屏幕**(`enable_default_screen`)的功能,并注意以下事项: + +- **函数重名**:为了避免多个 app 之间出现变量和函数重名的问题,推荐 app 内的全局变量和函数采用 "_" 前缀的命名方式。 + +如果用户采用 "Squareline 导出代码" 的方式,请关闭 **自动创建默认屏幕**(`enable_default_screen`)的功能,推荐 Squareline Stduio 的版本为 `v1.4.0` 及以上,并参考以下事项: + +- **函数重名**:为了避免多个 app 之间出现变量和函数重名的问题,推荐所有屏幕的名称采用 "_" 前缀的命名方式,并设置 Squareline Studio 中的 "Project Settings" > "Properties" > "Object Naming" 为 "[Screen_Widget]_Name"(此功能要求版本 >= `v1.4.0`)。 +- **重复的 UI helpers 文件**:由于每个 Squareline 导出的代码中都会有 *ui_helpers.c* 和 *ui_helpers.h* 文件,为了避免多个 app 之间出现函数重名的问题,请删除这两个文件,并统一使用 esp-brookesia 内部提供的 *ui_helpers* 文件,删除后需要修改 *ui.h* 文件中的 `#include "ui_helpers.h"` 为 `#include "esp_brookesia.h"`。 +- **重复的 UI components 文件**:当 Squareline 工程使用了 `componnets` 控件,此时导出的代码中都会有 *ui_comp.c* 和 *ui_comp.h* 文件,为了避免多个 app 之间出现函数重名的问题,请删除 *ui_comp.c* 文件,并统一使用 esp-brookesia 内部提供的 *ui_comp.c* 文件,然后需要删除 *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; + ``` + +- **不推荐使用动画**:建议用户不要在 Squareline 创建和使用动画,因为这些动画资源无法被用户或者 esp-brookesia 直接获取,从而无法被自动或者手动清理,可能会在 app 退出时导致程序崩溃或内存泄漏问题。如果一定要使用,需要对导出代码中动画资源的创建部分进行修改,具体请参考 [Squareline 示例](../src/app_examples/phone/squareline/) 中的实现,该示例通过在 `lv_anim_start()` 前后添加 `startRecordResource()` 和 `stopRecordResource()` 函数来手动记录动画资源,使其能够在 app 关闭时被自动清理。 +- **确保正常编译**:除此之外,使用 Squareline 导出的代码时,用户仍需根据实际情况进行一些额外的修改,如修改 `ui_init()` 函数名为 `_ui_init()`,以确保代码能够被正常编译与运行。 diff --git a/docs/system_ui_phone.md b/docs/system_ui_phone.md index 1eb44be..ef9cde8 100644 --- a/docs/system_ui_phone.md +++ b/docs/system_ui_phone.md @@ -36,9 +36,12 @@ It has the following features: To achieve the best display performance at fixed resolutions, esp-brookesia also provides UI stylesheets for the following resolutions: - [320 x 240](../src/systems/phone/stylesheets/320_240/) +- [320 x 480](../src/systems/phone/stylesheets/320_480/) - [480 x 480](../src/systems/phone/stylesheets/480_480/) - [800 x 480](../src/systems/phone/stylesheets/800_480/) +- [800 x 1280](../src/systems/phone/stylesheets/800_1280/) - [1024 x 600](../src/systems/phone/stylesheets/1024_600/) +- [1280 x 800](../src/systems/phone/stylesheets/1280_800/) > [!NOTE] > If your screen resolution is not listed in the above UI stylesheets, please refer to the GitHub issue - [Phone Resolution Support](https://github.com/espressif/esp-brookesia/issues/5). diff --git a/docs/system_ui_phone_CN.md b/docs/system_ui_phone_CN.md index c10dcc9..12f095f 100644 --- a/docs/system_ui_phone_CN.md +++ b/docs/system_ui_phone_CN.md @@ -36,9 +36,12 @@ 为了使 Phone 在固定分辨率下达到最佳显示效果,esp-brookesia 目前提供了以下分辨率的 UI 样式表: - [320 x 240](../src/systems/phone/stylesheets/320_240/) +- [320 x 480](../src/systems/phone/stylesheets/320_480/) - [480 x 480](../src/systems/phone/stylesheets/480_480/) - [800 x 480](../src/systems/phone/stylesheets/800_480/) +- [800 x 1280](../src/systems/phone/stylesheets/800_1280/) - [1024 x 600](../src/systems/phone/stylesheets/1024_600/) +- [1280 x 800](../src/systems/phone/stylesheets/1280_800/) > [!NOTE] > 如果上述 UI 样式表中没有您的屏幕分辨率,请参阅 Github issue - [Phone Resolution Support](https://github.com/espressif/esp-brookesia/issues/5)。 diff --git a/esp_brookesia_conf.h b/esp_brookesia_conf.h index 074b3a0..a3c19de 100644 --- a/esp_brookesia_conf.h +++ b/esp_brookesia_conf.h @@ -126,5 +126,5 @@ * */ #define ESP_BROOKESIA_CONF_FILE_VER_MAJOR 0 -#define ESP_BROOKESIA_CONF_FILE_VER_MINOR 1 +#define ESP_BROOKESIA_CONF_FILE_VER_MINOR 2 #define ESP_BROOKESIA_CONF_FILE_VER_PATCH 0 diff --git a/idf_component.yml b/idf_component.yml index 71a09b7..de77f16 100644 --- a/idf_component.yml +++ b/idf_component.yml @@ -1,4 +1,4 @@ -version: 0.3.1 +version: 0.4.0 description: ESP-Brookesia is a human-machine interaction development framework designed for AIoT devices. url: https://github.com/espressif/esp-brookesia issues: https://github.com/espressif/esp-brookesia/issues diff --git a/library.properties b/library.properties index 8ed606b..c2e4482 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=esp-brookesia -version=0.3.1 +version=0.4.0 author=espressif maintainer=espressif sentence=ESP-Brookesia is a human-machine interaction development framework designed for AIoT devices. diff --git a/src/core/esp_brookesia_core_event.cpp b/src/core/esp_brookesia_core_event.cpp index c0580bf..84cf37a 100644 --- a/src/core/esp_brookesia_core_event.cpp +++ b/src/core/esp_brookesia_core_event.cpp @@ -43,7 +43,7 @@ void ESP_Brookesia_CoreEvent::reset(void) bool ESP_Brookesia_CoreEvent::registerEvent(void *object, Handler handler, ID id, void *user_data) { ESP_BROOKESIA_LOGD("Register event for object(0x%p) ID(%d) handler(0x%p), user_data(0x%p)", object, static_cast(id), - handler, user_data); + handler, user_data); ESP_BROOKESIA_CHECK_NULL_RETURN(handler, false, "Invalid handler"); auto &handlers_for_object = _event_handlers[object]; diff --git a/src/esp_brookesia_versions.h b/src/esp_brookesia_versions.h index e3c6c0d..4bd07e1 100644 --- a/src/esp_brookesia_versions.h +++ b/src/esp_brookesia_versions.h @@ -10,13 +10,13 @@ /* Library Version */ #if !defined(ESP_BROOKESIA_VER_MAJOR) && !defined(ESP_BROOKESIA_VER_MINOR) && !defined(ESP_BROOKESIA_VER_PATCH) #define ESP_BROOKESIA_VER_MAJOR 0 -#define ESP_BROOKESIA_VER_MINOR 3 -#define ESP_BROOKESIA_VER_PATCH 1 +#define ESP_BROOKESIA_VER_MINOR 4 +#define ESP_BROOKESIA_VER_PATCH 0 #endif /* File `esp_brookesia_conf.h` */ #define ESP_BROOKESIA_CONF_VER_MAJOR 0 -#define ESP_BROOKESIA_CONF_VER_MINOR 1 +#define ESP_BROOKESIA_CONF_VER_MINOR 2 #define ESP_BROOKESIA_CONF_VER_PATCH 0 #ifndef ESP_BROOKESIA_CONF_SKIP diff --git a/src/systems/phone/esp_brookesia_phone_home.cpp b/src/systems/phone/esp_brookesia_phone_home.cpp index 6b97695..8dcbafa 100644 --- a/src/systems/phone/esp_brookesia_phone_home.cpp +++ b/src/systems/phone/esp_brookesia_phone_home.cpp @@ -302,7 +302,7 @@ bool ESP_Brookesia_PhoneHome::getAppVisualArea(ESP_Brookesia_CoreApp *app, lv_ar // Process status bar if ((_status_bar != nullptr) && (app_data.status_bar_visual_mode == ESP_BROOKESIA_STATUS_BAR_VISUAL_MODE_SHOW_FIXED) && - (_data.status_bar.data.main.background_color.opacity == LV_OPA_COVER)) { + (_data.status_bar.data.main.background_color.opacity == LV_OPA_COVER)) { visual_area.y1 = _data.status_bar.data.main.size.height; } diff --git a/src/systems/phone/stylesheets/stylesheets.h b/src/systems/phone/stylesheets/stylesheets.h index b882000..58fd18c 100644 --- a/src/systems/phone/stylesheets/stylesheets.h +++ b/src/systems/phone/stylesheets/stylesheets.h @@ -1,3 +1,8 @@ +/* + * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ #pragma once #include "default/dark/stylesheet.h" diff --git a/src/widgets/gesture/esp_brookesia_gesture.cpp b/src/widgets/gesture/esp_brookesia_gesture.cpp index 6b0374c..b5fd934 100644 --- a/src/widgets/gesture/esp_brookesia_gesture.cpp +++ b/src/widgets/gesture/esp_brookesia_gesture.cpp @@ -250,13 +250,13 @@ bool ESP_Brookesia_Gesture::calibrateData(const ESP_Brookesia_StyleSize_t &scree parent_size = &data.indicator_bars[i].main.size_min; parent_w = parent_size->width; ESP_BROOKESIA_CHECK_VALUE_RETURN(data.indicator_bars[i].main.layout_pad_all, 0, parent_w / 2, false, - "Invalid indicator bar main layout pad all"); + "Invalid indicator bar main layout pad all"); break; case ESP_BROOKESIA_GESTURE_INDICATOR_BAR_TYPE_BOTTOM: parent_size = &data.indicator_bars[i].main.size_min; parent_h = parent_size->height; ESP_BROOKESIA_CHECK_VALUE_RETURN(data.indicator_bars[i].main.layout_pad_all, 0, parent_h / 2, false, - "Invalid indicator bar main layout pad all"); + "Invalid indicator bar main layout pad all"); break; default: break; diff --git a/test_apps/main/test_app_main.cpp b/test_apps/main/test_app_main.cpp index 137d9e9..e634159 100644 --- a/test_apps/main/test_app_main.cpp +++ b/test_apps/main/test_app_main.cpp @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -32,24 +32,26 @@ void tearDown(void) extern "C" void app_main(void) { /** - * ________ ______ _______ __ __ ______ - * | \ / \ | \ | \ | \| \ - * | $$$$$$$$| $$$$$$\| $$$$$$$\ | $$ | $$ \$$$$$$ - * | $$__ | $$___\$$| $$__/ $$ ______ | $$ | $$ | $$ - * | $$ \ \$$ \ | $$ $$| \| $$ | $$ | $$ - * | $$$$$ _\$$$$$$\| $$$$$$$ \$$$$$$| $$ | $$ | $$ - * | $$_____ | \__| $$| $$ | $$__/ $$ _| $$_ - * | $$ \ \$$ $$| $$ \$$ $$| $$ \ - * \$$$$$$$$ \$$$$$$ \$$ \$$$$$$ \$$$$$$ - */ - printf(" ________ ______ _______ __ __ ______\r\n"); - printf("| \\ / \\ | \\ | \\ | \\| \\\r\n"); - printf("| $$$$$$$$| $$$$$$\\| $$$$$$$\\ | $$ | $$ \\$$$$$$\r\n"); - printf("| $$__ | $$___\\$$| $$__/ $$ ______ | $$ | $$ | $$\r\n"); - printf("| $$ \\ \\$$ \\ | $$ $$| \\| $$ | $$ | $$\r\n"); - printf("| $$$$$ _\\$$$$$$\\| $$$$$$$ \\$$$$$$| $$ | $$ | $$\r\n"); - printf("| $$_____ | \\__| $$| $$ | $$__/ $$ _| $$_\r\n"); - printf("| $$ \\ \\$$ $$| $$ \\$$ $$| $$ \\\r\n"); - printf(" \\$$$$$$$$ \\$$$$$$ \\$$ \\$$$$$$ \\$$$$$$\r\n"); + * + * ________ ______ _______ _______ __ __ + * | \ / \ | \ | \ | \ | \ + * | $$$$$$$$| $$$$$$\| $$$$$$$\ | $$$$$$$\ ______ ______ ______ | $$ __ ______ _______ \$$ ______ + * | $$__ | $$___\$$| $$__/ $$ ______ | $$__/ $$ / \ / \ / \ | $$ / \ / \ / \| \ | \ + * | $$ \ \$$ \ | $$ $$| \| $$ $$| $$$$$$\| $$$$$$\| $$$$$$\| $$_/ $$| $$$$$$\| $$$$$$$| $$ \$$$$$$\ + * | $$$$$ _\$$$$$$\| $$$$$$$ \$$$$$$| $$$$$$$\| $$ \$$| $$ | $$| $$ | $$| $$ $$ | $$ $$ \$$ \ | $$ / $$ + * | $$_____ | \__| $$| $$ | $$__/ $$| $$ | $$__/ $$| $$__/ $$| $$$$$$\ | $$$$$$$$ _\$$$$$$\| $$| $$$$$$$ + * | $$ \ \$$ $$| $$ | $$ $$| $$ \$$ $$ \$$ $$| $$ \$$\ \$$ \| $$| $$ \$$ $$ + * \$$$$$$$$ \$$$$$$ \$$ \$$$$$$$ \$$ \$$$$$$ \$$$$$$ \$$ \$$ \$$$$$$$ \$$$$$$$ \$$ \$$$$$$$ + * + */ + printf(" ________ ______ _______ _______ __ __\r\n"); + printf("| \\ / \\ | \\ | \\ | \\ | \\\r\n"); + printf("| $$$$$$$$| $$$$$$\\| $$$$$$$\\ | $$$$$$$\\ ______ ______ ______ | $$ __ ______ _______ \\$$ ______\r\n"); + printf("| $$__ | $$___\\$$| $$__/ $$ ______ | $$__/ $$ / \\ / \\ / \\ | $$ / \\ / \\ / \\| \\ | \\\r\n"); + printf("| $$ \\ \\$$ \\ | $$ $$| \\| $$ $$| $$$$$$\\| $$$$$$\\| $$$$$$\\| $$_/ $$| $$$$$$\\| $$$$$$$| $$ \\$$$$$$\\\r\n"); + printf("| $$$$$ _\\$$$$$$\\| $$$$$$$ \\$$$$$$| $$$$$$$\\| $$ \\$$| $$ | $$| $$ | $$| $$ $$ | $$ $$ \\$$ \\ | $$ / $$\r\n"); + printf("| $$_____ | \\__| $$| $$ | $$__/ $$| $$ | $$__/ $$| $$__/ $$| $$$$$$\\ | $$$$$$$$ _\\$$$$$$\\| $$| $$$$$$$\r\n"); + printf("| $$ \\ \\$$ $$| $$ | $$ $$| $$ \\$$ $$ \\$$ $$| $$ \\$$\\ \\$$ \\| $$| $$ \\$$ $$\r\n"); + printf(" \\$$$$$$$$ \\$$$$$$ \\$$ \\$$$$$$$ \\$$ \\$$$$$$ \\$$$$$$ \\$$ \\$$ \\$$$$$$$ \\$$$$$$$ \\$$ \\$$$$$$$\r\n"); unity_run_menu(); }