Messaging Structure

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

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.

Back to top

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

Back to top

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 CodeTouch Event Detected
EVENT_INVALIDScreen was untouched last time and remains untouched
EVENT_MOVEScreen was touched last time, this time the touch is in a different location
EVENT_PRESSScreen was untouched last time and is touched this time
EVENT_STILLPRESSScreen was touched last time and is still touched in the same location
EVENT_RELEASEScreen was touched last time, but is now untouched

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

Back to top

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 CodeEvent Detected
EVENT_INVALIDCurrent ADC value is not significantly different from last reported value
EVENT_KEYSCANCurrent value of the ADC requires the display to be updated
EVENT_CHARCODECurrent 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 CodeEvent Detected
EVENT_PRESSThe Pin value is now High and was Low on previous read
EVENT_STILLPRESSCurrent and Previous value of the pin is High
EVENT_RELEASEThe input value is now Low and was High on previous read

Back to top

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

​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 CodeEvent Detected
EVENT_KEYSCANValue of the Keyscan
EVENT_CHARCODEASCII code for the keyboard input

Back to top

Learn More

Back to top