Messaging Structure

Last modified by Microchip on 2024/12/05 12:59

Contents

Messaging Structure for Graphics Applications
Learn More

Messaging Structure for Graphics Applications

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

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 GFX_GOL_ObjectMessage function 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 gfx-gol.h file, the structure of the message is:

gfx-gol.h structure

Msg can be defined in any file with GFX_GOL_MESSAGE Msg;.

Structure for a Touch-Enabled Display

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

Touch enabled display Msg

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

Keyboard Message

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.

message structure for keyboards

Example of a Keyboard Input