C-APP应用程序

在本章中，我们将探讨GUI框架内C-APP的创建与管理。C-APP实质上是用户可以开发以制作互动和视觉吸引力用户界面的应用程序。每个C-APP都可以打开、关闭、切换，并在切换时应用动态过渡效果。
C-APP中显示的内容是使用嵌套控件树结构组织的。该结构包括诸如窗口、可滚动页面和可切屏的容器控件，以及诸如文本、图像和画布之类的内容显示控件。
除了默认功能和效果外，C-APP内的控件提供了高度的自定义性。用户可以为控件设置自定义帧动画，并绑定事件以执行他们定义的操作。这种灵活性使得能够根据特定需求和要求创建高度动态和互动的用户界面。

定义一个 C-APP

使用特定名称通过 GUI_APP_DEFINE_NAME_ANIMATION API定义应用程序句柄。

#define APP_STOPWATCH
GUI_APP_DEFINE_NAME_ANIMATION(APP_STOPWATCH, GUI_APP_ANIMATION_1, GUI_APP_ANIMATION_5)

还有其他方式可以定义应用程序，例如：
- GUI_APP_DEFINE
- GUI_APP_DEFINE_NAME
- GUI_APP_DEFINE_NAME_ANIMATION_FUNC_CUSTOM
- struct gui_app
使用 GUI_APP_ENTRY API定义应用程序的UI设计入口函数。
当应用程序启动时，UI设计入口函数将被执行一次。

GUI_APP_ENTRY(APP_STOPWATCH)
{
    extern void app_clock_ui_design(gui_obj_t *parent);
    app_clock_ui_design(GUI_APP_ROOT_SCREEN);
}

创建一个C-APP的控件树

这是一个时钟应用程序，作为本节的示例。
在下图中，您可以看到应用程序界面有秒表和倒计时器选项。
点击这些选项可以在它们之间切换。

下图显示了精简过的控件树结构：

SCREEN:APP_STOPWATCH: 秒表应用程序的主容器。
- WINDOW:LEFT_BUTTON: 包含左按钮的窗口。
  CANVAS_RECT:LEFT_BUTTON: 左按钮的背景画布。
  
  TEXTBOX:LEFT_BUTTON: 左按钮的文本标签。
- WINDOW:RIGHT_BUTTON: 包含右按钮的窗口。
  CANVAS_RECT:RIGHT_BUTTON: 右按钮的背景画布。
  
  TEXTBOX:RIGHT_BUTTON: 右按钮的文本标签。
- MULTI_LEVEL:0_0: 多级容器。
  MULTI_LEVEL:1_0: 多级容器中的一个子容器，供秒表使用。
  
  MULTI_LEVEL:1_1: 多级容器中的另一个子容器，供倒计时器使用。

https://foruda.gitee.com/images/1727332782414751516/5754a436_10088396.png

C-APP操作

以下是上述操作如何具体应用于秒表应用程序：

GUI_APP_SHUTDOWN(APP_STOPWATCH) ：此命令将关闭秒表应用程序。如果应用程序正在运行计时器，它将停止计时器并关闭界面。关闭时任何相关资源将被释放。
GUI_APP_STARTUP(APP_STOPWATCH) ：此命令将初始化并启动秒表应用程序。用户界面将会显示，应用程序将准备好开始记录时间。
GUI_APP_SWAP(APP_STOPWATCH, APP_MAP) ：这将在当前运行的秒表应用程序和地图应用程序之间切换。

C-APP 转场动画

C-APP 提供了一个强大的功能集来管理应用程序之间的转场动画。它主要提供三个功能: 内置动画 、 自定义动画 和 图层管理 。这些功能旨在通过提供流畅且视觉上令人愉悦的过渡来增强用户体验。

内置动画

开发者可以使用 GUI_APP_DEFINE_NAME_ANIMATION API，轻松实现应用程序过渡的内置动画。此 API 允许您指定应用程序打开或关闭时发生的过渡动画。第二个参数用于定义应用程序启动时的动画，而第三个参数用于指定关闭应用程序的动画，如 GUI_APP_ANIMATION_1 。这个简单的 API 简化了在应用程序中集成过渡效果的过程。
自定义动画

对于更复杂或独特的动画需求，C-APP 支持通过 GUI_APP_DEFINE_NAME_ANIMATION_FUNC_CUSTOM API 来实现自定义动画。此功能允许开发者为应用打开和关闭过渡设置自定义动画回调函数。第二个参数是打开动画的回调函数，第三个参数是关闭动画的回调函数。这些回调函数通过 GUI_ANIMATION_CALLBACK_FUNCTION_DEFINE API 定义。这个 API 提供一个 gui_animate_t 实例作为参数，其中包含成员可以提供有关动画进度和状态的信息，从而允许进行精细的控制和定制。
图层管理

C-APP 还包括用于管理应用程序图层的 API，这对于视觉层次结构和用户体验来说至关重要。 gui_app_layer_top 和 gui_app_layer_bottom API 允许开发者定义当前活动应用程序与即将打开的应用程序之间的图层关系。此功能确保窗口的正确顺序，并有助于维护应用程序界面的预期焦点和组织。

示例

内置动画
- 定义一个 C-APP
  启动动画：从屏幕中心放大 (GUI_APP_ANIMATION_1)
  
  关闭动画：缩小到屏幕中心 (GUI_APP_ANIMATION_5)
- 切换到该 C-APP
  从应用程序 APP_WATCH 到 APP_STOPWATCH

#define APP_STOPWATCH
GUI_APP_DEFINE_NAME_ANIMATION(APP_STOPWATCH, GUI_APP_ANIMATION_1, GUI_APP_ANIMATION_5)

static void stopwatch_cb()
{
    gui_app_layer_top();
    GUI_APP_SWAP_HANDLE(get_app_watch_ui(), GUI_APP_HANDLE(APP_STOPWATCH))
}

自定义动画
- 定义一个 C-APP
  启动动画：从屏幕底部弹出 (heart_rate_startup)
  
  关闭动画：滑动消失 (heart_rate_shutdown)
- 切换到该 C-APP
  从应用程序 APP_WATCH 到 APP_HEART_RATE

static GUI_ANIMATION_CALLBACK_FUNCTION_DEFINE(heart_rate_startup);
static GUI_ANIMATION_CALLBACK_FUNCTION_DEFINE(heart_rate_shutdown);
GUI_APP_DEFINE_NAME_ANIMATION_FUNC_CUSTOM(APP_HEART_RATE, heart_rate_startup,
                                          heart_rate_shutdown) // cppcheck-suppress syntaxError

static void heart_rate_cb()
{
    gui_app_layer_top();
    GUI_APP_SWAP_HANDLE(get_app_watch_ui(),
                        GUI_APP_HANDLE(APP_HEART_RATE))// cppcheck-suppress unknownMacro
}

API

Defines

GUI_APP_DEFINE(APP_NAME, UI_DESIGN)
static void UI_DESIGN(gui_app_t*); \

static gui_app_t _app_##APP_NAME = \

{ \

.screen = \

{ \

.name = #APP_NAME, /**< Screen name set to application name. */ \

.type =
SCREEN
,    /**< Screen type initialized to SCREEN. */ \

}, \

.ui_design = UI_DESIGN,   /**< UI design function assigned. */ \

.active_ms = 1000000,     /**< Active duration set to 1,000,000 ms. */ \

}; \

gui_app_t *_get_app_##APP_NAME##_handle(void) \

{ \

return &_app_##APP_NAME; \

}


Macro to define a GUI application.

This macro creates a new GUI application by defining a static function pointer to the UI design function, initializing the GUI application structure, and providing a way to retrieve a handle to this application.

参数:

APP_NAME – The name of the application.
UI_DESIGN – The function to design the UI of the application.

GUI_APP_HANDLE(APP_NAME) _get_app_##APP_NAME##_handle()

Macro to get the handle of a GUI application by its name.

参数:

APP_NAME – The name of the application.

返回:

A pointer to the application instance.

GUI_APP_SHUTDOWN(APP_NAME) extern gui_app_t *_get_app_##APP_NAME##_handle(void); gui_app_shutdown(_get_app_##APP_NAME##_handle());

Macro to shut down a GUI application.

This macro shuts down the application by calling the external function gui_app_shutdown with the application’s handle.

参数:

APP_NAME – The name of the application.

GUI_APP_STARTUP(APP_NAME) extern gui_app_t *_get_app_##APP_NAME##_handle(void); gui_app_startup(_get_app_##APP_NAME##_handle());

Macro to start up a GUI application.

This macro starts up the application by calling the external function gui_app_startup with the application’s handle.

参数:

APP_NAME – The name of the application.

GUI_APP_SWAP(APP_NAME, APP_NAME_NEXT) gui_app_switch(_get_app_##APP_NAME##_handle(), _get_app_##APP_NAME##_handle_next());

Macro to swap between two GUI applications.

This macro allows switching from one application to another by calling gui_app_switch and passing the handles of the current and next application.

参数:

APP_NAME – The name of the current application.
APP_NAME_NEXT – The name of the next application.

GUI_APP_ROOT_SCREEN ((void *)(app->window))

Macro to get a pointer to the root screen of the current application.

返回:: A pointer to the root screen of the current application.

GUI_APP_SWAP_HANDLE(HANDLE_FUNC, HANDLE_NEXT_FUNC) extern gui_app_t *HANDLE_FUNC; \ extern gui_app_t *HANDLE_NEXT_FUNC; \ gui_app_switch(HANDLE_FUNC, HANDLE_NEXT_FUNC);

Macro to swap between two GUI applications using their handle functions.

This macro swaps between two applications using their external handle functions.

参数:

HANDLE_FUNC – The handle function of the current application.
HANDLE_NEXT_FUNC – The handle function of the next application.

GUI_APP_DEFINE_NAME(APP_NAME)
static void _##APP_NAME##_ui_design(gui_app_t*); \

static gui_app_t _app_##APP_NAME = \

{ \

.screen = \

{ \

.name = #APP_NAME, /**< The screen name is set to the application name. */ \

.magic =
GUI_MAGIC_NUMBER
, /**< check number. */ \

}, \

.ui_design = _##APP_NAME##_ui_design, /**< The UI design function is assigned with the modified name. */ \

.active_ms = 1000000, /**< The active duration is set to 1,000,000 milliseconds. */ \

}; \

gui_app_t *_get_app_##APP_NAME##_handle(void) \

{ \

return &_app_##APP_NAME; \

}


Macro to define a GUI application with a specific name.

This macro works similarly to GUI_APP_DEFINE but with a naming convention for the UI design function.

参数:

APP_NAME – The name of the application.

GUI_APP_DEFINE_NAME_ANIMATION(APP_NAME, STARTUP_ANIMATION, SHUTDOWM_ANIMATION)
static void _##APP_NAME##_ui_design(gui_app_t*); \

static gui_app_t _app_##APP_NAME = { \

.screen = { \

.name = #APP_NAME,          /**< The screen name is set to the application name. */ \

.magic =
GUI_MAGIC_NUMBER
,   /**< check number. */ \

}, \

.ui_design = _##APP_NAME##_ui_design, /**< The UI design function is assigned with the modified name. */ \

.active_ms = 1000000,            /**< The active duration is set to 1,000,000 milliseconds. */ \

.startup_animation_flag = STARTUP_ANIMATION, \

.shutdown_animation_flag = SHUTDOWM_ANIMATION, \

}; \

gui_app_t *_get_app_##APP_NAME##_handle(void) \

{ \

return &_app_##APP_NAME; \

}


Defines a GUI application with a startup and shutdown animation.

This macro creates a definition for a GUI application:

APP_NAME: The name of the application.
STARTUP_ANIMATION: The animation used when the application starts.
SHUTDOWN_ANIMATION: The animation used when the application shuts down.

参数:

APP_NAME – Name of the application.
STARTUP_ANIMATION – The animation type used for startup (of type gui_app_animation_t).
SHUTDOWN_ANIMATION – The animation type used for shutdown (of type gui_app_animation_t).

GUI_APP_DEFINE_NAME_ANIMATION_FUNC_CUSTOM(APP_NAME, STARTUP_ANIMATION_FUNC, SHUTDOWM_ANIMATION_FUNC)
static void _##APP_NAME##_ui_design(gui_app_t*); \

static gui_app_t _app_##APP_NAME = \

{ \

.screen = \

{ \

.name = #APP_NAME, /**< The screen name is set to the application name. */ \

.magic =
GUI_MAGIC_NUMBER
, /**< check number. */ \

}, \

.ui_design = _##APP_NAME##_ui_design, /**< The UI design function is assigned with the modified name. */ \

.active_ms = 1000000, /**< The active duration is set to 1,000,000 milliseconds. */ \

.startup_animation = STARTUP_ANIMATION_FUNC, \

.shutdown_animation = SHUTDOWM_ANIMATION_FUNC, \

}; \

gui_app_t *_get_app_##APP_NAME##_handle(void) \

{ \

return &_app_##APP_NAME; \

}


GUI_APP_ENTRY(APP_NAME) static void _##APP_NAME##_ui_design(gui_app_t* app)

Macro to declare the entry point of a GUI application’s UI design function.

This macro declares the UI design function for the application.

参数:

APP_NAME – The name of the application.

GUI_APP_ANIMATION_NULL (gui_app_animation_t)0

GUI_APP_ANIMATION_1 (gui_app_animation_t)1: Recommended for startup.

GUI_APP_ANIMATION_2 (gui_app_animation_t)2: Recommended for startup.

GUI_APP_ANIMATION_3 (gui_app_animation_t)3: Recommended for startup.

GUI_APP_ANIMATION_4 (gui_app_animation_t)4: Recommended for startup.

GUI_APP_ANIMATION_5 (gui_app_animation_t)5: Recommended for shutdown.

GUI_APP_ANIMATION_6 (gui_app_animation_t)6: Recommended for shutdown.

GUI_APP_ANIMATION_7 (gui_app_animation_t)7: Recommended for shutdown.

GUI_APP_ANIMATION_8 (gui_app_animation_t)8: Recommended for shutdown.

GUI_APP_ANIMATION_9 (gui_app_animation_t)9: Recommended for startup.

GUI_APP_ANIMATION_10 (gui_app_animation_t)10: Recommended for shutdown.

Typedefs

typedef unsigned char gui_app_animation_t

Functions

gui_app_t *gui_current_app(void): Get current app pointer.

gui_app_t *gui_next_app(void): Get nect app pointer if there are two apps exist.

void gui_app_install(gui_app_t *app, void *ui_design, void *gui_app_entry)

void gui_app_startup(gui_app_t *app)

void gui_app_shutdown(gui_app_t *app)

gui_app_t *gui_app_create(const char *app_name, void *ui_design, void *gui_app_entry)

void gui_app_switch(gui_app_t *from, gui_app_t *to)

Switch app from A to B.

参数:

from – A pointer
to – B pointer

void gui_app_layer_top(void): Set next app top layer, call this function before the context of the next app startup.

void gui_app_layer_buttom(void): Set next app button layer, call this function before the context of the next app startup.

bool gui_app_get_layer(void)

Get next app layer.

返回:: true top layer
返回:: false button layer

void gui_set_app_active_time(gui_app_t *app, uint32_t active_ms)

Set app active ms time.

参数:

app – app set
active_ms – active ms times

gui_app_t *gui_obj_tree_get_app(gui_obj_t *obj)

Retrieves the application object associated with the specified GUI object.

This function traverses the object tree starting from the given GUI object until it finds the root object, and then returns the application object associated with that root.

参数:: obj – A pointer to a GUI object.
返回:: A pointer to the application object if found. If the input object is NULL or if no application object is found, the function returns NULL.

void gui_app_append(gui_app_t *app)

gui_app_t *gui_app_get_by_name(const char *name)

struct gui_app

APP structure.

Public Members

gui_obj_t screen: widget tree root

const char *xml: widget tree design file

gui_win_t *window: app transition window

uint32_t active_ms: screen shut down delay

uint32_t start_ms: screen shut down delay

void *thread_id: thread handle(optional)

void (*thread_entry)(void *_this): thread entry

void (*server_hook)(void *_this): thread entry

void (*ctor)(void *_this): constructor

void (*dtor)(void *_this): destructor

void (*ui_design)(gui_app_t*): ui create entry

gui_animate_callback_t startup_animation

gui_animate_callback_t shutdown_animation

bool lvgl

bool arm2d

bool close

bool next

bool close_sync

unsigned char startup_animation_flag

unsigned char shutdown_animation_flag