Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ The most reliable way to validate screen reader support is to test your app dire

## Accessible names from dynamic data

Many Windows controls render content through *data binding*, which means accessible names are often determined from runtime data rather than static XAML. When list or item templates are populated dynamically, verify that each generated item exposes a meaningful accessible name after binding completes. Depending on the control and template composition, you may need to set or update accessibility properties programmatically so the automation tree reflects the final rendered state. For an end-to-end example, see "Scenario 4" in the [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample) (archived legacy sample).
Many Windows controls render content through *data binding*, which means accessible names are often determined from runtime data rather than static XAML. When list or item templates are populated dynamically, verify that each generated item exposes a meaningful accessible name after binding completes. Depending on the control and template composition, you may need to set or update accessibility properties programmatically so the automation tree reflects the final rendered state. For an end-to-end example, see the [WinUI Gallery accessibility sample](https://github.com/microsoft/WinUI-Gallery/blob/main/WinUIGallery/Samples/ControlPages/Accessibility/AccessibilityScreenReaderPage.xaml).

## Accessible names and localization

Expand All @@ -129,5 +129,5 @@ Attached properties in [**AutomationProperties**](/windows/windows-app-sdk/api/w

* [Accessibility overview](accessibility-overview.md)
* [**AutomationProperties.Name**](/dotnet/api/system.windows.automation.automationproperties.name)
* [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample) (archived legacy sample)
* [WinUI Gallery accessibility sample](https://github.com/microsoft/WinUI-Gallery/blob/main/WinUIGallery/Samples/ControlPages/Accessibility/AccessibilityScreenReaderPage.xaml)
* [Accessibility testing](accessibility-testing.md)
6 changes: 3 additions & 3 deletions hub/apps/design/accessibility/custom-automation-peers.md
Original file line number Diff line number Diff line change
Expand Up @@ -461,6 +461,6 @@ More generally, be conservative with exceptions. Many clients cannot convert pro
## Related topics
* [Accessibility overview](accessibility-overview.md)
* [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample)
* [**FrameworkElementAutomationPeer**](/uwp/api/Windows.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer)
* [**AutomationPeer**](/uwp/api/Windows.UI.Xaml.Automation.Peers.AutomationPeer)
* [**OnCreateAutomationPeer**](/uwp/api/windows.ui.xaml.uielement.oncreateautomationpeer)
* [**FrameworkElementAutomationPeer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.peers.frameworkelementautomationpeer)
* [**AutomationPeer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.peers.automationpeer)
* [**OnCreateAutomationPeer**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.oncreateautomationpeer)
5 changes: 2 additions & 3 deletions hub/apps/design/accessibility/high-contrast-themes.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,6 @@ The following code snippet (from an App.xaml file) shows an example [**ThemeDict
## Related topics

- [Accessibility overview](accessibility-overview.md)
- [UI contrast and settings sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BC%23%5D-Windows%208%20app%20samples/C%23/Windows%208%20app%20samples/XAML%20high%20contrast%20style%20sample%20(Windows%208)) (archived legacy sample)
- [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample) (archived legacy sample)
- [XAML high contrast sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BC%23%5D-Windows%208%20app%20samples/C%23/Windows%208%20app%20samples/XAML%20high%20contrast%20style%20sample%20(Windows%208)) (archived legacy sample)
- [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample) (archived legacy sample — no WinUI 3 equivalent available)
- [XAML high contrast sample](https://github.com/microsoft/WinUI-Gallery/blob/main/WinUIGallery/Samples/ControlPages/Accessibility/AccessibilityColorContrastPage.xaml)
- [**ThemeSettings.HighContrast**](/windows/windows-app-sdk/api/winrt/microsoft.ui.system.themesettings.highcontrast)
2 changes: 1 addition & 1 deletion hub/apps/design/accessibility/keyboard-accessibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -307,4 +307,4 @@ For example, even without a physical Tab key, Narrator supports gestures that ma
- [Accessibility overview](accessibility-overview.md)
- [Keyboard interactions](../input/keyboard-interactions.md)
- [Touch keyboard sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/TouchKeyboard) (legacy sample)
- [XAML accessibility sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/XAML%20accessibility%20sample) (archived legacy sample)
- [XAML accessibility sample](https://github.com/microsoft/WinUI-Gallery/blob/main/WinUIGallery/Samples/ControlPages/Accessibility/AccessibilityKeyboardPage.xaml)
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,14 @@ If your app has images that must be mirrored (that is, the same image can be fli
If your app requires a different image to flip the image correctly, then you can use the resource management system with the `LayoutDirection` qualifier (see the LayoutDirection section of [Tailor your resources for language, scale, and other qualifiers](/windows/apps/windows-app-sdk/mrtcore/tailor-resources-lang-scale-contrast#layoutdirection)). The system chooses an image named `file.layoutdir-rtl.png` when the app runtime language (see [Understand user profile languages and app manifest languages](manage-language-and-region.md)) is set to an RTL language. This approach may be necessary when some part of the image is flipped, but another part isn't.

## Handling right-to-left (RTL) languages
When your app is localized for right-to-left (RTL) languages, use the [**FrameworkElement.FlowDirection**](/uwp/api/Windows.UI.Xaml.FrameworkElement.FlowDirection) property, and set symmetrical padding and margins. Layout panels such as [**Grid**](/uwp/api/Windows.UI.Xaml.Controls.Grid?branch=live) scale and flip automatically with the value of **FlowDirection** that you set.
When your app is localized for right-to-left (RTL) languages, use the [**FrameworkElement.FlowDirection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.flowdirection) property, and set symmetrical padding and margins. Layout panels such as [**Grid**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.grid) scale and flip automatically with the value of **FlowDirection** that you set.

Set **FlowDirection** on the root layout panel (or frame) of your Page, or on the Page itself. This causes all of the controls contained within to inherit that property.

> [!IMPORTANT]
> However, **FlowDirection** is *not* set automatically based on the user's selected display language in Windows settings; nor does it change dynamically in response to the user switching display language. If the user switches Windows settings from English to Arabic, for example, then the **FlowDirection** property will *not* automatically change from left-to-right to right-to-left. As the app developer, you have to set **FlowDirection** appropriately for the language that you are currently displaying.

The programmatic technique is to use the `LayoutDirection` property of the preferred user display language to set the [**FlowDirection**](/uwp/api/Windows.UI.Xaml.FrameworkElement.FlowDirection) property (see the code example below). Most controls included in Windows use **FlowDirection** already. If you're implementing a custom control, it should use **FlowDirection** to make appropriate layout changes for RTL and LTR languages.
The programmatic technique is to use the `LayoutDirection` property of the preferred user display language to set the [**FlowDirection**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.flowdirection) property (see the code example below). Most controls included in Windows use **FlowDirection** already. If you're implementing a custom control, it should use **FlowDirection** to make appropriate layout changes for RTL and LTR languages.

```csharp
this.languageTag = Windows.Globalization.ApplicationLanguages.Languages[0];
Expand All @@ -59,11 +59,11 @@ this.languageTag = Windows.Globalization.ApplicationLanguages.Languages[0];
var flowDirectionSetting = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues["LayoutDirection"];
if (flowDirectionSetting == "LTR")
{
this.layoutRoot.FlowDirection = Windows.UI.Xaml.FlowDirection.LeftToRight;
this.layoutRoot.FlowDirection = Microsoft.UI.Xaml.FlowDirection.LeftToRight;
}
else
{
this.layoutRoot.FlowDirection = Windows.UI.Xaml.FlowDirection.RightToLeft;
this.layoutRoot.FlowDirection = Microsoft.UI.Xaml.FlowDirection.RightToLeft;
}
```

Expand All @@ -79,11 +79,11 @@ m_languageTag = Windows::Globalization::ApplicationLanguages::Languages().GetAt(
auto flowDirectionSetting = Windows::ApplicationModel::Resources::Core::ResourceContext::GetForCurrentView().QualifierValues().Lookup(L"LayoutDirection");
if (flowDirectionSetting == L"LTR")
{
layoutRoot().FlowDirection(Windows::UI::Xaml::FlowDirection::LeftToRight);
layoutRoot().FlowDirection(Microsoft::UI::Xaml::FlowDirection::LeftToRight);
}
else
{
layoutRoot().FlowDirection(Windows::UI::Xaml::FlowDirection::RightToLeft);
layoutRoot().FlowDirection(Microsoft::UI::Xaml::FlowDirection::RightToLeft);
}
```

Expand All @@ -95,11 +95,11 @@ this->languageTag = Windows::Globalization::ApplicationLanguages::Languages->Get
auto flowDirectionSetting = Windows::ApplicationModel::Resources::Core::ResourceContext::GetForCurrentView()->QualifierValues->Lookup("LayoutDirection");
if (flowDirectionSetting == "LTR")
{
this->layoutRoot->FlowDirection = Windows::UI::Xaml::FlowDirection::LeftToRight;
this->layoutRoot->FlowDirection = Microsoft::UI::Xaml::FlowDirection::LeftToRight;
}
else
{
this->layoutRoot->FlowDirection = Windows::UI::Xaml::FlowDirection::RightToLeft;
this->layoutRoot->FlowDirection = Microsoft::UI::Xaml::FlowDirection::RightToLeft;
}
```

Expand All @@ -114,7 +114,7 @@ First, in your app's Resources File (.resw), add a property identifier with the
Instead of a single line of code for all languages, this depends on the translator "translating" this property resource correctly for each translated language; so be aware that there's that extra opportunity for human error when you use this technique.

## Important APIs
* [FrameworkElement.FlowDirection](/uwp/api/Windows.UI.Xaml.FrameworkElement.FlowDirection)
* [FrameworkElement.FlowDirection](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.flowdirection)
* [LanguageFont](/uwp/api/Windows.Globalization.Fonts.LanguageFont?branch=live)

## Related topics
Expand Down
8 changes: 4 additions & 4 deletions hub/apps/design/globalizing/manage-language-and-region.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,11 @@ The third language list of interest is the intersection between the two lists th

More specifically, the app runtime language list is made up of these items.

1. **(Optional) Primary Language Override**. The [**PrimaryLanguageOverride**](/uwp/api/Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride) is a simple override setting for apps that give users their own independent language choice, or apps that have some strong reason to override the default language choices. To learn more, see the [Application resources and localization sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BC%23%5D-Windows%208%20app%20samples/C%23/Windows%208%20app%20samples/Application%20resources%20and%20localization%20sample%20(Windows%208)).
1. **(Optional) Primary Language Override**. The [**PrimaryLanguageOverride**](/uwp/api/Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride) is a simple override setting for apps that give users their own independent language choice, or apps that have some strong reason to override the default language choices. To learn more, see the [Application resources and localization sample](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/ResourceManagement/cs/cs-winui/winui_desktop_packaged_app/MainWindow.xaml.cs).
2. **The user's languages that are supported by the app**. This is the user profile language list filtered by the app manifest language list. Filtering the user's languages by those supported by the app maintains consistency among software development kits (SDKs), class libraries, dependent framework packages, and the app.
3. **If 1 and 2 are empty, then the default or first language supported by the app**. If the user profile language list doesn't contain any languages that the app supports, then the app runtime language is the first language supported by the app.

In code you can use the [ResourceContext.QualifierValues](/uwp/api/windows.applicationmodel.resources.core.resourcecontext.QualifierValues) property to access the app runtime language list in the form of a string containing a semicolon-delimited list of BCP-47 language tags.
In code you can use the [ResourceContext.QualifierValues](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourcecontext.qualifiervalues) property to access the app runtime language list in the form of a string containing a semicolon-delimited list of BCP-47 language tags.

```csharp
string runtimeLanguages = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues["Language"];
Expand Down Expand Up @@ -193,7 +193,7 @@ The following table contains examples of what the user would see in your app's U
* [GlobalizationPreferences.Languages](/uwp/api/windows.system.userprofile.globalizationpreferences.Languages)
* [ApplicationLanguages.ManifestLanguages](/uwp/api/windows.globalization.applicationlanguages.ManifestLanguages)
* [PrimaryLanguageOverride](/uwp/api/Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride)
* [ResourceContext.QualifierValues](/uwp/api/windows.applicationmodel.resources.core.resourcecontext.QualifierValues)
* [ResourceContext.QualifierValues](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourcecontext.qualifiervalues)
* [ResourceContext.Languages](/uwp/api/windows.applicationmodel.resources.core.resourcecontext.Languages)
* [ApplicationLanguages.Languages](/uwp/api/windows.globalization.applicationlanguages.Languages)
* [Windows.Globalization](/uwp/api/windows.globalization?branch=live)
Expand All @@ -210,4 +210,4 @@ The following table contains examples of what the user would see in your app's U
* [How the Resource Management System matches language tags](/windows/uwp/app-resources/how-rms-matches-lang-tags)

## Samples
* [Application resources and localization sample](https://code.msdn.microsoft.com/windowsapps/Application-resources-and-cd0c6eaa)
* [Application resources and localization sample](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/ResourceManagement/cs/cs-winui/winui_desktop_packaged_app/MainWindow.xaml.cs)
Original file line number Diff line number Diff line change
Expand Up @@ -185,4 +185,4 @@ Sorting follows the **Regional Control Panel** format:

## Samples

- [Application resources and localization sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BC%23%5D-Windows%208%20app%20samples/C%23/Windows%208%20app%20samples/Application%20resources%20and%20localization%20sample%20(Windows%208))
- [Application resources and localization sample](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/ResourceManagement/cs/cs-winui/winui_desktop_packaged_app/MainWindow.xaml.cs)
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ See [Localize your UI strings](localize-strings.md) for more information on maki

## LayoutDirection

A `layoutdirection` qualifier corresponds to the layout direction of the display language setting. For example, an image may need to be mirrored for a right-to-left language such as Arabic or Hebrew. Layout panels and images in your UI will respond to layout direction appropriately if you set their [FlowDirection](/uwp/api/Windows.UI.Xaml.FrameworkElement.FlowDirection) property (see [Adjust layout and fonts, and support RTL](/windows/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl)). However, the `layoutdirection` qualifier is for cases where simple flipping isn't adequate, and it allows you to respond to the directionality of specific reading order and text alignment in more general ways.
A `layoutdirection` qualifier corresponds to the layout direction of the display language setting. For example, an image may need to be mirrored for a right-to-left language such as Arabic or Hebrew. Layout panels and images in your UI will respond to layout direction appropriately if you set their [FlowDirection](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.flowdirection) property (see [Adjust layout and fonts, and support RTL](/windows/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl)). However, the `layoutdirection` qualifier is for cases where simple flipping isn't adequate, and it allows you to respond to the directionality of specific reading order and text alignment in more general ways.

## Scale

Expand Down
Loading