Performing Actions based on User Input

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_app_code.png

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:

MessageCallbackSetup.png

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

onebutton.png


Given the following conditions:

  1. A screen defined with one button (as shown on the right)
  2. The ObjectID of the button set to button1
  3. A requirement to run the function Start_Machine when the button is pushed
  4. A requirement to run the function Stop_Machine when the button is released
  5. 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:

one-button-code.png

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

multiple-buttons-1.png

multiple-buttons-2.png

multiple-buttons-3.png

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

Callback-Setup1.png
Callback-createbuttons.png

3 Write the Message Callback Function

Callback-MultiObject-1.png
callback-upbutton.png
callback-downbutton.png
slider-callback.png

4 Set the Message Callback Functions

set-msg-callback.png

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

GFX_app_code.png

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:

msg_callback_setup_code.png
msg_callback_code.png

© 2024 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.