Timing Touch Events in Graphics Applications

Last modified by Microchip on 2023/11/10 11:03

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

In some applications, it is necessary to time how long an object is touched. Timing touch events allows the application to change a system value based on the length of time an object on the display is touched.

One example of a continuous touch event could be a dimmer switch for lighting. In addition to changing the lighting value each time an up or down button is pressed, the system may be configured to gradually increase or decrease the lighting in response to the user keeping their finger on either the up or down button.

This article describes the process and steps needed to take action based on the amount of time an object has been touched.

Overview

Processing Timed Events

The process for determining time intervals takes several steps:

  • When an event is first detected the Message Callback function sets a flag indicating a touch event that needs to be timed is taking place. The message callback function will then read the current system time from the tick module, add a calculated delay period, and store this value.
  • On each iteration of the main loop the Draw Callback function tests the flag to see if a continuous touch event is taking place. If a continuous touch event is active, the current system time is tested to see if the desired time delay has passed. When the desired time interval has passed, the Draw Callback function takes the appropriate system action, then calculates the next delay time interval.
  • When the Message Callback function detects the touch event has been RELEASED the flag telling the Draw Callback to monitor the timed touch event is cleared.

To implement continuous touch timing, three elements of the Graphics library must be used in conjunction with each other:

  • Message Callback function (GFX_GOL_ObjectMessageCallback)
  • Draw Callback function (GFX_GOL_ObjectDrawCallback)
  • The Tick Module

Back to top

Message Callback Function

The Message Callback function is called by GFX_GOL_ObjectMessage each time a touch event has been detected. To monitor the length of time a touch event occurs the Message Callback Function first records that a "timed" touch event is occurring by setting a global variable when the touch is detected. The Message Callback then determines what time to take the incremental system action.

Message Callback Function

For a complete description of the Message Callback function, including how to set up the callback feature, please refer to the tutorial section on processing user input.

Back to top

Draw Callback Function

The Draw Callback Function, described in detail below, is called by GFX_GOL_ObjectListDraw each time through the main loop. The draw callback function checks to see if the Message Callback function has set the flag indicating a particular touch event is happening. If a timed touch event is taking place and the desired time interval has passed the Draw Callback function takes the desired incremental action.

Draw Callback

Back to top

Tick Module (System Timing Module)

The tick module is a system resource that keeps track of the system time. Typically the tick module uses a timer interrupt to increment a variable at a constant interval. A description of how to set up and use the tick module is covered later on this page.

Using the Draw Callback Function

Before GFX_GOL_ObjectListDraw processes the display list it calls the Draw Callback function. The Draw Callback function is a user-written function. The Draw Callback function is executed every time GFX_GOL_ObjectListDraw is executed regardless of whether or not there are any changes detected on the touch screen.

The draw callback function is implemented by the application developer. The developer first writes a function to perform the Draw Callback tasks. This function may be given any valid function name. The function GFX_GOL_DrawCallbackSet is then used to assign the user-written function and the Draw Callback function. Each time GFX_GOL_ObjectListDraw is executed the user written draw callback function will be called.

User written draw callback function

The code example at the bottom of this page shows how a Draw Callback routine may be written.

Back to top

Setting up the Tick Module

A tick module is supplied with both Harmony and MLA projects. The basic features and services provided by the two tick modules are similar. There are significant differences between the Harmony and MLA implementation of the tick module. This tutorial discusses how to locate, configure, and use the tick module in an MLA application.

Back to top

Tick Module Location in an MLA Application

The functions needed to start up and implement the tick module in MLA applications are located in the system.c file. In Microchip-supplied graphics projects, system.c can be accessed in the project tree under the system_config directory. There is a sub-directory under system_config for every project configuration. Each of the sub-directories contains a system.c file, which is written to implement the tick function for the specific MCU used in the corresponding project configuration. The file properties of the multiple system.c files are set so that only the version of system.c for the current configuration is included in the build.

Dialog box showing current configuration

Key Functionality Included in the MLA Tick Module

The tick module includes:

  1. A tick module initialization routine that needs to be called for the tick module to operate.
  2. A timer-specific Interrupt Service Routine (ISR) that increments a data variable at specific intervals.
  3. Various #define functions and variable declarations to provide the application programmer with an easy method of calculating delay intervals.
  4. The ability to read the current value of the system tick variable.

For the following example, the tick module simply keeps the value in a 32-bit variable so the access method for the system tick is a simple read of the variable. Harmony and MLA applications for certain MCUs use function calls to get the system tick.

Example Code: Timing a Touch Event

The example code is for a portion of a speed control system for a motor. For simplicity and readability, only the function providing the ability to increase the speed of the motor is given. It is presumed the user can take the code in this example and expand it to supply multiple timed-event controls.

A button called UPbutton has been created and placed on the display list. In addition to the display, the MCU is connected to a motor. The speed of this motor is increased each time the UPMotor function is called.

In this example, the tick module uses a timer interrupt and places the system time in a uint32 variable called tick.

Design Requirements: The requirement is to incrementally increase the speed of the motor based on the amount of time-continuous contact is made with UPbutton. For each half second the button is continually pushed, UPMotor is called. When UPbutton is released, the motor speed will cease to increment.

Back to top

Steps to Implement this Example

Calculate and Define Delay Interval

Timing how long a touch event is accomplished by monitoring the increase in the tick timer. Since the tick is changed by a timer, its value will increment at a constant rate. Each increment in the tick corresponds to a finite amount of time.

The essential calculation is to determine how much the tick timer will increment in a given time interval. This calculation requires knowledge of the system clock frequency and both the period register and pre-scale value for the timer used by the tick module.

Tick Calculation

To implement this calculation the following #define functions are added to the project:

Define functions are added to the project

When a timed touch event is detected, the (current tick value + half_second_delay) will be stored in a variable to indicate the value the tick timer will contain in half second units.


Create Required Data Variables

Modify the Message Callback Function

When Msg informs the message callback function that the button has been PRESSED:

  1. The state variable touch_state is set to touched
  2. DoneAt is loaded with a value that the tick timer will contain in half-second units

When the Msg indicates the button has been RELEASED:

  • touch_state is set to not_touched

Timed Message Callback


Create the Draw Callback Function

When both (touch_state == pressed) and the time interval has passed:

  1. UPmotor() is called
  2. DoneAT is loaded with the value for tick in the next half second.

Timed Draw Callback


Set the Draw Callback Function

Draw Callback Function


Learn More

Back to top