Using Strings in Microchip Graphics Suite (MGS)
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 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.
Figure 1: String Assets Diagram
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 described below.
Figure 2: String Manager
- 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 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
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.
In the String Language Table window, click the + button to add a new language. Set the encoding mode based on the specified language.
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.
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
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 are not part of the generated code. The lifecycle of these string objects must be managed by the application.
The MGS 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 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
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.
