Merge pull request #81 from Spirik/appearance

`GEMAppearance` struct; methods for traversing; disable AltSerialGraphicLCD version by default; Todo List example

keywords.txt

@@ -8,10 +8,12 @@
 
 GEM	KEYWORD1
 GEM_u8g2	KEYWORD1
+GEM_adafruit_gfx	KEYWORD1
 GEMItem	KEYWORD1
 GEMPage	KEYWORD1
 GEMSelect	KEYWORD1
 GEMCallbackData	KEYWORD1
+GEMAppearance	KEYWORD1
 Splash	KEYWORD1
 FontSize	KEYWORD1
 FontFamilies	KEYWORD1
@@ -26,6 +28,7 @@ SelectOptionDouble	KEYWORD1
 # Methods and Functions (KEYWORD2)
 ####################################################
 
+setAppearance	KEYWORD2
 setSplash	KEYWORD2
 setSplashDelay	KEYWORD2
 hideVersion	KEYWORD2
@@ -37,6 +40,7 @@ enableCyrillic	KEYWORD2
 init	KEYWORD2
 reInit	KEYWORD2
 setMenuPageCurrent	KEYWORD2
+getCurrentMenuPage	KEYWORD2
 drawMenu	KEYWORD2
 readyForKey	KEYWORD2
 registerKeyPress	KEYWORD2
@@ -45,7 +49,12 @@ setCallbackVal	KEYWORD2
 getCallbackData	KEYWORD2
 setTitle	KEYWORD2
 getTitle	KEYWORD2
+getMenuItem	KEYWORD2
+getCurrentMenuItem	KEYWORD2
+getCurrentMenuItemIndex	KEYWORD2
+getMenuItemNext	KEYWORD2
 setPrecision	KEYWORD2
+setAdjustedASCIIOrder	KEYWORD2
 setReadonly	KEYWORD2
 getReadonly	KEYWORD2
 hide	KEYWORD2

src/GEM.h

@@ -40,6 +40,7 @@
 #ifdef GEM_ENABLE_GLCD_VERSION
 
 #include <AltSerialGraphicLCD.h>
+#include "GEMAppearance.h"
 #include "GEMPage.h"
 #include "GEMSelect.h"
 #include "constants.h"
@@ -94,6 +95,15 @@ class GEM {
       default 86 (suitable for 128x64 screen with other variables at their default values)
     */
     GEM(GLCD& glcd_, byte menuPointerType_ = GEM_POINTER_ROW, byte menuItemsPerScreen_ = 5, byte menuItemHeight_ = 10, byte menuPageScreenTopOffset_ = 10, byte menuValuesLeftOffset_ = 86);
+    /*
+      @param 'glcd_' - reference to the instance of the GLCD class created with AltSerialGraphicLCD library
+      @param 'appearance_' - object of type GEMAppearance
+    */
+    GEM(GLCD& glcd_, GEMAppearance appearance_);
+
+    /* APPEARANCE OPERATIONS */
+
+    GEM& setAppearance(GEMAppearance appearance);       // Set apperance of the menu (can be overridden in GEMPage on per page basis)
 
     /* INIT OPERATIONS */
 
@@ -112,6 +122,7 @@ class GEM {
     GEM& init();                                        // Init the menu (load necessary sprites into RAM of the SparkFun Graphic LCD Serial Backpack, display GEM splash screen, etc.)
     GEM& reInit();                                      // Reinitialize the menu (apply GEM specific settings to AltSerialGraphicLCD library)
     GEM& setMenuPageCurrent(GEMPage& menuPageCurrent);  // Set supplied menu page as current
+    GEMPage* getCurrentMenuPage();                      // Get pointer to current menu page
 
     /* CONTEXT OPERATIONS */
 
@@ -129,17 +140,15 @@ class GEM {
                                                          // Accepts GEM_KEY_NONE, GEM_KEY_UP, GEM_KEY_RIGHT, GEM_KEY_DOWN, GEM_KEY_LEFT, GEM_KEY_CANCEL, GEM_KEY_OK values
   private:
     GLCD& _glcd;
-    byte _menuPointerType;
-    byte _menuItemsPerScreen;
-    byte _menuItemHeight;
-    byte _menuPageScreenTopOffset;
-    byte _menuValuesLeftOffset;
-    byte _menuItemFontSize;
+    GEMAppearance* _appearanceCurrent = nullptr;
+    GEMAppearance _appearance;
+    GEMAppearance* getCurrentAppearance();
+    byte getMenuItemsPerScreen();
+    byte getMenuItemFontSize();
     FontSize _menuItemFont[2] = {{6,8},{4,6}};
     bool _invertKeysDuringEdit = false;
-    byte _menuItemInsetOffset;
-    byte _menuItemTitleLength;
-    byte _menuItemValueLength;
+    byte getMenuItemTitleLength();
+    byte getMenuItemValueLength();
     const uint8_t *_splash;
     uint16_t _splashDelay = 1000;
     bool _enableVersion = true;

src/GEMAppearance.h

@@ -0,0 +1,49 @@
+/*
+  GEMAppearance - struct for storing visual settings of GEM library.
+
+  GEM (a.k.a. Good Enough Menu) - Arduino library for creation of graphic multi-level menu with
+  editable menu items, such as variables (supports int, byte, float, double, bool, char[17] data types)
+  and option selects. User-defined callback function can be specified to invoke when menu item is saved.
+  
+  Supports buttons that can invoke user-defined actions and create action-specific
+  context, which can have its own enter (setup) and exit callbacks as well as loop function.
+
+  Supports:
+  - AltSerialGraphicLCD library by Jon Green (http://www.jasspa.com/serialGLCD.html);
+  - U8g2 library by olikraus (https://github.com/olikraus/U8g2_Arduino);
+  - Adafruit GFX library by Adafruit (https://github.com/adafruit/Adafruit-GFX-Library).
+
+  For documentation visit:
+  https://github.com/Spirik/GEM
+
+  Copyright (c) 2018-2023 Alexander 'Spirik' Spiridonov
+
+  This file is part of GEM library.
+
+  This library is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License as published by the Free Software Foundation; either
+  version 3 of the License, or (at your option) any later version.
+  
+  This library is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+  
+  You should have received a copy of the GNU Lesser General Public License
+  along with this library.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#ifndef HEADER_GEMAPPEARANCE
+#define HEADER_GEMAPPEARANCE
+
+// Declaration of GEMAppearance type
+struct GEMAppearance {
+  byte menuPointerType;
+  byte menuItemsPerScreen;
+  byte menuItemHeight;
+  byte menuPageScreenTopOffset;
+  byte menuValuesLeftOffset;
+};
+
+#endif

src/GEMItem.cpp

@@ -1273,36 +1273,43 @@ GEMItem::GEMItem(const char* title_, void (*callbackAction_)(GEMCallbackData), v
 //---
 
 GEMItem& GEMItem::setCallbackVal(byte callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valByte = callbackVal_;
   return *this;
 }
 
 GEMItem& GEMItem::setCallbackVal(int callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valInt = callbackVal_;
   return *this;
 }
 
 GEMItem& GEMItem::setCallbackVal(float callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valFloat = callbackVal_;
   return *this;
 }
 
 GEMItem& GEMItem::setCallbackVal(double callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valDouble = callbackVal_;
   return *this;
 }
 
 GEMItem& GEMItem::setCallbackVal(bool callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valBool = callbackVal_;
   return *this;
 }
 
 GEMItem& GEMItem::setCallbackVal(const char* callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valChar = callbackVal_;
   return *this;
 }
 
 GEMItem& GEMItem::setCallbackVal(void* callbackVal_) {
+  callbackData.pMenuItem = this;
   callbackData.valPointer = callbackVal_;
   return *this;
 }
@@ -1327,6 +1334,11 @@ GEMItem& GEMItem::setPrecision(byte prec) {
   return *this;
 }
 
+GEMItem& GEMItem::setAdjustedASCIIOrder(bool mode) {
+  adjustedAsciiOrder = mode;
+  return *this;
+}
+
 GEMItem& GEMItem::setReadonly(bool mode) {
   readonly = mode;
   return *this;

src/GEMItem.h

@@ -266,34 +266,37 @@ class GEMItem {
     GEMItem(const char* title_, void (*callbackAction_)(GEMCallbackData), const char* callbackVal_, bool readonly_ = false);
     GEMItem(const char* title_, void (*callbackAction_)(GEMCallbackData), void* callbackVal_, bool readonly_ = false);
 
-    GEMItem& setCallbackVal(byte callbackVal_); // Set value of an argument that will be passed to callback within GEMCallbackData (either byte, int, bool, float, double, char or void pointer)
+    GEMItem& setCallbackVal(byte callbackVal_);         // Set value of an argument that will be passed to callback within GEMCallbackData (either byte, int, bool, float, double, char or void pointer)
     GEMItem& setCallbackVal(int callbackVal_);
     GEMItem& setCallbackVal(float callbackVal_);
     GEMItem& setCallbackVal(double callbackVal_);
     GEMItem& setCallbackVal(bool callbackVal_);
     GEMItem& setCallbackVal(const char* callbackVal_);
     GEMItem& setCallbackVal(void* callbackVal_);
-    GEMCallbackData getCallbackData();          // Get GEMCallbackData struct associated with menu item
-    GEMItem& setTitle(const char* title_);      // Set title of the menu item
-    const char* getTitle();                     // Get title of the menu item
-    GEMItem& setPrecision(byte prec);           // Explicitly set precision for float or double variables as required by dtostrf() conversion,
-                                                // i.e. the number of digits after the decimal sign
-    GEMItem& setReadonly(bool mode = true);     // Explicitly set or unset readonly mode for variable that menu item is associated with
-                                                // (relevant for GEM_VAL_INTEGER, GEM_VAL_BYTE, GEM_VAL_FLOAT, GEM_VAL_DOUBLE, GEM_VAL_CHAR,
-                                                // GEM_VAL_BOOL variable menu items and GEM_VAL_SELECT option select), or menu button GEM_ITEM_BUTTON
-                                                // and menu link GEM_ITEM_LINK, pressing of which won't result in any action, associated with them
-    bool getReadonly();                         // Get readonly state of the variable that menu item is associated with (as well as menu link or button)
-    GEMItem& hide(bool hide = true);            // Explicitly hide or show menu item
-    GEMItem& show();                            // Explicitly show menu item
-    bool getHidden();                           // Get hidden state of the menu item
-    GEMItem& remove();                          // Remove menu item from parent menu page
-    void* getLinkedVariablePointer();           // Get pointer to a linked variable (relevant for menu items that represent variable)
+    GEMCallbackData getCallbackData();                  // Get GEMCallbackData struct associated with menu item
+    GEMItem& setTitle(const char* title_);              // Set title of the menu item
+    const char* getTitle();                             // Get title of the menu item
+    GEMItem& setPrecision(byte prec);                   // Explicitly set precision for float or double variables as required by dtostrf() conversion,
+                                                        // i.e. the number of digits after the decimal sign
+    GEMItem& setAdjustedASCIIOrder(bool mode = true);   // Turn adjsuted order of characters when editing char[17] variables on (with space character followed by `a` and preceded by `) or off
+    GEMItem& setReadonly(bool mode = true);             // Explicitly set or unset readonly mode for variable that menu item is associated with
+                                                        // (relevant for GEM_VAL_INTEGER, GEM_VAL_BYTE, GEM_VAL_FLOAT, GEM_VAL_DOUBLE, GEM_VAL_CHAR,
+                                                        // GEM_VAL_BOOL variable menu items and GEM_VAL_SELECT option select), or menu button GEM_ITEM_BUTTON
+                                                        // and menu link GEM_ITEM_LINK, pressing of which won't result in any action, associated with them
+    bool getReadonly();                                 // Get readonly state of the variable that menu item is associated with (as well as menu link or button)
+    GEMItem& hide(bool hide = true);                    // Explicitly hide or show menu item
+    GEMItem& show();                                    // Explicitly show menu item
+    bool getHidden();                                   // Get hidden state of the menu item
+    GEMItem& remove();                                  // Remove menu item from parent menu page
+    void* getLinkedVariablePointer();                   // Get pointer to a linked variable (relevant for menu items that represent variable)
+    GEMItem* getMenuItemNext(bool total = false);       // Get next menu item (including hidden ones if total set to true)
   private:
     const char* title;
     void* linkedVariable = nullptr;
     byte linkedType;
     byte type;
     byte precision = GEM_FLOAT_PREC;
+    bool adjustedAsciiOrder = false;
     bool readonly = false;
     bool hidden = false;
     GEMSelect* select = nullptr;
@@ -306,7 +309,6 @@ class GEMItem {
     };
     bool callbackWithArgs = false;
     GEMCallbackData callbackData;
-    GEMItem* getMenuItemNext(bool total = false); // Get next menu item (including hidden ones if total set to true)
 };
 
 #endif

src/GEMPage.cpp

@@ -109,6 +109,11 @@ const char* GEMPage::getTitle() {
   return title;
 }
 
+GEMPage& GEMPage::setAppearance(GEMAppearance* appearance) {
+  _appearance = appearance;
+  return *this;
+}
+
 GEMItem* GEMPage::getMenuItem(byte index, bool total) {
   GEMItem* menuItemTmp = (!total && _menuItem->hidden) ? _menuItem->getMenuItemNext() : _menuItem;
   for (byte i=0; i<index; i++) {
@@ -124,6 +129,10 @@ GEMItem* GEMPage::getCurrentMenuItem() {
   return getMenuItem(currentItemNum);
 }
 
+byte GEMPage::getCurrentMenuItemIndex() {
+  return currentItemNum;
+}
+
 int GEMPage::getMenuItemNum(GEMItem& menuItem, bool total) {
   GEMItem* menuItemTmp = (!total && _menuItem->hidden) ? _menuItem->getMenuItemNext() : _menuItem;
   for (byte i=0; i<(total ? itemsCountTotal : itemsCount); i++) {

src/GEMPage.h

@@ -38,6 +38,7 @@
 #define HEADER_GEMPAGE
 
 #include <Arduino.h>
+#include "GEMAppearance.h"
 #include "GEMItem.h"
 
 // Macro constant (alias) for the last possible position that menu item can be added at
@@ -68,13 +69,15 @@ class GEMPage {
     GEMPage& setParentMenuPage(GEMPage& parentMenuPage);        // Specify parent level menu page (to know where to go back to when Back button is pressed)
     GEMPage& setTitle(const char* title_);                      // Set title of the menu page
     const char* getTitle();                                     // Get title of the menu page
+    GEMPage& setAppearance(GEMAppearance* appearance);          // Set appearance of the menu page
+    GEMItem* getMenuItem(byte index, bool total = false);       // Get pointer to menu item by index (counting hidden ones if total set to true)
+    GEMItem* getCurrentMenuItem();                              // Get pointer to current menu item
+    byte getCurrentMenuItemIndex();                             // Get index of current menu item
   private:
     const char* title;
     byte currentItemNum = 0;                                    // Currently selected (focused) menu item of the page
     byte itemsCount = 0;                                        // Items count excluding hidden ones
     byte itemsCountTotal = 0;                                   // Items count incuding hidden ones
-    GEMItem* getMenuItem(byte index, bool total = false);
-    GEMItem* getCurrentMenuItem();
     int getMenuItemNum(GEMItem& menuItem, bool total = false);  // Find index of the supplied menu item
     void hideMenuItem(GEMItem& menuItem);
     void showMenuItem(GEMItem& menuItem);
@@ -83,6 +86,7 @@ class GEMPage {
     GEMItem _menuItemBack {"", static_cast<GEMPage*>(nullptr)}; // Local instance of Back button (created when parent level menu page is specified through
                                                                 // setParentMenuPage(); always becomes the first menu item in a list)
     void (*exitAction)() = nullptr;
+    GEMAppearance* _appearance = nullptr;
 };
 
 #endif