How-To: Create Run-time Strings
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 Strings" page 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.
MGS Harmony Composer Design
The following figure demonstrates what the screen design looks like in MGS Harmony Composer.
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.
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.
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.
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.
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.
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.
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.
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 "definitions.h"
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.
...
/* 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.
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.
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.
snprintf(cStrBuff, MAX_COUNTER_STR_SIZE, "%lu", counterValue++);
Then, this C string is used to update the Fixed String.
appFixedStrStatic.fn->setFromCStr(&appFixedStrStatic, cStrBuff); //Set string data from C-string
Then, the label widget is updated with this Fixed String.
Screen0_LabelWidget_Fixed_Stat->fn->setString(Screen0_LabelWidget_Fixed_Stat, (leString *) &appFixedStrStatic);
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.
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.
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.
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.
leString_Delete((leString *) appDynamicString);
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.
Screen0_ButtonWidget_StartStop->fn->setString(Screen0_ButtonWidget_StartStop, (leString *) &string_StringStop);
Screen0_ButtonWidget_StartStop->fn->setString(Screen0_ButtonWidget_StartStop, (leString *) &string_StringRun);
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.
