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 reflect variable information such as system status or user-provided input.

This guide provides users with step-by-step instructions on implementing 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 in Microchip Graphics Suite (MGS)" 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

The application runs as follows: 

1. 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.
2. 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.
3. The Dynamic String label uses a Dynamic String object that automatically resizes the character buffer based on the length of the text.
4. Pressing the Language Flags will show the language translations for the String Assets shown in the GUI.

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.

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 using images, refer to the "Using Images in Microchip Graphics Suite (MGS)" page.

Back to Top

Font Assets

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

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

Back to Top

String Assets

Table String assets were created and defined using the String Manager. The "Using Strings in Microchip Graphics Suite (MGS)" page describes this process in more detail. 

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.

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.

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 so that those that are unused are deallocated.

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

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

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

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

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

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.

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

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

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

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.

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.

Back to Top