Creating a Dynamic UI with Event Handling

Introduction

This guide will discuss event processing and handling within Microchip Graphics Suite (MGS) Harmony while creating a dynamic User Interface (UI) application.

This guide will cover how to configure different types of graphics events needed for a UI application. Additionally, it provides users with instructions on how to implement dynamic run-time strings to display a live counter. Lastly, this guide shows a tutorial on constructing a multilingual user interface that changes the displayed text according to the user's language preference.

In the end, the user will be able to quickly understand how to create a dynamic UI application using MGS Harmony.

MGS Example Project

Refer to the GFX_Sim_EventUI project in GitHub for an example.

MGS Simulator Output

Here's how the application runs.

Pressing the Change Screen button will change the screen from screen0 to Screen1. On Screen1, a clock timer will start counting up.

Hours, minutes, seconds, and tenths of a second are displayed as Dynamic String objects. Each Dynamic String object automatically resizes the character buffer based on the length of the clock digits.

Pressing the Change Language button on Screen1 will show the French language translations for the String Assets shown on both screens. Press the Change Language button a second time and the language with turn back to English.

The clock timer will only run when on screen1. When switching to Screen0, the timer will stop until you return to screen1.

Back to Top

MGS Events

MGS Harmony can receive two types of events, a touch event and a screen event. A typical UI application has a touch event from a button widget causing a screen change event. The UI application created in this tutorial demonstrates these typical events.

This diagram shows the touch input causing the execution of a widget event callback. Pressed and Released are two event callback functions that can be selected from the button widget configuration. Within the widget event callback function, a screen change can be commanded. On Hide, On Show, and On Update event callbacks can be selected from the screen configuration.

For more information on events, see the "Designing an Application with Microchip Graphics Suite (MGS)" page.

Back to Top

MGS Composer Design

The UI application created was started with the screens and widgets from the project in the class, "Getting Started with a New Harmony Graphics Application".

The UI application is created with examples of events and handling in the following order:

1. Button Widget event.

2. Screen change events.

3. Dynamic String events.

4. Language changing at run-time.

Button Event Configuration

The accompanying image shows Screen0 opened with Microchip Graphics Composer. In the Object Editor for Screen0, ButtonWidget1 is selected showing the Pressed event checkbox selected.

Button Widget Event Code

The code generated creates the new event function prototype for the button widget, which is to be implemented in the application code. The header file le_gen_screen_Screen0.h now contains the new prototype as shown in the accompanying images.

The MGS Harmony code will automatically call the event callback function after the Pressed touch of the button widget. The application code in app.c contains the action to change to screen1 using the legato_showScreen (<screen id>) library function call.

Back to Top

Screen Event Configuration

The screen events get enabled when selecting the event checkboxes for the selected screen. Screen1 is selected in the MPLAB X IDE Object Editor.

Screen Change Event Code

The code generated creates the new event function prototypes for the Screen1 events. The MGS Harmony code will automatically call the event callback functions after the screen has been commanded to change. The application code in app.c contains the actions within each of the event callbacks. The header file le_gen_screen_Screen1.h now contains the three new prototypes as shown in the accompanying images.

Screen1 OnShow

The Screen OnShow event is triggered when a new screen is created, right before the screen is drawn to the frame buffer. Having an application callback for this event is useful for pre-configuring widgets on a screen right before the screen is drawn on the frame buffer.

For example, if a label in the screen needs to show the current timer value when the screen is shown, then the OnShow callback function is the right place to call the Label widget APIs to configure that label.

Screen1 OnHide

The Screen OnHide event is triggered when the current screen is about to be hidden. This happens right before the widget objects are destroyed and their memory allocations are freed. Having an application callback for this event is useful for saving the states of widgets before the screen is hidden or to free up any memory allocations in the Screen OnShow callback and prevent memory leaks.

Screen1 OnUpdate

The Screen OnUpdate event for the currently active screen is periodically triggered at every execution cycle of the MGS Harmony Task. The OnUpdate() callback function is the recommended place where system-level events and statuses that affect the UI can be monitored and where the MGS Harmony Graphics screen and widget states can be called to update the UI.

For example, if the UI needs to show a label with a current timer value that is constantly running, then that timer value can be polled in the OnUpdate() event callback function, and the label is updated when the counter value has changed.

Back to Top

Dynamic Strings Configuration

Another type of event used in MGS for MPLAB Harmony is a non-user triggered or system event.  Dynamic Strings will be used to show this event type by implementing a clock timer. There are no Composer checkboxes to enable with a timer. The timer is created using library calls with the time and period parameters defined in the application code.

For more information on Dynamic Strings, see the "How-To: Create Run-time Strings" page.

Timer Screen Setup

The screen uses label widgets to represent hours, minutes, seconds, and tenths of a second (separated by colon labels).

Each label widget uses a ClockString string. The size and position of the string/font are configured so that only two digits will be rendered at a time. The code will also limit the value of each Dynamic String value to the appropriate number of digits. For more information, view the strings and fonts pages. 

Application Code

The project's app.c source file contains the application code and event callback definitions. The screen event callback functions are used to initialize, update, and clean-up the run-time strings.

1. Screen1_OnShow - Dynamic String object for labels (hour, minute, second, tenth of a second) is constructed.
2. Screen1_OnHide - Dynamic String objects are destructed.
3. clockTimer_Callback - Dynamic String counter values are updated when the clock timer expires.
4. Screen1_OnUpdate - Controls the state machine to switch Screen1 to Screen0 - remember that there are no Screen0 events enabled in the Composer.

Back to Top