Working with Text

Storyboard gives you the ability to create and control text content with the text render extension. This render extension offers a single styled text display with options to control the text alignment, text overflow behaviour along with line and inter-character spacing. The text will be rendered using the font and point size selected in the property panel.

Storyboard uses standard TrueType (*.ttf) and OpenType (*.otf) font files and includes a number of commercially redistributable fonts. As these distributed fonts are selected and used the font will be copied to the fonts directory of the project. To use a custom TrueType or OpenType font in your application you just have to copy the font file into the fonts directory of the project. Once the font is parsed and analyzed it will show up for selection and use in the Font property selection.

By using the font files directly Storyboard offers developers total control over what resources are used on the embedded system. For example, a system that uses a specific font for only numeric elements can be edited to remove all other glyphs. Similarly, several different fonts can be merged together to provide broader language support for a particular product. The editing of these font files can be done with standard commercial editing tools such as FontForge or TypeTool among others.

To support internationalization and broad character support, Storyboard uses UTF-8 encoding universally for all text rendering. As long as the selected font contains support for the Unicode code points described by the encoding, Storyboard will be able to display the content. Support for advanced bi-directional text layout is provided by third party Crank Software partners and is discussed in more detail in Text Shaping and Layout..

There are times when you will want to make formatting choices on your text based on the content you are displaying. Situations like this usually come up when dealing with internationalization and handling languages that have more characters than can be displayed or require a simple layout re-ordering to be displayed right to left. In these cases, Storyboard provides you with ways to gather metrics about the text being displayed through gre.get_string_size. With the functionality provided by the Lua API, you can choose to do things like reduce the font size of your text if the language you are displaying is more verbose. The Scrolling Text sample provides an example of how to use this Lua text API to size and measure text and adapt it to a particular display environment.

There are three available text rotation styles that determine the rotation and alignment behavior of text.

Fixed – This rotation style only supports rotation angles of 0, 90, 180, 270. When the rotation angle is 0 or 180, text runs are created using the width to determine how many characters to fit in a line.

rotation_fixed.png

The render extension width and height are flipped when rotated at 90 or 270. In the flipped case, the height dictates the number of characters in a text run. In some cases, it may be recommended to only use center-center alignment with this rotation style

rotation_fixed_app.png

Free – This rotation style mimics the fill render extension. First text is laid out in the bounding box of the render extension, it is justified in the bounding box according to the specified horizontal and vertical alignment. Next, the surface containing the text is rotated, finally, the rotated surface is aligned to the control according to the horizontal and vertical alignment parameters.

rotation_free.png
rotation_free_app.png

Path – This rotation style allows text to be laid out along a path specified by the next render extension on the control. Vertical alignment on the text render extension is disabled in this case. Horizontal alignment will determine where the text is laid out on the path. Some configurations of paths, fonts, and font sizes may require using horizontal spacing to achieve the desired outcome. If the render extension providing the path is configured to create an empty path (such as an arc with equal start and end angles), no text will be drawn.

rotation_path.png
rotation_path_app.png

Rich Text Styling and Markup

Along with standard text support, Storyboard also supports the use of rich text. The rich text render extension allows the user to use a subset of HTML/XML tags to define the text formatting.

Table 1. Supported Rich Text Tags

NAME

DESCRIPTION

TAG

OPTIONS

Paragraph

The <p> tag specifies a paragraph.

<p> </p>

style - Set of attributes that define how to style the text.

Span

The <span> tag is used for styling text.

<span> </span>

style - Set of attributes that define how to style the text.

Bold

The <b> tag specifies bold text.

<b> </b>

None

Italic

The <i> tag specifies italic text.

<i> </i>

None

Underline

The <u> tag specifies underlined text.

<u> </u>

None

Break

The <br> tag specifies a line break.

<br> or </br>

None

Non-Breaking Text

The <nobr> tag specifies text that can't break.

<nobr> </nobr>

None

Font File

This is used to specify a font face for a font family (local file only, truetype fonts only).

<style> @font-face { font-family: roboto-bold; src: url('file:fonts/roboto_bold.ttf') } </style>

  1. font-style - Defines how the font should be styled. The values "oblique" and "italic" are treated the same, this specifies the font as italic. Default is "normal".

  2. font-weight - Defines the boldness of the font. Only support value is "bold", otherwise it's treated as "normal"

Ordered Lists

The <ol> tag is used to define an ordered list.

<ol> </ol>

style - Set of attributes that define how to style the list.

Unordered Lists

The <ul> tag is used to define an unordered list.

<ul> </ul>

style - Set of attributes that define how to style the list.

List Items

The <li> tag is used to specify a list item.

<li> </li>

None


Table 2. Supported Style Attributes

NAME

DESCRIPTION

ATTRIBUTE NAME

PARAMETERS

Text Color

The color attribute specifies the color of the text.

<p style="color:red;">This is a paragraph.</p> or <p style="color:#FF0000;">This is a paragraph.</p>

Color can be a color name (ie. "red", "blue") or a hex value (ie. "#FF0000")

Background Color

The background-color attribute specifies the color of the background behind the text

<p style="background-color:red;">This is a paragraph.</p> or <p style="background-color:#FF0000;">This is a paragraph.</p>

Color can be a color name (ie. "red", "blue") or a hex value (ie. "#FF0000")

Text Alignment

The text-align attribute specifies the alignment of the text block.

<p style="text-align:left">Left Aligned </p>

  1. left - Left justifies text.

  2. center - Center justifies text.

  3. right - Right justifies text.

Vertical Alignment

The vertical-align attribute specifies the vertical alignment of the text with it's line.

<p style="vertical-align:top;">Top Aligned</p>

  1. top - Aligns text at the top of the line.

  2. baseline - Aligns text at the baseline.

  3. bottom - Aligns text at the bottom of the line.

Font Family

The font-family attribute specifies the font family to use.

<p style="font-family:roboto-bold;">This is a paragraph.</p>

Name of the font family to use.

Font Size

The font-size attribute specifies the size of the font.

<p style="font-size:24px;">This is a paragraph.</p>

Text font size, point size syntax only.

Left Padding

The left-padding attribute specifies the left padding of the list.

<ol style="left-padding:0">

Number of tabs to use for list padding.


Example Rich Text

                <style>
                          @font-face {
                                font-family: roboto-bold;
                                src: url('file:fonts/Roboto-Bold.ttf')
                          }
                           @font-face {
                                font-family: light;
                                src: url('file:fonts/Roboto-Light.ttf')
                          } 
                        </style>
                         <p style="text-align:left">Left Aligned </p>
                         <p style="text-align:right"> Right Aligned </p>
                         <p style="text-align:center"> Aligned Center </p> 
                         <p> <b> <u> I am Bold </u> </b> <br>I should be on my own line <br>
                         <i> I am italic </i> This long text should not be broken up. This
             long text should not be broken up.This long text should not be
             broken up.</p>
                         <p>
                         <ol>
                         <li> item 1 </li>
                         <li> item 2 </li> 
                         <li> item 3 </li> 
                         </ol>
                         <ul> 
                                <li> item A </li> 
                                <li> item B </li> 
                                <li> item C </li> 
                         </ul>
                         </p>
                         <p style="font-family:roboto-bold"> Roboto Bold </p> 
                          <p style="font-family:light"> Roboto Light </p> 
                          <p style="font-size: 50px"> 50px </p> 
                         <p style="text-align:right">right aligned <span style="color:blue">
             combined with blue</span></p>
                         <p style="text-align:center">mixed styles: <span style="font-family
                         :roboto-bold;color:blue">blue and bold</span> or <span style="color
             :green"><i>Green italic</i></span></p>
                

Translation and Internationalization

Storyboard makes it simple to translate and internationalize the text content of your application. Dynamic text content is treated the same as any other dynamic content that is rendered to the display. Within the text render extension, the translatable content should be associated with a variable. Any changes that occur to that variable, will trigger a screen re-draw to occur if that variable is being used in the current display.

translation_sample.png

Changes in string content of variables is automatically reflected in the user interface to those locations. This makes the translation activity significantly less labour intensive, as it is only required to identify text strings that are statically declared (ie not bound to a variable) and convert them to be associated with a variable. This variable to text string association forms the base of Storyboard's internationalization support. In order to change the UI to reflect a new language one has only to update the text variables with the appropriate UTF-8 encoded text strings.

There are many different ways to organize the association of language to text strings and then the association of those text strings to user interface variables. Storyboard does not impose any particular method, but generally speaking there are two main techniques that can be considered to accomplish these associations.

One method is to simply keep track of all of the text variables being referenced and for each variable have the translated string stored. This means that if I had a control, for example named mybutton on a layer named mylayer, with a text render extension whose text property was associated with a variable (ie myvariable) that our language database would store the the fully qualified name, mylayer.mybutton.myvariable, along with the value of the string, perhaps "Hello". This technique is simple and works well for small applications where there is not a lot of duplication of text content. The sample Translation demonstrates this technique being used in conjunction with multiple independent comma separated value (CSV) files containing the language database information. Early versions of Storyboard provided a minimal level of automation to help manage these mappings.

A second technique provides a more scalable approach to translated applications and is recommended for sophisticated translation and internationalization applications. Instead of having each UI instance of text declare a local variable all translated text refers to a single translation namespace with unique text strings identified by unique ids. This centralized approach allows unique text strings to be declared once and more easily allows for contextualized translations to be differentiated from one another. The sample TranslationUsingId demonstrates this technique and is supported within Storyboard Designer with automation tools that more easily integrate into workflows supported by text translation professionals.

The TranslationUsingId and Translation samples can be imported into your Storyboard Designer workspace via File > Import > Storyboard Sample.

In some circumstances, most notably with non-latin character sets, it may also be a requirement to dynamically change the fonts being used to map to an alternative font that provides the appropriate glyph support for the characters being rendered. Additionally it may be that a change in translated text requires additional properties to be adjusted, such as font point size or control dimensions, to accommodate the new translation. These can be adjusted as a straightforward change in value of a Storyboard variable. This is exactly the same technique that is used for translated text, the difference of course being that rather than changing text string values, the changes are to the font name or point size or numeric property of a control.

Text Translation View

Storyboard Designer contains a view specifically designed to assist with the process of converting and managing translated text using the common translation namespace technique mentioned above. To open the Text Translation view select Window>Show View> Text Translation.

open_translation_view.png

The Text Translation view shows the text and translation content for projects that have identified themselves as having a translation database. For information on getting started establishing a translation database, refer to the section Translating a Storyboard Application.

For example, looking at the Text Translation view when then TranslationUsingId project is selected will show three areas of content.

translation_text_fields.png

The Text References tab of the Text Translation view shows all of the text references in text render extensions that have been detected in the project. This includes text references that are static (not bound to variables), already associated with variables or associated with variables in the translation namespace. The filters at the bottom of the tab can help reduce the content displayed. This tab is the primary area where you would manage the associations of text in the application with translated values. Right clicking on any of the text entry fields will show a menu of choices:

Translate...

This will perform a lookup of the text string in the translation database. If a value is found then it will be used, otherwise a prompt to create a new text translation entry will occur. This option is only available for non-translated content.

Synchronize Selection

This is used to synchronize the value of the current selection with other language values using the same key. This can only be performed on translated content.

Switch Translation ID

This is used to switch an existing translation to another translation and is used when there are multiple translations with different contexts of use, or to change the translation id to something different entirely. This can only be performed on translated content.

Remove Translation

This will remove a translation id mapping and revert the value to a static string or local variable. This can only be performed on translated content.

translation_attributes_fields.png

The Attributes tab of the Text Translation view shows all of the non-text variables that are being tracked and adjusted in association with language changes. Unlike text references, these variables must be manually added but can include both user defined variables, such as font names or point sizes, and model internal variables, such as a control's position or size. This tab is the primary area where you would manage the associations of variables, but it is possible to add variables to the translation view from the Variables view or Application Model by right clicking on an existing variable and selecting Add Translation Variable. Within the Attributes tab, right clicking on any of the text entry fields will show a menu of choices:

Add Variable To Translation

This will open a variable selection dialog allowing you to manually select variables that have already been defined within the model to be associated with a translation language change.

Update Translated Variable

This is used to synchronize the value maintained in the attribute database for the current language with the current value used in the UI. This is a handy option to use when you want to interactively work through a set of language translations and make UI adjustments interactively and save the current value as shown in Designer.

Synchronize Selection

Similar to the the functionality in the Text References tab, this allows the synchronization of values for a field across multiple languages.

Remove Translation

This will remove the association of a variable as being changed when a language changes. This change is propagated to the translation attribute database.

translation_id_fields.png

The Translation IDs tab of the Text Translation view shows all of the translation identifiers (ids) for the current translation set and the value of those ids for the currently selected language. Translation ids that are currently referenced and in use are shown in bold. At this time Storyboard does not offer support for the editing of these database values from within Designer but suggests that the values be edited in their source database, for example the comma separated value (CSV) file in the translations directory.

Translating a Storyboard Application

Many user interfaces do not start out with translation as a primary concern. Translation and internationalization of a UI is frequently an activity that occurs after the main user experience issues have been addressed and a workflow established in a primary language.

When the Text Translation view is opened and no translation database has been associated with the project, then what you will see will be an empty view prompting for a translation database to be created:

translation_no_database.png

To get started translating your application, create a binding to a translation database where the text strings for the application in the default language can be stored along with any additional attributes that need to be considered as part of the internationalization effort for this application. Create this binding by selecting Create Translation Database which will open a New Translationwizard:

translation_pick_database.png

Currently Storyboard Designer only has the ability to interface with comma separated value (CSV) multi-column language files. In these files, commonly used by translators in programs such as Excel, a single column contains a unique identifier, then subsequent columns contain the different language values for that identifier. For example:

ID,English,French,Spanish
1,Hello,Bonjour,Hola
                    

If a translation database such as this is already available, then you can select it in this dialog, otherwise a new one will be created for you. These files contain the text string information used for different text values in different languages. It is frequently necessary to also change non-text attributes that are Storyboard specific so these attributes are maintained in a separate database file using the same organization but instead of unique identifiers the fully qualified path to the Storyboard variable that should be changed is used instead:

ID,English,French,Spanish
Layer.Control.grd_width,192,310,192
                    

These files are stored in the translations directory of the project with the name(s) that you have provided.

Once a translation database is established, then the first thing to do is to run an analysis of the current user interface and to establish translation mappings for the text content that is present in the default language of the application. This can be done on a field by field basis using the entries in the Text References tab or a full analysis can be performed using the Extra Text option. The Extract Text button in the Text Translation view scans the all text field references and presents a dialog that allows the user to select and approve the automatically identified translations and to create new text translations for fields that do not already have a translation entry. This tool significantly helps bootstrap the translation process.

After this bootstrapping, the translation database file (default translations/translations.csv) can be provided to text translators or linguists to populate with new language entries. For more details on the best practices for editing these files to create UTF-8 encoded text strings, refer to the next section Creating and Editing Translation Content CSV Files. If the translation database file is replaced in the project and the project re-opened, then the new language values will automatically become available for use.

Creating and Editing Translation Content CSV Files

We have explored two tools for editing and creating translation content, Microsoft Office and Open Office Calc. Both tools are able to save UTF-8 encoded (csv) files.

Microsoft Excel (Office 365 Version)

Microsoft Excel is a popular spreadsheet software solution that is widely adopted in many industries.

  1. Using Excel, open a spreadsheet file via File > Open... (note: this can be a spreadsheet created using Excel or Calc)

  2. Save the file as a (csv) file via File > Save As > Browse

  3. Choose 'CSV (Comma delimited) (*.csv)' in 'Save as type:'

  4. At the bottom of the dialog, select tools > Web Options....

    excel_save_as.png
  5. Select the 'Encoding' tab and choose to save this document as: Unicode (UTF-8).

    excel_web_options.png

Open Office Calc

It is free and can be downloaded from www.openoffice.org.

  1. Using Calc, open a spreadsheet file via File > Open... (note: this can be a spreadsheet created using Calc or Excel).

  2. Save the file as a (csv) file via File > Save as... > Text CSV(.csv)

    calc_save_as_csv.png
  3. When saving a (csv) file, Open Office Calc will ask which character encoding you wish to use for the file, be sure to choose Unicode(UTF-8).

    calc_char_encoding_utf8.png

Script Specific Text Shaping and Layout

Storyboard includes unidirectional text layout as part of the standard product offering. Support for bi-directional (mixed mode left-to-right and right-to-left) text is provided through commercial third party Crank Software partners.

Advanced text shaping and glyph positioning functionality for certain language scripts is provided in Storyboard by the libgre-plugins-harfbuzz plugin based on the functionality of the Harfbuzz text shaping library (harfbuzz.github.io). This text shaping technology is dependent on the FreeType font manager and advanced C++ toolchain support and is available for QNX, MacOS and most Linux platforms.

Advanced text shaping can have a significant impact on performance so it is disabled by default. In order to enable text shaping globally within an application for all text rendering set the text shaping script and language values into the application level grd_text_shaper_attrs variable. The value for this variable should be a string that identifies the desired text script and the language processing by their respective ISO codes and formatted as script=<script_code>;language=<language_code>

Script tags: https://en.wikipedia.org/wiki/ISO_15924
Language tags: https://en.wikipedia.org/wiki/ISO_639

For example, a sample Lua script to set the text shaping for Thai script may look like:

gre.set_value("grd_text_shaper_attrs", "script=Thai;lang=th")

To disable the text shaping set the value to an empty string.

gre.set_value("grd_text_shaper_attrs", "")

Most latin languages do not require text shaping support and can receive an increase in performance by omitting the text shaping processing.

Was this article helpful?
0 out of 0 found this helpful