How-To: Create Run-time Strings

Last modified by Microchip on 2024/03/29 13:32

Introduction

Run-time strings refer to text elements in the Graphical User Interface (GUI) that are subject to change during program execution. They are utilized to reflect variable information such as system status or user-provided input.

This guide provides users with step-by-step instructions on how to implement run-time strings to display a live counter. Additionally, it offers a comprehensive tutorial on constructing a multilingual user interface that automatically adjusts the displayed text according to the user's language preference.

Refer to the "Using Stringspage for more information on String Assets and Run-time strings in Microchip Graphics Suite (MGS) Harmony.

MGS Example Project

Refer to the project in GitHub for the example.

MGS Harmony Web Simulator Output

Here is how the application runs. 

Pressing the Start button will start the counter. Pressing it again will stop the counter. The counter value is shown in the labels titled Fixed String and Dynamic String.

The Fixed String label uses a Fixed String object that only holds up to three characters, which truncates the displayed value to the three most significant digits.

The Dynamic String label uses a Dynamic String object that automatically resizes the character buffer based on the length of the text.

Pressing the Language Flags will show the language translations for the String Assets shown in the GUI.

Runtime Strings Example

Back to Top

MGS Harmony Composer Design

The following figure demonstrates what the screen design looks like in MGS Harmony Composer.

MGS Composer Design

The design uses a few label widgets to show the counter value. The design adds button widgets for the Start/Stop button and language selection.

Note that the On Show, On Hide, and On Update screen events are enabled and defined in the application code.

The language selection buttons are configured with their pressed and released images, and the Pressed Event callback is enabled. The event callback function is defined in the application code.

Flag Button Image Properties

The Start/Stop button is configured to be toggleable and the unique images were used for the pressed and released states. The callbacks for pressed and released events are enabled and the callback functions are defined in the application code.

Start/Stop Button Image Properties

Back to Top

Image Assets

The images used in the UI are imported using the Image Manager and configured for RGB output format with Compression and RGB 565 Color Mode. For more information on how to use images, refer to the "Using Images in Microchip Graphics Suite (MGS)" page.

Image Assets Properties

Back to Top

Font Assets

In the example project, the Font Manager was used to import the font assets. The name, size, and anti-alias options are set for these font assets.

For more information on how to use fonts, refer to the "Using Fonts in Microchip Graphics Suite (MGS)" page.

Font Assets Properties

Note that the Font Assets used to display the counter value have Character Ranges start and end indices set to 48 to 57, which are the Unicode values for the numeric digits 0 - 9. This tells the Graphics Assets Generator to only generate glyph data for numeric characters, eliminating glyph data for unused characters and saving Flash space.

Font Glyph Ranges

Back to Top

String Assets

Table String assets were created and defined using the String Manager which is described in more detail in the "Using Strings in Microchip Graphics Suite (MGS)" page. 

String Assets Settings

For each language, a string value is set in the String Table. The languages were added using the String Language Table, which can be launched from the String Manager > Languages > Edit Language menu.

Note that the Encoding Mode is set to UTF-16. This is required to properly display and render extended glyphs for the Chinese language.

String Language Settings

Back to Top

Application Code

The project's app.c source file contains the application code and event callback definitions. The screen event callback functions are used to initialize, update and clean up the run-time strings.

The Screen0_OnShow() function is called every time the screen is shown and can be used to initialize variables and allocate buffers.

The Screen0_OnUpdate() function is periodically called by the MGS GFX task and used to monitor the value of the counter to update the run-time strings.

The Screen0_OnHide() function is called every time the screen is destroyed during a transition. This is used to clean up variables and free dynamic allocations.

Note that the appropriate MGS header files are included in the source file.

#include "gfx/legato/generated/le_gen_assets.h"
#include
"definitions.h"

Back to Top

Run-time Fixed Strings

To use Fixed Strings, the Fixed String object and the data buffer must be declared. The data buffer allocation can be static, like the following example, or it can be dynamically allocated in the system heap using malloc. Heap allocations need to be managed by the application to make sure that those are deallocated when unused.

#define APP_FIXED_STR_SIZE 3
...
/* Fixed String Variable Declarations */
static leFixedString appFixedStrStatic;                       // Fixed String with static data store 
static leChar appFixedStrStatBuff[APP_FIXED_STR_SIZE] = {0};    // Fixed sized data store

Next, the Fixed String object is initialized in the Screen0_OnShow() function and the font is also set.

 /* Initialize Fixed String with statically allocated data store */
 leFixedString_Constructor(&appFixedStrStatic, appFixedStrStatBuff, APP_FIXED_STR_SIZE); //Set data store
appFixedStrStatic.fn->setFont(&appFixedStrStatic, (leFont*) &FontBigStatic);  //Set Font

To update the text in Fixed Strings, a regular C-character array is used.

/* C-type string buffer s*/
static char cStrBuff[MAX_COUNTER_STR_SIZE];

The text in this character array is created based on the value of the counter in the Screen0_OnUpdate() function.

//Create C string from counterValue
snprintf(cStrBuff, MAX_COUNTER_STR_SIZE, "%lu", counterValue++);

Then, this C string is used to update the Fixed String.

/* Update Fixed String label */
appFixedStrStatic.fn->setFromCStr(&appFixedStrStatic, cStrBuff); //Set string data from C-string

Then, the label widget is updated with this Fixed String.

//Update label widget string 
Screen0_LabelWidget_Fixed_Stat->fn->setString(Screen0_LabelWidget_Fixed_Stat, (leString *) &appFixedStrStatic); 

Back to Top

Run-time Dynamic Strings

To use Dynamic Strings, the Dynamic String object pointer is declared. Unlike Fixed Strings, the data buffer for Dynamic Strings is automatically allocated and reallocated by the MGS library depending on the length of the text.

/* Dynamic String Variable Declarations */
static leDynamicString * appDynamicString;

In the Screen0_OnShow() function, the Dynamic String is created and assigned to the pointer. The font for the string is also set. 

/* Allocate and initialize Dynamic String */
appDynamicString = leDynamicString_New(); //Allocate dynamic string object, must be freed with leString_Delete
appDynamicString->fn->setFont(appDynamicString, (leFont*) &FontBigDynamic); //Set Font

Like the Fixed String, the Dynamic String is also updated in the Screen0_OnUpdate() function and used to update the associated label.

/* Update Dynamic String label */
appDynamicString->fn->setFromCStr(appDynamicString, cStrBuff);  //Set string data from C-string
Screen0_LabelWidget_Dyn->fn->setString(Screen0_LabelWidget_Dyn, leString *) appDynamicString); //Update label widget string

In the Screen0_OnHide() function, the Dynamic String and its data buffer allocations are freed.

/* Free dynamic string allocations */
leString_Delete((leString *) appDynamicString);

Back to Top

Run-time Table Strings

Table Strings are assets created using the String Table. Since Table Strings are already generated and stored in code, there's no need to create them at run-time; they can be used directly to update the labels.

The labels are updated when the RUN/STOP button is toggled in the button event OnPressed()/OnReleased() callback functions.

/* Update button label to show 'STOP' */
Screen0_ButtonWidget_StartStop->fn->setString(Screen0_ButtonWidget_StartStop, (leString *) &string_StringStop);
/* Update button label to show 'RUN' */
Screen0_ButtonWidget_StartStop->fn->setString(Screen0_ButtonWidget_StartStop, (leString *) &string_StringRun);

Back to Top

Run-time Language Change

Language is changed by calling the leSetStringLanguage Application Programming Interface (API) in the respective language button OnPressed event callback function. After calling this API, the MGS Library will automatically switch the values of the Table Strings.

leSetStringLanguage(language_English);

Back to Top