Creating Graphics Objects

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 for MPLAB® Harmony Graphics Library.

Graphics objects are created at run-time. Before a screen is initially drawn, the application calls a sequence of object-creating functions. Each of these functions creates a data structure for an instance of an object. Parameters passed to the object-creating functions determine the location, size, state, and colors of the object. In addition to the commonly shared parameters just mentioned, many object functions accept parameters unique to specific objects.

The created data structures are placed in a single linked list. The drawing function (GFX_GOL_ObjectListDraw) reads the object's state bits in the display list, then updates the frame buffer as needed.

All object-creating functions return a pointer to the memory location of the data structure they create. The object structures are kept in the heap memory of the PIC® MCU's RAM.

Before graphics objects can be used, you must modify the MPLAB X IDE's project to set up the heap. To determine the specific heap size needed by a graphics application, see the Heap Requirements for Graphics Objects page.

Object Creating Functions

Below is a partial list of the functions used to create objects:

ObjectCreate
Function
Object Unique Input Parameters
ButtonGFX_GOL_ButtonCreate()radius - the roundness of the buttons
Digital MeterGFX_GOL_DigitalMeterCreate()value - initial value
NoOfDigits - number of digits
DotPos - location of decimal point
Scroll BarGFX_GOL_ScrollBarCreate()range - highest possible value
page - incremental value change
pos - initial slider position
Group BoxGFX_GOL_GroupboxCreate()alignment - text alignment designation for the group box
Check BoxGFX_GOL_CheckBoxCreate()n/a

To get a complete list of all Primitive Graphics functions, you can open GFX_help.png help_mlagfx.jar located in ..microchip/mla/vYYYY_MM_DD/doc.

Back to top

Example: Creating a Screen With Two Buttons and a Slider

Project Tree showing desired files

When preparing to use graphic objects in a project, two steps need to be taken:

  • Ensure GFX_GOL.h and GFX_GOL.c are added to the project.
  • Add the source and header file for the particular object in the file. For example: since the steps below show at least one button and one slider, GFX_GOL__Button.c/GFX_GOL_Button.h and GFX_GOL_ScrollBar.c/GFX_GOL_ScrollBar.h need to be added to the project.

When drawn to the screen, the structure created by the function, Create_Screen (below), will display:

Create_Screen function

In the example above, Create_Screen calls several instances of object-creating functions. When an object is created, the creating function returns a pointer to the location in memory where the object has been placed. If for some reason the object is not successfully made, then a NULL is returned. In this example, the function Create_Screen is written to return a "true" if all the objects were successfully created. If any object was not able to be created, then Create_Screen will return a "false."

Learn More

 Back to top