How to Add A Widget Event Callback

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

The previous guide How to Add a Screen Event introduces event by teaching how to create an event to trigger a screen transition. This guide teaches event callback and how to add an event callback to a widget.

Event Callbacks

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

Different widgets have various kinds of events to add callbacks to.

Enabling Event Callbacks with the Event Manager

The Event Manager is an interface to enable/disable event callbacks for a screen as well as for all the event-capable widgets in that screen.

In the Graphics Composer, press Event Manager under the Project menu item to access the Event Manager interface.

Enabling Event Callbacks via the Object Editor

You can enable/disable screen and widget event callbacks by using the Object Editor also.

The events for the screen will show-up in the Object Editor window when you select the screen in the Screens sub-window.

The events for the widget will show-up in the Object Editor window when you select the widget in the Screen Tree sub-window.

Implementing Event Callbacks

Callback functions for enabled events are declared and called by the library.

Event callback functions must be user-defined in application code.

Event Callbacks Best Practice

• 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.

Example: Adding Event Callbacks to Screen Specific Application Source File

Here is an example of how to add event callbacks for a screen named "Screen0". The callbacks are for several button widgets to activate some LEDS.

In MPLABX:

a) Add a new C source file by right-clicking on Source Files, then go to New > Other

b) Set Categories to C

c) Set File Types to ‘C Source File’

d) Click ‘Next’

e) Set File Name to app_Screen0

f) Click Finish to complete

g) Open the file app_Screen0.c

h) Include the header file definitions.h

i) Add the Widget Callback Definitions (HINT: Copy the function declarations from the screen header file and just add the definition)

NOTE: LEDx_On/Off macros are pre-defined in the SAM E70 XULT board BSP. If these macros are not available for your board, use MHC Pin Configuration to add these LED macros

Press Event Cancelling

The release event is a function of the actual release detection on the area of the button. The expected behavior to cancel a press action can be done with the user dragging a finger touch outside of the button area.

Q: If the user is pressing but wishes to cancel the press, often, the user moves the finger (still pressing on the screen) outside the button. In this scenario, is the OnRelease callback event called?

A: Press is an event that is repeatedly sent by the touch driver as long as the finger is pressed. On the other hand, the release is a one-time event. Standard UI behavior is to associate any binary operations (such as ON/OFF) to the release event, not the press event. A press cancel event is actually handled inherently by the Graphics Library + System Input architecture. As the user moves the finger, the touch controller will switch from sending Press events to Move events, even as the finger moves off the button. When the finger is lifted, the Release event will not be registered as within the button’s screen space, and the release event will not be triggered. So the press request is essentially cancelled.

---

Next Step

In this tutorial, you learned to about widget event callback. You can learn about widget event filter in the next guide How to Add a Widget Event Filter.

---

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