By dave | November 11, 2020

An item that can represent a known series of values where only one can be selected at a time. Somewhat like a combo box. For enum items these values must be set at compile time, and on AVR / ESP they are in program memory. We store the choice as a zero based integer with the first choice being 0 and so on.

If you want choices that can change at runtime, or acquired from EEPROM or RAM then see ScrollChoiceMenuItem

Class types for EnumMenuItem

Creating an enum item in the designer

From the add item dialog choose Enum item, the editor panel will look similar to:

image showing the enumeration editor

Enumeration Item Editor UI

To add additional choices, press the Add button below the values list. Double click on the item in the list to edit it, press enter when done. Pressing remove deletes the selected item.

Working with enum menu items in code

To get and set the current values on an enumeration as an integer index.

uint16_t currentValue = menuItem.getCurrentValue()
menuItem.setCurrentValue(uint16_t val, bool silent = false)

To get the textual representation of an index:

void menuItem.copyEnumStrToBuffer(char* buffer, int size, int idx);

Where:

  • buffer is where the string will be copied
  • size is the size of the buffer
  • idx is the index in the enum - for example from calling menuItem.getCurrentValue()

Creating an enum menu item from the CLI

To create an enum menu item from the CLI here is a template command (options in square brackets are optional):

tcmenu create-item --parent 0 --type enum --eeprom AUTO --name EnumName [--localonly --readonly --hide]

The structure of a float menu item in the EMF file is as follows, you can add and remove entries from the enumEntries section:

{
  "parentId": 0,
  "type": "enumItem",
  "item": {
    "enumEntries": [
      "Enum 1",
      "Enum 2"
    ],
    "name": "EnumName",
    "variableName": "EnumName",
    "id": 10,
    "eepromAddress": -1,
    "readOnly": false,
    "localOnly": false,
    "visible": true
  }
}

Creating an enum item manually

In nearly all cases it’s better to create items using the designer. However, this is how you create an additional enum item manually should it be required. We strongly recommend that you do not create EnumMenuItem manually, instead use ScrollChoice items for this.

// first we create text strings for each of the choices
// if on AVR/ESP then PROGMEM keyword is needed.
const char enumStrFruits_0[] PROGMEM  = "Apples";
const char enumStrFruits_1[] PROGMEM  = "Oranges";
const char enumStrFruits_2[] PROGMEM  = "Pears";
const char enumStrFruits_3[] PROGMEM  = "Plums";
const char enumStrFruits_4[] PROGMEM  = "Grapes";

// Now we assemble the list of enumerations, again on AVR/ESP use progmem
const char* const enumStrFruits[] PROGMEM  = { 
        enumStrFruits_0, enumStrFruits_1, enumStrFruits_2,
        enumStrFruits_3, enumStrFruits_4 
};
const EnumMenuInfo PROGMEM minfoFruits = { "Fruits", myId, eepromLocation, numChoices,
                                           NO_CALLBACK, enumStrFruits };
EnumMenuItem menuFruits(&minfoFruits, 0, &nextMenuItem);

Above we create an enum item along with it’s associated info structure and choices. myId should be replaced with the unique ID for the item, eepromLocation should be replaced with either -1 (no eeprom location) or a location in ROM, NO_CALLBACK signifies there is no callback, you can replace this with a callback if there is one.

Each of the choices has it’s own string enumStrFruits_N, and then they are assembled into a list of choices enumStrFruits, finally these are passed into the Info block as the last parameter.

Other pages within this category

comments powered by Disqus

This site uses cookies to analyse traffic, serve ads by Google AdSense (non-personalized in EEA/UK), and to record consent. We also embed Twitter, Youtube and Disqus content on some pages, these companies have their own privacy policies.

Our privacy policy applies to all pages on our site

Should you need further guidance on how to proceed: External link for information about cookie management.