added Font names, method to get font names. Methods to get a string size in pixels - so user does not deal with font objects. updated examples

Author: Kirk

docs/api_draw.md

@@ -58,6 +58,44 @@ QwiicFont * getFont(void)
 | :--- | :--- | :--- |
 | return value | `QwiicFont*` | A pointer to the current font. See `setFont()` for font object details.|
 
+### getFontName()
+
+This method returns the height in pixels of a provided String based on the current device font.
+
+```c++
+String getFontName(void)
+```
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| return value | String | The name of the current font.|
+
+### getStringWidth()
+
+This method returns the width in pixels of a provided String based on the current device font.
+
+```c++
+unsigned int getStringWidth(String text)
+```
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| text | `String` | The string used to determine width |
+| return value | `unsigned int` | The width of the provide string, as determined using the current font.|
+
+### getStringHeight()
+
+This method returns the height in pixels of a provided String based on the current device font.
+
+```c++
+unsigned int getStringHeight(String text)
+```
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| text | `String` | The string used to determine height |
+| return value | `unsigned int` | The height of the provide string, as determined using the current font.|
+
 ### setDrawMode()
 This method sets the current draw mode for the library. The draw mode determines how pixels are set on the screen during drawing operations. 
 

examples/Example-01_Hello/Example-01_Hello.ino

@@ -22,9 +22,6 @@
 
 #include <SparkFun_Qwiic_OLED.h> //http://librarymanager/All#SparkFun_Qwiic_Graphic_OLED
 
-// Add in our font descriptor -- so we can center the text on the scren
-#include <res/qw_fnt_5x7.h>
-
 // The Library supports three different types of SparkFun boards. The demo uses the following
 // defines to determine which device is being used. Uncomment the device being used for this demo.
 
@@ -56,13 +53,14 @@ void setup()
 
     String hello = "hello"; // our message
 
-    // Center our message on the screen. Use our Font Descriptor: QW_FONT_5X7, the default
-    // font of the system.
+    // Center our message on the screen. Get the screen size of the "hello" string,
+    // calling the getStringWidth() and getStringHeight() methods on the oled
 
-    // starting x position - width minus string length (font width * number of characters) / 2
-    int x0 = (myOLED.getWidth() - QW_FONT_5X7.width * hello.length()) / 2;
+    // starting x position - screen width minus string width  / 2
+    int x0 = (myOLED.getWidth() - myOLED.getStringWidth(hello)) / 2;
 
-    int y0 = (myOLED.getHeight() - QW_FONT_5X7.height) / 2;
+    // starting y position - screen height minus string height / 2 
+    int y0 = (myOLED.getHeight() - myOLED.getStringHeight(hello)) / 2;
 
     // Draw the text - color of black (0)
     myOLED.text(x0, y0, hello, 0);

examples/Example-04_Text/Example-04_Text.ino

@@ -52,7 +52,6 @@ int nFONTS = sizeof(demoFonts) / sizeof(demoFonts[0]);
 int iFont = 0;
 
 // Some vars for the title.
-int xTitle, yTitle;
 String strTitle = "<<Font>>";
 QwiicFont *pFntTitle = &QW_FONT_5X7;
 
@@ -72,25 +71,19 @@ void setup()
     }
     Serial.println("Begin success");
 
-    // Position to use for the time/banner displayed before each font
-
-    // starting x position - width minus string length (font width * number of characters) / 2
-    xTitle = (myOLED.getWidth() - (pFntTitle->width + 1) * strTitle.length()) / 2;
-
-    yTitle = (myOLED.getHeight() - pFntTitle->height) / 2;
 }
 
 void loop()
 {
-    // Write out a title
-    writeTitle();
-
-    delay(1000);
-
     // next font for display
     iFont = (iFont + 1) % nFONTS;
     myOLED.setFont(demoFonts[iFont]);
 
+    // Write font name to screen
+    writeTitle();
+
+    delay(1000);
+
     // Write out the full font char set
     writeFontChars();
 
@@ -101,16 +94,16 @@ void loop()
 void writeFontChars()
 {
     // get the font
-    QwiicFont *pFont = myOLED.getFont();
+    QwiicFont * currFont = myOLED.getFont();
 
     // how many chars can a screen handle? (x * y)
-    uint16_t screenChars = myOLED.getWidth() / (pFont->width + 1); // X
-    uint8_t nY = myOLED.getHeight() / pFont->height;               // Y
+    uint16_t screenChars = myOLED.getWidth() / (currFont->width + 1); // X
+    uint8_t nY = myOLED.getHeight() / currFont->height;               // Y
 
     screenChars *= (nY == 0 ? 1 : nY); // need at least 1 row
 
     // Loop over the characters in the font.
-    for (int i = 0; i < pFont->n_chars; i++)
+    for (int i = 0; i < currFont->n_chars; i++)
     {
 
         if (i % screenChars == 0)
@@ -122,7 +115,7 @@ void writeFontChars()
 
         // if the character is a carriage return, send a blank - otherwise the
         // write routine will perform a CR and lead to a confusing display.
-        myOLED.write((i + pFont->start != '\n') ? i + pFont->start : ' ');
+        myOLED.write((i + currFont->start != '\n') ? i + currFont->start : ' ');
 
         myOLED.display(); // show the added char
 
@@ -133,14 +126,35 @@ void writeFontChars()
 // Simple title for a font
 void writeTitle()
 {
+
+    // Get the current font name
+    String strTitle = myOLED.getFontName();
+
+    // save our current font, then switch to font for title
+    QwiicFont * currFont = myOLED.getFont();
+   
     // Set title font font
     myOLED.setFont(pFntTitle);
 
+    // Position to use for the time/banner displayed before each font
+
+    // Get the width of the title in screen size
+    int width = myOLED.getStringWidth(strTitle);
+
+    // if the string is wider than the screen, set x at 0, otherwise center text
+
+    int xTitle = (width >= myOLED.getWidth() ? 0 : (myOLED.getWidth() - width) / 2);
+
+    // starting y position - width minus string height / 2. No need to chech height, 5x7 font fits everything
+    int yTitle = (myOLED.getHeight() - myOLED.getStringHeight(strTitle)) / 2;
+
     myOLED.erase();
 
     // Draw the text
     myOLED.text(xTitle, yTitle, strTitle);
 
     // There's nothing on the screen yet - Now send the graphics to the device
     myOLED.display();
+
+    myOLED.setFont(currFont);
 }

examples/Example-05_ScrollFlip/Example-05_ScrollFlip.ino

@@ -129,7 +129,7 @@ void setup()
     }
     Serial.println("Begin success");
 
-    yoffset = (myOLED.getHeight() - myOLED.getFont()->height) / 2;
+    yoffset = (myOLED.getHeight() - myOLED.getStringHeight("a")) / 2;
 
     delay(1000);
 }

src/SparkFun_Qwiic_OLED.h

@@ -402,6 +402,66 @@ class QwiicOLEDBaseClass : public Print
         return _device.get_font();
     }
 
+    ///////////////////////////////////////////////////////////////////////
+    // getFontName()
+    //
+    // This method returns the name of the current font for the device.
+
+    String getFontName(void)
+    {
+        QwiicFont *pFont = _device.get_font();
+
+        if(!pFont)
+            return String("");
+
+        return String(pFont->name);
+    }
+    ///////////////////////////////////////////////////////////////////////
+    // getStringWidth()
+    //
+    // Returns the width of the provide string using the current font.
+    //
+    // Parameter    Description
+    // ---------    -----------------------------
+    //  text        The string used to determine width
+    //  retval      The width of the provide string, as determined using the current font.
+
+    unsigned int getStringWidth(String &text)
+    {
+        return getStringWidth(text.c_str());
+    }
+    unsigned int getStringWidth(const char *text)
+    {
+
+        uint16_t height, width;
+
+        return (_device.get_string_size(text, width, height) ? width : 0);
+
+    }
+
+    ///////////////////////////////////////////////////////////////////////
+    // getStringHeight()
+    //
+    // Returns the height of the provide string using the current font.
+    //
+    // Parameter    Description
+    // ---------    -----------------------------
+    //  text        The string used to determine height
+    //  retval      The height of the provide string, as determined using the current font.
+
+    unsigned int getStringHeight(String &text)
+    {
+        return getStringHeight(text.c_str());
+    }
+
+    unsigned int getStringHeight(const char *text)
+    {
+
+        uint16_t height, width;
+
+        return (_device.get_string_size(text, width, height) ? height : 0);
+
+    }
     ///////////////////////////////////////////////////////////////////////
     // setDrawMode()
     //
@@ -700,7 +760,7 @@ class QwiicOLEDBaseClass : public Print
 
         QwiicFont *pFont = _device.get_font();
 
-        if (!pFont) // no Font?! No dice?
+        if (!pFont) // no Font?! No dice
             return 0;
 
         switch (theChar)

src/qwiic_grbuffer.cpp

@@ -163,7 +163,7 @@ bool QwGrBufferDevice::init(void)
     return init_draw_functions();
 }
 ////////////////////////////////////////////////////////////////////////////////////
-// Font things
+// Font related things
 ////////////////////////////////////////////////////////////////////////////////////
 // init_font()
 //
@@ -214,6 +214,36 @@ void QwGrBufferDevice::set_font(const QwFont *font)
         init_font();
 }
 
+////////////////////////////////////////////////////////////////////////////////////////
+// get_string_size()
+//
+// Return the size (width, height) in pixels of the given string using the current font
+
+bool QwGrBufferDevice::get_string_size(const char *text, uint16_t &width, uint16_t &height)
+{
+
+    if(!_currFont) // no font?
+        init_font();
+
+    // no font, no text - no dice
+    if(!_currFont || !text)
+        return false; 
+
+    int sLen = strlen(text);
+
+    width = sLen * _currFont->width;
+
+    // The 5x7 font width is off by one - historical - was same in orig lib, which fonts
+    // are used. 
+    if(_currFont == &QW_FONT_5X7)
+        width += sLen;
+
+    height = (sLen  > 0 ? _currFont->height : 0 );
+
+    return true;
+
+}
+
 ////////////////////////////////////////////////////////////////////////////////////////
 // Public Graphics Methods
 ////////////////////////////////////////////////////////////////////////////////////////

src/qwiic_grbuffer.h

@@ -175,12 +175,15 @@ class QwGrBufferDevice : protected _QwIDraw
     // Lifecycle
     virtual bool init(void);
 
-    // current font methods
+    // Font methods
     void init_font(void);
     void set_font(QwFont &font);
     void set_font(const QwFont *font);
     QwFont *get_font(void);
 
+    // Returns the size of a string - in pixels - using current font
+    bool get_string_size(const char *text, uint16_t &width, uint16_t &height);
+
     // Public Interface - Graphics interface
     void line(uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, uint8_t clr = 1);
 

src/res/_fnt_31x48.h

@@ -26,6 +26,7 @@ August 13, 2015
 #define FONT_31X48_START        65
 #define FONT_31X48_NCHAR        58
 #define FONT_31X48_MAP_WIDTH    62
+#define FONT_31X48_NAME         "31 x 48"
 
 #if defined(ARDUINO_ARCH_MBED)
 	// ARDUINO_ARCH_MBED (APOLLO3 v2) does not support or require pgmspace.h / PROGMEM

src/res/_fnt_5x7.h

@@ -30,6 +30,7 @@ July 27, 2015
 #define FONT_5X7_START        0
 #define FONT_5X7_NCHAR        255
 #define FONT_5X7_MAP_WIDTH    1275
+#define FONT_5X7_NAME         "5 x 7"
 
 // Standard ASCII 5x7 font
 #if defined(ARDUINO_ARCH_MBED)

src/res/_fnt_7segment.h

@@ -31,6 +31,7 @@ July 27, 2015
 #define FONT_7SEG_START        46
 #define FONT_7SEG_NCHAR        13
 #define FONT_7SEG_MAP_WIDTH    130
+#define FONT_7SEG_NAME         "7 Segment"
 
 #if defined(ARDUINO_ARCH_MBED)
 	// ARDUINO_ARCH_MBED (APOLLO3 v2) does not support or require pgmspace.h / PROGMEM