Text

Text in the built-in 5x7 font or any GFXfont: plain, scaled, measured, and outlined/shadowed banners. More...

Functions
void	gfx_setFont (const GFXfont *f)
	Selects the font every text call uses from now on.
const GFXfont *	gfx_font (void)
	The current font.
int	gfx_fontLineHeight (void)
	Baseline-to-baseline line spacing of the current font, at scale 1.
int	gfx_fontBaseline (void)
	The current font's ascent: how far its tallest ink reaches above the baseline, at scale 1.
void	gfx_char (int x, int y, char ch, uint8_t c)
	Draws one character.
void	gfx_charScaled (int x, int y, char ch, uint8_t c, uint8_t scale)
	Draws one character, scaled up by a whole number.
void	gfx_text (int x, int y, const char *s, uint8_t c)
	Draws a string in the current font.
void	gfx_textScaled (int x, int y, const char *s, uint8_t c, uint8_t scale)
	Draws a string in the current font, scaled up by a whole number.
int	gfx_textWidth (const char *s)
	Advance width of a string in the current font - the number to use for centring and right-alignment.
int	gfx_textWidthScaled (const char *s, uint8_t scale)
	Advance width of a string in the current font at a scale.
void	gfx_textBounds (const char *s, int x, int y, uint8_t scale, int *bx, int *by, int *bw, int *bh)
	Bounding box of a string drawn at (x, y).
bool	gfx_textFx (int x, int y, const char *s, uint8_t scale, uint8_t fill, int outline=-1, int shadow=-1, const uint8_t *ramp=nullptr, const int8_t *dy=nullptr)
	Draws outlined, shadowed or gradient-filled text - titles and banners.

Detailed Description

Text in the built-in 5x7 font or any GFXfont: plain, scaled, measured, and outlined/shadowed banners.

The default font is the built-in 5x7, ASCII 32..126, 475 bytes, no setup. gfx_setFont() swaps in a proportional GFXfont; gfx_setFont(nullptr) puts the built-in one back.

#include <fonts/CHGfx_Sans12.h>
Gfx.setFont(&CHGfx_Sans12);
Gfx.print(4, 20, "Hello", WHITE);

GFXfont is byte-for-byte Adafruit's format (see CHGfx_gfxfont.h), so anything from Adafruit_GFX's Fonts/ directory, or produced by either font converter, works here as-is:

#include <Fonts/FreeSans9pt7b.h>
Gfx.setFont(&FreeSans9pt7b);

The origin changes with the font. Built-in font: y is the TOP of the glyph box. Custom font: y is the BASELINE, with ascenders above it and descenders below. Adafruit_GFX behaves exactly the same way, which is why it is worth living with. gfx_fontBaseline() converts:

gfx_text(x, y + gfx_fontBaseline(), s, c);   // y = top, either font

A newline starts a new line at the original x; a carriage return is ignored. Characters outside the font's range are drawn as '?', or dropped if the font has no '?'.

Bundled fonts live in src/fonts/ - see Fonts for the list, their flash cost, and how to convert your own with extras/fontconvert.py.

Function Documentation

gfx_setFont()

void gfx_setFont

(

const GFXfont *

f

)

Selects the font every text call uses from now on.

Scans the glyphs once to find the font's ascent (for gfx_fontBaseline()).

Parameters

f	A GFXfont, or nullptr for the built-in 5x7.

gfx_font()

const GFXfont * gfx_font

(

void

)

The current font.

Returns

The GFXfont last given to gfx_setFont(), or nullptr for the built-in 5x7.

gfx_fontLineHeight()

int gfx_fontLineHeight

(

void

)

Baseline-to-baseline line spacing of the current font, at scale 1.

Returns

Pixels: the font's yAdvance, or 8 for the built-in font. Multiply by your scale.

gfx_fontBaseline()

int gfx_fontBaseline

(

void

)

The current font's ascent: how far its tallest ink reaches above the baseline, at scale 1.

Returns

Pixels; 0 for the built-in font, since that one is already top-anchored. Add it to a top y to get the y to draw at.

gfx_char()

void gfx_char	(	int	x,
		int	y,
		char	ch,
		uint8_t	c
	)

Draws one character.

Parameters

x	Left edge (pen position).
y	Top of the glyph box (built-in font) or baseline (GFXfont).
ch	The character.
c	Palette index.

gfx_charScaled()

void gfx_charScaled	(	int	x,
		int	y,
		char	ch,
		uint8_t	c,
		uint8_t	scale
	)

Draws one character, scaled up by a whole number.

Parameters

x	Left edge (pen position).
y	Top of the glyph box (built-in font) or baseline (GFXfont).
ch	The character.
c	Palette index.
scale	Integer scale, 1 or more (0 counts as 1).

gfx_text()

void gfx_text	(	int	x,
		int	y,
		const char *	s,
		uint8_t	c
	)

Draws a string in the current font.

The built-in font advances 6 pixels a character.

Parameters

x	Left edge of the first character.
y	Top of the glyph box (built-in font) or baseline (GFXfont).
s	Null-terminated string; a newline starts a new line at x.
c	Palette index.

gfx_textScaled()

void gfx_textScaled	(	int	x,
		int	y,
		const char *	s,
		uint8_t	c,
		uint8_t	scale
	)

Draws a string in the current font, scaled up by a whole number.

Parameters

x	Left edge of the first character.
y	Top of the glyph box (built-in font) or baseline (GFXfont).
s	Null-terminated string; a newline starts a new line at x.
c	Palette index.
scale	Integer scale, 1 or more (0 counts as 1).

gfx_textWidth()

int gfx_textWidth

(

const char *

s

)

Advance width of a string in the current font - the number to use for centring and right-alignment.

Parameters

s	Null-terminated string.

Returns

Width in pixels; for a multi-line string, the widest line.

gfx_textWidthScaled()

int gfx_textWidthScaled	(	const char *	s,
		uint8_t	scale
	)

Advance width of a string in the current font at a scale.

Parameters

s	Null-terminated string.
scale	Integer scale, 1 or more (0 counts as 1).

Returns

Width in pixels; for a multi-line string, the widest line.

gfx_textBounds()

void gfx_textBounds	(	const char *	s,
		int	x,
		int	y,
		uint8_t	scale,
		int *	bx,
		int *	by,
		int *	bw,
		int *	bh
	)

Bounding box of a string drawn at (x, y).

Same units and origin convention as gfx_text() - use it to frame or erase text without guessing. With a custom font this is the tight ink box; with the built-in font it is the 5x7 cell box, so a leading space still counts. A string with no ink gives a 0x0 box at (x, y).

Parameters

	s	Null-terminated string.
	x	Where the string would be drawn.
	y	Where the string would be drawn (top or baseline, as gfx_text()).
	scale	Integer scale, 1 or more (0 counts as 1).
[out]	bx	Left edge of the box (may be nullptr).
[out]	by	Top edge of the box (may be nullptr).
[out]	bw	Width of the box (may be nullptr).
[out]	bh	Height of the box (may be nullptr).

gfx_textFx()

bool gfx_textFx	(	int	x,
		int	y,
		const char *	s,
		uint8_t	scale,
		uint8_t	fill,
		int	outline = -1,
		int	shadow = -1,
		const uint8_t *	ramp = nullptr,
		const int8_t *	dy = nullptr
	)

Draws outlined, shadowed or gradient-filled text - titles and banners.

Same font, origin and scale rules as gfx_textScaled(). Drawing the glyphs nine times over would cost ~9x a plain print. This renders the text once into a 1 bpp mask in gfx_chunkScratch(), grows the outline out of it with word-wide ORs and paints each row as spans, so a 3x outlined, shadowed nine-letter banner costs about 2.9 ms. The mask - the text's ink box plus a 1 px margin - must fit in 1 KB: text up to 126x62 px, or 254x30. Waits for any flush in flight first.

Parameters

x	Left edge, as gfx_text().
y	Top (built-in font) or baseline (GFXfont), as gfx_text().
s	Null-terminated string.
scale	Integer scale, 1 or more.
fill	Palette index of the letters.
outline	Palette index of a 1 px ring around them (all 8 directions), or -1 (the default) for none.
shadow	Palette index of the outlined shape again, 1 px down-right, underneath, or -1 (the default) for none.
ramp	Optional: a fill colour per pixel row of the text, top to bottom (as many entries as the text is tall), replacing fill; nullptr for none.
dy	Optional: a vertical offset per character, for wavy text; nullptr for none.

Returns

false, having drawn nothing, if the text is too big for the mask; true otherwise (also when nothing was inside the clip).