How-To: Use Widget Event Filters for Sliding Menus

Last modified by Microchip on 2024/10/30 14:44

Introduction

Microchip Graphics Suite (MGS) Harmony offers ready-to-use input widgets like buttons, scroll bars, keypad, etc. These widgets support common user input like touch down, up and move. When processing user input, the widget's default configuration supports basic behavior such as toggling the button or sliding the scroll bar.

To process more complex events and customize a widget's behavior when processing these events, the MGS Library enables application developers to override the default input handling of a widget using widget event filters.

Since these event filters are applied to a specific widget instance, they ensure that input events are processed only within the widget's area or when the widget is in focus.

For application-wide custom event handling, consider using the Input System Service (ISS).

MGS Example Project

Refer to the project in GitHub for the example mentioned in this user guide.

This example shows how to use widget event filters to create a sliding menu selection UI. A filter is used to capture and process touch events on a specific area of the screen and slide the menu selection UI based on the touch events.

MGS Simulator Output

The application shows a menu selection UI that lets users slide horizontally. Tapping an item in the menu highlights the item and shows the item's value on the screen.

Widget Event Filter Example

MGS Harmony Composer Design

Here is what the design looks like in MGS Harmony Composer. The design consists of a single screen scrnScroll which contains the widgets in the UI.

Note: The On Show, On Hide, and On Update events are enabled for the scrnScroll screen.

Selecting the widgets in the Screen Tree window will show the widget in the Screen Designer. These panel widgets are key to the sliding menu function:

pnlSlideMenu

This oversized panel contains multiple label widgets that represent the individual menu items. The panel is moved horizontally to slide the menu selection list.

pnlEventFilter

This panel occupies the area on the screen where the user can touch to slide or select a menu item. An event filter is installed on this panel to detect these user touch events.

Note: The pnlEventFilter is on top of pnlSlideMenu and is not obscured by any widget in the tree. This ensures that the pnlEventFilter captures the touch events in the area of the screen that it covers.

Application Code

The screen application code in app_scrnScroll.c contains the application code that uses widget event filters and library APIs for performing the sliding menu UI.

Installing a Widget Event Filter

The SlideMenu_filterEvent function contains the code that handles the touch down, touch move, and touch up events.

static leBool SlideMenu_filterEvent(leWidget* target, leWidgetEvent* evt, void* data)

This function is added to an event filter structure.

static leWidgetEventFilter SlideMenu_eventFilter =
{
SlideMenu_filterEvent,
NULL
};

In the scrnScroll screen callback functions, the event filter structure is installed to the pnlEventFilter widget when the screen is shown using the installEventFilter widget API.

void scrnScroll_OnShow(void)
{
/* Install event filter to the event filter panel (pnlEventFilter) */
scrnScroll_pnlEventFilter->fn->installEventFilter(scrnScroll_pnlEventFilter, SlideMenu_eventFilter);
}

The event filter is removed when the screen is hidden using the removeEventFilter widget API.

/* Screen callback when hidden */
void scrnScroll_OnHide(void)
{
/* Remove event filter when hiding screen */
scrnScroll_pnlEventFilter->fn->removeEventFilter(scrnScroll_pnlEventFilter, SlideMenu_eventFilter);
}

Processing Events

As mentioned earlier, the function SlideMenu_filterEvent contains the code that handles the touch down, touch move, and touch up events using a switch-case statement.

static leBool SlideMenu_filterEvent(leWidget* target, leWidgetEvent* evt, void* data)

Refer to the function's inline documentation for detailed information on how the MGS Library APIs are used to move the panel and select items on the menu based on the received event.

Note: The example only processes touch events, which are a subset of all the library events that are passed to a widget.

Widget event filters can be used to implement application-specific behavior for other widget events using the same widget event filter APIs described above. Here's a list of all the widget events that can be customized using widget event filters.

Refer to legato_event.h for more information.

typedef enum leEventID
{
   // internal events
   LE_EVENT_NONE, /**< No event found. */
    LE_EVENT_TOUCH_DOWN, /**< Touch down event. */
    LE_EVENT_TOUCH_UP, /**< Touch up event. */
    LE_EVENT_TOUCH_MOVE, /**< Touch move event. */
    LE_EVENT_LANGUAGE_CHANGED, /**< Language changed. */

   // widget events
   LE_WIDGET_EVENT_PAINT = 100, /**< Paint event. */
    LE_WIDGET_EVENT_MOVED, /**< Moved event. */
    LE_WIDGET_EVENT_RESIZED, /**< Resized event. */
    LE_WIDGET_EVENT_FOCUS_GAINED, /**< Focus gained event. */
    LE_WIDGET_EVENT_FOCUS_LOST, /**< Focus lost event. */
} leEventID;

Summary

This how-to guide shows how to use the widget event filter for filtering touch events on a widget area and using them to slide and select items in a horizontal sliding menu. The same technique can be used for a vertical menu or a drag-and-drop UI.