This page contains information for the Graphics Library found in Microchip Libraries for Applications (MLA). It is not relevant for 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 Register value such as a timer register.
This article begins by showing how the user program can decode a touch event detected by GetTouchMsg. The article proceeds to show how the user can write code to record and process a change to an MCU peripheral.
Process Overview
For touch events, GFX_GOL_ObjectMessage processes the message structure (Msg) loaded by TouchGetMsg.
If needed, refer to the section of this tutorial on getting user input 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.
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:
The types of actions that are translated are contained in the enumeration GFX_GOL_TRANSLATED_ACTION. The definition is found in the file gfx_gol.h.
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
Given the following conditions:
- A screen defined with one button (as shown on the right)
- 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 sample code above presumes GFX_GOL_MessageCallbackSet was called to set APP_ObjectMessageCallback as the message callback function.
Example 2: One Touch Effecting Multiple Objects
The Message Callback function could be implemented with the following steps:
1 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.
2 Add Definitions and Create Objects
3 Write the Message Callback Function
4 Set the Message Callback Functions
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.
1 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
2 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 used to implement this requirement:
