Support for Assistive Technology

The medical equipment that helps people with disabilities accomplish everyday tasks usually tends to illustrate or read what is shown inside a user interface. For this reason, all of the items inside a UI must support interaction with the following:

• On-screen keyboard software
• Voice-recognition software
• Screen readers

As mentioned, Windows Store apps have built-in support for these hardware/software instruments. For example, every control inside a XAML page supports the Tab navigation or provides an “accessible name” that can be used from the screen reader. Usually the value of this name is the inner text for controls. Sometimes this value needs to be explicitly set using the AutomationProperties.Name field. Table 10-1 summarizes which controls have built-in support for the accessible name and in which controls this property needs to be set.

Listing 10-1 shows an example of how to use AutomationProperties.Name.

Listing 10-1.  AutomationProperties.Name

XAML
<StackPanel>
  <!-- Content property is used as accessible name -->
  <TextBlock Name="BuiltInSupport">This is an accessible name</TextBlock>
  <!-- This is an example of AutomationProperties.Name -->
  <TextBox AutomationProperties.Name="MyAccessibleName" Name="AccessibleNameTextBox" Width="100"/>
  <!-- This is an example of AutomationProperties.LabeledBy -->
  <TextBox
      AutomationProperties.LabeledBy="{Binding ElementName=BuiltInSupport}"
      Name="LabeledByTextBox" Width="100"/>
</StackPanel>

To fully support keyboard capabilities, all the controls inside a user interface must provide navigation through the Tab key. Usually the navigation order is based on how the controls are added or listed in a XAML view, or how they are programmatically added to a container. It is possible to override this setting using the TabIndex attribute, assigning an incremental value corresponding to the order. If a control needs to be passed over the Tab key, IsEnabled or IsTabStop properties must be set to False. Listing 10-2 shows an example.

Listing 10-2.  TabIndex and IsTabStop Example

XAML
<StackPanel>
  <!-- Content property is used as accessible name -->
  <TextBlock Name="BuiltInSupport" TabIndex="1">This is an accessible name</TextBlock>
  <!-- This is an example of AutomationProperties.Name -->
  <TextBox AutomationProperties.Name="MyAccessibleName" Name="AccessibleNameTextBox" Width="100" TabIndex="2" />
  <!-- This is an example of AutomationProperties.LabeledBy -->
  <TextBox
      AutomationProperties.LabeledBy="{Binding ElementName=BuiltInSupport}"
      Name="LabeledByTextBox" Width="100" IsTabStop="False" />
</StackPanel>

In Listing 10-2, the third label won’t ever take focus using Tab key.

ItemsControls, also a Tab navigation feature, provides built-in navigation between shown data. This is reached using directional arrows on the keyboard.

Sometimes is very helpful to provide shortcuts inside a user interface. There are two kinds of shortcuts:

• AccessKey, linked to a UI portion by a combination of Alt + letter key
• AcceleratorKey, linked to an app command by a combination of Ctrl + letter key

These shortcuts can be defined using the AutomationProperties.AccessKey and AutomationProperties.AcceleratorKey attached properties, as shown in Listing 10-3.

Listing 10-3.  AccessKey and AcceleratorKey Example

XAML
<StackPanel>
  <!-- This is an example of AutomationProperties.AccessKey -->
  <TextBox AutomationProperties.Name="MyAccessibleName"    Name="AccessibleNameTextBox" Width="100" TabIndex="2"   ToolTipService.ToolTip="Shortcut key: Alt+P"
AutomationProperties.AccessKey="Alt P"
 />
  <Button x:Name="SubmitButton" Click="SubmitButton_Click"
      ToolTipService.ToolTip="Shortcut key: Ctrl+A"
      AutomationProperties.AcceleratorKey="Control A">
      <TextBlock>Submit</TextBlock>
    </Button>
</StackPanel>

Supporting High-Contrast Themes

High-contrast themes allow people with lower vision to identify controls on a user interface. Windows Store apps have a built-in support for high-contrast themes because the default theme has the high-contrast support in it. If you need to customize a theme, remember to check if support for high-contrast themes is present. If you use Blend to customize a theme, it automatically generates a cloned theme for high-contrast support. You can also check programmatically if a high-contrast theme is enabling by using the AccessibilitySettings class (Figure 10-1).

There are two properties available in this class: HighContrast, which contains a value that indicates if high-contrast feature is enabled, and HighContrastScheme, which contain the name of the high-contrast scheme.

Testing a Windows Store App for Accessibility

After your app provides all the features related to accessibility, you can take advantage of some tools to verify if these functionalities are correctly implemented. Windows Software Development Kit for Windows 8.1 includes two tools named Inspect and UI Accessibility Checker that can be found in <install_dir><Program Files>Windows Kits8.1in<version>.

Inspect allows you to verify accessible data in a UI element, reading available AutomationProperties (Figure 10-2).

UI Accessibility Checker (AccChecker) can be used to check if the app generates accessibility problems at runtime. Once started, select the name of the application in the “Choose window from list” field, then select on the right side what kind of verification routines need to be executed, and then click the Run Verification button. The results will be display in a series of tabbed windows inside the tool (Figure 10-3).

Get Ready for Localization

Again, if you are planning to distribute your application to users in different cultures and languages, it is necessary to provide localization for UI controls. There are few steps to follow.

• Translate the UI resources
• Convert the date and time format
• Convert the number and currency format
• Adapt layout and fonts for different languages
• Use the Multilingual App Toolkit

The localization process is not simple, so it is best to use a global-ready format to simplify the process (if you decide to distribute to a global market your app in the development stage).

Let’s start from resources.

Using UI Resources in Windows Store Apps

It’s a good practice to put strings shown in the user interface inside the resource file: this makes editing very simple. Then the strings are ready to be referenced in the code or markup.

The first step is to set the Default Language property of a Windows Store app: double-click package.appxmanifest in Visual Studio 2013 and find the Application UI tab. Type into the Default Language box en-US (using the BCP-47 language tag, more info at tools.ietf.org/html/bcp47). This setting is used when no user language or display language on the user machine is available inside the application (Figure 10-4).

All the string resources are contained inside a resource file: to create an English-localized resource file these steps need to be followed.

1. Localize the Strings folder in the project root, and then add a subfolder named as the BCP-47 language tag. Note that the project already has an en-US folder because it’s the default language (Figure 10-5).

   

   Figure 10-5. Resources folder structure

2. Add a new item, selecting the “Resources File (.resw)” template from the list (Figure 10-6). It is suggested to use the default name for the resource file (Resources.resw).

Finally, each localized string needs to be added to this file. After double-clicking Resources.resw, Visual Studio 2013 opens the Resource Editor. For each localized string, the following fields must be filled:

• Name: A unique name for the resource
• Value: The value for the resource
• Comment: A comment for the resource

It’s a good practice to always fill the comment field to simplify the translation process to other languages by other people then the resource can be used inside the code (see Listing 10-4).

Listing 10-4.  Use Resources Inside the Code

C#
var loader = new Windows.ApplicationModel.Resources.ResourceLoader();
var message = loader.GetString("WelcomeMessage");
VB
Dim loader = New Windows.ApplicationModel.Resources.ResourceLoader()
Dim message = loader.GetString("WelcomeMessage")

Another way to link a resource to a control is to use a pointed notation in the resource file. For example, to insert text inside a TextBlock in Windows Store App UI with the x:Name equal to “WelcomeLabel”, you can add a new resource using the syntax ControlId.ControlProperty in the Name field, as in Figure 10-7.

Then you can set the x:UID field with the value of the x:Name, as shown in Listing 10-5.

Listing 10-5.  Use Resources Inside Markup

XAML
<TextBlock x:Name="WelcomeLabel" x:Uid="WelcomeLabel"></TextBlock>

Now it is possible to add other languages to your Windows Store app by adding to the Resources folder a new subfolder for the specific language. Figures 10-8 and 10-9 show the adding of another resource file already filled with the value for the it-IT language.

To test the application in a different language, it is possible to change the display language on the development machine in the Clock, Language and Region section of the Control Panel, as shown in Figure 10-10.

Note that the listed order is important: if the first language is not available in the application, the following language is chosen as a display language replacement.

You can create more resource files for specific languages inside a language subfolder by using the same filename in different available language subfolders. Figure 10-11 shows how to create a new resource file and Listing 10-6 shows how to retrieve stored values using the syntax /ResourceFileName/StringName. In this case you use GetCurrentView, passing in the name of the resource file.

Listing 10-6.  Use Multiple Resource Files

XAML
<TextBlock x:Name="ErrorLabel" x:Uid="/Errors/GenericError"></TextBlock>
C#
var res = Windows.ApplicationModel.Resources.ResourceLoader.GetForCurrentView("Errors");
ErrorLabel.Text = res.GetString("GenericError");
VB
Dim res = Windows.ApplicationModel.Resources.ResourceLoader.GetForCurrentView("Errors")
ErrorLabel.Text = res.GetString("GenericError")

How To Set Available Languages for a Windows Store App

Available languages in your Windows Store app can be set inside the Package.appxmanifest file: by doing this, the Windows Store will show the same language in the app description. The following steps show how to set available languages.

1. Open the Package.appxmanifest with a right-click and then select View Code (Figure 10-12).

   

   Figure 10-12. Open the Package.appxmanifest code editor

2. Localize the Resources node.
3. Comment the item <Resource Language=“x-generate” />.
4. Type the code lines in Listing 10-7 containing the language tag available in the app.

   Listing 10-7.  Manually Set Available Languages

   <Resources>
     <!-- <Resource Language="x-generate" /> -->
     <!-- Manually setting available languages -->
     <Resource Language="en-US" />
     <Resource Language="it-IT" />
   </Resources>

How To Format Date and Time Properly

The date and time needs to be formatted using the current culture. If the date is provided by a user, it is possible to use a DatePicker control that has a built-in support for localization. On the other hand, WinRT include the Windows.Globalization.DateTimeFormatting namespace, which includes all the classes and enumeration to format the date and time programmatically. Figure 10-13 shows its objects.

The only available class is DateTimeFormatter, which allows you to format the date and time through its constructors. Let’s see how to format a date inside a TextBlock using the display language. In this case, DateTimeFormatter needs to be created with the correct culture and then the date is passed to the Format() method of the current instance, as shown in Listing 10-8.

Listing 10-8.  Use DateTimeFormatter

C#
DateTimeFormatter formatter =
    new DateTimeFormatter(HourFormat.Default, MinuteFormat.Default, SecondFormat.None);
 
DateNoSecondsTextblock.Text = formatter.Format(DateTime.Now);
VB
 
Dim formatter As New DateTimeFormatter(HourFormat.[Default], MinuteFormat.[Default], SecondFormat.None)
 
DateNoSecondsTextblock.Text = formatter.Format(DateTime.Now)

In Listing 10-8, the output shows the date and the time without the seconds part. It is also possible to use templates to format the date. In Listing 10-9, you reach the same result as you do in Listing 10-8.

Listing 10-9.  Use DateTimeFormatter with Templates

C#
DateTimeFormatter formatter =
    new DateTimeFormatter("longdate shorttime");
 
DateMaskFormatTextblock.Text = formatter.Format(DateTime.Now);
VB
 
Dim formatter As New DateTimeFormatter("longdate shorttime")
 
DateMaskFormatTextblock.Text = formatter.Format(DateTime.Now)

Table 10-2 summarizes the date format templates.

There are also available patterns to format dates: these are delimited by braces. Listing 10-10 shows how to use them.

Listing 10-10.  Use DateTimeFormatter with Patterns

C#
formatter = new DateTimeFormatter("{month.integer}/{day.integer}/{year.full}
  {hour.integer}:{minute.integer}");
DateTemplateTextblock.Text = formatter.Format(DateTime.Now);
VB
 
formatter = New DateTimeFormatter("{month.integer}/{day.integer}/{year.full}{hour.integer}:{minute.integer}")
DateTemplateTextblock.Text = formatter.Format(DateTime.Now)

Table 10-3 lists the common date format patterns.

Starting with Visual Studio 2013, you can also take advantage of IntelliSense in XAML markup for these patterns. A full list can be found at msdn.microsoft.com/en-us/library/windows/apps/windows.globalization.datetimeformatting.datetimeformatter.aspx.

How To Format Number and Currency Properly

Every language has a way to format numbers and currency. WinRT provides one namespace to simplify the task: Windows.Globalization.NumberFormatting. Figure 10-14 shows the included classes.

Listing 10-11 shows a simple usage of DecimalFormatter that shows an integer part of the number grouped and always using a decimal point.

Listing 10-11.  Use DecimalFormatter

C#
DecimalFormatter formatter = new DecimalFormatter();
formatter.IsGrouped = true;
formatter.IsDecimalPointAlwaysDisplayed = true;
DecimalFormatterTextblock.Text = formatter.Format(12345.00);
VB
Dim formatter As New DecimalFormatter()
formatter.IsGrouped = True
formatter.IsDecimalPointAlwaysDisplayed = True
DecimalFormatterTextblock.Text = formatter.Format(12345.0)

The same namespace also includes the CurrencyFormatter class that helps to format currencies. Usually the first step is to retrieve the default currency (linked to the default language in the app manifest) and use it as input to create a default formatter. Then it is possible to create a specific formatter based on an input string with the name of the currency (i.e. USD) or the name of the currency associated to the BCP code and the geographical region (i.e. EUR), as shown in Listing 10-12.

Listing 10-12.  Use CurrencyFormatter

C#
// Determine the current user's default currency.
string currency = GlobalizationPreferences.Currencies[0];
 
// Create currency formatter with current preferences
CurrencyFormatter defaultCurrencyFormatter = new CurrencyFormatter(currency);
DefaultCurrencyTextblock.Text = defaultCurrencyFormatter.Format(1234.56);
 
// Create currency formatter for USD
CurrencyFormatter usdCurrencyFormatter = new CurrencyFormatter("USD");
USDCurrencyTextblock.Text = usdCurrencyFormatter.Format(1234.56);
 
// Create currency formatter for EUR
CurrencyFormatter eurITCurrencyFormatter = new CurrencyFormatter("EUR", new[] { "it-IT" }, "IT");
EurItCurrencyTextblock.Text = eurITCurrencyFormatter.Format(1234.56);
VB
' Determine the current user's default currency.
Dim currency As String = GlobalizationPreferences.Currencies(0)
 
' Create currency formatter with current preferences
Dim defaultCurrencyFormatter As New CurrencyFormatter(currency)
DefaultCurrencyTextblock.Text = defaultCurrencyFormatter.Format(1234.56)
 
' Create currency formatter for USD
Dim usdCurrencyFormatter As New CurrencyFormatter("USD")
USDCurrencyTextblock.Text = usdCurrencyFormatter.Format(1234.56)
 
' Create currency formatter for EUR
Dim eurITCurrencyFormatter As New CurrencyFormatter("EUR", New () {"it-IT"}, "IT")
EurItCurrencyTextblock.Text = eurITCurrencyFormatter.Format(1234.56)

Layout and Font Adjustment, Bi-Directional Support

Different languages may occupy more space than others in a user interface. For this reason, you should avoid setting a fixed width to controls that show text; it’s preferable to add a string resource in a localized resource file that contains the value. In Figure 10-15 you add a string named WelcomeLabel.Width with the value of 75 in the file Resources/en-US/Resources.resw. This value is used when the default language is used. Instead, if the current language is Italian, 80 is the value used in Resources/it-IT/Resources.resw (Figure 10-16). You don’t need to add anything more to the markup or code!

WinRT also provides built-in support for bi-directional text. In XAML it is possible to use the FlowDirection control property to LeftToRight (0) or RightToLeft (1). This value can be set directly inside the resource files (Figure 10-17).

The Multilingual App Toolkit

The translating process sometimes be very long and tedious. In these cases, the Multilingual App Toolkit may come in handy. This is a tool directly integrated inside Visual Studio 2013 that provides the following capabilities:

• Verify and track changes in resource files
• Provide a useful UI for choosing languages
• Support the XLIFF file format (more info at www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff)
• Help translate and identify translating issues (it supports also Microsoft Translator)

The Multilingual App Toolkit is a free tool and can be downloaded from msdn.microsoft.com/en-US/windows/apps/hh848309.aspx. Once installed, it needs to be enabled in Visual Studio in the Tools menu by clicking Enable Multilingual App Toolkit (Figure 10-18).

This step adds a new folder with a file in it called Pseudo Language(Pseudo).xlf (Figure 10-19).

Now it is possible to add a new translation language inside your app by right-clicking the project name and choosing the “Add translation languages” item (Figure 10-20).

This opens a pop-up window where you can choose the desired language (Figure 10-21).

As you can see, some items offer the Microsoft Translator to automate the resource translation process, but the non-selectable Pseudo Language item is used during testing. After selecting the Italian [it] item, a new file is added to the MultilingualResources folder (Figure 10-22).

Now you can rebuild the project and Visual Studio 2013 will automatically fill these files with all the available resources in the project. To test if something went wrong, double-click the Italian localized xlf file. Visual Studio will open the Multilingual Editor (Figure 10-23).

In this editor it is possible, using the Translate button, to automatically translate (through Microsoft Translator) all the resources (Figure 10-24).

The main reason that XLIFF files are created is so that you can share them with others to create or check translations. Visual Studio 2013 provides a very helpful feature called Send For Translation, which can be reached by right-clicking the XLF file. This feature will open a pop-up where you can choose to export the XLF file inside a folder or attach it and send through e-mail to a friend (Figure 10-25).