Changing the State of a Graphics Object

This page contains information for the Graphics Library found in the Microchip Libraries for Applications (MLA). It is not relevant for the MPLAB® Harmony Graphics Library.

 Summary

This page describes the functions needed to get access to, and modify the state-bits of graphics objects. Modifying an object's state bits will change the appearance of the object when the object is rendered. The functions described on this page are typically called by the Message Callback function to respond to external events. After reviewing this page on how to alter an object's state bit, you may find it useful to visit the "Performing Actions based on User Input" page to understand when to alter an object's state bits.

Finding the Object in the Display List

The object-modifying functions require a pointer to the object in the display list in order to execute. The required data is the address returned when the object was created. Some applications store a unique pointer for every object created. It is not necessary to consume memory by storing a pointer to every object. An object's address can always be retrieved by using the function GFX_GOL_ObjectFind.

GFX_GOL_ObjectFind
Input: Object ID used when the object was created
Returns: Address of the object in the Display List

Each object in the display list has a unique ObjectID.

Example: Getting an Object's Address in the Display List

GetObjectID-code1.png
GetObjectID-code3.png
GetObjectID-code4.png

SETTING State Bits

The function used to set the value of an object's states bit to the "true" condition is GFX_GOL_ObjectStateSet.

GFX_GOL_ObjectStateSet
Inputs: pOBJ pointer to the object
State Bits: The state bit(s) to be set to true
Actions Taken: Sets the object's state bits matching those
passed to the function. Leaves the object's state bits
not referenced unchanged.

Example: A "Pressed" Button

ObjectStateSet-code1.png

When setting a state bit in order to have the change updated on the screen, the "DRAW" state bit must also be SET.

CLEARING State Bits

The function used to put the value of an object's states bit in the "false" condition is GFX_GOL_ObjectStateClear.

GFX_GOL_ObjectStateClear
Inputs: pOBJ pointer to the object
State Bits: State bits to be cleared
Actions Taken: Clears the object's state bits matching those
passed to the function. Leaves the object's state bits
not referenced unchanged.

Example: An "UN-Pressed" Button

ObjectStateClear-code1.png

When a change in the condition of an object requires a state bit to be CLEARED (such as a button being released), the DRAW bit must be SET in order to update the frame buffer.

Changing the VALUE of an object

Unlike buttons which have only two states, several object types display a range of data. Such objects includeslider-bar, meters, and progessbars. Specific functions are used to update the value of objects displaying variable data. Some of the updating functions are GFX_GOL_ScrollBarPositionSet, GFX_GOL_MeterValueSet, and ProgressBarPostionSet. A list of the functions available to modify objects is available in the help file.

Example: Setting the Position of Progress Bar

ProgressBarPositionSet.png

Example: Updating the Value of a Digital Meter

DigitalMeterValueSet.png

Setting the UPDATE state bit will cause GFX_GOL_ObjectListDraw to place only the portion of the object containing the value in the frame buffer. Re-writing only a portion of the object to the frame buffer reduces the visual flicker some people notice when an entire object is re-drawn.

Reading an Object's State Bits

GFX_GOL_ObjectStateGet
Inputs: pOBJ pointer to the object
State Bits: The state bit(s) to be set to be retrieved
Function: Return the value of state bits of those passed to the function.

Example

ObjectStateGet-code.png

Getting the Object ID from the Display List

Occasionally you will have a pointer to the object and want to determine the ObjectID referenced. The function GFX_GOL_ObjectIDGet returns the ObjectID for a given pointer.

GFX_GOL_ObjectIDGet
Input: pOBJ pointer to the object
Returns: @The ObjectId of the object pointed to by pOBJ

Example

ObjectIDGet-code.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.