How to Trigger An Event At Screen Show

It’s time to add a screen event behavior. You’ll start by working on the user interface created from How to Add a Transition Between Two Screens.

Graphics does not exist in a vaccum. The whole point of Graphics User Interface is to provide human-machine interaction.

Event callbacks can:

• Call MGS Harmony library functions to update the user interface
• Call a driver or peripheral library (PLIB) function to control hardware
• Call application functions for business logic operations

You can learn about widget event callback in the next guide How to Add a Widget Event Callback.

In this guide, we will add a event to respond to a notification that screen1 is displayed. We will add application logic to receive the event.

Screen Events

There are three events available.

<"Screen Name">_OnShow()

Called right after the screen and children widgets are created

TIP: Use to allocate and initialize run-time screen objects (e.g., strings)

TIP: Use to restore widget states

<"Screen Name">_OnUpdate()

Called right before the screen and children widgets are updated and redrawn. This is periodically called inside the Legato task.

TIP: Use to manage screen application states

TIP: Use to set widget properties

<"Screen Name">_OnHide()

Called right before the screen and children widgets are destroyed/freed*

TIP: Use to delete and free allocations for run-time screen objects

TIP: Use to save widget states

*screens marked ‘persistent’ are not destroyed when hidden and all dynamic allocations are preserved in memory.

Screen Event Best Practices

• Define all callback functions for a screen and widgets inside a screen-specific application source file. This makes for a cleaner project since screen-specific code are in one source file.

• Always call Legato Widget APIs in <"Screen Name">_Update(). This guarantees that the memory for the screen and widgets are valid. This eliminates race condition in RTOS-based projects.

Add a On Show Event for screen1

Enable the On Show event

1. In the Screen designer select screen1 to activate its properties in the Object Editor.

In the Object editor under Events section, enable On Show.

Upon MHC generate, the following event callback code will be generated:

le_gen_screen_Screen1.h

// Screen Events:
void Screen1_OnShow(); // called when this screen is shown);

le_gen_screen_Screen1.c

Screen1_OnShow(); // raise event |

app_Screen1.c - We recommend users create a separate application file for each screen. Event handlers defined in le_gen_screen_Screen1.h should be implemented in your app_Screen1.c file. Implement the following code in your app_Screen1.c file.

// event handlers
void Screen1_OnShow()
{
    // Add business logic to respond to the OnShow event
}

Click File -> Save to finalize your new event addition.

---

Next Step

In this tutorial, you learned to enable an onShow event for screen1. This event allows you to be notified when screen1 is displayed. You can learn about widget event callback in the next guide How to Add a Widget Event Callback.

---

If you are new to MPLAB® Harmony, you should probably start with these tutorials:

• MPLAB® Harmony v3 Graphics Example Applications at MPLAB® Discover
• MPLAB® Harmony v3 software framework
• MPLAB® Harmony v3 Configurator Overview
• Create a New MPLAB® Harmony v3 Project

---

Is this page helpful? Send feedback