Using Strings in Microchip Graphics Suite (MGS)

Last modified by Microchip on 2024/10/21 14:17

Introduction

In Graphical User Interfaces (GUIs), strings are used to represent text that is displayed to the user or received from the user. They are sequences of characters that can include letters, numbers, and symbols. For example, labels, buttons, text fields and other components of a GUI may use strings to display text. When a user enters text into a text field, this input is also typically handled as a string.

Microchip Graphics Suite (MGS) Harmony enables users to create and use two types of strings (1) String Assets and (2) Run-time Strings

This guide provides information on how to add and configure string assets in an MGS Harmony Composer project, and how to create run-time strings.

Refer to the "How-To: Create Run-time Strings" guide for an example of how to use string assets and run-time strings to show a running counter with multi-language text.

Using String Assets

String Assets, also called Table Strings, are strings that are created at design time when creating the UI screens using MGS Harmony Composer. These strings are statically allocated in the code and stored in the String Table.

The String Table stores the association of strings, language indices, and font assets. Strings can be encoded in ASCII, UTF8, and UTF16. The string table supports localization where a string asset can be set with different values that can correspond to a language/translation or typeface/font.

MGS Harmony Composer String Manager

The MGS Harmony Composer includes a utility called the String Manager that lets users create, configure and manage String Assets. The utility can be opened by clicking Asset > Strings.

The String Manager window has different sections:

The Main Menu provides options to add and manage string assets, add languages and select the encoding.
Controls for adding and deleting String Assets.
Shows list of String Assets. Selecting a String will show information about the asset.
A unique name must be specified for the String Asset. This name is used in the generated C code, so it must use valid characters for C variable names.
An optional description can be set to describe what the string is for.
The String Data table lets users specify the text value and font for each language.
Each supported language will be a row in the table. This allows different text values to be set based on the language, which enables the library to switch translations at run-time based on the language setting.

Multi-language and Localization

The String Manager uses a String Table to let users specify a unique text value per language for each String Asset. This enables the library to show a unique text based on the language setting at run-time.

Figure 3: Table Strings with Multi-Language

Note: For languages that use extended glyphs that are outside the ASCII character range, make sure that the appropriate encoding is set.

UTF-8 or UTF-16 encoding may be necessary for rendering Arabic, Hebrew, European, and East Asian glyphs (Chinese, Japanese, Korean).

Enable the String Manager using the Encoding > UTF8/UTF16 setting.

Adding a Language

For multi-language, each language that needs to be supported must be added to the String Language table.

Click Languages > Edit Languages to open the String Language Table.

Open Language Settings

In the String Language Table window, click the + button to add a new language. Set the encoding mode based on the specified language.

String Language Table

Specify the name of the new language. The Size column will be updated with the code size consumed by that language as language translations are set in the string table.

Adding a new Language to the Language Table

All added languages will now be shown in the String Data table.

Adding a String Translation

To add a translation text for a string, the value of the string asset must be set for each language.

Figure 4: Adding a string table translation

Select the String Asset from the list.

Note that all the languages are in a row in the String Data table.

Set the text value for each language.

Set the font for each language. Note that some languages may require a specific font set that supports the language's character encoding and range.

For a preview of how these strings would look on the screen, in MGS Harmony Composer, go to View > Display Language and select the desired language to preview.

Figure 5: Previewing a language in Composer

Importing/Exporting String Assets

The String Manager supports the import and export of string assets to a CSV file. This enables designs with a large number of strings and multiple languages to store the string translations in a spreadsheet that can be filled out by a localization specialist and imported into the MGS Harmony Composer design.

Figure 6: Importing and Exporting the String Table

To generate the base CSV file, it is recommended to create the string assets and languages in MGS Harmony Composer and use the export function.

The translation fields for each string can be filled out in the CSV file and the file can be imported back into MGS Harmony Composer.

Using Run-time Strings

Run-time strings are string objects that are created by the application at run-time. These strings are useful when displaying changing text, like a running clock or a sensor reading.

Since these are created at run-time (versus design-time for Table Strings), these strings are not included in the MGS Harmony Composer project design. MGS Harmony Composer is not aware of these strings and they are not part of the generated code. The lifecycle of these string objects must be managed by the application.

The MGS Harmony library supports two types of run-time strings (1) Fixed Strings and (2) Dynamic Strings.

Fixed Strings

Fixed strings are run-time strings that have fixed length. The length is set by the character buffer used to store the string data. The data buffer can be statically declared or allocated from the system heap.

Fixed strings are useful when displaying run-time strings of known length (like a digital clock) or to enforce a limit to the length of text to be displayed. Since the character buffer is allocated by the application, it doesn't use the heap memory allocated for the MGS Harmony library.

Dynamic Strings

Dynamic strings are run-time strings that can have variable lengths. The character buffer used to store the string data is automatically allocated by the MGS Harmony library based on the length of the string. These allocations are made in the MGS Harmony library's heap memory. The application is responsible for deleting these allocations when the strings are not used anymore.

Dynamic strings are useful when displaying run-time strings of variable length. It offers some flexibility for displaying text that may come from the end-user or external data, like in a keypad. Since the character buffer is allocated in the library's memory pool, the application should still enforce limits to the maximum length of the string to prevent starving the library.

Design Recommendations

Here are recommendations on how to effectively use string assets in your design.

Use the String Manager to create a table of strings for your project. Export the string table to a CSV file for your localization team to fill out the string translations.
Make sure that the memory allocated for run-time strings is freed when the strings are not used anymore. Otherwise, memory leaks may occur. For run-time strings used in a screen, use the screen's OnShow() and OnHide() callback functions to manage the lifecycle of these run-time strings during screen transitions. Allocate screen run-time strings in the OnShow() function, and free those allocations in the OnHide() function.

Project Example