Add support for international date/time formatting

Author: Electric-Diversions

README.md

@@ -46,6 +46,7 @@ In order to run this project on your device, you will need to setup an applicati
   - Home view with track metadata and album art
   - Cover Art only view
   - Clock view with time and playback progress
+  - Supports 12-hour and 24-hour time formats
   - Diagnostics view with system stats and Spotify state
 
 - **OAuth 2.0 Authorization Flow**
@@ -60,6 +61,7 @@ In order to run this project on your device, you will need to setup an applicati
   - Modular architecture allows easy addition of new Views (UI screens)
   - Built-in monitoring tools for measuring system performance and UI responsiveness
   - Structured and tag-based logging system for easier debugging and analysis
+  - Optional `user.ini` file for easy credential and time zone management
 
 
 <!--Design Context Diagram -->

data/user.ini.template

@@ -26,6 +26,9 @@ client_secret = Enter your Spotify Client Secret here
 ; System Settings:
 ; Timezone format - see
 ;      https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
+; For US date and time formatting, include:
+; ui_date_time_format = US
 ; ----------------------------------------------------------------------
 [system]
-timezone = CST6CDT,M3.2.0,M11.1.0
+timezone = CST6CDT,M3.2.0,M11.1.0
+ui_date_time_format = US

documentation/UserSettings.md

@@ -34,6 +34,7 @@ The template includes guidance on privacy levels and where to enter your credent
 | `[spotify]` | `client_id`    | Your Spotify Developer App Client ID                                     |
 |           | `client_secret`  | Your Spotify Developer App Client Secret                                 |
 | `[system]` | `timezone`      | POSIX timezone format string (see example or link below)                 |
+|             | `ui_date_time_format` | Optional: `US` for 12-hour clock and month-first date format; omit or use other values for international formatting |
 
 > 🔗 Refer to the [POSIX timezone list](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv) for formatting guidance.
 
@@ -113,6 +114,9 @@ client_secret = abcdefghijklmnopqrstuv1234567890
 ; System Settings:
 ; Timezone format - see
 ;      https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
+; For US date and time formatting, include:
+; ui_date_time_format = US
 ; ----------------------------------------------------------------------
 [system]
-timezone = CST6CDT,M3.2.0,M11.1.0
+timezone = CST6CDT,M3.2.0,M11.1.0
+ui_date_time_format = US

src/DisplayUI.cpp

@@ -1200,10 +1200,22 @@ void DisplayUI::rDrawString( const char  *str,
 **    Draws the current time using clock font and updates only when values change.
 ** ===================================================================
 */
-void DisplayUI::drawClockTime(bool isForceRepaint)
+void DisplayUI::drawClockTime(bool isUSFormat, bool isForceRepaint)
 {
+    const int fontSize  = 128;
+    const int fontWidth = 76;
 
-    std::string hours   = getCurrentTimestamp("%l").c_str();  
+    int offset          = 0;
+    std::string hours   = "";
+    if (isUSFormat)
+    {
+        hours  = getCurrentTimestamp("%l").c_str();  
+    }
+    else
+    {
+        hours  = getCurrentTimestamp("%H").c_str();
+        offset = 50;
+    }
     std::string minutes = getCurrentTimestamp("%M").c_str();  
     std::string ampm    = getCurrentTimestamp("%p").c_str();  
     std::string seconds = getCurrentTimestamp("%S").c_str();
@@ -1212,51 +1224,55 @@ void DisplayUI::drawClockTime(bool isForceRepaint)
     static std::string lastMinutes = "";
     static std::string lastAmpm    = "";
 
-    const int fontSize  = 128;
-    const int fontWidth = 76;
-
+    // Hours
     if ((lastHours != hours)
     ||  isForceRepaint)
     {
-        _tft->fillRect(20, 35, fontWidth * 2, 100, toValue(getBackground())); 
-        drawClockString(hours.c_str(), 20, 25, fontSize, TFTColor::White, getBackground());   
+        _tft->fillRect(20 + offset, 35, fontWidth * 2, 100, toValue(getBackground())); 
+        drawClockString(hours.c_str(), 20 + offset, 25, fontSize, TFTColor::White, getBackground());   
         lastHours = hours;     
     }
 
+    // Seconds indicator :
     static bool isLastColonVisible      = true;
     int         iSeconds              = std::stoi(seconds);
     bool        isCurrentColonVisible = (iSeconds % 2 == 0);
     if (isCurrentColonVisible != isLastColonVisible 
     ||  isForceRepaint)
     {
-        _tft->fillRect(180, 53, 35, 84, toValue(getBackground())); 
+        _tft->fillRect(180 + offset, 53, 35, 84, toValue(getBackground())); 
         const char* colonChar = isCurrentColonVisible ? ":" : " ";
-        drawClockString(colonChar, 160, 20, fontSize, TFTColor::Yellow, getBackground());
+        drawClockString(colonChar, 160 + offset, 20, fontSize, TFTColor::Yellow, getBackground());
         isLastColonVisible = isCurrentColonVisible;
     }
 
+    // Minutes
     if ((lastMinutes != minutes)
     ||  isForceRepaint)
     {  
-        _tft->fillRect(225, 35, fontWidth * 2, 100, toValue(getBackground())); 
-        drawClockString(minutes.c_str(), 220, 25, fontSize, TFTColor::White, getBackground());
+        _tft->fillRect(225 + offset, 35, fontWidth * 2, 100, toValue(getBackground())); 
+        drawClockString(minutes.c_str(), 220 + offset, 25, fontSize, TFTColor::White, getBackground());
         lastMinutes = minutes;     
     }
 
-    if ((lastAmpm != ampm)
-    ||  isForceRepaint)
-    { 
-        _tft->fillRect(380, 40, fontWidth, 100, toValue(getBackground())); //toValue(getBackground())); 
-        if (ampm == "AM")
-        {
-            drawClockString(ampm.c_str(), 380, 35, fontSize / 2, TFTColor::Yellow, getBackground());
-        }  
-        else
-        {
-            drawClockString(ampm.c_str(), 380, 80, fontSize / 2, TFTColor::Yellow, getBackground());           
-        } 
-
-        lastAmpm = ampm;     
+    // AM/PM if US Format
+    if (isUSFormat)
+    {
+        if ((lastAmpm != ampm)
+        ||  isForceRepaint)
+        { 
+            _tft->fillRect(380, 40, fontWidth, 100, toValue(getBackground())); //toValue(getBackground())); 
+            if (ampm == "AM")
+            {
+                drawClockString(ampm.c_str(), 380, 35, fontSize / 2, TFTColor::Yellow, getBackground());
+            }  
+            else
+            {
+                drawClockString(ampm.c_str(), 380, 80, fontSize / 2, TFTColor::Yellow, getBackground());           
+            } 
+
+            lastAmpm = ampm;     
+        }
     }
 }
 

src/DisplayUI.h

@@ -161,7 +161,7 @@ class DisplayUI {
                     TFTColor bg,
                     const char  *clearMask);
 
-    void drawClockTime(bool isForceRepaint);
+    void drawClockTime(bool isUSFormat, bool isForceRepaint);
 
     void showTouchDown(TFTColor color = TFTColor::SC_TouchDown);
     void showTouchUp(); 

src/UIViews/ClockView.cpp

@@ -22,6 +22,7 @@
 #include "ThingPulse/util.h"  
 #include "SpotifyArtMgr.h"
 #include "Renderers/BackButtonRenderer.h"
+#include "Vault.h"
 
 /*
 ** ===================================================================
@@ -87,7 +88,7 @@ void ClockView::drawUI()
     if (millis() > _requestDueTime)
     {
         handleDate(false);
-        _pUI->drawClockTime(false);
+        _pUI->drawClockTime(Vault::getInstance().isUSDateTimeFormattingUsed(),false);
         char s[50];
         snprintf(s, sizeof(s), "%s", getCurrentTimestamp("%Y-%m-%d %H:%M:%S").c_str());        
     }
@@ -290,7 +291,12 @@ void ClockView::handlePlayStatus(bool isForcedUpdate)
 */
 void ClockView::handleDate(bool isForceRefresh)
 {
-    std::string        dateStr  = getCurrentTimestamp("%A %B %d %Y").c_str();
+    std::string          format = UI_DATE_FORMAT;
+    if (Vault::getInstance().isUSDateTimeFormattingUsed())
+    {
+        format = UI_DATE_FORMAT_US;
+    }
+    std::string        dateStr  = getCurrentTimestamp(format.c_str()).c_str();
     static std::string lastDate = "";
 
     if ((lastDate != dateStr)
@@ -386,7 +392,7 @@ void ClockView::enteringView()
     // Make sure the UI is painted fresh
     _pUI->setBackground(TFTColor::DarkestGreen, false);
     _pUI->clearScreenHome();  
-    _pUI->drawClockTime(true);
+    _pUI->drawClockTime(Vault::getInstance().isUSDateTimeFormattingUsed(), true);
     _pUI->markUIDirty(true); // force refresh to get album details
 
 }

src/UIViews/HomeView.cpp

@@ -24,6 +24,7 @@
 #include "Renderers/PreviousTrackButtonRenderer.h"
 #include "Renderers/PlayPauseButtonRenderer.h"
 #include "Renderers/NextTrackButtonRenderer.h"
+#include "Vault.h"
 
 /*
 ** ===================================================================
@@ -341,19 +342,26 @@ void HomeView::handlePlayStatus()
 **                    changed.
 **
 ** Notes:
-**    - The time is displayed in the format "XX:XX PM".
+**    - The time is displayed in the format "XX:XX PM" if US formatting is used.
 **    - If the current time differs from the last displayed time or 
 **      if a forced repaint is requested, the time is redrawn.
 ** ===================================================================
 */
 void HomeView::handleClock(bool isPaintForced)
 {
-    std::string        timeStr  = getCurrentTimestamp("%l:%M %p").c_str();         
+    std::string       format = UI_TIME_FORMAT;
+    int               offset = 10;
+    if (Vault::getInstance().isUSDateTimeFormattingUsed())
+    {
+        format = UI_TIME_FORMAT_US;
+        offset = 0;
+    }
+    std::string        timeStr  = getCurrentTimestamp(format.c_str()).c_str();         
     static std::string lastTime = "X:XX/X:XX";
     if ((lastTime != timeStr)
     ||  (isPaintForced))
     {            
-        _pUI->lDrawString(timeStr.c_str(), 310, 287, 20, TFTColor::DarkGreen, TFTColor::Black,"XX:XX PM");    
+        _pUI->lDrawString(timeStr.c_str(), 310 + offset, 287, 20, TFTColor::DarkGreen, TFTColor::Black,"XX:XX PM");    
         lastTime = timeStr;
     }    
 }

src/Vault.cpp

@@ -203,6 +203,11 @@ void Vault::initialize()
             {
                 strncpy(_timezone.data(), value.c_str(), _timezone.size() - 1);
             }
+            else if (key == "ui_date_time_format")
+            {
+                value.toLowerCase();
+                _dateTimeFormatUS = (value == "us");
+            }
         }
         else if (section == "vault")
         {
@@ -714,3 +719,19 @@ std::array<uint8_t, 16> Vault::getAesKey(bool tiedToDevice)
     return finalKey;
 }
 
+/*
+** ===================================================================
+** isUSDateTimeFormattingUsed()
+**
+**    Determines whether US-style date/time formatting should be used.
+** ===================================================================
+*/
+bool Vault::isUSDateTimeFormattingUsed()
+{
+    if (_useHardcodedValues)
+    {
+        return Use_US_Date_Time_Format;
+    }
+
+    return _dateTimeFormatUS;
+}

src/Vault.h

@@ -79,6 +79,7 @@ class Vault
     String            getSpotifyClientID();
     String            getSpotifyClientSecret();
     String            getTimezone();
+    bool              isUSDateTimeFormattingUsed();
 
 private:
     Vault();
@@ -87,7 +88,8 @@ class Vault
     String                  decrypt(const String& encryptedBase64, bool tiedToDevice);
     void                    printEncryptionHints();
     bool                    _useHardcodedValues   = true;
-    VaultPrivacyLevel       _privacyLevel          = VaultPrivacyLevel::None;
+    VaultPrivacyLevel       _privacyLevel         = VaultPrivacyLevel::None;
+    bool                    _dateTimeFormatUS     = false;
     std::array<char, VAULT_MAX_CRED_LENGTH>   _ssid{};
     std::array<char, VAULT_MAX_CRED_LENGTH>   _wifiPwd{};
     std::array<char, VAULT_MAX_CRED_LENGTH>   _clientId{};

src/settings.h

@@ -41,6 +41,20 @@ static const char *SPOTIFY_CLIENT_SECRET = "SPOTIFY_CLIENT_SECRET goes here";
 // https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
 #define TIMEZONE "CET-1CEST,M3.5.0,M10.5.0/3"
 
+// format specifiers: https://cplusplus.com/reference/ctime/strftime/
+// values below are tested. updating the formatting may affect UI layout.
+
+  // Set to true to use US date/time formatting (12 hour times and US dates)
+  static const bool Use_US_Date_Time_Format = false;
+
+  // Formatting consistent with norms in the United States
+  #define UI_DATE_FORMAT_US "%A %B %d %Y"
+  #define UI_TIME_FORMAT_US "%l:%M %p"
+
+  // Formatting consistent with many countries outside the United States
+  #define UI_DATE_FORMAT "%A %d %B %Y"
+  #define UI_TIME_FORMAT "%H:%M"
+
 /*
 ** ===================================================================
 ** Version and Name Information