olikraus / U8g2_for_Adafruit_GFX

Add U8g2 fonts to any Adafruit GFX based graphics library.

• U8g2_for_Adafruit_GFX
  • What is U8g2_for_Adafruit_GFX?
  • Which Adafruit GFX Libraries are Supported?
  • How to use U8g2_for_Adafruit_GFX?
• Reference
  • Command Reference
  • Differences to U8g2

U8g2_for_Adafruit_GFX

Download: https://github.com/olikraus/U8g2_for_Adafruit_GFX/archive/master.zip

What is U8g2_for_Adafruit_GFX?

• Arduino Library
• Adds a the U8g2 text drawing engine to all Adafruit GFX based Arduino librarys.
• All U8g2 fonts can be used
• Support for UTF-8 and Unicode
• Support for Arduino print() command and F() Macro

U8g2 is a graphics library for monochrome displays. U8g2 supports many displays, some of them are also supported by Adafruit GFX based libraries. Others are supported by Adafruit GFX libraries, but are not supported by U8g2. U8g2_for_Adafruit_GFX connects to an existing Adafruit Library and adds support for U8g2 fonts to all Adafruit GFX based libraries.

Which Adafruit GFX Libraries are Supported?

All libraries based on the Adafruit GFX engine are supported. This is a incomplete list of such libraries. Probably many more are supported:

• https://github.com/adafruit/Adafruit_SSD1306 (tested)
• https://github.com/adafruit/Adafruit-ST7735-Library (not tested)
• https://github.com/adafruit/Adafruit-Graphic-VFD-Display-Library (not tested)
• https://github.com/adafruit/Adafruit-HX8340B (not tested)
• https://github.com/adafruit/Adafruit_HX8357_Library (not tested)
• https://github.com/adafruit/Adafruit_ILI9340 (not tested)
• https://github.com/adafruit/Adafruit_ILI9341 (not tested)
• https://github.com/adafruit/Adafruit-PCD8544-Nokia-5110-LCD-library (not tested)

How to use U8g2_for_Adafruit_GFX?

This is a complete example for U8g2_for_Adafruit_GFX connected to Adafruit SSD1306 library:

#include <Adafruit_SSD1306.h>
#include <U8g2_for_Adafruit_GFX.h>

Adafruit_SSD1306 display(/*MOSI*/ 11, /*CLK*/ 13, /*DC*/ 9, /*RESET*/ 8, /*CS*/ 10);
U8G2_FOR_ADAFRUIT_GFX u8g2_for_adafruit_gfx;

void setup() {
  display.begin(SSD1306_SWITCHCAPVCC);
  u8g2_for_adafruit_gfx.begin(display);                 // connect u8g2 procedures to Adafruit GFX
}

void loop() {  
  display.clearDisplay();                               // clear the graphcis buffer  
  u8g2_for_adafruit_gfx.setFontMode(1);                 // use u8g2 transparent mode (this is default)
  u8g2_for_adafruit_gfx.setFontDirection(0);            // left to right (this is default)
  u8g2_for_adafruit_gfx.setForegroundColor(WHITE);      // apply Adafruit GFX color
  u8g2_for_adafruit_gfx.setFont(u8g2_font_helvR14_tf);  // select u8g2 font from here: https://github.com/olikraus/u8g2/wiki/fntlistall
  u8g2_for_adafruit_gfx.setCursor(0,20);                // start writing at this position
  u8g2_for_adafruit_gfx.print(F("Hello World"));
  u8g2_for_adafruit_gfx.setCursor(0,40);                // start writing at this position
  u8g2_for_adafruit_gfx.print(F("Umlaut ÄÖÜ"));            // UTF-8 string with german umlaut chars
  display.display();                                    // make everything visible
  delay(2000);
} 

Reference

Command Reference

• U8G2_FOR_ADAFRUIT_GFX u8g2_for_adafruit_gfx: Constructor call. This must be the first command. No paramenters are required.
• void u8g2_for_adafruit_gfx.begin(Adafruit_GFX &gfx): Connect to Adafruit GFX library
• void u8g2_for_adafruit_gfx.setFont(const uint8_t *font): Assign u8g2 font, see here for a list. Note: The list from the u8g2 project might be a little bit newer, so maybe not allways all fonts are available for this project. See also: https://github.com/olikraus/u8g2/wiki/u8g2reference#setfont
• void u8g2_for_adafruit_gfx.setFontMode(uint8_t is_transparent): Define, whether the background color should be drawn or not. See also: https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontmode
• void u8g2_for_adafruit_gfx.setFontDirection(uint8_t dir): Identical to the u8g2 command https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontdirection
• void u8g2_for_adafruit_gfx.setForegroundColor(uint16_t color): Set the foreground color for the text.
• void u8g2_for_adafruit_gfx.setBackgroundColor(uint16_t color): Set the background color for the text. This is only required if the font mode is not set to transparent.
• void u8g2_for_adafruit_gfx.setCursor(int16_t x, int16_t y): Specify the x/y position for the next print() command. This x/y position is the lower left baseline of a character. For "Arduino" this will be the lower left corner of the A character.
• void u8g2_for_adafruit_gfx.print(...): This is the standard Arduino print function. Any text given here will be output on the display via Adafruit GFX library. See here for further description. Note: This function supports UTF-8.
• int8_t u8g2_for_adafruit_gfx.getFontAscent(void): The height of the character 'A' in the current font.
• int8_t u8g2_for_adafruit_gfx.getFontDescent(void): The extend of 'g' below baseline. This value usually is negative.
• int16_t u8g2_for_adafruit_gfx.getUTF8Width(const char *str): Return the width of the provided string. It is assumed, that str is encoded in UTF8 (this is default for Arduino IDE and gcc/g++).

Differences to U8g2

There are some minor differences to the U8g2 library:

• For U8g2 the color is specified with the setDrawColor() function.
• The print() command supports UTF-8 by default. It also can not be disabled. For U8g2 the UTF-8 support must be enabled first.
• This library does not support the change of the reference position. The reference position is the lower left baseline of a character.

Release Procedure

• Copy font file u8g2_fonts.c to "src" folder
• Change the include file in u8g2_fonts.c from "u8g2.h" to "u8g2_fonts.h"
• Update the list of fonts in "U8g2_for_Adafruit_GFX.h"
• Update keywords.txt
• Update version in library.properties