Messaging Structure for 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

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:

GFX_GOL_MESSAGE.png

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:

Msg-filled.png

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

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.

keyboard-msg.png

Example of a Keyboard Input

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 value of the input character or scan code

Expected uiEvent Codes for Keyboard

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

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