Changing the State of a Graphics Object

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

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 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 GFX_GOL_ObjectFind function.

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

Getting an Object's Address in the Display List

Getting an Object's Address in the Display List

Getting an Object's Address in the Display List

Back to top

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

A "Pressed" Button

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

Back to top

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

An "UN-Pressed" Button

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.

Back to top

Changing the VALUE of an object

Unlike buttons which have only two states, several object types display a range of data. Such objects include slider-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

Setting the Position of Progress Bar

Example: Updating the Value of a Digital Meter

Updating the Value of a Digital Meter

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.

Back to top

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

Return the value of state bits

Back to top

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

The function GFX_GOL_ObjectIDGet returns the ObjectID for a given pointer.
Back to top

Learn More

Back to top