Processing User Input in a Graphics Application

Last modified by Microchip on 2024/12/05 12:58

Contents

Summary
Process Overview
Learn More

This page contains information for the Graphics Library found in Microchip Libraries for Applications (MLA). It is not relevant to the MPLAB® Harmony Graphics Library.

Summary

This page describes how to process user input in a graphics application. There are two primary ways user data is input into a graphics application. The first method of inputting data is by using a touch screen. The second method of getting user data is by a change to a PIC^® MCU peripheral. A change in a peripheral could be a digital input, an analog input, or a change to a Special Function Registers (SFR) value such as a timer register.

In this article, you'll learn how the user program can decode a touch event detected by GetTouchMsg. Additionally, we'll cover how the user can write code to record and process a change to an MCU peripheral. how to decode a touch event detected by GetTouchMsg in your user program.

Process Overview

For touch events, GFX_GOL_ObjectMessage processes the message structure (Msg) loaded by TouchGetMsg.

If needed, refer to the "Getting Touch Input from a Screen" tutorial to review how TouchGetMsg operates.

GFX_GOL_ObjectMessage

Translates Msg to see if an object in the display list experienced a touch event.

If an event has contacted an object AND the object can accept the event, the user-written callback function is called to perform specific MCU action.

The callback function has the option of performing custom changes to multiple objects in the display list or allowing GFX_GOL_ObjectMessage to administer default settings for the object based on the event.

Object Message

Setting Up the Callback Function

The callback function is written by the user and may be given any valid function name. The user-written callback function is set as the "Message Callback" by GFX_GOl_MessageCallbackSet (see example). The inputs to the callback function are GFX_GOL_TRANSLATED_ACTION, a pointer to the Object touched, and a pointer to Msg.

GFX_GOL_MessageCallbackSet
Input	User-written function to be set as the Message Callback Function
Returns	Establishes the function as the Message Callback Function

Example

User written call back function

The types of actions that are translated are contained in the enumeration GFX_GOL_TRANSLATED_ACTION. The definition is found in the gfx_gol.h file.

Processing Touch Events

The user-written callback functions are written to perform specific MCU operations based on the detected event. The callback functions are also capable of modifying the appearance of any object, objects, in the display list. The callback function can be configured to allow GFX_GOL_ObjectMessage to apply a default appearance for the event to the object. The callback function returns a boolean value to determine which function updates the appearance in the display list. A returned FALSE value indicates the callback function has set the state-bit for an object (or objects) in the display list. A TRUE value causes GFX_GOL_ObjectMessage to apply the default changes to the object.

Examples of Touch Event Processing

Example 1: Processing a Simple Object

Push Me button

Given the following conditions:

A screen defined with one button
The ObjectID of the button set to button1
A requirement to run the function Start_Machine when the button is pushed
A requirement to run the function Stop_Machine when the button is released
The appearance of the button will take the default conditions for a pushed or released button object

Code to implement the callback function could be:

The previous sample code presumes GFX_GOL_MessageCallbackSet was called to set APP_ObjectMessageCallback as the message callback function.

Example 2: One Touch Affecting Multiple Objects

Multiple Buttons and a scrollbar configured as a slider

Multiple Buttons when the down button is pushed and released

Slider is moved to the right and left

The Message Callback function could be implemented with the following steps:

Import Required Images

This example requires two images to be imported into the project. The tutorial on working with graphics primitives will give you the information to import images into your project. The two arrow images used in this example are called UpArrow and DownArrow.

Add Definitions and Create Objects

Identify the Pointers

Set the Text for the Buttons

Write the Message Callback Function

Message Callback Function

Callback Up Button

Callback Down Button

Slider Callback Function

Set the Message Callback Functions

Set Message Callback

Processing Non-touch Events

Example: Non-touch Event Processing

The user application can be written to accept and use input from sources other than the touch screen. The application can be written such that a change to a non-touch element (input pin or SFR) causes the display to be changed.

When adding non-touch inputs to a graphics application ensure the changes to the display list are made only when GFX_GOL_ObjectListDraw has finished processing the display list.

Make Display Changes in Safe Zone

The "Safe" Zone

Altering the state-bits of the display list while the list is being processed by GFX_GOL_ObjectListDraw can result in anomalies in the image being displayed.

To avoid problems with the display the only safe place to update the list of objects is after the drawing function returns a true condition

Safe Zone

Sample Code

Given a screen created with a radio button called RadioButton1, the user is given the task of displaying the state of pin RE9 (bit 9 on PORTE). When the pin value is set, the radio button will appear checked. When the pin value is cleared, the radio button will appear unchecked.

The following code could be used to implement this requirement:

Msg Callback Setup Code

Msg Callback Code