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.
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 the specific objects.
The created data structures are placed in a single linked list. The drawing function (GFX_GOL_ObjectListDraw) reads the objects 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:
| Object | Create Function |
Object Unique Input Parameters |
|---|---|---|
| Button | GFX_GOL_ButtonCreate() | radius - the roundness of the buttons |
| Digital Meter | GFX_GOL_DigitalMeterCreate() | value - initial value NoOfDigits - number of digits DotPos - location of decimal point |
| Scroll Bar | GFX_GOL_ScrollBarCreate() | range - highest possible value page - incremental value change pos - initial slider position |
| Group Box | GFX_GOL_GroupboxCreate() | alignment - text alignment designation for the group box |
| Check Box | GFX_GOL_CheckBoxCreate() | n/a |
help_mlagfx.jar located in ..microchip/mla/vYYYY_MM_DD/doc….Example: Creating a Screen With Two Buttons and a Slider
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:
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."