GFX4dESP32

Introduction

The GFX4dESP32 library is provided by 4D Systems for use with gen4-ESP32-XX product series. This library provides users access to the graphics, touch, and Wi-Fi functionalities of 4D Systems' ESP32-S3 display modules.

Note however that some functionalities might not be supported by a certain product types, depending on its specifications. For instance, non-touch variants have no access to all touch-related functions. For more information on the specifications of a product, refer to its datasheet.

To install the library, please refer to the instructions in Workshop4 ESP32 Development Manual.

It is recommended to use Workshop4 IDE to get the most out of the library functions.

Note

Workshop4 is a Windows-only application.

Library Setup

When using Workshop4, the library is automatically included in the code.

To set up the library for use with Arduino IDE or other Arduino-compatible IDEs, the correct header file for the target display must be included and an instance of the library needs to be created.

A sample code should look like this:

#include "gfx4desp32_%%displaynm%%.h"

gfx4desp32_%%displaynm%% gfx = gfx4desp32_%%displaynm%%();

where %%displaynm%%is the name of the target display module with underscores (_) as separators instead of a hyphen (-).

Here's a table listing all the available products and their respective header files.

Product	Header File
gen4-ESP32-24	gfx4desp32_gen4_ESP32_24.h
gen4-ESP32-24CT	gfx4desp32_gen4_ESP32_24CT.h
gen4-ESP32-24CT-CLB	gfx4desp32_gen4_ESP32_24CT-CLB.h
gen4-ESP32-28	gfx4desp32_gen4_ESP32_28.h
gen4-ESP32-28CT	gfx4desp32_gen4_ESP32_28CT.h
gen4-ESP32-28CT-CLB	gfx4desp32_gen4_ESP32_28CT-CLB.h
gen4-ESP32-32	gfx4desp32_gen4_ESP32_32.h
gen4-ESP32-32CT	gfx4desp32_gen4_ESP32_32CT.h
gen4-ESP32-32CT-CLB	gfx4desp32_gen4_ESP32_32CT-CLB.h
gen4-ESP32-35	gfx4desp32_gen4_ESP32_35.h
gen4-ESP32-35CT	gfx4desp32_gen4_ESP32_35CT.h
gen4-ESP32-35CT-CLB	gfx4desp32_gen4_ESP32_35CT-CLB.h
gen4-ESP32-43	gfx4desp32_gen4_ESP32_43.h
gen4-ESP32-43T	gfx4desp32_gen4_ESP32_43T.h
gen4-ESP32-43CT	gfx4desp32_gen4_ESP32_43CT.h
gen4-ESP32-43CT-CLB	gfx4desp32_gen4_ESP32_43CT-CLB.h
gen4-ESP32-50	gfx4desp32_gen4_ESP32_50.h
gen4-ESP32-50T	gfx4desp32_gen4_ESP32_50T.h
gen4-ESP32-50CT	gfx4desp32_gen4_ESP32_50CT.h
gen4-ESP32-50CT-CLB	gfx4desp32_gen4_ESP32_50CT-CLB.h
gen4-ESP32-70	gfx4desp32_gen4_ESP32_70.h
gen4-ESP32-70T	gfx4desp32_gen4_ESP32_70T.h
gen4-ESP32-70CT	gfx4desp32_gen4_ESP32_70CT.h
gen4-ESP32-70CT-CLB	gfx4desp32_gen4_ESP32_70CT-CLB.h
gen4-ESP32Q-43	gfx4desp32_gen4_ESP32Q_43.h
gen4-ESP32Q-43T	gfx4desp32_gen4_ESP32Q_43T.h
gen4-ESP32Q-43CT	gfx4desp32_gen4_ESP32Q_43CT.h
gen4-ESP32Q-43CT-CLB	gfx4desp32_gen4_ESP32Q_43CT-CLB.h
ESP32-90	gfx4desp32_ESP32_90.h
ESP32-90T	gfx4desp32_ESP32_90T.h
ESP32-90CT	gfx4desp32_ESP32_90CT.h
ESP32-90CT-CLB	gfx4desp32_ESP32_90CT-CLB.h

5-inch Resistive Touch Variant Example

#include "gfx4desp32_gen4_ESP32_50T.h"

gfx4desp32_gen4_ESP32_50T gfx = gfx4desp32_gen4_ESP32_50T();

Note

When using Workshop4, a new project will include the snippet of code with %%displaynm%% above. Workshop4 automatically replaces %%displaynm%% with the correct name for the current display selected in the project before the project is compiled.f!!

To start using the created gfx instance, add the line gfx.begin() before using any other library functions.

Common Setup Routine

void setup() {
    gfx.begin(); // Initialize the display
    gfx.Cls();
    gfx.ScrollEnable(true);
    gfx.BacklightOn(true);
    gfx.Orientation(PORTRAIT);
    gfx.SmoothScrollSpeed(5);
    gfx.TextColor(WHITE); gfx.Font(2); gfx.TextSize(1);
}

General and Utility Functions

begin

Initialize the display module and all onboard components.

Syntax: gfx.begin();

Return: None (void)

Example

void setup()
{
    gfx.begin();
    gfx.Cls();
    gfx.ScrollEnable(false);
    gfx.BacklightOn(true);
    gfx.Orientation(LANDSCAPE);
    gfx.SmoothScrollSpeed(5);
    gfx.TextColor(WHITE, BLACK); gfx.Font(2);  gfx.TextSize(1);
    gfx.Open4dGFX("sample");        // Opens DAT/GCI files using filename w/o extension
    gfx.touch_Set(TOUCH_ENABLE);    // Global touch enabled
}

getHeight

Returns the height of the display in pixels at the current orientation

Syntax: gfx.getHeight();

Return: Height of the display in pixels at the current orientation (int16_t)

Example

gfx.Orientation(LANDSCAPE);
int16_t displayHeight = gfx.getHeight();
// Get display height then print its value
gfx.print("Height: "); gfx.println(displayHeight);

getWidth

Returns the width of the display in pixels at the current orientation

Syntax: gfx.getWidth();

Return: Width of the display in pixels at the current orientation (int16_t)

Example

gfx.Orientation(PORTRAIT);
int16_t displayWidth = gfx.getWidth();
// Get display Width then print its value
gfx.print("Width: "); gfx.println(displayWidth);

Transparency

Enables or disables transparent colours.

Syntax: gfx.Transparency(mode);

Argument	Type	Description
mode	boolean	Use true to enable or false to disable transparent colours

Return: None (void)

Example

gfx.TransparentColor(BLACK);
gfx.Transparency(true);     // Enable transparency
gfx.DrawImageFile("sample.gci");
gfx.Transparency(false);

Note

This doesn't apply to pushColors function

TransparentColor

Sets the colour to be treated as transparent when transparency is enabled

Syntax: gfx.TransparentColor(colour);

Argument	Type	Description
colour	uint16_t	RGB565 colour that won't be drawn in all functions when transparency is enabled

Return: None (void)

Example

See gfx.Transparency for an example

Note

This doesn't apply to pushColors function

AlphaBlend

Enables Alpha Blending of new foreground colour to existing background colour

Syntax: gfx.AlphaBlend(mode);

Argument	Type	Description
mode	bool	Specifies whether to enable (true) or disable (false) alpha blending

Return: None (void)

Example

gfx.AlphaBlendLevel(127); // sets level to 127 of 0 to 255
gfx.AlphaBlend(true); // Enable alpha blending
gfx.DrawImageFile("sample.gci");
gfx.AlphaBlend(false);

AlphaBlendLevel

Sets the level of alpha blending between new foreground colour and existing background colour. gfx.AlphaBlend must be used and set to true or ON for this to take effect.

Syntax: gfx.AlphaBlendLevel(value);

Argument	Type	Description
value	uint32_t	Specifies the intensity for alpha blending (0 to 255)

Return: None (void)

Example

See gfx.AlphaBlend for an example

BacklightOn

Turns the backlight ON or OFF.

Syntax: gfx.BacklightOn(mode);

Argument	Type	Description
mode	boolean	Use true to turn ON and false to turn OFF

Return: None (void)

Example

gfx.BacklightOn(false); // Turns the backlight OFF
delay(3000);            // Wait for approx. 3 seconds
gfx.BacklightOn(true);  // Turns the backlight ON

Contrast

Sets the backlight intensity

Syntax: gfx.Contrast(level);

Argument	Type	Description
level	int	0 = backlight is OFF, 1-15 = backlight brightness level

Return: None (void)

Example

for (i = currentLevel; i >= 0; i--) {
    delay(200);         // Slowly dim the backlight
    gfx.Contrast(i);    // until it is off
}

Invert

Inverts the colours displayed on the screen or returns to original.

Syntax: gfx.Invert(mode);

Argument	Type	Description
mode	boolean	Use true to invert display colours and false to display original

Return: None (void)

Example

gfx.RectangleFilled(0, 0, 50, 50, BLACK);
gfx.RectangleFilled(100, 100, 150, 150, BLUE);
delay(2000);
gfx.Invert(true);   // Inverts colours displayed on screen
delay(2000);
gfx.Invert(false);  // Revert back to original colours

Cls

Clear the screen and fill with the specified colour. If no colour value was specified, the function will use BLACK.

This function also brings some settings back to default.

• Cursor position is reset to (0, 0)
• Scroll is set to 0 pixels

Syntax: gfx.Cls([colour]);

Argument	Type	Description
colour (optional)	uint16_t	Specifies the colour to clear the screen with

Return: None (void)

Example

gfx.Cls();      // Clears the screen with BLACK
gfx.Cls(LIME);  // Clears the screen with LIME

FillScreen

Fills the screen with the specified colour.

Syntax: gfx.FillScreen(colour);

Argument	Type	Description
colour	uint16_t	Specifies the colour to fill the screen with

Return: None (void)

Example

gfx.FillScreen(LIME);   // Fills the screen with LIME

Orientation

Get Orientation

Get the current display orientation. See Set Orientation for possible values

Syntax: gfx.Orientation();

Return: Current orientation (uint8_t)

Example

gfx.Orientation(PORTRAIT);
int8_t orientation = gfx.Orientation();
// Get orientation then print its value
gfx.print("Orientation: "); gfx.println(orientation);

Set Orientation

Sets the orientation of the display the mode specified.

Constants	Value
LANDSCAPE	0
LANDSCAPE_R	1
PORTRAIT	2
PORTRAIT_R	3

Syntax: gfx.Orientation(orient);

Argument	Type	Description
orient	uint8_t	Specifies the orientation, refer to table above

Return: None (void)

Example

gfx.Orientation(PORTRAIT);  // Sets Orientation to PORTRAIT

Note

The cursor position is not altered in any way by changing the orientation.

CheckSD

Check if a uSD card is properly mounted to the display module.

If the uSD Card is properly mounted during the execution of gfx.begin(), this function will return true. Otherwise, this will return false.

Syntax: gfx.CheckSD();

Return: true if uSD is properly mounted, false otherwise (boolean)

Example

gfx.begin();
if (!gfx.CheckSD()) {
    gfx.print("uSD Card not mounted.");
    gfx.print("Please insert uSD Card and restart module");
    while(1);
} // Check if the uSD is mounted

Orbit

Calculate the position of the pixel relative to the current cursor position using the given angle and length.

Syntax: gfx.Orbit(angle, length, output);

Argument	Type	Description
angle	int	Angle in degrees relative to the current cursor position
length	int	Pixel distance from current cursor position
output	int *	Pointer to an int array with at least 2 elements for x and y

Return: None (void)

Example

int xy[2];
gfx.MoveTo(gfx.getWidth() / 2, gfx.getHeight() / 2);
gfx.Orbit(135, 50, xy);
gfx.printf("Pixel is in (%d, %d)\n", xy[0], xy[1]);

XYposToDegree

Calculate the angle between the current cursor position and the pixel position specified and return it in degrees.

Syntax: gfx.XYposToDegree(x, y);

Argument	Type	Description
x	int	Horizontal pixel position of the pixel
y	int	Vertical pixel position of the pixel

Return: Angle in degrees relative to current cursor position (int16_t)

Example

int16_t deg = gfx.XYposToDegree(100, 150);
gfx.printf("(100, 150) is at %d degrees from current cursor position\n", deg);

ScreenCapture

Capture and save to uSD an area of the screen and returns true if successful.

The operation can fail under two conditions:

• uSD is not mounted properly
• File with the filename specified already exists

Syntax: gfx.ScreenCapture(x, y, w, h, fname);

Argument	Type	Description
x	int16_t	Top left horizontal position in pixels
y	int16_t	Top left vertical position in pixels
w	int16_t	Width of the capture area in pixels
h	int16_t	Height of the capture area in pixels
fname	String	Filename to save the image with

Return: true if successful, false otherwise (boolean)

Example

gfx.begin();

// draw a few things here...

gfx.ScreenCapture(0, 0, gfx.getWidth(), gfx.getHeight(), "fullpage.bmp");

getSdFatInstance

Returns a reference to the initialized SdFat instance of the uSD. This allows access full access to the mounted uSD card.

Please refer to the SdFat documentation for more information.

Syntax: gfx.getSdFatInstance();

Return: Instance of SdFat (SdFat &)

Example

SdFat& uSD;

void setup()
{
    gfx.begin();
    gfx.Cls();
    gfx.ScrollEnable(false);
    gfx.BacklightOn(true);
    gfx.Orientation(LANDSCAPE);
    gfx.SmoothScrollSpeed(5);
    gfx.TextColor(WHITE, BLACK); gfx.Font(2);  gfx.TextSize(1);
    gfx.Open4dGFX("sample");        // Opens DAT/GCI files using filename w/o extension
    gfx.touch_Set(TOUCH_ENABLE);    // Global touch enabled
    uSD = gfx.getSdFatInstance();

    // use "uSD" as needed here
}

void loop() 
{
    // use "uSD" as needed here
}

Note

Version 1.0.0 of the GFX4dESP32 library depends on SdFat version 2.2.2 or higher.

The library is tested to work specifically with SdFat v2.2.2, therefore using this version is mainly recommended if any issues are encountered with newer versions.

DisplayControl

Executes various display initialization functions as listed:

• DISP_CTRL_RE_INIT
• DISP_CTRL_RESET
• DISP_CTRL_NEW
• DISP_CTRL_INIT
• DISP_CTRL_STOP
• DISP_CTRL_START_TX
• DISP_CTRL_DEL
• DISP_CTRL_START
• DISP_CTRL_FLUSH

Syntax: gfx.DisplayControl(action);

Argument	Type	Description
action	uint8_t	Specifies the initialization function to perform

Return: None (void)

Example

gfx.DisplayControl(DISP_CTRL_RESET);

Clipping

Enables previously defined clipping area.

Syntax: gfx.Clipping(true);

Argument	Type	Description
mode	bool	Specifies whether to enable (true) or disable (false) clipping

Return: None (void)

Example

gfx.Clipping(true);;

ClipWindow

Set clip window specified by the rectangle with diagonal at (x1, y1) to (x2, y2)

Syntax: gfx.ClipWindow(x1, y1, x2, y2);

Argument	Type	Description
x1	int	Horizontal position of first endpoint of one diagonal of the clipping window
y1	int	Vertical position of first endpoint of one diagonal of the clipping window
x2	int	Horizontal position of second endpoint of one diagonal of the clipping window
y2	int	Vertical position of second endpoint of one diagonal of the clipping window

Return: None (void)

Example

gfx.ClipWindow(10, 0, 229, 319);

Primitive Shapes

PutPixel

Writes the pixel colour to the specified position

Syntax: gfx.PutPixel(x, y, colour);

Argument	Type	Description
x	int16_t	Horizontal position in pixels
y	int16_t	Vertical position in pixels
colour	uint16_t	16-bit RGB565 colour to be drawn to the specified position

Return: None (void)

Example

gfx.PutPixel(5, 10, RED); // Draws a RED pixel at (5,10)

PutPixelAlpha

Draws a pixel to the current frame buffer with color parameter switch.

Syntax: gfx.PutPixelAlpha(x, y, colour, alpha);

Argument	Type	Description
x	int	Horizontal position in pixels
y	int	Vertical position in pixels
colour	int32_t	16-bit RGB565 colour, a GCI image, or Framebuffer image to be drawn to the specified position
alpha	uint8_t	Alpha level (0-255)

Return: None (void)

Example

gfx.PutPixelAlpha(10, 10, GCI_IMAGE + 3, 255);           
// draws a pixel at 10, 10
// from GCI image index 3 and full alpha level. x and y are relative to objects x and y.

gfx.PutPixelAlpha(10, 10, FRAMEBUFFER_IMAGE + 3, 127); 
// draws a pixel at 10, 100
// from Framebuffer index 3 with half alpha at the same x and y position.

gfx.PutPixelAlpha(10, 10, RED, 127);                     
// draws a RED pixel at 10, 10
// with half alpha at the same x and y position.

Vline

Draws a vertical line from point (x, y) with length equal to height using the specified colour.

Direction is specified by the sign of height: positive (+) draws downwards and negative (-) draws upwards

Syntax: gfx.Vline(x, y, height, colour);

Argument	Type	Description
x	int16_t	Horizontal position in pixels
y	int16_t	Vertical position in pixels
height	int16_t	Length in pixels and direction of the vertical line
colour	uint16_t	16-bit RGB565 colour of the line

Return: None (void)

Example

gfx.Vline(5,10,100,RED);
// Draws a 100-pixel RED Vline from (5,10) downwards
gfx.Vline(5,10,-100,BLUE);
// Draws a 100-pixel BLUE Vline from (5,10) upwards

Hline

Draws a horizontal line from point (x, y) with length equal to width using the specified colour.

Direction is specified by the sign of width: positive (+) draws to the right and negative (-) draws to the left

Syntax: gfx.Hline(x, y, width, colour);

Argument	Type	Description
x	int16_t	Horizontal position in pixels
y	int16_t	Vertical position in pixels
height	int16_t	Length in pixels and direction of the horizontal line
colour	uint16_t	16-bit RGB565 colour of the line

Return: None (void)

Example

gfx.Hline(5,10,100,RED);
// Draws a 100-pixel RED Hline from (5,10) to the right
gfx.Hline(5,10,-100,BLUE);
// Draws a 100-pixel BLUE Hline from (5,10) to the left

VlineD

Draws a vertical line from point (x, y1) to (x, y2) using the specified colour.

Syntax: gfx.VlineD(x, y1, y2, colour);

Argument	Type	Description
x	int	Horizontal position in pixels
y1	int	Vertical position in pixels of first endpoint
y2	int	Vertical position in pixels of second endpoint
colour	int	16-bit RGB565 colour of the line

Return: None (void)

Example

gfx.VlineD(5,10,100,RED);
// Draws a vertical RED line from (5,10) to (5, 100)

HlineD

Draws a horizontal line from point (x1, y) to point (x2, y) using the specified colour.

Syntax: gfx.HlineD(y, x1, x2, colour);

Argument	Type	Description
y	int	Vertical position in pixels
x1	int	Horizontal position in pixels of first endpoint
x1	int	Horizontal position in pixels of second endpoint
colour	int	16-bit RGB565 colour of the line

Return: None (void)

Example

gfx.HlineD(10, 5, 100, RED);
// Draws a horizontal RED line from (5, 10) to (100, 10)

VlineX

Draws a vertical line from point (x, y) with length equal to height using the specified colour, source GCI image, or source framebuffer.

Direction is specified by the sign of height: positive (+) draws downwards and negative (-) draws upwards

Syntax: gfx.Vline(x, y, height, colour);

Argument	Type	Description
x	int	Horizontal position in pixels
y	int	Vertical position in pixels
height	int	Length in pixels and direction of the vertical line
colour	int32_t	16-bit RGB565 colour, source GCI image, or source framebuffer.

Return: None (void)

Example

gfx.VlineX(10, 10, 100, GCI_IMAGE + 3);
// draws a vertical line at 10, 10 and a length of 100 pixels
// from GCI image index 3. x and y are relative to objects x and y.

gfx.VlineX(10, 10, 100, FRAMEBUFFER_IMAGE + 3);
// draws a vertical line at 10, 10 and a length of 100 pixels
// from framebuffer index 3 at the same x and y position.

HlineX

Draws a horizontal line from point (x, y) with length equal to width using the specified colour, source GCI image, or source framebuffer.

Direction is specified by the sign of width: positive (+) draws to the right and negative (-) draws to the left

Syntax: gfx.HlineX(x, y, width, colour);

Argument	Type	Description
x	int	Horizontal position in pixels
y	int	Vertical position in pixels
height	int	Length in pixels and direction of the horizontal line
colour	int32_t	16-bit RGB565 colour, source GCI image, or source framebuffer.

Return: None (void)

Example

gfx.HlineX(10, 10, 100, GCI_IMAGE + 3);
// draws a horizontal line at 10, 10 and a length of 100 pixels
// from GCI image index 3. x and y are relative to objects x and y.

gfx.HlineX(10, 10, 100, FRAMEBUFFER_IMAGE + 3);
// draws a horizontal line at 10, 10 and a length of 100 pixels
// Draws a 100-pixel BLUE Hline from (5,10) to the left

Line

Draws a line from point (x0, y0) to point (x1, y1) using the specified colour.

Syntax: gfx.Line(x0, y0, x1, y1, colour);

Argument	Type	Description
x0	int16_t	Horizontal position of starting point in pixels
y0	int16_t	Vertical position of starting point in pixels
x1	int16_t	Horizontal position of endpoint in pixels
y1	int16_t	Vertical position of endpoint in pixels
colour	uint16_t	16-bit RGB565 colour of the line

Return: None (void)

Example

gfx.Line(0,0,50,50,RED);
// Draws a RED line from (0,0) to (50,50)

LineAA

Draws a smooth line from point (x0, y0) to point (x1, y1) using the specified colour and width w

Syntax: gfx.LineAA(x0, y0, x1, y1, w, colour);

Argument	Type	Description
x0	float	Horizontal position of starting point in pixels
y0	float	Vertical position of starting point in pixels
x1	float	Horizontal position of endpoint in pixels
y1	float	Vertical position of endpoint in pixels
w	float	Line width
colour	int32_t	16-bit RGB565 colour of the line, GCI image index, or Framebuffer index

Return: None (void)

Example

gfx.LineAA(0, 0, 50, 50, 3, RED);
// Draws a RED line from (0,0) to (50,50) with thickness 3

RectangleFilled

Draws a solid rectangle having a diagonal with endpoints at (x1, y1) and (x2, y2).

Syntax: gfx.RectangleFilled(x1, y1, x2, y2, colour);

Argument	Type	Description
x1	int	Horizontal position of first endpoint of one diagonal of the rectangle
y1	int	Vertical position of first endpoint of one diagonal of the rectangle
x2	int	Horizontal position of second endpoint of one diagonal of the rectangle
y2	int	Vertical position of second endpoint of one diagonal of the rectangle
colour	uint16_t	16-bit RGB565 colour of the solid rectangle

Return: None (void)

Example

gfx.RectangleFilled(0, 0, 50, 50, YELLOW);
// Draws a YELLOW solid rectangle with:
// a diagonal whose end points are (0, 0) and (50, 50)

RectangleFilledX

Draws a rectangle to the current frame buffer having a diagonal with endpoints at (x1, y1) and (x2, y2) with color parameter switch

Syntax: gfx.RectangleFilledX(x1, y1, x2, y2, colour);

Argument	Type	Description
x1	int	Horizontal position of first endpoint of one diagonal of the rectangle
y1	int	Vertical position of first endpoint of one diagonal of the rectangle
x2	int	Horizontal position of second endpoint of one diagonal of the rectangle
y2	int	Vertical position of second endpoint of one diagonal of the rectangle
colour	int32_t	16-bit RGB565 colour, GCI image index, or Framebuffer index to draw in the rectangular region

Return: None (void)

Example

gfx.RectangleFilledX(0, 0, 50, 50, YELLOW);
// Draws a YELLOW solid rectangle
// with a diagonalwhose end points are (0, 0) and (50, 50)

gfx.RectangleFilledX(10, 10, 100, 100, GCI_IMAGE + 3); 
// Draws a rectangle at (10, 10) from GCI image index 3,
// x and y are relative to objects x and y.

gfx.RectangleFilledX(10, 10, 100, 100, FRAMEBUFFER_IMAGE + 3); 
// Draws a rectangle at (10, 10) from framebuffer 3
// at the same x and y position.

Rectangle

Draws an outlined rectangle having a diagonal with endpoints at (x1, y1) and (x2, y2).

Syntax: gfx.Rectangle(x1, y1, x2, y2, colour);

Argument	Type	Description
x1	int16_t	Horizontal position of first endpoint of one diagonal of the rectangle
y1	int16_t	Vertical position of first endpoint of one diagonal of the rectangle
x2	int16_t	Horizontal position of second endpoint of one diagonal of the rectangle
y2	int16_t	Vertical position of second endpoint of one diagonal of the rectangle
colour	uint16_t	16-bit RGB565 colour of the outlined rectangle

Return: None (void)

Example

gfx.Rectangle(0, 0, 50, 50, CYAN);
// Draws a CYAN rectangle with:
// a diagonal whose end points are (0, 0) and (50, 50) 

CircleFilled

Draws a solid-coloured circle with the specified radius and colour with the center at (x, y)

Syntax: gfx.CircleFilled(x, y, r, colour);

Argument	Type	Description
x	int16_t	Horizontal position of the centre of the circle
y	int16_t	Vertical position of the centre of the circle
r	int16_t	Radius of the filled circle in pixels
colour	uint16_t	16-bit RGB565 colour of the filled circle

Return: None (void)

Example

gfx.CircleFilled(50, 50, 10, RED);
// Draws a RED filled circle with:
// radius of 10 and center @(50, 50)

CircleFilledAA

Draws a smooth filled circle with the specified radius and colour with the center at (x, y)

Syntax: gfx.CircleFilledAA(x, y, r, colour);

Argument	Type	Description
x	float	Horizontal position of the centre of the circle
y	float	Vertical position of the centre of the circle
r	float	Radius of the filled circle in pixels
colour	int32_t	16-bit RGB565 colour of the filled circle, GCI image index, or Framebuffer index

Return: None (void)

Example

gfx.CircleFilledAA(50.0, 50.0, 10.0, RED);
// Draws a RED filled circle with:
// radius of 10 and center @(50, 50)

Circle

Draws an outlined circle with the specified radius and colour with the center at (x, y)

Syntax: gfx.Circle(x, y, r, colour);

Argument	Type	Description
x	int16_t	Horizontal position of the centre of the circle
y	int16_t	Vertical position of the centre of the circle
r	int16_t	Radius of the outlined circle in pixels
colour	uint16_t	16-bit RGB565 colour of the filled circle

Return: None (void)

Example

gfx.Circle(50, 50, 10, RED);
// Draws a RED circle w/ radius of 10 and center at (50, 50)

EllipseFilled

Draws a solid coloured ellipse with the specified x radius (radx), y radius (rady), and colour with the center at (x, y)

Syntax: gfx.EllipseFilled(x, y, radx, rady, colour);

Argument	Type	Description
x	int16_t	Horizontal position of the centre of the ellipse
y	int16_t	Vertical position of the centre of the ellipse
radx	int16_t	Radius of the ellipse along the x-axis
rady	int16_t	Radius of the ellipse along the y-axis
colour	uint16_t	16-bit RGB565 colour of the filled ellipse

Return: None (void)

Example

gfx.EllipseFilled(50, 50, 10, 5, RED);
// Draws a RED filled ellipse with:
// x-radius of 10, y-radius of 5 and center @(50, 50)

Ellipse

Draws an outlined ellipse with the specified x radius (radx), y radius (rady), and colour with the center at (x, y)

Syntax: gfx.Ellipse(x, y, radx, rady, colour);

Argument	Type	Description
x	int16_t	Horizontal position of the centre of the ellipse
y	int16_t	Vertical position of the centre of the ellipse
radx	int16_t	Radius of the ellipse along the x-axis
rady	int16_t	Radius of the ellipse along the y-axis
colour	uint16_t	16-bit RGB565 colour of the outlined ellipse

Return: None (void)

Example

gfx.Ellipse(50, 50, 10, 5, RED);
// Draws a RED ellipse with:
// x-radius of 10, y-radius of 5 and center @(50, 50)

ArcFilled

Draw 90-degree Arcs with center at (x, y) and gap between left and right parts. This is a support function used for filled rounded rectangles and circles.

Syntax: gfx.ArcFilled(x, y, r, topBottom, gap, colour);

Argument	Type	Description
x	int16_t	Horizontal position of the centre of the arc
y	int16_t	Vertical position of the centre of the arc
r	int16_t	Radius in pixels of the filled arc
topBottom	int16_t	Indicates whether to draw the top arcs (1), bottom arcs (2) or both sets (3)
gap	int16_t	Indicates the gap between the left and right arcs
colour	uint16_t	16-bit RGB565 colour of the filled arc

Return: None (void)

Example

gfx.ArcFilled(100, 100, 50, 3, 0, RED);

Arc

Draw 90-degree Arcs with center at (x, y) for the selected quadrants This is a support function used for outlined rounded rectangles and circles.

Multiple quadrants can be selected by setting the following bits for the value of quadrants:

• 0x01 - Top left
• 0x02 - Top right
• 0x04 - Bottom right
• 0x08 - Bottom left

Syntax: gfx.Arc(x, y, r, quadrants, colour);

Argument	Type	Description
x	int16_t	Horizontal position of the centre of the arc
y	int16_t	Vertical position of the centre of the arc
r	int16_t	Radius in pixels of the outlined arc
quadrants	uint16_t	The selected quadrants
colour	uint16_t	16-bit RGB565 colour of the outlined arc

Return: None (void)

Example

gfx.Arc(100, 100, 50, 0x8 | 0x4, RED);
// Draw the bottom left and bottom right arcs with
// center at (100, 100), a radius of 50 pixels

RoundRectFilled

Draws a solid round-cornered rectangle having an outer rectangle diagonal with endpoints at (x, y) and (x1, y1) and with a corner radius of r.

Syntax: gfx.RoundRectFilled(x, y, x1, y1, r, colour);

Argument	Type	Description
x	int16_t	Horizontal position of first endpoint of one diagonal of the outer rectangle
y	int16_t	Vertical position of first endpoint of one diagonal of the outer rectangle
x1	int16_t	Horizontal position of second endpoint of one diagonal of the outer rectangle
y1	int16_t	Vertical position of second endpoint of one diagonal of the outer rectangle
r	int16_t	Corner radius. This is the distance in pixels extending from the corners of the inner rectangle.
colour	uint16_t	16-bit RGB565 colour of the filled rounded rectangle

Return: None (void)

Example

gfx.RoundRectFilled(0, 0, 50, 50, 10, RED);
// Draws a solid RED round-cornered rectangle with:
// a diagonal whose end points are (0, 0) and (50, 50)
// and with a corner radius of 10

RoundRect

Draws an outlined round-cornered rectangle having an outer rectangle diagonal with endpoints at (x, y) and (x1, y1) and with a corner radius of r.

Syntax: gfx.RoundRect(x, y, x1, y1, r, colour);

Argument	Type	Description
x0	int16_t	Horizontal position of first endpoint of one diagonal of the outer rectangle
y0	int16_t	Vertical position of first endpoint of one diagonal of the outer rectangle
x1	int16_t	Horizontal position of second endpoint of one diagonal of the outer rectangle
y1	int16_t	Vertical position of second endpoint of one diagonal of the outer rectangle
r	int16_t	Corner radius. This is the distance in pixels extending from the corners of the inner rectangle.
colour	uint16_t	16-bit RGB565 colour of the outlined rounded rectangle

Return: None (void)

Example

gfx.RoundRect(0,0,50,50,10,GREEN);
// Draws a GREEN round-cornered rectangle with:
// a diagonal whose end points are (0,0) and (50,50) // and corner radius of 10

TriangleFilled

Draws a solid triangle between vertices (x1, y1), (x2, y2) and (x3, y3) using the specified colour c.

Syntax: gfx.TriangleFilled(x1, y1, x2, y2, x3, y3, c);

Argument	Type	Description
x1	int16_t	Horizontal position of first vertex of the triangle
y1	int16_t	Vertical position of first vertex of the triangle
x2	int16_t	Horizontal position of second vertex of the triangle
y2	int16_t	Vertical position of second vertex of the triangle
x3	int16_t	Horizontal position of third vertex of the triangle
y3	int16_t	Vertical position of third vertex of the triangle
c	uint16_t	16-bit RGB565 colour of the filled triangle

Return: None (void)

Example

gfx.TriangleFilled(0, 0, 10, 50, 50, 50, CYAN);
// Draws a solid CYAN triangle with:
// the vertices (0, 0), (10, 50), and (50, 50)

Triangle

Draws a triangle outline between vertices (x0, y0), (x1, y1), and (x2, y2) using the specified colour c.

Syntax: gfx.Triangle(x0, y0, x1, y1, x2, y2, c);

Argument	Type	Description
x0	int16_t	Horizontal position of first vertex of the triangle
y0	int16_t	Vertical position of first vertex of the triangle
x1	int16_t	Horizontal position of second vertex of the triangle
y1	int16_t	Vertical position of second vertex of the triangle
x2	int16_t	Horizontal position of third vertex of the triangle
y2	int16_t	Vertical position of third vertex of the triangle
c	uint16_t	16-bit RGB565 colour of the outlined triangle

Return: None (void)

Example

gfx.Triangle(0, 0, 10, 50, 50, 50, CYAN);
// Draws a CYAN triangle with:
// the vertices (0, 0), (10, 50), and (50, 50)

TriangleAA

Draws a smooth triangle outline between vertices (x0, y0), (x1, y1), and (x2, y2) using the specified colour c and line width w.

Syntax: gfx.TriangleAA(x0, y0, x1, y1, x2, y2, w, c);

Argument	Type	Description
x0	float	Horizontal position of first vertex of the triangle
y0	float	Vertical position of first vertex of the triangle
x1	float	Horizontal position of second vertex of the triangle
y1	float	Vertical position of second vertex of the triangle
x2	float	Horizontal position of third vertex of the triangle
y2	float	Vertical position of third vertex of the triangle
w	int	Line width
c	int32_t	16-bit RGB565 colour of the outlined triangle, GCI image index, or Framebuffer index

Return: None (void)

Example

gfx.TriangleAA(0, 0, 10, 50, 50, 50, 2, CYAN);
// Draws a CYAN triangle with:
// the vertices (0, 0), (10, 50), and (50, 50)
// with line width 2

GradTriangleFilled

Produce a triangle with or without a gradient

Syntax: gfx.GradTriangleFilled(x0, y0, x1, y1, x2, y2, colour, ncCol, h, ypos, lev, erase);

Argument	Type	Description
x0	int	Horizontal position of first vertex of the triangle
y0	int	Vertical position of first vertex of the triangle
x1	int	Horizontal position of second vertex of the triangle
y1	int	Vertical position of second vertex of the triangle
x2	int	Horizontal position of third vertex of the triangle
y2	int	Vertical position of third vertex of the triangle
colour	int	Colour that will be used if the Solid or Gradient parameter is set to 0
ncCol	int	Colour that will be used if the Solid or Gradient parameter is set to 1
h	int	Height of the area that the gradient will be calculated. Can be larger than the triangle
ypos	int	Position on the Y axis that the gradient will be calculated from with respect to triangle position
lev	int	Level of gradient applied
erase	int	Select whether solid triangle or gardient triangle is drawn

Return: None (void)

Example

gfx.GradTriangleFilled(10, 10, 10, 100, 100, 100, YELLOW, DARKKHAKI, 100, 10, 30, 1);

gradientShape

Produce a shaped color gradient using the supplied parameters

Syntax: gfx.gradientShape(vert, ow, xPos, yPos, w, h, r1, r2, r3, r4, darken, color, sr1, gl1, colorD, sr3, gl3, gtb);

Argument	Type	Description
vert	int	Horizontal or Vertical gradient -- 0 or 1
ow	int	Outer gradient width
ow	int	Outer gradient width
xPos	int	x co-ordinate
yPos	int	y co-ordinate
w	int	Width
h	int	Height
r1	int	Top left corner radius
r2	int	Top right corner radius
r3	int	Bottom left radius
r4	int	Bottom right radius
darken	int	Darken both colours by a value. Can be a negative to lighten instead
color	int	Outer Gradient colour
sr1	int	Outer Gradient type (0 - 3 horizontal, +4 vertical)  0 - Raised  1 - Sunken  2 - Raised flatter middle  3 - Sunken flatter middle
gl1	int	Outer Gradient level 0 - 63
colorD	int	Inner Gradient colour
sr3	int	Outer Gradient type (0 - 3 horizontal, +4 vertical)  0 - Raised  1 - Sunken  2 - Raised flatter middle  3 - Sunken flatter middle
gl3	int	Inner Gradient level 0 - 63
gtb	int	Split gradient

Return: None (void)

Example

gfx.gradientShape(HorzVert, OuterWidth, X, Y, W, H, TLrad, TRrad, BLrad, BRrad,
    Darken, OuterColor, OuterType, OuterLevel,
    InnerColor, InnerType, InnerLevel, Split);

Primitive Widgets

Panel

Draws a raised 3-dimensional rectangular panel at a screen location defined by x and y parameters (top left corner). The size of the panel is set with the w and h parameters. The colour is defined by colour c

Syntax: gfx.Panel(x, y, w, h, c);

Argument	Type	Description
x	int16_t	Horizontal position of the top left pixel of the panel
y	int16_t	Vertical position of the top left pixel of the panel
w	int16_t	Horizontal position of second endpoint of one diagonal of the panel
h	int16_t	Vertical position of second endpoint of one diagonal of the panel
c	uint16_t	16-bit RGB565 colour of the panel

Return: None (void)

Example

gfx.Panel(0, 0, 100, 50, GRAY);
// Draws a 100x50 GRAY raised panel @(0, 0) 

PanelRecessed

Draw recessed Panel at (x, y), with dimensions w and h and colour c.

Syntax: gfx.Panel(x, y, w, h, c);

Argument	Type	Description
x	int16_t	Left most pixel position of the panel
y	int16_t	Vertical position of first endpoint of one diagonal of the panel
w	int16_t	Horizontal position of second endpoint of one diagonal of the panel
h	int16_t	Vertical position of second endpoint of one diagonal of the panel
c	uint16_t	16-bit RGB565 colour of the panel

Return: None (void)

Example

gfx.PanelRecessed(0, 0, 100, 50, GRAY);
// Draws a 100x50 GRAY recessed panel @(0, 0) 

ButtonXstyle

Sets the style of primitive buttons with the following defined styles

• BUTTON_SQUARE
• BUTTON_ROUNDED
• BUTTON_CIRCULAR
• BUTTON_CIRCULAR_TOP

Syntax: gfx.ButtonXstyle(style);

Argument	Type	Description
style	byte	Selected button style

Return: None (void)

Example

gfx.ButtonXstyle(BUTTON_ROUNDED);

drawButton

This function draws a button at the specified state using the size, color and text parameters provided. This is a support function for ButtonX functions.

Syntax: gfx.drawButton(updn, x, y, w, h, colourb, btext, tfont, tfontsize, tfontsizeht, tcolour [, compressed]);

Argument	Type	Description
updn	uint8_t	State of the button
x	int16_t	Horizontal pixel position of the left side of the button
y	int16_t	Vertical pixel position of the top side of the button
w	int16_t	Width of the button in pixels
h	int16_t	Height of the button in pixels
colourb	uint16_t	Button colour
btext	String	Button text
tfont	uint8_t const uint8_t * gfx4d_font	Button text font
tfontsize	int8_t	Font size multiplier
tfontsizeht	int8_t
tcolour	uint16_t	Button text colour
compressed (optional)	bool	Only used when using font array (const uint8_t *), specifies whether the font array is compressed or GCI formatted

Return: None (void)

Example

gfx.drawButton(1, 50, 50, 150, 50, GRAY, "START", FONT2, 1, 1, BLACK);

Slider

Draws a slider with diagonal at (x1, y1) and (x2, y2). The thumb will be drawn depending on the specified scale and value.

Syntax: gfx.Slider(state, x1, y1, x2, y2, colourb, colourt, scale, value);

Argument	Type	Description
state	uint8_t	State of the slider
x1	int16_t	Horizontal pixel position of the left side of the slider
y1	int16_t	Vertical pixel position of the top side of the slider
x2	int16_t	Horizontal pixel position of the right side of the slider
y2	int16_t	Vertical pixel position of the bottom side of the slider
colourb	uint16_t	Base colour
colourt	uint16_t	Thumb colour
scale	int16_t	Maximum value of the slider
value	int16_t	Value of the slider

Return: None (void)

Example

gfx.Slider(state, x1, y1, x2, y2, colourb, colourt, scale, value);

Note

x2 ad y2 should be greater than x1 and y1 respectively

Button

Draws a 3-dimensional Text Button at screen location defined by (x, y).

The font to be used can be system font, GCI font (opened using gfx.Open4dFont) or font array. When using font array, an optional parameter can be specified to indicate whether the format is compressed or GCI formatted.

Syntax: gfx.Button(state, x, y, colorb, tcolor, tfont, tfontsizeh, tfontsize, btext [, compressed]);

Argument	Type	Description
state	uint8_t	State of the button
x	int16_t	Horizontal pixel position of the left side of the button
y	int16_t	Vertical pixel position of the top side of the button
colorb	uint16_t	Button colour
tcolor	uint16_t	Text colour
tfont	uint8_t const uint8_t * gfx4d_font	Button text font
tfontsizeh	int8_t	Font height multiplier
tfontsize	int8_t	Font width multiplier
btext	String	Button text
compressed (optional)	bool	Only used when using font array (const uint8_t *), specifies whether the font array is compressed or GCI formatted

Return: None (void)

Example

gfx.Button(state, x, y, colorb, tcolor, tfont, tfontsizeh, tfontsize, btext, compressed);

Buttonx

Draws a 3-dimensional Text Button at screen location defined by (x, y) parameters The user needs to specify a handler for the button that will be used by the functions:

• ButtonUp
• ButtonDown
• ButtonActive
• DeleteButton
• CheckButtons

The font to be used can be system font, GCI font (opened using gfx.Open4dFont) or font array. When using font array, an optional parameter can be specified to indicate whether the format is compressed or GCI formatted.

Syntax: gfx.Buttonx(hndl, x, y, w, h, colorb, btext, tfont, tcolor [, compressed]);

Argument	Type	Description
hndl	uint8_t	ID specified to identify the button
x	int16_t	Horizontal pixel position of the left side of the button
y	int16_t	Vertical pixel position of the top side of the button
w	int16_t	Width of the button in pixels
h	int16_t	Height of the button in pixels
colorb	uint16_t	Button colour
btext	String	Button text
tfont	uint8_t const uint8_t * gfx4d_font	Button text font
tcolor	uint16_t	Text colour
compressed (optional)	bool	Only used when using font array (const uint8_t *), specifies whether the font array is compressed or GCI formatted

Return: None (void)

Example

gfx.Buttonx(hndl, x, y, w, h, colorb, btext, tfont, tcolor, compressed);

ButtonActive

Enable/disable the specified button.

Syntax: gfx.ButtonActive(id, mode);

Argument	Type	Description
id	uint8_t	ID specified using gfx.Buttonx to identify the button
mode	boolean	Indicates whether to activate (true) or deactivate (false) a buttonx

Return: None (void)

Example

gfx.ButtonActive(1, true);

DeleteButton

Delete previously created primitive button n and, optionally, redraw background in colour bc.

Syntax: gfx.DeleteButton(hndl, bc);

Argument	Type	Description
id	uint8_t	ID specified using gfx.Buttonx to identify the button
bc (optional)	uint16_t	Optional background color to redraw when deleting button

Return: None (void)

Example

gfx.DeleteButton(2);
gfx.DeleteButton(3, BLACK);

DeleteButtonBG

Delete previously created primitive button n and redraw section of background image bg.

Syntax: gfx.DeleteButtonBG(id, bg);

Argument	Type	Description
id	uint8_t	ID specified using gfx.Buttonx to identify the button
bg	uint16_t	Background image to redraw

Return: None (void)

Example

gfx.DeleteButton(3, iForm0);

Support Colour Functions

bevelColor

Returns a darker and lighter colour of the given colour (colorb) by a set 18 steps.

The darker color is stored in the high word of the return value while the lighter color is stored in the low word.

Syntax: gfx.bevelColor(colorb);

Argument	Type	Description
colorb	uint16_t	Color to process into darker and lighter shades

Return: Combined darkened and lightened color (uint32_t)

Example

uint32_t output = gfx.bevelColor(0x8787);
uint16_t darkColor = output >> 16;
uint16_t lightColor = output & 0xFFFF;

HighlightColors

Returns a darker and lighter colour of the given colour (colorh) by the given steps

The darker color is stored in the high word of the return value while the lighter color is stored in the low word.

Syntax: gfx.HighlightColors(colorh, step);

Argument	Type	Description
colorh	uint16_t	Color to process into darker and lighter shades
step	int	Number of steps to darken/lighten the original color

Return: Combined darkened and lightened color (uint32_t)

Example

uint32_t output = gfx.HighlightColors(0x8787, 15);
uint16_t darkColor = output >> 16;
uint16_t lightColor = output & 0xFFFF;

RGBto565

Converts red green and blue colour elements to RGB565 16bit colour value

Syntax: gfx.RGBto565(rc, gc, bc);

Argument	Type	Description
r	uint8_t	8-bit red component
g	uint8_t	8-bit green component
b	uint8_t	8-bit blue component

Return: 16-bit RGB565 color (uint16_t)

Example

uint16_t color = gfx.RGBto565(255, 0, 100);

RGBs2COL

Converts RGB888 to 16-bit RGB565 value

This function is provided for compatibility with gen4-IoD projects.

Syntax: gfx.RGBs2COL(r, g, b);

Argument	Type	Description
r	uint8_t	8-bit red component
g	uint8_t	8-bit green component
b	uint8_t	8-bit blue component

Return: 16-bit RGB565 color (uint16_t)

Example

uint16_t color = gfx.RGBs2COL(255, 0, 100);

Text Functions

write

The GFX4dESP32 class inherits Arduino's Print class by overriding this function.

This function can be used directly or simply use any print functions from the Print class such as print, println and printf

Syntax: gfx.write(c);

Argument	Type	Description
c	uint8_t	8-bit character to process/write to the display

Return: Number of characters written (size_t)

Example

void setup() {
    gfx.begin(); // Initialize the display
    gfx.Cls();
    gfx.ScrollEnable(true);
    gfx.BacklightOn(true);
    gfx.Orientation(PORTRAIT);
    gfx.SmoothScrollSpeed(5);
    gfx.TextColor(WHITE); gfx.Font(2); gfx.TextSize(1);

    gfx.write('4'); gfx.write('D');
    gfx.println(" Systems");
}

print

The GFX4dESP32 class inherits Arduino's Print class by overriding write(c). This provides access to all functions from this parent class which is commonly used when using Serial.

Syntax: gfx.print(value [, format]);

Argument	Type	Description
value	any	The value to print
format (optional)	int	Specifies the number base (for intergral data types) or number of decimal places (for floating point types)

Return: Number of characters written (size_t)

Example

AutoformatSpecify Format

gfx.print(78);              // gives "78"
gfx.print(1.23456);         // gives "1.23"
gfx.print('N');             // gives "N"
gfx.print("Hello world.");  // gives "Hello world."

gfx.print(78, BIN);         // gives "1001110"
gfx.print(78, OCT);         // gives "116"
gfx.print(78, DEC);         // gives "78"
gfx.print(78, HEX);         // gives "4E"
gfx.print(1.23456, 0);      // gives "1"
gfx.print(1.23456, 2);      // gives "1.23"
gfx.print(1.23456, 4);      // gives "1.2346"

Note

For more information, please refer to Arduino documentation.

println

The GFX4dESP32 class inherits Arduino's Print class by overriding write(c). This provides access to all functions from this parent class which is commonly used when using Serial.

The println function is very similar to print and simply adds carriage return '\r' and a line feed character '\n' at the end.

Syntax: gfx.println(value [, format]);

Argument	Type	Description
value	any	The value to print
format (optional)	int	Specifies the number base (for intergral data types) or number of decimal places (for floating point types)

Return: Number of characters written (size_t)

Example

AutoformatSpecify Format

gfx.println(78);              // gives "78\r\n"
gfx.println(1.23456);         // gives "1.23\r\n"
gfx.println('N');             // gives "N\r\n"
gfx.println("Hello world.");  // gives "Hello world.\r\n"

gfx.println(78, BIN);         // gives "1001110\r\n"
gfx.println(78, OCT);         // gives "116\r\n"
gfx.println(78, DEC);         // gives "78\r\n"
gfx.println(78, HEX);         // gives "4E\r\n"
gfx.println(1.23456, 0);      // gives "1\r\n"
gfx.println(1.23456, 2);      // gives "1.23\r\n"
gfx.println(1.23456, 4);      // gives "1.2346\r\n"

Note

For more information, please refer to Arduino documentation.

printf

The GFX4dESP32 class inherits Arduino's Print class by overriding write(c). This provides access to all functions from this parent class which is commonly used when using Serial.

The printf function takes a format string as its first argument, followed by optional additional arguments that correspond to the placeholders in the format string. These placeholders are denoted by % followed by a format specifier, such as %d for integers, %f for floating-point numbers, %s for strings, and more.

Syntax: gfx.println(value [, format]);

Argument	Type	Description
format	const char *	The base string format to use when printing
...	any / multiple	Multiple additional values that should be formatted according to the format string

Return: Number of characters written (size_t)

Example

gfx.printf("Slider Value: %d\r\n", sliderVal);

MoveTo

Moves the cursor to the new position specified by (x, y).

Syntax: gfx.MoveTo(x, y);

Argument	Type	Description
x	int16_t	Horizontal pixel position of the print cursor
y	int16_t	Vertical pixel position of the print cursor

Return: None (void)

Example

gfx.MoveTo(50, 30);
int16_t CursorX = gfx.getX();
int16_t CursorY = gfx.getY();

// Get cursor X and Y positions then print their values
gfx.print("X-Position: "); gfx.println(CursorX);
gfx.print("Y-Position: "); gfx.println(CursorY);

getX

Returns the current position of the cursor in the X-axis

Syntax: gfx.getX();

Return: Current cursor position in X-axis (int16_t)

Example

gfx.MoveTo(50, 30);
int16_t CursorX = gfx.getX();

// Get cursor X position then print its value
gfx.print("X-Position: "); gfx.println(CursorX);

getY

Returns the current position of the cursor in the Y-axis

Syntax: gfx.getY();

Return: Current cursor position in Y-axis (int16_t)

Example

gfx.MoveTo(50, 30);
int16_t CursorY = gfx.getY();

// Get cursor Y position then print its value
gfx.print("Y-Position: "); gfx.println(CursorY);

Font

Get Font

Get the currently set font type or internal/system font.

Possible return values are:

Value	Description
2	System Font 2
1	System Font 1
0	Font file in uSD, opened using Open4dFont
-1	Font array in program space

Syntax: gfx.Font();

Return: Font type (int8_t)

Example

gfx.Font(FONT2); // Sets FONT2 as font to be used for printing text

int8_t fontID = gfx.Font(); // Get current font then print its value
gfx.print("Current Font: "); gfx.println(fontID);

Set System Font

Sets a system font to use for printing text.

Constants	Value
FONT1	1
FONT2	2

Syntax: gfx.Font(f);

Argument	Type	Description
f	uint8_t	System font to use when printing text

Return: None (void)

Example

gfx.Font(FONT2); // Sets FONT2 as font to be used for printing text

Set Font File

Sets a GCI/IFont file in the uSD as font to use for printing text.

Syntax: gfx.Font(f);

Argument	Type	Description
f	gfx4d_font	Font opened using Open4dFont

Return: None (void)

Example

gfx4d_font arial = gfx.Open4dFont("Arial.IFont");
gfx.Font(arial);
// Sets "Arial.IFont" as font to be used for printing text

Set Font Array

Sets a byte array to use as font for printing text.

Syntax: gfx.Font(f [, compressed]);

Argument	Type	Description
f	const uint8_t	Byte array containing font data in the GCI/IFont format of WS4's compressed font format
compressed (optional)	boolean	Specifies whether the data is compressed or following the original GCI/IFont format, default: false

Return: None (void)

Example

const uint8_t sample_data[BYTE_COUNT] = {
    // ... font data here
};

void setup() {
    gfx.begin(); // Initialize the display
    gfx.Cls();
    gfx.ScrollEnable(true);
    gfx.BacklightOn(true);
    gfx.Orientation(PORTRAIT);
    gfx.SmoothScrollSpeed(5);
    gfx.TextColor(WHITE);
    gfx.Font(sample_data, true); 
    gfx.TextSize(1);
}

TextSize

Sets the text width and height multiplier. Text will be printed magnified horizontally and vertically by this factor.

Syntax: gfx.TextSize(s);

Argument	Type	Description
s	uint8_t	Specifies the text width and height multiplier

Return: None (void)

Example

gfx.TextSize(1);
// Sets the current text width and height multiplier to 1

TextColor

Sets the text foreground and background colour for printing text.

If background colour is not specified, this function will treat it as transparent.

Syntax: gfx.TextColor(c [, b]);

Argument	Type	Description
c	uint16_t	Specifies the text foreground colour
b (optional)	uint16_t	Specifies the text background colour

Return: None (void)

Example

gfx.TextColor(WHITE);
// sets the text foreground colour to WHITE

gfx.TextColor(WHITE, BLACK);
// sets the text foreground colour to WHITE
// and the text background colour to BLACK

BGcolour

Set text background colour

Syntax: gfx.BGcolour(c);

Argument	Type	Description
c	uint16_t	Specifies the text background colour

Return: None (void)

Example

gfx.BGcolour(BLACK);
// sets the text background colour to BLACK

FGcolour

Set text foreground colour

Syntax: gfx.FGcolour(c);

Argument	Type	Description
c	uint16_t	Specifies the text foreground colour

Return: None (void)

Example

gfx.FGcolour(WHITE);
// sets the text foreground colour to WHITE

TextWrap

Text wrapping is ENABLED if mode is true otherwise text wrapping is DISABLED

Syntax: gfx.TextWrap(mode);

Argument	Type	Description
mode	boolean	Use true to ENABLE and false to DISABLE

Return: None (void)

Example

gfx.TextWrap(false);    // Disable text wrapping

gfx.TextWrap(true);     // Enable text wrapping

Note

The default mode is ENABLED.

FontHeight

Return height of current selected font without the multiplier

Syntax: gfx.FontHeight();

Return: Font height without multiplier (int8_t)

Example

gfx.Font(2);
int8_t fontHeight = gfx.FontHeight();

FontStyle

Select font style for Font1 characters.

Valid styles are:

• SOLID
• DOTMATRIXROUND
• DOTMATRIXLED
• DOTMATRIXSQUARE
• DOTMATRIXFADE

Syntax: gfx.FontStyle(ctyp);

Argument	Type	Description
ctyp	uint8_t	Specifies the style to use when using System Font 1

Return: None (void)

Example

gfx.Font(1);
gfx.FontStyle(DOTMATRIXROUND); // Sets FONT1 style to DOTMATRIXROUND

Opacity

Sets whether to draw background color when printing font characters or not.

Syntax: gfx.Opacity(opacity);

Argument	Type	Description
opacity	boolean	Enable (true) or disable (false) font background transparency

Return: None (void)

Example

// Enable font background transparency
gfx.Opacity(true);

// Disable font background transparency
gfx.Opacity(false);

UserCharacter

Draw user defined character using data array of size l at x, y, with foreground colour fc and background colour bc.

Syntax: gfx.UserCharacter(data, l, x, y, fc, bc);

Argument	Type	Description
data	uint32_t*	Array containing character data
l	uint8_t	Pixel size multiplier to use for displaying the character
x	int16_t	Horizontal pixel position of the character
y	int16_t	Vertical pixel position of the character
fc	uint16_t	16-bit RGB565 foreground color
bc	uint16_t	16-bit RGB565 background color

Return: None (void)

Example

gfx.UserCharacter(data, l, x, y, fc, bc);

UserCharacterBG

Option 1

Draw a user defined character with a specified (ui) gci image number being drawn as the character background

• Setting draw to false will draw backround only.
• Setting draw to true will draw background and character.

Syntax: gfx.UserCharacterBG(ui, data, ucsize, ucx, ucy, colour, draw);

Argument	Type	Description
ui	int8_t	Specifies the GCI index for the background
data	uint32_t *	Array containing character data
ucsize	uint8_t	Pixel size multiplier to use for displaying the character
ucx	int16_t	Horizontal pixel position of the character
ucy	int16_t	Vertical pixel position of the character
color	uint16_t	16-bit RGB565 foreground color
draw	boolean	Determines whether to draw the the character (true) or only the background (false)

Return: None (void)

Example

gfx.UserCharacterBG(ui, data, ucsize, ucx, ucy, colour, draw);

Option 2

Draw a user defined character with a downloaded gci image file being drawn as the character background. bgindex is set to 0 if a a single image exists in the gci image file or can be set to other images if they exist

• Setting draw to false will draw backround only.
• Setting draw to true will draw background and character.

Syntax: gfx.UserCharacterBG(data, ucsize, ucx, ucy, colour, draw, bgindex);

Argument	Type	Description
data	uint32_t *	Array containing character data
ucsize	uint8_t	Pixel size multiplier to use for displaying the character
ucx	int16_t	Horizontal pixel position of the character
ucy	int16_t	Vertical pixel position of the character
color	uint16_t	16-bit RGB565 foreground color
draw	boolean	Determines whether to draw the the character (true) or only the background (false)
bgindex	uint32_t	Specifies the GCI index for the background

Return: None (void)

Example

gfx.UserCharacterBG(data, ucsize, ucx, ucy, colour, draw, bgindex);

putstr

Prints string to the current cursor position

Syntax: gfx.putstr(text);

Argument	Type	Description
text	String const char *	Text to print at current cursor position

Return: None (void)

Example

gfx.putstr("4D Systems");

putstrXY

Prints string to the specified position

Syntax: gfx.putstrXY(xpos, ypos, text);

Argument	Type	Description
xpos	int	Horizontal pixel position
ypos	int	Vertical pixel position
text	String const char *	Text to print at specified position

Return: None (void)

Example

gfx.putstrXY(50, 100, "4D Systems");

putch

Prints a single character to the current cursor position

Syntax: gfx.putch(chr);

Argument	Type	Description
chr	uint8_t	Character to print at current cursor position

Return: None (void)

Example

gfx.putch('4');
gfx.putch('D');

putchXY

Prints a single character to the specified position

Syntax: gfx.putchXY(xpos, ypos, chr);

Argument	Type	Description
xpos	int	Horizontal pixel position
ypos	int	Vertical pixel position
chr	uint8_t	Character to print at specified position

Return: None (void)

Example

gfx.putch(50, 20, '4');
gfx.putch('D');

charWidth

Returns the width of the character in pixels with the font size multiplier

Syntax: gfx.charWidth(ch);

Argument	Type	Description
ch	uint8_t	Character to get the print width of

Return: Print width of the character (int)

Example

int width = gfx.charWidth('4') + gfx.charWidth('D');

charHeight

Returns the height of the character with the font size multiplier

Syntax: gfx.charHeight(ch);

Argument	Type	Description
ch	uint8_t	Character to get the print height of

Return: Print height of the character (int)

Example

int height = gfx.charHeight('4');

strWidth

Returns the width of the string with the font size multiplier

Syntax: gfx.strWidth(ts);

Argument	Type	Description
ts	String const char *	Text to get the print width of

Return: Print width of the string (int)

Example

int width = gfx.strWidth("4D Systems");

Text Window Functions

TWprintln

Prints the value to the TextWindow followed by new line

Syntax: gfx.TWprintln(value);

Argument	Type	Description
value	String char * int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t float	Value to print

Return: None (void)

Example

gfx.TWprint(4);
gfx.TWprintln("D Systems");

TWprint

Prints the value to the TextWindow

Syntax: gfx.TWprint(value);

Argument	Type	Description
value	String char * int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t float	Value to print

Return: None (void)

Example

gfx.TWprint(4);
gfx.TWprintln("D Systems");

GetCommand

Retrieves the text entered in text window since previous carriage return sent

Syntax: gfx.GetCommand();

Return: Command entered in the text window (string)

Example

String cmd = gfx.GetCommand();
// Get the last entered command from the Text Window

TWtextcolor

Sets the print color when printing to the text window

Syntax: gfx.TWtextcolor(twc);

Argument	Type	Description
twc	uint16_t	Text foreground color

Return: None (void)

Example

String cmd = gfx.GetCommand();
// Get the last entered command from the Text Window

TWMoveTo

Sets the cursor position for printing in the text window

Syntax: gfx.TWMoveTo(twcrx, twcry);

Argument	Type	Description
twcrx	uint8_t	Horizontal cursor position
twcry	uint8_t	Vertical cursor position

Return: whether this is successful (true) or not (false) (boolean)

Example

result = gfx.TWMoveTo(10, 10);

TWprintAt

Print a string at the specified position in the text window

Syntax: gfx.TWprintAt(pax, pay, istr);

Argument	Type	Description
pax	uint8_t	Horizontal cursor position
pay	uint8_t	Vertical cursor position
istr	String	Text to print at specified position

Return: None (void)

Example

gfx.TWprintAt(10, 5, "4D Systems");

TWwrite

Write a character to Text Window.

Syntax: gfx.TWwrite(c);

Argument	Type	Description
c	char	Character to write to the text window

Return: None (void)

Example

gfx.TWwrite('4');

TWcursorOn

Enables cursor in Text Window

Syntax: gfx.TWcursorOn(mode);

Argument	Type	Description
mode	boolean	Specifies whether to enable (true) or disable (false) cursor

Return: None (void)

Example

gfx.TWcursorOn(true);

TWcls

Clear TextWindows of characters and reset cursor.

Syntax: gfx.TWcls();

Return: None (void)

Example

gfx.TWcls();

TWcolor

Sets the specified foreground colour (fcol) and background colour (bcol) as the colours of the text in the text window.

If background colour is not specified, this function will treat it as transparent.

Additionally, when gfx.TextWindowRestore is used, the text window background colour will match the background colour set by this function.

Syntax: gfx.TWcolor(fcol, bcol);

Argument	Type	Description
fcol	uint16_t	Specifies the text foreground color for text windows
bcol	uint16_t	Specifies the text background color for text windows

Return: None (void)

Example

gfx.Orientation(LANDSCAPE);
gfx.TextWindow(25, 25, 270, 190, BLACK, SILVER, BROWN);
// Creates a SILVER text window @(25,25) with:
// width of 190 and height of 270 pixels and BROWN frame
// The text printed in this text window is colour BLACK
gfx.TWprintln("1. 4D Systems");

gfx.TWcolor(BROWN);
// The text that will be printed next will be colour BROWN
gfx.TWprintln("2. 4D Systems");

gfx.TWcolor(LIME,GRAY);
// The text that will be printed next will be:
// colour LIME with GRAY background

gfx.TWprintln("3. 4D Systems");

TextWindowImage

Create Text window at x, y, with dimensions w, h and text colour tcolour, GCI image img, with optional frame colour fcolour to add frame.

Background image will be automatically replaced with image data as text changes

Syntax: gfx.TextWindowImage(x, y, w, h, tc, img, fc);

Argument	Type	Description
x	int16_t	Horizontal pixel position of the top left of the text window
y	int16_t	Vertical pixel position of the top left of the text window
w	int16_t	Width of the text window
h	int16_t	Height of the text window
tc	uint16_t	Text foreground colour
img	uint16_t	Specifies the GCI index to use as background
fc (optional)	uint16_t	Frame colour

Return: None (void)

Example

gfx.TextWindowImage(10, 20, 200, 100, BLACK, iForm3);

TextWindow

Creates a text window at x, y, with dimensions w, h, text colour tc, background colour bc, and frame in colour fc.

If no frame colour is specified, then no frame will not be rendered.

Syntax: gfx.TextWindow(x, y, w, h, tc, bc [, fc]);

Argument	Type	Description
x	int16_t	Horizontal pixel position of the top left of the text window
y	int16_t	Vertical pixel position of the top left of the text window
w	int16_t	Width of the text window
h	int16_t	Height of the text window
tc	uint16_t	Text foreground colour
bc	uint16_t	Text background colour
fc (optional)	uint16_t	Frame colour

Return: None (void)

Example

gfx.TextWindow(25,25, 190,270, BLACK, SILVER, DARKGRAY);
// Creates a SILVER text window @(25,25) with:
// width of 190 and height of 270 pixels
// and DARKGRAY frame

TWenable

Enables or Disables drawing to the text window

Syntax: gfx.TWenable(mode);

Argument	Type	Description
mode	boolean	Enables (true) or disables (false) writing to the text window

Return: None (void)

Example

gfx.TWenable(false);

TextWindowRestore

Restore a previously created text window and its contents.

Syntax: gfx.TextWindowRestore();

Return: None (void)

Example

gfx.TextWindow(25,25, 190,270, BLACK, SILVER, DARKGRAY);
// Creates a SILVER text window @(25,25) with:
// width of 190 and height of 270 pixels
// and DARKGRAY frame
// The text printed in this text window is colour BLACK
gfx.Cls();
delay(1000);
// Retrieve deleted text window
gfx.TextWindowRestore();

Note

Contents cleared using gfx.TWcls will not be restored

Scroll Functions

setScrollArea

By Specifing Top and Bottom

Set scroll window specified by the top and bottom pixel positions.

This assumes the horizontal area is the full width of the screen.

Syntax: gfx.setScrollArea(y1, y2);

Argument	Type	Description
y1	int	Top pixel position of the scroll area
y2	int	Bottom pixel position of the scroll area

Return: None (void)

Example

gfx.setScrollArea(10, 229);

By Specifing a Rectangle

Set scroll window specified by the rectangle with diagonal at (x1, y1) to (x2, y2)

Syntax: gfx.setScrollArea(x1, y1, x2, y2);

Argument	Type	Description
x1	int	Horizontal pixel position of the top-left pixel of the scroll area
y1	int	Vertical pixel position of the top-left pixel of the scroll area
x2	int	Horizontal pixel position of the bottom-right pixel of the scroll area
y2	int	Vertical pixel position of the bottom-right pixel of the scroll area

Return: None (void)

Example

gfx.setScrollArea(10, 0, 229, 319);

ScrollEnable

Enable or disable auto scrolling

Syntax: gfx.ScrollEnable(mode);

Argument	Type	Description
mode	boolean	Enables (true) or disables (false) scrolling

Return: None (void)

Example

gfx.Orientation(PORTRAIT);  // Sets Orientation to PORTRAIT
gfx.ScrollEnable(false);    // Disables Hardware Scrolling
gfx.ScrollEnable(true);     // Enables Hardware Scrolling

Note

Scrolling is disabled by default

Scroll

If scroll is enabled, this function scrolls the display by the specified number of pixels.

If SmoothScrollSpeed has been set, it will be scrolled pixel line by pixel line, delayed by the value set using gfx.SmoothScrollSpeed in milliseconds

Syntax: gfx.Scroll(steps);

Argument	Type	Description
steps	int	Specifies the number of pixels

Return: None (void)

Example

gfx.Scroll(10); // Scroll the screen by 10 pixels

setScrollBlankingColor

Set blanking line colour after scroll has moved. This can be used to match the current text background colour.

Syntax: gfx.setScrollBlankingColor(colour);

Argument	Type	Description
colour	uint16_t	Color to use for scroll blanking

Return: None (void)

Example

gfx.setScrollBlankingColor(WHITE);

SmoothScrollSpeed

Smoothens the scroll animation for the automatic scrolling that occurs when the text being printed is going outside the display area.

Using zero will scroll height defined by character height in one step.

Syntax: gfx.SmoothScrollSpeed(speed);

Argument	Type	Description
speed	uint8_t	Speed to use for scrolling

Return: None (void)

Example

gfx.Orientation(PORTRAIT);  // Sets Orientation to PORTRAIT
gfx.SmoothScrollSpeed(7);   // Change Scroll Speed to 7

Note

Default delay is 5

setScrollDirection

Set scroll direction to the following:

• SCROLL_UP
• SCROLL_DOWN
• SCROLL_LEFT
• SCROLL_RIGHT

Syntax: gfx.setScrollArea(scrDir);

Argument	Type	Description
scrDir	uint8_t	Specifies the direction

Return: None (void)

Example

gfx.setScrollArea(SCROLL_UP);

4D Graphics Functions

Open4dGFX

GCI/DAT File

Opens 4D DAT file for parsing and GCI file for read using filename without extension.

Syntax: gfx.Open4dGFX(filename);

Argument	Type	Description
filename	String	Specifies the filename of the GCI/DAT file without extension

Return: None (void)

Example

gfx.Open4dGFX("filename"); // Opens filename.dat and filename.gci

Note

Filename should have no extension. Both GCI and DAT file should share the same filename. Also, 4D Graphics files follow the 8.3 DOS format

GCI/DAT Arrays

Loads a 4D DAT array and GCI DATA array for reading 4D widgets

Syntax: gfx.Open4dGFX(DATa, DATlen, GCIa, GCIlen);

Argument	Type	Description
DATa	const uint8_t *	Specifies the array containing the DAT information
DATlen	uint32_t	Specifies the size of the DAT array
GCIa	const uint8_t *	Specifies the array containing the GCI information
GCIlen	uint32_t	Specifies the size of the DAT array

Return: None (void)

Example

gfx.Open4dGFX(dat_arr, dat_len, gci_arr, gci_len);

Close4dGFX

Closes the DAT and GCI files opened by gfx.Open4dGFX(filename)

Syntax: gfx.Close4dGFX();

Return: None (void)

Example

gfx.Close4dGFX();

Open4dFont

Opens a Workshop4 font (IFont/GCI format) for reading.

This returns a reference to the opened font and can be used with gfx.Font

Syntax: gfx.Open4dFont(filename);

Argument	Type	Description
filename	String	Complete filename of the font file in SD card

Return: Reference to the opened font (gfx4d_font)

Example

gfx4d_font customFont;

void setup() {
    gfx.begin(); // Initialize the display
    gfx.Cls();
    gfx.ScrollEnable(true);
    gfx.BacklightOn(true);
    gfx.Orientation(PORTRAIT);
    gfx.SmoothScrollSpeed(5);
    gfx.TextColor(WHITE); gfx.Font(2); gfx.TextSize(1);

    customFont = gfx.Open4dFont("custom.IFont");
}

DrawImageFile

Draw widget from GCI file

Syntax: gfx.DrawImageFile(Fname);

Argument	Type	Description
Fname	String	Filename of the GCI file in the SD card

Return: None (void)

Example

gfx.DrawImageFile("sample.gci");

DrawImageArray

Draw widget from GCI array

Syntax: gfx.DrawImageArray(ImageArray);

Argument	Type	Description
ImageArray	uint8_t * uint16_t *	Specifies the array containing the GCI data

Return: None (void)

Example

gfx.DrawImageArray(sample_gci_arr);

getImageValue

Returns the current value of a GCI widget

Syntax: gfx.getImageValue(ui);

Argument	Type	Description
ui	uint16_t	Index of GCI object

Return: Current value of the GCI widget (int16_t)

Example

uint16_t gauge2Val = gfx.getImageValue(iGauge2);

imageGetWord

Queries the current selected parameter of the GCI widget.

Parameters can be IMAGE_XPOS, IMAGE_YPOS, IMAGE_WIDTH, IMAGE_HEIGHT or IMAGE_INDEX

Syntax: gfx.imageGetWord(img, controlIndex);

Argument	Type	Description
img	uint16_t	Index of GCI object
controlIndex	byte	Parameter to query

Return: Value of the selected parameter of the GCI widget (int)

Example

int gaugeWidth = gfx.imageGetWord(iGauge2, IMAGE_WIDTH);

imageSetWord

Sets the selected parameter(s) of the GCI widget.

Parameters can be IMAGE_XPOS, IMAGE_YPOS, IMAGE_XYPOS or IMAGE_INDEX. When using IMAGE_XYPOS, two values are required.

Syntax: gfx.imageSetWord(img, controlIndex, val1 [, val2]);

Argument	Type	Description
img	uint16_t	Index of GCI object
controlIndex	byte	Parameter to set
val1	int	Value to set the selected parameter to
val2 (optional)	int	Additional value when setting IMAGE_XYPOS

Return: None (void)

Example

gfx.imageSetWord(iGauge2, IMAGE_XPOS, 100);

getNumberofObjects

Get the number of GCI objects found in the GCI file opened with gfx.Open4dGFX

Syntax: gfx.getNumberofObjects();

Return: Number of GCI objects found (uint16_t)

Example

uint16_t gciCount = gfx.getNumberofObjects();

setGCIsystem

Sets the GCI system to uSD or from a data array

Valid options are:

• GCI_SYSTEM_USD - sets GCI system to uSD
• GCI_SYSTEM_PROGMEM - sets GCI system to data array

Syntax: gfx.setGCIsystem(gs);

Argument	Type	Description
gs	uint8_t	Indicates whether to set for uSD or progmem

Return: None (void)

Example

gfx.setGCIsystem(GCI_SYSTEM_USD);

getGCIsystem

Returns currently selected GCI system

Syntax: gfx.getGCIsystem();

Return: GCI_SYSTEM_USD or GCI_SYSTEM_PROGMEM (uint8_t)

Example

uint8_t gciSys = gfx.getGCIsystem();

UserImage

Draw a single frame GCI widget in the default location or as specified by (x, y)

Syntax: gfx.UserImage(id [, x, y]);

Argument	Type	Description
id	uint16_t	Index of the GCI object
x (optional)	int	Optional horizontal position to draw the image
y (optional)	int	Optional vertical position to draw the image

Return: None (void)

Example

gfx.UserImage(iImage1);
// Show iImage1

gfx.UserImage(iImage2,50,50);
// Show iImage2 at (50,50)

Note

The GCI and DAT files should have been previously opened with the function gfx.Open4dGFX functions

UserImages

Displays the frame of the GCI object specified by 'id'.

The following can be optionally specified:

• Horizontal offset - useful for Spectrum and Digits type widgets
• Alternate X and Y positions - useful for temporarily drawing widgets in alternate positions
• Both horizontal offset and alternate X and Y positions - useful for temporarily drawing spectrum and digits in alternate positions

Syntax: gfx.UserImages(id, frame [, offset, x, y]);

• gfx.UserImages(id, frame);
• gfx.UserImages(id, frame, offset);
• gfx.UserImages(id, frame, newx, newy);
• gfx.UserImages(id, frame, offset, altx, alty);

Argument	Type	Description
id	uint16_t	Index of the GCI object
frame	int16_t	Specifies the frame number of the selected GCI object
offset (optional)	int	Optional horizontal offset to draw the GCI object
x (optional)	int16_t	Optional horizontal position to draw the GCI object
y (optional)	int16_t	Optional vertical position to draw the GCI object

Return: None (void)

Note

The GCI and DAT files should have been previously opened with the function gfx.Open4dGFX functions

UserImageDR

Draws a section of the selected single frame GCI object (id). The section starts at x and y and has a width of w and height of h.

Syntax: gfx.UserImageDR(id, x, y, w, h, altx, alty);

Argument	Type	Description
id	uint16_t	Index of the GCI object
frame	int	Specifies the frame number of the selected GCI object
x	int16_t	Specifies the horizontal position of the top left pixel of the section relattve to the top left pixel of the image
y	int16_t	Specifies the vertical position of the top left pixel of the section relattve to the top left pixel of the image
w	int16_t	Specifies the width of the section
h	int16_t	Specifies the height of the section
altx	int16_t	Specifies the alternate horizontal position for the GCI object
alty	int16_t	Specifies the alternate vertical position for the GCI object

Return: None (void)

UserImagesDR

Draws a section of the frame of the selected GCI object (id). The section starts at x and y and has a width of w and height of h.

Syntax: gfx.UserImagesDR(id, frame, x, y, w, h);

Argument	Type	Description
id	uint16_t	Index of the GCI object
frame	int	Specifies the frame number of the selected GCI object
x	int16_t	Specifies the horizontal position of the top left pixel of the section relattve to the top left pixel of the image
y	int16_t	Specifies the vertical position of the top left pixel of the section relattve to the top left pixel of the image
w	int16_t	Specifies the width of the section
h	int16_t	Specifies the height of the section

Return: None (void)

Note

The GCI and DAT files should have been previously opened with the function gfx.Open4dGFX functions

UserImageDRcache

Draw section of a single frame GCI widget while utilizing cache

Syntax: gfx.UserImageDRcache(id, x, y, w, h, altx, alty);

Argument	Type	Description
id	uint16_t	Index of the GCI object
frame	int	Specifies the frame number of the selected GCI object
x	int16_t	Specifies the horizontal position of the top left pixel of the section relattve to the top left pixel of the image
y	int16_t	Specifies the vertical position of the top left pixel of the section relattve to the top left pixel of the image
w	int16_t	Specifies the width of the section
h	int16_t	Specifies the height of the section
altx	int16_t	Specifies the alternate horizontal position for the GCI object
alty	int16_t	Specifies the alternate vertical position for the GCI object

Return: None (void)

setCacheSize

Sets the cache size to use with gfx.UserImageDRcache

Syntax: gfx.setCacheSize(cs);

Argument	Type	Description
cs	uint32_t	Size of cache to use with gfx.UserImageDRcache

Return: None (void)

Example

gfx.setCacheSize(2048000);

LedDigitsDisplaySigned

Displays a signed or unsigned numeric value using graphics from Led or Custom Digits.

This routine only works with all numbers and must be generated with project option 'Allow -ve Led and Custom Digits and leading blanks on Custom Digits' is enabled. If not, use gfx.LedDigitsDisplay instead

Position can be overriden by specifying x and y values.

Each of the Leddigits objects and Customdigits objects is composed of 2 GCI objects. A Leddigits object at index 1 si composed of GCI objects named iLeddigits1 and iiLeddigits1. The first one being a single frame containing the whole digits area as seen in Workshop4’s WYSIWYG. The other GCI object is composed of multiple frames containing the digits 0-9, a blank space and a negative sign depending on the setting enabled in the project.

It is ideal to simply let Workshop4 generate this code using the Paste Code functionality.

Syntax: gfx.LedDigitsDisplaySigned(newval, index, Digits, MinDigits, WidthDigit, LeadingBlanks [, x, y]);

Argument	Type	Description
newval	int64_t	Value to display using the Digits widget
index	uint16_t	Specifies which LedDigits object to update
Digits	int16_t	Maximum number of digits in the widget
MinDigits	int16_t	Minimum number of digits in the object
WidthDigit	int16_t	Width of each digit image
LeadingBlanks	int16_t	Specifies whether to display leading blanks or not
x (optional)	int16_t	Optional horizontal position to draw the GCI object
y (optional)	int16_t	Optional vertical position to draw the GCI object

Return: None (void)

LedDigitsDisplay

Displays a signed or unsigned numeric value using graphics from Led or Custom Digits.

This routine only works with all numbers and must be generated with project option 'Allow -ve Led and Custom Digits and leading blanks on Custom Digits' is disabled. If not, use gfx.LedDigitsDisplaySigned instead

Position can be overriden by specifying x and y values.

Each of the Leddigits objects and Customdigits objects is composed of 2 GCI objects. A Leddigits object at index 1 is composed of GCI objects named iLeddigits1 and iiLeddigits1. The first one being a single frame containing the whole digits area as seen in Workshop4’s WYSIWYG. The other GCI object is composed of multiple frames containing the digits 0-9, a blank space and a negative sign depending on the setting enabled in the project.

It is ideal to simply let Workshop4 generate this code using the Paste Code functionality.

Syntax: gfx.LedDigitsDisplay(newval, index, Digits, MinDigits, WidthDigit, LeadingBlanks [, x, y]);

Argument	Type	Description
newval	int64_t	Value to display using the Digits widget
index	uint16_t	Specifies which LedDigits object to update
Digits	int16_t	Maximum number of digits in the widget
MinDigits	int16_t	Minimum number of digits in the object
WidthDigit	int16_t	Width of each digit image
LeadingBlanks	int16_t	Specifies whether to display leading blanks or not
x (optional)	int16_t	Optional horizontal position to draw the GCI object
y (optional)	int16_t	Optional vertical position to draw the GCI object

Return: None (void)

Example

gfx.LedDigitsDisplay(50, iLeddigits1, 4, 3, 20, false);
// Writes the value 50 to the iLedDigits1 object

gfx.LedDigitsDisplay(50, iLeddigits1, 4, 3, 20, false, 5, 50);
// Writes the value 50 to the iiLeddigits2 object.
// The object will then be shown at (5,50)

PrintImage

Print image from GCI file at 'index' at current cursor position.

Syntax: gfx.PrintImage(index);

Argument	Type	Description
index	uint16_t	Specifies the GCI object to print

Return: None (void)

Example

gfx.MoveTo(50, 50);
gfx.PrintImage(iImage0);

PrintImageFile

Prints the first frame of the first object from the specified GCI file at the current cursor position

Syntax: gfx.PrintImageFile(filename);

Argument	Type	Description
filename	String	Specifies the GCI file to print an image from

Return: None (void)

Example

gfx.MoveTo(50, 50);
gfx.PrintImageFile("filename.GCI");
// Prints the 1st frame of the 1st object from filename.GCI

Note

Unlike the function gfx.Open4dGFX, this function requires the extension of the file

UserImageHide

Hides the GCI widget using the specified colour or BLACK if no colour is specified. Use -1 for hndl to apply to all GCI widgets.

For touch capable display modules, this also disables touch.

Syntax: gfx.UserImageHide(hndl [, colour]);

Argument	Type	Description
hndl	int	Specifies the widget or all widgets (-1) to hide
colour (optional)	uint16_t	Optional background colour to use to hide the widget

Return: None (void)

Example

gfx.UserImageHide(iImage1);         // Hide iImage1 using default BLACK colour
gfx.UserImageHide(iImage2, WHITE);  // Hide iImage2 using colour WHITE

UserImageHideBG

Hides the GCI widget using the specified background image objBG. Use -1 for hndl to apply to all GCI widgets.

For touch capable display modules, this also disables touch.

Syntax: gfx.UserImageHideBG(hndl, objBG);

Argument	Type	Description
hndl	int	Specifies the widget or all widgets (-1) to hide
objBG	int	Specifies the index of GCI background to use to hide the widget

Return: None (void)

Example

gfx.UserImageHide(iImage2, iForm1);  // Hide iImage2 using background image iForm1

getLastPointerPos

Get the x or y value of the change position of 2 & 3 image widgets

Syntax: gfx.getLastPointerPos();

Return: Value of the widget, x value if horizontal or y value if vertical (int16_t)

Wi-Fi Functions

DownloadFile

Full Address

Downloads the file from the specified web address and save it with the specified filename.

An optional certificate can be used.

Syntax: gfx.DownloadFile(WebAddr, Fname [, sha1]);

Argument	Type	Description
WebAddr	String	Full URL address of the file
Fname	String	Filename to store the file with
sha1 (optional)	const char *	Optional certificate to use

Return: None (void)

Example

gfx.DownloadFile("example.com/sample.txt", "sample.txt");

Note

It is advisable to follow the 8.3 DOS format

Address and Port

Downloads the file from the specified web address and port and save it with the specified filename.

An optional certificate can be used.

Syntax: gfx.DownloadFile(Address, port, hfile, Fname [, certUsed, sha1]);

Argument	Type	Description
Address	String	Server address hosting the file
port	uint16_t	Port number used by the server to host the file
hfile	String	File path of file to download from the server
Fname	String	Filename to save the file with
certUsed	bool	Optionally indicate to use a certificate
sha1	const char *	Optional certificate to use

Return: None (void)

Example

gfx.DownloadFile("example.com", 80, "/sample.txt", "sample.txt");

Note

It is advisable to follow the 8.3 DOS format

CheckDL

Check if the last download performed was successful

Syntax: gfx.CheckDL();

Return: true if successful otherwise false (boolean)

Example

gfx.DownloadFile("example.com/sample.txt", "sample.txt");
if (gfx.CheckDL()) {
    gfx.println("Download successful");
} else {
    gfx.println("Download failed");
}

Sprite Functions

SetMaxNumberSprites

Sets the maximum number of sprites in the sprites list

Syntax: gfx.SetMaxNumberSprites(count);

Argument	Type	Description
count	uint16_t	Specifies the new max number of sprites

Return: None (void)

Example

gfx.SetMaxNumberSprites(100);

SpriteAreaSet

Sets the area of the screen that sprites will be displayed in.

Syntax: gfx.SpriteAreaSet(x, y, x1, y1);

Argument	Type	Description
x	uint16_t	Horizontal pixel position of the top-left corner of the sprite area
x	uint16_t	Vertical pixel position of the top-left corner of the sprite area
x1	uint16_t	Horizontal pixel position of the bottom-right corner of the sprite area
y1	uint16_t	Vertical pixel position of the bottom-right corner of the sprite area

Return: None (void)

Example

gfx.SpriteAreaSet(0, 0, 239, 319);

SetNumberSprites

Sets number of sprites to use

Syntax: gfx.SetNumberSprites(count);

Argument	Type	Description
count	uint16_t	Number of sprites to use

Return: None (void)

Example

gfx.SetNumberSprites(20);

SpriteInit

Initialize the sprites data array

Syntax: gfx.SpriteInit(data, len);

Argument	Type	Description
data	uint16_t *	Pointer to the sprite data array
len	size_t	Size of sprite data

Return: true if successful otherwise false (boolean)

Example

gfx.SpriteInit(spriteData, sizeof(spriteData));

GetNumberSprites

Return the total number of initialized sprites

Syntax: gfx.GetNumberSprites();

Return: Total number of initialized sprites (int)

Example

initSprites = gfx.GetNumberSprites();

SpriteAdd

Add a sprite into a specified position in the sprite list.

Syntax: gfx.SpriteAdd(pos, num, x, y, data);

Argument	Type	Description
pos	int	Position in the sprite list
num	int	Number of the sprite in the sprite data
x	int	Horizontal start position of the sprite
y	int	Vertical start position of the sprite
data	uint16_t *	Sprite data array

Return: true if successful otherwise false (boolean)

SetSprite

Sets the position of sprite.

Syntax: gfx.SetSprite(num, active, x, y, bscolor, sdata);

Argument	Type	Description
num	int	Number of the sprite in the sprite data
active	bool	Specifies whether the sprite is active (true) or not (`false)
x	int	Horizontal new position of the sprite
y	int	Vertical new position of the sprite
bscolor	uint16_t	Background color to use to clear previous sprite position
data	uint16_t	Sprite data array

Return: None (void)

SpriteEnable

Enables or disables chosen sprite

Syntax: gfx.SpriteEnable(snum, mode);

Argument	Type	Description
snum	int	Number of the sprite in the sprite data
mode	bool	Enables (true) or disables (false) sprite

Return: None (void)

UpdateSprites

Updates all sprites in the previously set sprite area

Syntax: gfx.UpdateSprites(bscolor, sdata);

Argument	Type	Description
bscolor	uint16_t	Background colour to use for clearing old sprite position
sdata	uint16_t *	Sprite data array

Return: None (void)

SpriteUpdate

Update all sprites in the selected area

Syntax: gfx.SpriteUpdate(tsx, tsy, tsx1, tsy1, bscolor, sdata);

Argument	Type	Description
tsx	int16_t	Horizontal pixel position of the top-left corner of the selected area
tsy	int16_t	Vertical pixel position of the top-left corner of the selected area
tsx1	int16_t	Horizontal pixel position of the bottom-right corner of the selected area
tsy1	int16_t	Vertical pixel position of the bottom-right corner of the selected area
bscolor	uint16_t	Background colour to use for clearing old sprite position
sdata	uint16_t *	Sprite data array

Return: None (void)

SpriteGetPixel

Returns the colour of the pixel of the chosen sprite at x, y position

Syntax: gfx.SpriteGetPixel(snum, xo, yo, tcolor, sdata);

Argument	Type	Description
snum	int	Number of the sprite in the sprite data
xo	int	Horizontal position of selected pixel
yo	int	Vertical position of selected pixel
tcolor	uint16_t	Colour to test against as transparent
sdata	uint16_t *	Sprite data array

Return: Pixel colour of the chosen sprite at x, y position (uint16_t)

SpriteGetPalette

Return the 16-bit colour in the palette array position specified by pnumber

Syntax: gfx.SpriteGetPalette(pnumber);

Argument	Type	Description
pnumber	int	Palette array position

Return: 16-bit colour in the palette array position specified (uint16_t)

GetSpritesAt

Queries the sprites at the current x,y position to a created slist array

Syntax: gfx.GetSpritesAt(xo, yo, tcolour, slist, sdata);

Argument	Type	Description
xo	int	Horizontal position of selected pixel
yo	int	Vertical position of selected pixel
tcolour	uint16_t	Colour to test against as transparent
slist	int *	Array to store the list of sprites found
sdata	uint16_t *	Sprite data array

Return: Number of sprites found (int)

GetSprite

Returns the selected sprite parameter.

Parameter	Description
SPRITE_X	x position of sprite
SPRITE_Y	y position of sprite
SPRITE_W	width of sprite
SPRITE_H	height of sprite
SPRITE_ACTIVE	1 if sprite enabled
SPRITE_COLLIDE1	number of first collided sprite
SPRITE_COLLIDE2	number of second collided sprite

Syntax: gfx.GetSprite(snum, param);

Argument	Type	Description
snum	int	Number of the sprite in the sprite data
param	int	Sprite parameter to query

Return: Value of the queried parameter (int)

GetSpriteImageNum

Returns the position of the chosen sprite in the sprite list

Syntax: gfx.GetSpriteImageNum(snum);

Argument	Type	Description
snum	int	Number of the sprite in the sprite data

Return: Position of the chosen sprite in the sprite list (int16_t)

SpriteSetPalette

Set the colour in the 4 bit pallette specified by the colour number (pnumber) with 16bit colour (plcolour)

Syntax: gfx.SpriteSetPalette(pnumber, plcolour);

Argument	Type	Description
pnumber	int	Colour number
plcolour	uint16_t	Colour value

Return: None (void)

GRAM Functions

SetGRAM

Define pixel write area in the current framebuffer

Syntax: gfx.SetGRAM(x1, y1, x2, y2);

Argument	Type	Description
x1	int16_t	Horizontal position of the top-left pixel of the GRAM
y1	int16_t	Vertical position of the top-left pixel of the GRAM
x2	int16_t	Horizontal position of the bottom-right pixel of the GRAM
y2	int16_t	Vertical position of the bottom-right pixel of the GRAM

Return: None (void)

Example

gfx.SetGRAM(0, 0, 239, 319);

setAddrWindow

Sets the GRAM window as specified by the top-left corner (x, y) and dimensions w and h

Syntax: gfx.setAddrWindow(x, y, w, h);

Argument	Type	Description
x	int16_t	Horizontal position of the top-left pixel of the GRAM
y	int16_t	Vertical position of the top-left pixel of the GRAM
w	int16_t	Width of the GRAM window
h	int16_t	Height of the GRAM window

Return: None (void)

Example

gfx.setAddrWindow(0, 0, 240, 320);

WrGRAMs

Write an array of pixels with the specified length len from an array to the selected framebuffer. The array can be 8-bit, 16-bit or 32-bit.

WrGRAMs should be used intead of pushColors if image data is likely to exceed display boundaries or if transparency is used

Syntax: gfx.WrGRAMs(data, len);

Argument	Type	Description
data	uint8_t uint16_t uint32_t *	Pointer to array of pixels
len	uint16_t	Length of data in array

Return: None (void)

Example

gfx.WrGRAMs(color_data, color_data_len);

Note

32bit data arrays can used for IoD compatibility

WrGRAM

Write a single 16-bit RGB565 colour to GRAM window to the selected framebuffer

Syntax: gfx.WrGRAM(colour);

Argument	Type	Description
colour	uint16_t	16-bit colour to write to the GRAM window

Return: None (void)

Example

gfx.WrGRAM(0xFFE0);

pushColors

Write an array of pixels with the specified length len from an array to the selected framebuffer. The array can be 8-bit, 16-bit or 32-bit.

This function operates faster than WrGRAMs due to no boundary or transparency checks.

Care must be taken to ensure image area does not exceed the displays boundaries as an error will occur.

Syntax: gfx.pushColors(color_data, len);

Argument	Type	Description
data	uint8_t uint16_t uint32_t *	Pointer to array of pixels
len	uint16_t	Length of data in array

Return: None (void)

Example

gfx.pushColors(color_data, color_data_len);

Note

32-bit data arrays can used for IoD compatibility

StartWrite

Sets the start write condition

Syntax: gfx.StartWrite();

Return: true if successful otherwise false (boolean)

Example

bool res = gfx.StartWrite();

// Use draw functions as required
// and when done, run EndWrite

if (res) gfx.EndWrite();

EndWrite

Unsets the start write condition allowing all changes to the framebuffer to update the display

Syntax: gfx.EndWrite();

Return: None (void)

Example

bool res = gfx.StartWrite();

// Use draw functions as required
// and when done, run EndWrite

if (res) gfx.EndWrite();

ReadPixel

Read a single pixel from the framebuffer

Syntax: gfx.ReadPixel(x, y);

Argument	Type	Description
x	uint16_t	Horizontal position of the pixel
y	uint16_t	Vertical position of the pixel

Return: Pixel colour at specified x, y position (uint16_t)

Example

pixelColour = gfx.ReadPixel(50, 20);

ReadLine

Read a line of pixels starting from (x, y) and store it in the specified 16-bit data array

Syntax: gfx.ReadLine(x, y, w, data);

Argument	Type	Description
x	int16_t	Horizontal position of the starting pixel
y	int16_t	Vertical position of the starting pixel
w	int16_t	Number of pixels to read
data	uint16_t *	Array to store the colour data

Return: Number of pixels read (uint16_t)

Example

uint16_t line_data[100];
gfx.ReadLine(40, 50, 100, line_data);

WriteLine

Writes a line of pixels from the specified 16-bit array starting from (x, y)

Syntax: gfx.WriteLine(x, y, w, data);

Argument	Type	Description
x	int16_t	Horizontal position of the starting pixel
y	int16_t	Vertical position of the starting pixel
w	int16_t	Number of pixels to write
data	uint16_t *	Array containing the colour data to write

Return: None (void)

Example

gfx.WriteLine(40, 50, 100, colour_data);

DrawToframebuffer

Set the frame buffer for drawing functions. Once set, all drawing functions will be sent to specified framebuffer.

If frame buffer 0 is set (default) all drawing functions will appear immediately on the display.

Syntax: gfx.DrawToframebuffer(fbnum);

Argument	Type	Description
fbnum	uint8_t	Specifies the framebuffer number (0 to 4)

Return: None (void)

Example

gfx.DrawToframebuffer(1);

GetFrameBuffer

Queries the current framebuffer in use.

Syntax: gfx.GetFrameBuffer();

Return: Current framebuffer (uint8_t)

Example

uint8_t curFb = gfx.GetFrameBuffer();

DrawFrameBuffer

Flush the whole specified framebuffer

Syntax: gfx.DrawFrameBuffer(fbnum);

Argument	Type	Description
fbnum	uint8_t	Specifies the framebuffer number (0 to 4)

Return: None (void)

Example

gfx.DrawFrameBuffer(1);

DrawFrameBufferArea

Using GCI Object Info

Flush the area occupied by GCI widget specified by id from the selected framebuffer fbnum

Syntax: gfx.DrawFrameBufferArea(fbnum, ui);

Argument	Type	Description
fbnum	uint8_t	Specifies the framebuffer number (0 to 4)
ui	int16_t	Specifies the GCI widget to get position and size

Return: None (void)

Example

gfx.DrawFrameBufferArea(1, iGauge1);

Using Custom Area

Flush the rectangular area specified by the diagonal (x1, y1), (x2, y2) from the selected framebuffer fbnum

Syntax: gfx.DrawFrameBufferArea(fbnum, x1, y1, x2, y2);

Argument	Type	Description
fbnum	uint8_t	Specifies the framebuffer number (0 to 4)
x1	uint16_t	Horizontal position of top-left pixel of the area
y1	uint16_t	Vertical position of top-left pixel of the area
x2	uint16_t	Horizontal position of bottom-right pixel of the area
y2	uint16_t	Vertical position of bottom-right pixel of the area

Return: None (void)

Example

gfx.DrawFrameBufferArea(1, 0, 0, 99, 199);

MergeFrameBuffers

Merge 2 or 3 frame buffers and send to specified frame buffer.

Syntax: gfx.MergeFrameBuffers(fbto, fbfrom1, fbfrom2[, fbfrom3], transColor [, transColor1]);

Argument	Type	Description
fbto	uint8_t	Output framebuffer
fbfrom1	uint8_t	Base framebuffer for the second framebuffer to be merged to
fbfrom2	uint8_t	Second framebuffer to merge to the first
fbfrom3 (optional)	uint8_t	Third framebuffer to merge to the second and first
transColor	uint16_t	16-bit colour from second framebuffer to treat as transparent
transColor1 (optional)	uint16_t	16-bit colour from third framebuffer to treat as transparent

Return: None (void)

Example

Merge 2 FramebuffersMerge 3 Framebuffers

gfx.MergeFrameBuffers(0, 1, 2, BLACK); // Merge Frame Buffers 1 and 2 to 0

gfx.MergeFrameBuffers(0, 1, 2, 3, BLACK, WHITE); // Merge Frame Buffers 1, 2 and 3 to 0

Note

Using this function without first writing to a frame buffer will cause issue

WriteToFrameBuffer

Writes 8bit or 16bit colour data array directly to current frame buffer at given offset. Needs a gfx.FlushArea(x1, x2, y1, y2, -1); after write to display new data.

Syntax: gfx.WriteToFrameBuffer(offset, data, len);

Argument	Type	Description
offset	uint32_t	Offset indicating the position of the first write
data	uint16_t *	Colour data array to write
len	uint32_t	Length/Size of data to write to the frame buffer

Return: None (void)

Example

gfx.WriteToFrameBuffer(0, colour_data, 100);

FlushArea

Flushes display area specified.

Syntax: gfx.FlushArea(x1, x2, y1, y2, xpos);

Argument	Type	Description
x1	int	Horizontal position of top-left pixel of the area
x2	int	Horizontal position of bottom-right pixel of the area
y1	int	Vertical position of top-left pixel of the area
y2	int	Vertical position of bottom-right pixel of the area
xpos	int	-1 for normal use, otherwise refreshes one pixel at xpos position

Return: None (void)

Example

gfx.FlushArea(10, 100, 10, 100, -1);

drawBitmap

Draws a bitmap using the data array at the given co-ordinates

Syntax: gfx.drawBitmap(x1, y1, x2, y2, data);

Argument	Type	Description
x1	int	Horizontal position of top-left pixel of the area
y1	int	Vertical position of top-left pixel of the area
x2	int	Horizontal position of bottom-right pixel of the area
y2	int	Vertical position of bottom-right pixel of the area
data	uint16_t *	Pointer to array containing the colour data

Return: None (void)

Example

gfx.drawBitmap(0, 0, 100, 200, bmp_data);

GPIO Functions

PinMode

Sets the operation mode of the specified pin

Syntax: gfx.PinMode(pin, mode);

Argument	Type	Description
pin	byte	Specifies the pin number/name
mode	bool	Specifies whether to use the pin as INPUT or OUTPUT

Return: None (void)

Example

gfx.PinMode(5, OUTPUT);

DigitalWrite

Sets the specified pin to either HIGH or LOW. The pin must first be set as OUTPUT using gfx.PinMode

Syntax: gfx.DigitalWrite(pin, state);

Argument	Type	Description
pin	byte	Specifies the pin number/name
state	bool	Specifies whether to set the pin to HIGH or LOW

Return: None (void)

Example

gfx.PinMode(5, OUTPUT);
gfx.DigitalWrite(5, HIGH);

DigitalRead

Reads the current state of the specified pin

Syntax: gfx.DigitalRead(pin);

Argument	Type	Description
pin	byte	Specifies the pin number/name

Return: Whether the pin is HIGH (1) or LOW (0) (int)

Example

gfx.PinMode(5, INPUT);
pinState = gfx.DigitalRead(5);

Touch Functions

The functions included in this section are only applicable for touch enabled display modules.

touch_Set

Enables or disable touch functionality

Syntax: gfx.touch_Set(mode);

Argument	Type	Description
mode	uint8_t	Specifies whether to enable (TOUCH_ENABLE) or disable (TOUCH_DISABLE) touch

Return: None (void)

Example

touch_Set(TOUCH_DISABLE);

Note

This function is only available for capacitive and resistive touch displays

touch_Update

Checks whether a touch event is detected. If a touch event has occurred, pen, xpos, ypos and images touched will be updated.

Syntax: gfx.touch_Update();

Return: true if successful otherwise false (boolean)

Example

gfx.Cls();
gfx.println("Draw something, exit by pressing center square");

gfx.RectangleFilled(midx0, midy0, midx1, midy1, RED);

while (true) {

    gfx.touch_Update();
    tx = gfx.touch_GetX();
    ty = gfx.touch_GetY();
    TOUCHED = gfx.touch_GetPen();

    // If the screen gets touched
    if (TOUCHED == TOUCH_PRESSED) {

        if (tx >= midx0 && tx <= midx1 && ty >= midy0 && ty <= midy1) {
            waitForRelease();
            break;
        }

        // First touch of the screen, draw a pixel where it was touched
        if (firstTouch) {
            gfx.PutPixel(tx, ty, BLUE);
            firstTouch = false;
        }
        // Screen previously touched and pixel drawn, so draw a line from first touch to this location
        else {
            gfx.Line(gfx.touch_GetLastX(), gfx.touch_GetLastY(), tx, ty, BLUE);
        }
    }

    // If the screen touch is released after previously touching it, draw a circle to mark the release point
    if (TOUCHED == NOTOUCH || TOUCHED == TOUCH_RELEASED) {
        gfx.CircleFilled(tx, ty, 3, RED);
        firstTouch = true;
    }
};

Note

This function is only available for capacitive and resistive touch displays

touch_GetPen

Returns the latest pen status after the last gfx.touch_Update

Syntax: gfx.touch_GetPen();

Return: Pen Status (int16_t)

Example

See gfx.touch_Update example

Note

This function is only available for capacitive and resistive touch displays.

touch_GetX

Returns the latest touch X position after the last gfx.touch_Update

Syntax: gfx.touch_GetX();

Return: Horizontal pixel position of last touch event (int16_t)

Example

See gfx.touch_Update example

Note

This function is only available for capacitive and resistive touch displays

touch_GetY

Returns the latest touch Y position after the last gfx.touch_Update

Syntax: gfx.touch_GetY();

Return: Vertical pixel position of last touch event (int16_t)

Example

See gfx.touch_Update example

Note

This function is only available for capacitive and resistive touch displays

touch_GetLastX

Returns the previous touch X position prior to the last gfx.touch_Update

Syntax: gfx.touch_GetLastX();

Return: Horizontal pixel position of touch event prior to the last (int16_t)

Example

See gfx.touch_Update example

Note

This function is only available for capacitive and resistive touch displays

touch_GetLastY

Returns the previous touch Y position prior to the last gfx.touch_Update

Syntax: gfx.touch_GetLastY();

Return: Vertical pixel position of touch event prior to the last (int16_t)

Example

See gfx.touch_Update example

Note

This function is only available for capacitive and resistive touch displays

imageTouchEnable

Enable or disable touch for the specified GCI widget Optionally, a special type of input widget can be specified:

• TOGGLE4STATES
• SLIDER3IMAGE
• GAUGE2IMAGE
• MOMENTARY
• TOGGLE

Syntax: gfx.imageTouchEnable(gcinum, en [, type]);

Argument	Type	Description
gcinum	int	Specifies the target widget or -1 for all widgets
en	boolean	Enable (true) or disable (false)
type (optional)	int	Optional type of widget

Example

gfx.imageTouchEnable(iWinbutton1, true, MOMENTARY);
gfx.imageTouchEnable(iWinbutton2, true, TOGGLE);

Return: None (void)

Note

1. This function is only available for capacitive and resistive touch displays
2. It is advisable to use Workshop4 to generate necessary touch related code by using the Paste Code option
3. When using Workshop4 buttons, Momentary options Yes, No and On can be selected. Momentary Both is currently not supported.

imageTouchEnableRange

Enable or disable touch for the specified range of GCI widget. Optionally, a special type of input widget can be specified:

• TOGGLE4STATES
• SLIDER3IMAGE
• GAUGE2IMAGE
• MOMENTARY
• TOGGLE
• KEYPAD

Syntax: gfx.imageTouchEnableRange(gcinumFrom, gcinumTo, en [, type]);

Argument	Type	Description
gcinumFrom	int	Specifies the target widget or -1 for all widgets
gcinumTo	int	Specifies the target widget or -1 for all widgets
en	boolean	Enable (true) or disable (false)
type (optional)	int	Optional type of widget

Return: None (void)

Example

gfx.imageTouchEnableRange(iKeyboard1_0, iKeyboard1_59, true, KEYPAD);

Note

1. This function is only available for capacitive and resistive touch displays
2. It is advisable to use Workshop4 to generate necessary touch related code by using the Paste Code option

ImageTouchedAuto

Evaluate touch events for the input widgets automatically. The correct widget type should be set using gfx.imageTouchEnable

Syntax: gfx.ImageTouchedAuto();

Return: Returns the widget pressed or -1 if no touch (int16_t)

Example

imgTouched = gfx.ImageTouchedAuto();

Note

1. This function is only available for capacitive and resistive touch displays
2. It is advisable to use Workshop4 to generate necessary touch related code by using the Paste Code option

imageTouched

Returns the touched widget after the last gfx.touch_Update or return -1 if no touch.

Syntax: gfx.imageTouched();

Return: Returns the touched widget (int)

Example

imgTouched = gfx.imageTouched();

Note

This function is only available for capacitive and resistive touch displays

imageAutoSlider

Calculates the value of the slider based on the last user input position

Syntax: gfx.imageAutoSlider(ui, axis, uiv, ming, maxg);

Argument	Type	Description
ui	uint16_t	Specifies the GCI slider
axis	uint16_t	Indicates whether the slider is a HORIZONTAL_SLIDER or VERTICAL SLIDER
uiv	uint16_t	Touch position based on the orientation for the slider  - X position for horizontal  - Y position for vertical
ming	uint16_t	Touch offset near the minimum position
maxg	uint16_t	Touch offset near the maximum position

Return: Value of the Slider (int16_t)

Example

sliderVal = gfx.imageAutoSlider(iSlider1, HORIZONTAL_SLIDER, gfx.touch_GetX(), 8, 8);

Note

This function is only available for capacitive and resistive touch displays

imageAutoKnob

Calculates the value of the knob based on the last user input position

Syntax: gfx.imageAutoKnob(hndl, uix, uiy, minarc, maxarc, ming, maxg);

Argument	Type	Description
hndl	int	Specifies the GCI knob
uix	int	Horizontal touch position
uiy	int	Vertical touch position
minarc	int	Angle position of minimum value
maxarc	int	Angle position of maximum value
ming	int	Value at minimum position
maxg	int	Value at maximum position

Return: Value of the Knob (int16_t)

Example

sliderVal = gfx.imageAutoKnob(iKnob1, gfx.touch_GetX(), gfx.touch_GetY(), 30, 330, 0, 100);

Note

This function is only available for capacitive and resistive touch displays

CheckButtons

Evaluate the button touches and return the buttonx touched

Syntax: gfx.CheckButtons();

Return: ID of the ButtonX that was touched (uint8_t)

Example

btnxPressed = gfx.CheckButtons();

Note

This function is only available for capacitive and resistive touch displays

GetSliderValue

Calculate the value of slider based on touch position

Syntax: gfx.GetSliderValue(ui, axis, uiv, ming, maxg);

Argument	Type	Description
ui	uint16_t	Specifies the GCI slider
axis	uint16_t	Indicates whether the slider is a HORIZONTAL_SLIDER or VERTICAL SLIDER
uiv	uint16_t	Touch position based on the orientation for the slider  - X position for horizontal  - Y position for vertical
ming	uint16_t	Touch offset near the minimum position
maxg	uint16_t	Touch offset near the maximum position

Return: Value of the slider (uint16_t)

Example

sliderVal = gfx.GetSliderValue(iSlider1, HORIZONTAL_SLIDER, gfx.touch_GetX(), 8, 8);

Note

This function is only available for capacitive and resistive touch displays

DecodeKeypad

Decodes the key pressed in the keyboard

Syntax: gfx.DecodeKeypad(kpad, kpress, kbks, kbck);

Argument	Type	Description
kpad	int	Base keyboard widget
kpress	int	Keyboard button pressed
kbks	byte *	Keyboard information generated by Workshop4
kbck	int8_t *	Keyboard information generated by Workshop4

Return: Value of the pressed key (int)

Note

1. This function is only available for capacitive and resistive touch displays.
2. It is highly advisable to use Workshop4 when using this function.

ResetKeypad

Resets the state of the keypad

Syntax: gfx.ResetKeypad();

Return: None (void)

Note

This function is only available for capacitive and resistive touch displays

KeypadStatus

Checks whether the keypad state is on SHIFT, CAPSLOCK or CTRL or not.

Syntax: gfx.KeypadStatus(keyType);

Argument	Type	Description
keyType	int	Specify the status to check

Return: true if successful otherwise false (boolean)

Example

isShifted = gfx.KeypadStatus(SHIFT);
isCapsLocked = gfx.KeypadStatus(CAPSLOCK);
isCtrled = gfx.KeypadStatus(CTRL);

Note

This function is only available for capacitive and resistive touch displays

SpriteTouched

Returns the id of the sprite touched

Syntax: gfx.SpriteTouched();

Return: ID of the touched sprite (int)

Example

int spriteTouched = gfx.SpriteTouched();

Note

This function is only available for capacitive and resistive touch displays

touchCalibration

Starts touch calibration for resistive touch displays

Syntax: gfx.touchCalibration();

Return: None (void)

Example

if (!calibrated) {
    gfx.touchCalibration();
    calibrated = true;
}

Note

This is only available for resistive touch displays

RTC Functions

The functions included in this section are only applicable for gen4-ESP32 variants with on-board RTC. This includes display modules sized

RTCinit

Initializes the RTC module

Syntax: gfx.RTCinit();

Return: None (void)

Example

gfx.RTCinit();

Note

This is only available for display modules with built-in RTC.

RTCstartClock

Starts the RTC clock

Syntax: gfx.RTCstartClock();

Return: None (void)

Example

gfx.RTCstartClock();

Note

This is only available for display modules with built-in RTC.

RTCstopClock

Stops the RTC clock

Syntax: gfx.RTCstopClock();

Return: None (void)

Example

gfx.RTCstopClock();

Note

This is only available for display modules with built-in RTC.

RTCcheckClockIntegrity

Checks for clock integrity

Syntax: gfx.RTCcheckClockIntegrity();

Return: Clock integrity (bool)

Example

rtcOk = gfx.RTCcheckClockIntegrity();

Note

This is only available for display modules with built-in RTC.

RTCsetYear

Sets the year value for the RTC

Syntax: gfx.RTCsetYear(year);

Argument	Type	Description
year	uint16_t	Specify the new year value to set the RTC to

Return: None (void)

Example

gfx.RTCsetYear(2023);

Note

This is only available for display modules with built-in RTC.

RTCsetMonth

Sets the month value for the RTC from 1 to 12

Syntax: gfx.RTCsetMonth(month);

Argument	Type	Description
month	uint8_t	Specify the new month value to set the RTC to

Return: None (void)

Example

gfx.RTCsetMonth(9);

Note

This is only available for display modules with built-in RTC.

RTCsetDay

Sets the day of month value for the RTC from 1 to 31

Syntax: gfx.RTCsetDay(day);

Argument	Type	Description
day	uint8_t	Specify the new day value to set the RTC to

Return: None (void)

Example

gfx.RTCsetDay(5);

Note

This is only available for display modules with built-in RTC.

RTCsetHour

Sets the hour value for the RTC from 0 to 23

Syntax: gfx.RTCsetHour(hour);

Argument	Type	Description
hour	uint8_t	Specify the new hour value to set the RTC to

Return: None (void)

Example

gfx.RTCsetHour(14);

Note

This is only available for display modules with built-in RTC.

RTCsetMinute

Sets the minutes value for the RTC from 0 to 59

Syntax: gfx.RTCsetMinute(minute);

Argument	Type	Description
minute	uint8_t	Specify the new minute value to set the RTC to

Return: None (void)

Example

gfx.RTCsetMinute(42);

Note

This is only available for display modules with built-in RTC.

RTCsetSecond

Sets the seconds value for the RTC from 0 to 59

Syntax: gfx.RTCsetSecond(second);

Argument	Type	Description
second	uint8_t	Specify the new second value to set the RTC to

Return: None (void)

Example

gfx.RTCsetSecond(57);

Note

This is only available for display modules with built-in RTC.

RTCgetTime

Queries the current time

Syntax: gfx.RTCgetTime();

Return: Current time in Time struct (Time)

Example

Time curTime = gfx.RTCgetTime();

Note

This is only available for display modules with built-in RTC.

RTCformatDateTime

Formats the time and return a pointer to the string.

The following are the accepted styles:

• RTC_TIMEFORMAT_HM
• RTC_TIMEFORMAT_HMS
• RTC_TIMEFORMAT_YYYY_MM_DD
• RTC_TIMEFORMAT_MM_DD_YYYY
• RTC_TIMEFORMAT_DD_MM_YYYY
• RTC_TIMEFORMAT_YYYY_MM_DD_H_M_S
• RTC_TIMEFORMAT_DD_MM_YYYY_H_M_S

If an invalid format is specified, this will default to RTC_TIMEFORMAT_HM

Syntax: gfx.RTCformatDateTime(style);

Argument	Type	Description
style	uint8_t	Specify the style to format the current time to

Return: Character pointer to the date/time string (const char *)

Example

const char * curTimeStr = gfx.RTCformatDateTime(RTC_TIMEFORMAT_HMS);

Note

This is only available for display modules with built-in RTC.

Revision History

Document Revision

Revision Number	Date	Description
1.0	25/09/2023	Initial Public Release Version
1.1	29/01/2024	Added the functions: PutPixelAlpha, VlineX, HlineX, RectangleFilledX, GetFrameBuffer, setScrollDirection, WriteToFrameBuffer, FlushArea
1.2	10/06/2024	Added the following functions: CircleFilledAA, TriangleAA, LineAA, Clipping, ClippingWindow