Timing Touch Events in Graphics Applications

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

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 upon 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 upon 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 which 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

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.

msg-callback.png

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


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

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.

draw-callback-setup.png

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

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.

Location of tick module in an MLA Application


The functions needed to start-up and implement the tick module in MLA applications are located in the file system.c. 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 contain 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.

system-location.png

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) which increments a data variable at specific intervals.
  3. Various #define functions and variable declarations to provide the application programmer an easy method of calculated delay intervals.
  4. The ability to read the current value of the system tick variable.

For the example shown below 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 1/2 second the button is continually pushed, UPMotor is called. When UPbutton is released, the motor speed will cease to increment.

Steps to Implement this Example

1 Calculate and Define Delay Interval

Timing how long a touch event is accomplished by monitoring the increase in the tick timer. Since 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.png

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

defines.png

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 1/2 second units.


2 Create Required Data Variables

variable.png

3 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 value which the tick timer will contain in 1/2 second units

When the Msg indicates the button has been RELEASED:

  • touch_state is set to not_touched
timed-msg-callback.png

4 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 1/2 second.
timed-draw-callback.png

5 Set the Draw Callback Function

set-draw-callback.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.