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
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
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
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
Example: 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.
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
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
