Summary

This page describes the configuration and usage of the messaging data structure used in Microchip Graphics Applications. Defined in the gfx-gol.h file and typically named Msg by the application, this structure is used to communicate changes in system input to the graphics processing software. The input sources can be:

A Touch Screen
An Input Pin or PIC^® Special Function Register (SFR)
Keypad Device

The Microchip supplied function TouchGetMsg will populate Msg when using a touch-enabled display offered as part of a Microchip Development tool. For non-Microchip supported touch displays and for all non-touch input detection, the user's application is responsible for identifying input changes and filling in the Msg data structure.
When an input change has been recorded, the application will fill in Msg and pass it to the function GFX_GOL_ObjectMessage for processing. The sections of this tutorial that cover processing user input and the graphics overview provide the details of how Msg is processed.

Message Structure Definition

Defined in the file gfx-gol.h the structure of the message is:

Msg can be defined in any file with the following code:

Structure for a Touch Enabled Display

When populated by TouchGetMsg for a touch enabled display, Msg will contain:

For Touch Enabled Displays:
Msg.type always contains value: TYPE_TOUCHSCREEN
Msg.param1 contains the X position of the event
Msg.param2 contains the Y position of the evnet
Msg.uiEvent contains the code for the specific event detected

uiEvent Codes for Touch Displays

	Event Code	Touch Event Detected
	EVENT_INVALID	Screen was untouched last time and remains untouched
	EVENT_MOVE	Screen was touched last time, this time the touch is in a different location
	EVENT_PRESS	Screen was untouched last time and is touched this time
	EVENT_STILLPRESS	Screen was touched last time and is still touched in the same location
	EVENT_RELEASE	Screen was touched last time, but is now untouched

Once filled, Msg is passed on to GFX_GOL_ObjectMessage for processing.

Structure for Pin or SFR Changes

For non-touch display inputs, Msg is populated with the type set to TYPE_KEYBOARD.
TYPE_KEYBOARD is used when a change in an SFR needs to be reflected on the display. (Note: A change to an input pin will be reflected in the corresponding PORTx SFR.)

Example of an Analog Pin Change

For Analog Pin Changes:
Msg.type always contains value: TYPE_KEYBOARD
Msg.uiEvent contains EVENT_KEYSCAN or EVENT_CHARCODE
Msg.param1 ObjectID of the event recipient
Msg.param2 The new value of the ADC Result register

Expected uiEvent Codes for Analog Pin Changes

	Event Code	Event Detected
	EVENT_INVALID	Current ADC value is not significantly different from last reported value
	EVENT_KEYSCAN	Current value of the ADC requires the display to be updated
	EVENT_CHARCODE	Current value of the ADC requires the display to be updated ( same as EVENT_KEYSCAN)

Example of a Digital Pin Change

For Digital Pin Changes:
Msg.type always contains value: TYPE_KEYBOARD
Msg.uiEvent contains valid Event code
Msg.param1 ObjectID of the event recipient
Msg.param2 -Not Used-

Expected uiEvent Codes for Digital Pin Changes

	Event Code	Event Detected
	EVENT_PRESS	The Pin value is now High and was Low on previous read
	EVENT_STILLPRESS	Current and Previous value of the pin is High
	EVENT_RELEASE	The input value is now Low and was High on previous read

Structure for Keyboard Input

For keyboard inputs, Msg is populated with the type set to TYPE_KEYBOARD.
The message structure for keyboards is similar to the structure for changes in digital inputs.

Example of a Keyboard Input

Expected uiEvent Codes for Keyboard

	Event Code	Event Detected
	EVENT_KEYSCAN	Value of the Keyscan
	EVENT_CHARCODE	ASCII code for the keyboard input

Return to Top