How-To: Create Persistent Global Widgets

Last modified by Microchip on 2025/02/11 16:17

Introduction

A global or persistent widget in a graphical user interface (GUI) refers to a user interface element that remains visible and accessible across different screens in the application. Unlike standard widgets which are created and destroyed within a screen's lifecycle, persistent widgets are designed to provide continuous access to certain functionalities or information.

For example, a persistent widget could be a toolbar, a status bar, or a navigation menu that is visible regardless of which screen the user is on.

This example shows how to use a persistent screen to create global widgets that can be used on any screen.

Microchip Graphics Suite (MGS) Example Project

Refer to the project in GitHub for the example.

MGS Harmony Web Simulator Output

The application shows the first screen with a top menu bar or banner. By pressing the buttons, "Screen X" will switch screens and increment the counter on the right.

The banner menu is a global widget that persists across different screens. This means that the state of the widgets on the top menu bar, such as the counter value, will persist across screen transitions.

Global Widgets Example (Interactive)

MGS Harmony Composer Design

The MGS Composer design contains four screens: GlobalScreen, Screen0, Screen1 and Screen2.

Persistent Screen and Global Widgets

GlobalScreen contains the design for the top menu bar (pnlMenu). pnlMenu is a global widget container, which includes the menu buttons (btnScreen0, btnScreen1, btnScreen2) and a label (lblCount) for the counter.

Note that the screen's Persistent property is enabled. This means that the screen and its widgets are created once during boot, and never get destroyed.

GlobalScreen MGS Composer Design

The OnReleased event property is enabled for the buttons on the top menu bar. The event callback will be used to switch to the appropriate screen.

Button Event Callbacks

Other Screens

The other screens are designed to have a label that shows the screen ID. The OnShow and OnHide event properties are enabled for these screens. The screen event callbacks will call the APIs to add the global pnlMenu widget to these screens.

Note that the global top menu bar widget is not included in the screen designs in MGS Composer. The global widget is added to the screens at run-time thru the application code.

Other Screen Designs

Application Code

The app_globalscreen.c file contains the screen application code for the persistent screen, GlobalScreen. The button's onReleased callback functions contain the call to increment the counter and to show the selected screen.

/* Callback function for Screen0 button in banner */
void event_GlobalScreen_btnScreen0_OnReleased(leButtonWidget* btn)
{
    app_IncrementScreenCount();

    legato_showScreen(screenID_Screen0);
}

A helper function is called to increment the counter and update the label on the top menu bar.

/* Helper function that increments the screen transition count and label */
static void app_IncrementScreenCount(void)

Using the Global Widget

The app_screenX.c files contain the screen application code for the other screens. The screen callback functions add and remove the global widget to a screen.

Adding to a Screen

The screen OnShow() callback function adds the global pnlMenu panel widget for the top menu bar as a child to the screen's root widget. This will tell the library to show the panel widget (and its children) with the screen.

/* Called when Screen 0 is to be shown.
*
* Here the parent panel widget for the global menu banner is added
* to the screen's root widget so that it is displayed on the screen.
*/
void Screen0_OnShow(void)
{
   /* Get the screen's root widget for layer 0 */
    leLayerState* layerState = leGetLayerState(SCREEN_LAYER_IDX);
    root0 = &layerState->root;

   /* Add the banner's parent panel widget as child to the
     * screen's root widget*/
    root0->fn->addChild(root0, (leWidget*)GlobalScreen_pnlMenu);
}

Removing from a Screen

The screen OnHide() function removes the pnlMenu panel widget from the screen's widget tree. This is needed so that the panel widget is not destroyed along with the screen when the screen is hidden.

/* Called when Screen 0 is to be hidden or destroyed
*
* Here, the parent panel widget for the global menu banner is removed
* from the screen's root widget children tree so that it is not destroyed.
*/
void Screen0_OnHide(void)
{
/* Remove the banner's parent panel from the screen's root widget*/
root0->fn->removeChild(root0, (leWidget*)GlobalScreen_pnlMenu);
}