Creating Graphics Objects

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
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….

Example: Creating a Screen With Two Buttons and a Slider

obj-create-sample.png

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:

firstscreen.png

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."

© 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.