By dave | November 11, 2020

An item that represents a complex data type that needs to be edited a part at a time. The value is generally held in RAM and can usually be saved in EEPROM between sessions. These items take various forms on the embedded side, either an Ip Address, date, time or plain text. Time menu items allow for the editing of time values, either to the hundredth of a second or to the second either as 24 hour or 12 hour. Ip address items are IPV4 addresses edited in 4 parts. Text fields can be regular text fields or password text fields, each character is edited separately. Date fields allow for the editing of gregorian dates.

Class types for MultiEdit items

Table showing what getMenuType() returns for each class type

Class type MenuType Enumeration
TextMenuItem MENUTYPE_TEXT_VALUE
IpAddressMenuItem MENUTYPE_IPADDRESS
TimeFormattedMenuItem MENUTYPE_TIME
DateFormattedMenuItem MENUTYPE_DATE

Creating an object from the designer

From the add dialog choose to create a text menu item and once it’s selected the editor panel will look similar to:

image showing the text editor

Text Item Editor UI

  • maxLength: the allocated size of the string, anything copied in that’s longer will be truncated.
  • editorType: at the moment plain text or IP address

Note that PLAIN_TEXT is one of the few menu item types that is variable length, so you should set the length before generating any other items and using the EEPROM auto allocation, otherwise an overlap may be possible.

Working with complex editable items in code

To get and set the value of a plain text menu item:

void setTextValue(const char* text, bool silent = false);
const char* getTextValue() { return data; } 

To get and set the value of an IpAddress menu item:

// set IP address from text
void setIpAddress(const char* source);

// as four parts.
void setIpAddress(uint8_t p1, uint8_t p2, uint8_t p3, uint8_t p4);

// get the four parts of the address.
byte* getIpAddress()

// or as a string
void copyValue(char* buffer, int bufferSize);

To get and set the value of a time item:

// First we can get and set the time storage object
TimeStorage getTime()
void setTime(TimeStorage storage)

// On the TimeStorage object we can access the hours, minutes, seconds and hundreds 
uint8_t hours;
uint8_t minutes;
uint8_t seconds;
uint8_t hundreds;

To get and set the value of a date item:

DateStorage getDate()
void setDate(DateStorage date)

// On the DateStorage object we can access the years, months and days.
uint16_t year;
uint8_t  month;
uint8_t  day;

Creating a text menu item from the CLI

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

tcmenu create-item --parent 0 --type text --eeprom AUTO --name TextName [--localonly --readonly --hide]

The structure of a text menu item in the EMF file is:

{
  "parentId": 0,
  "type": "textItem",
  "item": {
    "textLength": 0,
    "itemType": "PLAIN_TEXT",
    "name": "TextName",
    "variableName": "TextName",
    "id": 6,
    "eepromAddress": 6,
    "readOnly": false,
    "localOnly": false,
    "visible": true
  }
}

Where itemType is one of:

PLAIN_TEXT
IP_ADDRESS
TIME_24H
TIME_12H
TIME_24_HUNDREDS
GREGORIAN_DATE
TIME_DURATION_SECONDS
TIME_DURATION_HUNDREDS
TIME_24H_HHMM
TIME_12H_HHMM

Creating items manually

As always, the easiest way to generate items is in the designer. All the items have similar constructors, which can be looked up in the reference docs linked above. However, here we give a couple of examples to get you started:

// ipAddress item
RENDERING_CALLBACK_NAME_INVOKE(fnIpAddressRtCall, ipAddressRenderFn, "IpAddress",
                               myEepromLocation, NO_CALLBACK)
IpAddressMenuItem menuConnectivityIpAddress(fnIpAddressRtCall, myId, &nextMenuItem);

// Text item  
RENDERING_CALLBACK_NAME_INVOKE(fnConnectivityTextCb, textItemRenderFn, "Text Data", 
                               myEepromLocation, onChangePin)
TextMenuItem menuConnectivityChangePin(fnConnectivityTextCb, myId, textMaxLen, &nextMenuItem);

Above we create two textual items, one for text, one for IP addresses, the name of the callback method is fnIpAddressRtCall/fnConnectivityTextCb and most requests pass through to ipAddressRenderFn/textItemRenderFn. The menu item name will be “TextData” or “IpAddress” and the callback is not set NO_CALLBACK for IpAddress, and onChangePin for the text case. Change myId to the desired ID and myEepromLocation to a suitable storage location or 0xFFFF.

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.