C-APP Application

In this chapter, we will explore the creation and management of C-APPs within GUI framework. A C-APP is essentially an application that users can develop to craft interactive and visually appealing user interfaces. Each C-APP can be opened, closed, switched between, and can incorporate dynamic transition effects during switching.
The displayed content within a C-APP is organized using a nested widget tree structure. This structure includes container widgets such as windows, scrollable pages, and switchable tabs, as well as content display widgets like text, images, and canvases.
In addition to the default functions and effects, widgets within C-APPs offer a high degree of customization. Users can set up custom frame animations for widgets and bind events to execute their defined operations. This flexibility enables the creation of highly dynamic and interactive user interfaces tailored to specific needs and requirements.

Define A C-APP

Define app handle using a specific name with GUI_APP_DEFINE_NAME_ANIMATION API:

#define APP_STOPWATCH
GUI_APP_DEFINE_NAME_ANIMATION(APP_STOPWATCH, GUI_APP_ANIMATION_1, GUI_APP_ANIMATION_5)

There are also other ways available to define the app:
- GUI_APP_DEFINE
- GUI_APP_DEFINE_NAME
- GUI_APP_DEFINE_NAME_ANIMATION_FUNC_CUSTOM
- struct gui_app
Define app UI design entry function with GUI_APP_ENTRY API.
The UI design entry function will be executed once when the app startup.

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

Create The Widget Tree of A C-APP

This is a clock app, serving as an example for this section.
In the image below, you can see that the app interface has options for a stopwatch and a countdown timer.
Clicking on these options allows you to switch between them.

The graph below shows the widget tree structure simplified:

SCREEN:APP_STOPWATCH: The main container for the stopwatch app.
- WINDOW:LEFT_BUTTON: The window containing the left button.
  CANVAS_RECT:LEFT_BUTTON: The background canvas of the left button.
  
  TEXTBOX:LEFT_BUTTON: The text label for the left button.
- WINDOW:RIGHT_BUTTON: The window containing the right button.
  CANVAS_RECT:RIGHT_BUTTON: The background canvas of the right button.
  
  TEXTBOX:RIGHT_BUTTON: The text label for the right button.
- MULTI_LEVEL:0_0: A multi-level container.
  MULTI_LEVEL:1_0: A sub-container within the multi-level container, for the stopwatch.
  
  MULTI_LEVEL:1_1: Another sub-container within the multi-level container, for the countdown timer.

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

C-APP Operations

Here is how the earlier mentioned operations could be applied specifically to the Stopwatch app:

GUI_APP_SHUTDOWN(APP_STOPWATCH) : This command will close the Stopwatch application. If the app is running a timer, it will stop the timer and close the interface. Any associated resources will be freed upon shutdown.
GUI_APP_STARTUP(APP_STOPWATCH) : This command will initialize and start the Stopwatch application. The user interface will be displayed, and the app will be ready to start recording time.
GUI_APP_SWAP(APP_STOPWATCH, APP_MAP) : This will switch from the currently running Stopwatch app to the Map app.

C-APP Transition Animation

C-APP provides a robust feature set for managing transition animations between applications. It offers three main functionalities: built-in animations, custom animations, and layer management. These features are designed to enhance the user experience by providing smooth and visually appealing transitions.

Built-in Animations

C-APP allows developers to easily implement built-in animations for app transitions using the GUI_APP_DEFINE_NAME_ANIMATION API. This API lets you specify the transition animations that occur when an app is opened or closed. The second parameter is used to define the animation for opening an app, while the third parameter specifies the animation for closing an app, such as GUI_APP_ANIMATION_1. This straightforward API streamlines the process of integrating transition effects within your applications.
Custom Animations

For more complex or unique animation requirements, C-APP supports custom animations through the GUI_APP_DEFINE_NAME_ANIMATION_FUNC_CUSTOM API. This feature enables developers to set custom animation callback functions for both opening and closing transitions. The second parameter is the callback function for the opening animation, and the third parameter is for the closing animation. These callback functions are defined using the GUI_ANIMATION_CALLBACK_FUNCTION_DEFINE API. This API provides an animation structure gui_animate_t instance as an argument, which includes members that offer insights into the progress and status of the animation, allowing for fine-tuned control and customization.
Layer Management

C-APP also includes APIs for managing the layering of applications, which can be crucial for visual hierarchy and user experience. The gui_app_layer_top and gui_app_layer_bottom APIs allow developers to define the layer relationship between the currently active app and the app that is about to open. This functionality ensures the correct ordering of windows and can help in maintaining the intended focus and organization of the app interfaces.

Example

Built-in Animations
- Define a C-APP
  Startup Animation: Zoom In from Screen Center (GUI_APP_ANIMATION_1)
  
  Shutdown Animation: Zoom Out to Screen Center (GUI_APP_ANIMATION_5)
- Swap to the C-APP
  From app watch to 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))
}

Custom Animations
- Define a C-APP
  Startup Animation: Pop-Up from Bottom of Screen (heart_rate_startup)
  
  Shutdown Animation: Slide Down to Disappear (heart_rate_shutdown)
- Swap to the C-APP
  From app watch to 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.

Parameters:

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.

Parameters:

APP_NAME – The name of the application.

Returns:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Returns:: 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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Returns:: true top layer
Returns:: false button layer

void gui_set_app_active_time(gui_app_t *app, uint32_t active_ms)

Set app active ms time.

Parameters:

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.

Parameters:: obj – A pointer to a GUI object.
Returns:: 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