Add UTF-8 on/off control via new setAttribute function

No change to legacy sketches meeded, UTF-8 decoding is on by default.
Add colour test example.

TFT_eSPI.cpp

@@ -218,7 +218,9 @@ TFT_eSPI::TFT_eSPI(int16_t w, int16_t h)
   locked = true;        // ESP32 transaction mutex lock flags
   inTransaction = false;
 
-  _booted = true;
+  _booted   = true;
+  _cp437    = true;
+  _utf8     = true;
 
   addr_row = 0xFFFF;
   addr_col = 0xFFFF;
@@ -703,14 +705,14 @@ uint16_t TFT_eSPI::readPixel(int32_t x0, int32_t y0)
   // Dummy read to throw away don't care value
   tft_Read_8();
   
-  #if !defined (ILI9488_DRIVER)
+  //#if !defined (ILI9488_DRIVER)
 
     // Read the 3 RGB bytes, colour is actually only in the top 6 bits of each byte
     // as the TFT stores colours as 18 bits
     uint8_t r = tft_Read_8();
     uint8_t g = tft_Read_8();
     uint8_t b = tft_Read_8();
-
+/*
   #else
 
     // The 6 colour bits are in MS 6 bits of each byte, but the ILI9488 needs an extra clock pulse
@@ -720,7 +722,7 @@ uint16_t TFT_eSPI::readPixel(int32_t x0, int32_t y0)
     uint8_t b = (tft_Read_8()&0x7E)<<1;
 
   #endif
-
+*/
   CS_H;
 
   #ifdef TFT_SDA_READ
@@ -3903,6 +3905,46 @@ void TFT_eSPI::invertDisplay(boolean i)
 }
 
 
+/**************************************************************************
+** Function name:           setAttribute
+** Description:             Sets a control parameter of an attribute
+**************************************************************************/
+void TFT_eSPI::setAttribute(uint8_t attr_id, uint8_t param) {
+    switch (attr_id) {
+            break;
+        case 1:
+            _cp437 = param;
+            break;
+        case 2:
+            _utf8  = param;
+            break;
+        //case 3: // TBD future feature control
+        //    _tbd = param;
+        //    break;
+    }
+}
+
+
+/**************************************************************************
+** Function name:           getAttribute
+** Description:             Get value of an attribute (control parameter)
+**************************************************************************/
+uint8_t TFT_eSPI::getAttribute(uint8_t attr_id) {
+    switch (attr_id) {
+        case 1: // ON/OFF control of full CP437 character set
+            return _cp437;
+            break;
+        case 2: // ON/OFF control of UTF-8 decoding
+            return _utf8;
+            break;
+        //case 3: // TBD future feature control
+        //    return _tbd;
+        //    break;
+    }
+
+    return false;
+}
+
 /***************************************************************************************
 ** Function name:           decodeUTF8
 ** Description:             Serial UTF-8 decoder with fall-back to extended ASCII
@@ -3998,12 +4040,14 @@ uint16_t TFT_eSPI::decodeUTF8(uint8_t *buf, uint16_t *index, uint16_t remaining)
 ***************************************************************************************/
 size_t TFT_eSPI::write(uint8_t utf8)
 {
-  uint16_t uniCode = decodeUTF8(utf8);
-
-  if (!uniCode) return 1;
-
   if (utf8 == '\r') return 1;
 
+  uint16_t uniCode = utf8;
+
+  if (_utf8) uniCode = decodeUTF8(utf8);
+
+  if (uniCode == 0) return 1;
+
 #ifdef SMOOTH_FONT
   if(fontLoaded)
   {

TFT_eSPI.h

@@ -808,8 +808,8 @@ class TFT_eSPI : public Print {
 
   void     setAddrWindow(int32_t xs, int32_t ys, int32_t w, int32_t h);
 
-           // Compatibility additions (non-essential)
+           // Compatibility additions
-  void     startWrite(void);                         // Begin SPI transaction (not normally needed)
+  void     startWrite(void);                         // Begin SPI transaction
   void     writeColor(uint16_t color, uint32_t len); // Write colours without transaction overhead
   void     endWrite(void);                           // End SPI transaction
 
@@ -825,6 +825,10 @@ class TFT_eSPI : public Print {
   void     end_SDA_Read(void);
 #endif
 
+  // Set or get an arbitrary library attribute or configuration option
+  void     setAttribute(uint8_t id = 0, uint8_t a = 0);
+  uint8_t  getAttribute(uint8_t id = 0);
+
   void     getSetup(setup_t& tft_settings); // Sketch provides the instance to populate
 
   int32_t  cursor_x, cursor_y, padX;
@@ -877,17 +881,19 @@ class TFT_eSPI : public Print {
 
   uint32_t fontsloaded;
 
-  uint8_t  glyph_ab,  // glyph height above baseline
+  uint8_t  glyph_ab,   // glyph delta Y (height) above baseline
-           glyph_bb;  // glyph height below baseline
+           glyph_bb;   // glyph delta Y (height) below baseline
 
-  bool     isDigits;  // adjust bounding box for numbers to reduce visual jiggling
+  bool     isDigits;   // adjust bounding box for numbers to reduce visual jiggling
   bool     textwrapX, textwrapY;   // If set, 'wrap' text at right and optionally bottom edge of display
   bool     _swapBytes; // Swap the byte order for TFT pushImage()
   bool     locked, inTransaction; // Transaction and mutex lock flags for ESP32
 
-  bool     _booted;
+  bool     _booted;    // init() or begin() has already run once
+  bool     _cp437;     // If set, use correct CP437 charset (default is ON)
+  bool     _utf8;      // If set, use UTF-8 decoder in print stream 'write()' function (default ON)
 
-  uint32_t _lastColor;
+  uint32_t _lastColor; // Buffered value of last colour used
 
 #ifdef LOAD_GFXFF
   GFXfont  *gfxFont;

examples/Test and diagnostics/Colour_Test/Colour_Test.ino

@@ -0,0 +1,132 @@
+
+//   Diagnostic test for the displayed colour order
+//
+// Writen by Bodmer 17/2/19 for the TFT_eSPI library:
+// https://github.com/Bodmer/TFT_eSPI
+
+/* 
+ Different hardware manufacturers use different colour order
+ configurations at the hardware level.  This may result in
+ incorrect colours being displayed.
+
+ Incorrectly displayed colours could also be the result of
+ using the wrong display driver in the library setup file.
+
+ Typically displays have a control register (MADCTL) that can
+ be used to set the Red Green Blue (RGB) colour order to RGB
+ or BRG so that red and blue are swapped on the display.
+
+ This control register is also used to manage the display
+ rotation and coordinate mirroring. The control register
+ typically has 8 bits, for the ILI9341 these are:
+
+ Bit Function
+ 7   Mirror Y coordinate (row address order)
+ 6   Mirror X coordinate (column address order)
+ 5   Row/column exchange (for rotation)
+ 4   Refresh direction (top to bottom or bottom to top in portrait orientation)
+ 3   RGB order (swaps red and blue)
+ 2   Refresh direction (top to bottom or bottom to top in landscape orientation)
+ 1   Not used
+ 0   Not used
+
+ The control register bits can be written with this example command sequence:
+ 
+    tft.writecommand(TFT_MADCTL);
+    tft.writedata(0x48);          // Bits 6 and 3 set
+    
+ 0x48 is the default value for ILI9341 (0xA8 for ESP32 M5STACK)
+ in rotation 0 orientation.
+ 
+ Another control register can be used to "invert" colours,
+ this swaps black and white as well as other colours (e.g.
+ green to magenta, red to cyan, blue to yellow).
+ 
+ To invert colours insert this line after tft.init() or tft.begin():
+
+    tft.invertDisplay( invert ); // Where invert is true or false
+
+*/
+
+#include <SPI.h>
+
+#include <TFT_eSPI.h>       // Hardware-specific library
+
+TFT_eSPI tft = TFT_eSPI();  // Invoke custom library
+
+void setup(void) {
+  tft.init();
+
+  tft.fillScreen(TFT_BLACK);
+  
+  // Set "cursor" at top left corner of display (0,0) and select font 4
+  tft.setCursor(0, 0, 4);
+
+  // Set the font colour to be white with a black background
+  tft.setTextColor(TFT_WHITE, TFT_BLACK);
+
+  // We can now plot text on screen using the "print" class
+  tft.println("Intialised default\n");
+  tft.println("White text");
+  
+  tft.setTextColor(TFT_RED, TFT_BLACK);
+  tft.println("Red text");
+  
+  tft.setTextColor(TFT_GREEN, TFT_BLACK);
+  tft.println("Green text");
+  
+  tft.setTextColor(TFT_BLUE, TFT_BLACK);
+  tft.println("Blue text");
+
+  delay(10000);
+
+}
+
+void loop() {
+
+  tft.invertDisplay( false ); // Where i is true or false
+ 
+  tft.fillScreen(TFT_BLACK);
+  
+  tft.setCursor(0, 0, 4);
+
+  tft.setTextColor(TFT_WHITE, TFT_BLACK);
+  tft.println("Invert OFF\n");
+
+  tft.println("White text");
+  
+  tft.setTextColor(TFT_RED, TFT_BLACK);
+  tft.println("Red text");
+  
+  tft.setTextColor(TFT_GREEN, TFT_BLACK);
+  tft.println("Green text");
+  
+  tft.setTextColor(TFT_BLUE, TFT_BLACK);
+  tft.println("Blue text");
+
+  delay(10000);
+
+
+  // Binary inversion of colours
+  tft.invertDisplay( true ); // Where i is true or false
+ 
+  tft.fillScreen(TFT_BLACK);
+  
+  tft.setCursor(0, 0, 4);
+
+  tft.setTextColor(TFT_WHITE, TFT_BLACK);
+  tft.println("Invert ON\n");
+
+  tft.println("White text");
+  
+  tft.setTextColor(TFT_RED, TFT_BLACK);
+  tft.println("Red text");
+  
+  tft.setTextColor(TFT_GREEN, TFT_BLACK);
+  tft.println("Green text");
+  
+  tft.setTextColor(TFT_BLUE, TFT_BLACK);
+  tft.println("Blue text");
+
+  delay(10000);
+}

library.json

@@ -1,6 +1,6 @@
 {
   "name": "TFT_eSPI",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "keywords": "tft, ePaper, display, ESP8266, NodeMCU, ESP32, M5Stack, ILI9341, ST7735, ILI9163, S6D02A1, ILI9486, ST7789",
   "description": "A TFT and ePaper SPI graphics library for ESP8266 and ESP32",
   "repository":

library.properties

@@ -1,5 +1,5 @@
 name=TFT_eSPI
-version=1.4.5
+version=1.4.6
 author=Bodmer
 maintainer=Bodmer
 sentence=A fast TFT graphics library for ESP8266 and ESP32 processors for the Arduino IDE