When thinking about layout in WPF, it is important to understand the bounding box that surrounds all elements. Each FrameworkElement consumed by the layout system can be thought of as a rectangle that is slotted into the layout. The LayoutInformation class returns the boundaries of an element's layout allocation, or slot. The size of the rectangle is determined by calculating the available screen space, the size of any constraints, layout-specific properties (such as margin and padding), and the individual behavior of the parent Panel element. Processing this data, the layout system is able to calculate the position of all the children of a particular Panel. It is important to remember that sizing characteristics defined on the parent element, such as a Border, affect its children.

The following illustration shows a simple layout.

This layout can be achieved by using the following XAML.

<Grid Name="myGrid" Background="LightSteelBlue" Height="150">
  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="250"/>
  </Grid.ColumnDefinitions>
  <Grid.RowDefinitions>
    <RowDefinition />
    <RowDefinition />
    <RowDefinition />
  </Grid.RowDefinitions>
  <TextBlock Name="txt1" Margin="5" FontSize="16" FontFamily="Verdana" Grid.Column="0" Grid.Row="0">Hello World!</TextBlock>
  <Button Click="getLayoutSlot1" Width="125" Height="25" Grid.Column="0" Grid.Row="1">Show Bounding Box</Button>
  <TextBlock Name="txt2" Grid.Column="1" Grid.Row="2"/>
</Grid>

A single TextBlock element is hosted within a Grid. While the text fills only the upper-left corner of the first column, the allocated space for the TextBlock is actually much larger. The bounding box of any FrameworkElement can be retrieved by using the GetLayoutSlot method. The following illustration shows the bounding box for the TextBlock element.

As shown by the yellow rectangle, the allocated space for the TextBlock element is actually much larger than it appears. As additional elements are added to the Grid, this allocation could shrink or expand, depending on the type and size of elements that are added.

The layout slot of the TextBlock is translated into a Path by using the GetLayoutSlot method. This technique can be useful for displaying the bounding box of an element.

private void getLayoutSlot1(object sender, System.Windows.RoutedEventArgs e)
{
    RectangleGeometry myRectangleGeometry = new RectangleGeometry();
    myRectangleGeometry.Rect = LayoutInformation.GetLayoutSlot(txt1);
    GeometryDrawing myGeometryDrawing = new GeometryDrawing();
    Path myPath = new Path();
    myPath.Data = myRectangleGeometry;
    myPath.Stroke = Brushes.LightGoldenrodYellow;
    myPath.StrokeThickness = 5;
    Grid.SetColumn(myPath, 0);
    Grid.SetRow(myPath, 0);
    myGrid.Children.Add(myPath);
    txt2.Text = "LayoutSlot is equal to " + LayoutInformation.GetLayoutSlot(txt1).ToString();
}

At its simplest, layout is a recursive system that leads to an element being sized, positioned, and drawn. More specifically, layout describes the process of measuring and arranging the members of a Panel element's Children collection. Layout is an intensive process. The larger the Childrencollection, the greater the number of calculations that must be made. Complexity can also be introduced based on the layout behavior defined by the Panel element that owns the collection. A relatively simple Panel, such as Canvas, can have significantly better performance than a more complex Panel, such as Grid.

Each time that a child UIElement changes its position, it has the potential to trigger a new pass by the layout system. Therefore, it is important to understand the events that can invoke the layout system, as unnecessary invocation can lead to poor application performance. The following describes the process that occurs when the layout system is invoked.

1. A child UIElement begins the layout process by first having its core properties measured.

2. Sizing properties defined on FrameworkElement are evaluated, such as Width, Height, and Margin.

3. Panel-specific logic is applied, such as Dock direction or stacking Orientation.

4. Content is arranged after all children have been measured.

5. The Children collection is drawn on the screen.

6. The process is invoked again if additional Children are added to the collection, a LayoutTransform is applied, or the UpdateLayout method is called.

This process and how it is invoked are defined in more detail in the following sections.

The layout system completes two passes for each member of the Children collection, a measure pass and an arrange pass. Each child Panel provides its own MeasureOverride and ArrangeOverride methods to achieve its own specific layout behavior.

During the measure pass, each member of the Children collection is evaluated. The process begins with a call to the Measure method. This method is called within the implementation of the parent Panel element, and does not have to be called explicitly for layout to occur.

First, native size properties of the UIElement are evaluated, such as Clip and Visibility. This generates a value named constraintSize that is passed to MeasureCore.

Secondly, framework properties defined on FrameworkElement are processed, which affects the value of constraintSize. These properties generally describe the sizing characteristics of the underlying UIElement, such as its Height, Width, Margin, and Style. Each of these properties can change the space that is necessary to display the element. MeasureOverride is then called with constraintSize as a parameter.

Note

There is a difference between the properties of Height and Width and ActualHeight and ActualWidth. For example, the ActualHeight property is a calculated value based on other height inputs and the layout system. The value is set by the layout system itself, based on an actual rendering pass, and may therefore lag slightly behind the set value of properties, such as Height, that are the basis of the input change. Because ActualHeight is a calculated value, you should be aware that there could be multiple or incremental reported changes to it as a result of various operations by the layout system. The layout system may be calculating required measure space for child elements, constraints by the parent element, and so on.

The ultimate goal of the measure pass is for the child to determine its DesiredSize, which occurs during the MeasureCore call. The DesiredSize value is stored by Measure for use during the content arrange pass.

The arrange pass begins with a call to the Arrange method. During the arrange pass, the parent Panel element generates a rectangle that represents the bounds of the child. This value is passed to the ArrangeCore method for processing.

The ArrangeCore method evaluates the DesiredSize of the child and evaluates any additional margins that may affect the rendered size of the element. ArrangeCore generates an arrangeSize, which is passed to the ArrangeOverride method of the Panel as a parameter. ArrangeOverridegenerates the finalSize of the child. Finally, the ArrangeCore method does a final evaluation of offset properties, such as margin and alignment, and puts the child within its layout slot. The child does not have to (and frequently does not) fill the entire allocated space. Control is then returned to the parent Panel and the layout process is complete.

WPF includes a group of elements that derive from Panel. These Panel elements enable many complex layouts. For example, stacking elements can easily be achieved by using the StackPanel element, while more complex and free flowing layouts are possible by using a Canvas.

The following table summarizes the available layout Panel elements.

For applications that require a layout that is not possible by using any of the predefined Panel elements, custom layout behaviors can be achieved by inheriting from Panel and overriding the MeasureOverride and ArrangeOverride methods. For an example, see Custom Radial Panel Sample.

Layout is a recursive process. Each child element in a Children collection gets processed during each invocation of the layout system. As a result, triggering the layout system should be avoided when it is not necessary. The following considerations can help you achieve better performance.

• Be aware of which property value changes will force a recursive update by the layout system.

  Dependency properties whose values can cause the layout system to be initialized are marked with public flags. AffectsMeasure and AffectsArrange provide useful clues as to which property value changes will force a recursive update by the layout system. In general, any property that can affect the size of an element's bounding box should have a AffectsMeasure flag set to true. For more information, see Dependency Properties Overview.

• When possible, use a RenderTransform instead of a LayoutTransform.

  A LayoutTransform can be a very useful way to affect the content of a user interface (UI). However, if the effect of the transform does not have to impact the position of other elements, it is best to use a RenderTransform instead, because RenderTransform does not invoke the layout system. LayoutTransform applies its transformation and forces a recursive layout update to account for the new position of the affected element.

• Avoid unnecessary calls to UpdateLayout.

  The UpdateLayout method forces a recursive layout update, and is frequently not necessary. Unless you are sure that a full update is required, rely on the layout system to call this method for you.

• When working with a large Children collection, consider using a VirtualizingStackPanel instead of a regular StackPanel.

  By virtualizing the child collection, the VirtualizingStackPanel only keeps objects in memory that are currently within the parent's ViewPort. As a result, performance is substantially improved in most scenarios.

The WPF graphics system uses device-independent units to enable resolution and device independence. Each device independent pixel automatically scales with the system's dots per inch (dpi) setting. This provides WPF applications proper scaling for different dpi settings and makes the application automatically dpi-aware.

However, this dpi independence can create irregular edge rendering because of anti-aliasing. These artifacts, typically seen as blurry or semi-transparent edges, can occur when the location of an edge falls in the middle of a device pixel instead of between device pixels. The layout system provides a way to adjust for this with layout rounding. Layout rounding is where the layout system rounds any non-integral pixel values during the layout pass.

Layout rounding is disabled by default. To enable layout rounding, set the UseLayoutRounding property to true on any FrameworkElement. Because it is a dependency property, the value will propagate to all the children in the visual tree. To enable layout rounding for the entire UI, set UseLayoutRounding to true on the root container. For an example, see UseLayoutRounding.

You can make the most of the globalization and localization functionality that is built into WPF by following the UI design and localization-related tips that this section provides.

When you localize a WPF application, you have several options. For example, you can bind the localizable resources in your application to an XML file, store localizable text in resx tables, or have your localizer use Extensible Application Markup Language (XAML) files . This section describes a localization workflow that uses the BAML form of XAML , which provides several benefits:

• You can localize after you build .

• You can update to a newer version of the BAML form of XAMLwith localizations from an older version of the BAML form of XAML so that you can localize at the same time that you develop.

• You can validate original source elements and semantics at compile time because the BAML form of XAML is the compiled form of XAML.

This section contains examples of localized applications to help you understand how to build and localize WPF applications.

Extensible Application Markup Language (XAML) is based on XML and takes advantage of the globalization support defined in the XML specification. The following sections describe some XAML features that you should be aware of.

This section describes user interface (UI) features that you should consider when writing an application.

When you write an application for global consumption you should keep in mind that the application must be localizable. The following topics point out things to consider.

ClickOnce is a new Windows Forms deployment technology that will ship with Microsoft Visual Studio 2005. It enables application installation and upgrading of Web applications. When an application that was deployed with ClickOnce is localized it can only be viewed on the localized culture. For example, if a deployed application is localized to Japanese it can only be viewed on Japanese Microsoft Windows not on English Windows. This presents a problem because it is a common scenario for Japanese users to run an English version of Windows.

The solution to this problem is setting the neutral language fallback attribute. An application developer can optionally remove resources from the main assembly and specify that the resources can be found in a satellite assembly corresponding to a specific culture. To control this process use theNeutralResourcesLanguageAttribute. The constructor of the NeutralResourcesLanguageAttribute class has two signatures, one that takes anUltimateResourceFallbackLocation parameter to specify the location where the ResourceManager should extract the fallback resources: main assembly or satellite assembly. The following example shows how to use the attribute. For the ultimate fallback location, the code causes theResourceManager to look for the resources in the "de" subdirectory of the directory of the currently executing assembly.

[assembly: NeutralResourcesLanguageAttribute(
    "de" , UltimateResourceFallbackLocation.Satellite)]

Because the WPF presentation system is powerful and flexible, it provides the ability to layout elements in an application that can be adjusted to fit the requirements of different languages. The following list points out some of the advantages of automatic layout.

• UI displays well in any language.

• Reduces the need to readjust position and size of controls after text is translated.

• Reduces the need to readjust window size.

• UI layout renders properly in any language.

• Localization can be reduced to the point that it is little more than string translation.

Automatic layout enables an application to adjust the size of a control automatically. For example, a control can change to accommodate the length of a string. This capability enables localizers to translate the string; they no longer need to resize the control to fit the translated text. The following example creates a button with English content.

<Window
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="ButtonLoc.Pane1"
    Name="myWindow"
    SizeToContent="WidthAndHeight"
    >

<DockPanel> 
    <Button FontSize="28" Height="50">My name is Hope.</Button>
</DockPanel>
</Window>

In the example, all you have to do to make a Spanish button is change the text. For example,

<Window
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="ButtonLoc.Pane1"
    Name="myWindow"
    SizeToContent="WidthAndHeight"
    >

 <DockPanel> 
    <Button FontSize="28" Height="50">Me llamo Esperanza.</Button>
  </DockPanel>
</Window>

The following graphic shows the output of the code samples.

Auto Resizable Button

Using the automatic layout approach requires a set of coding and design standards and rules to produce a fully localizable UI. The following guidelines will aid your automatic layout coding.

<StackPanel
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="GridLoc.Pane1"
>

The Grid element, is useful for automatic layout because it enables a developer to position elements. A Grid control is capable of distributing the available space among its child elements, using a column and row arrangement. The UI elements can span multiple cells, and it is possible to have grids within grids. Grids are useful because they enable you to create and position complex UI. The following example demonstrates using a grid to position some buttons and text. Notice that the height and width of the cells are set to Auto; therefore, the cell that contains the button with an image adjusts to fit the image.

<Grid Name="grid" ShowGridLines ="false">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="Auto"/>
<ColumnDefinition Width="*"/>
</Grid.ColumnDefinitions>
<Grid.RowDefinitions>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
</Grid.RowDefinitions>

<TextBlock Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="0" FontSize="24">Grid
</TextBlock>
<TextBlock Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="1" FontSize="12"  
    Grid.ColumnSpan="2">The following buttons and text are positioned using a Grid.
</TextBlock>  
<Button Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="2" Background="Pink" 
    BorderBrush="Black" BorderThickness="10">Button 1
</Button>
<TextBlock Margin="10, 10, 5, 5" Grid.Column="1" Grid.Row="2" FontSize="12" 
   VerticalAlignment="Center" TextWrapping="WrapWithOverflow">Sets the background 
   color.
</TextBlock>  
<Button Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="3" Foreground="Red">
   Button 2
</Button>
<TextBlock Margin="10, 10, 5, 5" Grid.Column="1" Grid.Row="3" FontSize="12" 
   VerticalAlignment="Center" TextWrapping="WrapWithOverflow">Sets the foreground 
   color.
</TextBlock>  
<Button Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="4">
   <Image Source="data\flower.jpg"></Image>
</Button>
<TextBlock Margin="10, 10, 5, 5" Grid.Column="1" Grid.Row="4" FontSize="12" 
   VerticalAlignment="Center" TextWrapping="WrapWithOverflow">Adds an image as 
   the button's content.
</TextBlock>
</Grid>

The following graphic shows the grid produced by the previous code.

Grid

A Grid element is useful in localizable applications to create controls that adjust to fit content. However, at times you want controls to maintain a particular size regardless of content. For example, if you have "OK", "Cancel" and "Browse" buttons you probably do not want the buttons sized to fit the content. In this case the Grid.IsSharedSizeScope attached property is useful for sharing the same sizing among multiple grid elements. The following example demonstrates how to share column and row sizing data between multiple Grid elements.

<StackPanel Orientation="Horizontal" DockPanel.Dock="Top">  
    <Button Click="setTrue" Margin="0,0,10,10">Set IsSharedSizeScope="True"</Button>
    <Button Click="setFalse" Margin="0,0,10,10">Set IsSharedSizeScope="False"</Button>
</StackPanel> 

<StackPanel Orientation="Horizontal" DockPanel.Dock="Top">

<Grid ShowGridLines="True" Margin="0,0,10,0">
  <Grid.ColumnDefinitions>
    <ColumnDefinition SharedSizeGroup="FirstColumn"/>
    <ColumnDefinition SharedSizeGroup="SecondColumn"/>
  </Grid.ColumnDefinitions>
  <Grid.RowDefinitions>
    <RowDefinition Height="Auto" SharedSizeGroup="FirstRow"/>
  </Grid.RowDefinitions>

    <Rectangle Fill="Silver" Grid.Column="0" Grid.Row="0" Width="200" Height="100"/>
    <Rectangle Fill="Blue" Grid.Column="1" Grid.Row="0" Width="150" Height="100"/>

    <TextBlock Grid.Column="0" Grid.Row="0" FontWeight="Bold">First Column</TextBlock>
    <TextBlock Grid.Column="1" Grid.Row="0" FontWeight="Bold">Second Column</TextBlock>
</Grid>

<Grid ShowGridLines="True">
  <Grid.ColumnDefinitions>
    <ColumnDefinition SharedSizeGroup="FirstColumn"/>
    <ColumnDefinition SharedSizeGroup="SecondColumn"/>
  </Grid.ColumnDefinitions>
  <Grid.RowDefinitions>        
    <RowDefinition Height="Auto" SharedSizeGroup="FirstRow"/>
  </Grid.RowDefinitions>

    <Rectangle Fill="Silver" Grid.Column="0" Grid.Row="0"/>
    <Rectangle Fill="Blue" Grid.Column="1" Grid.Row="0"/>

    <TextBlock Grid.Column="0" Grid.Row="0" FontWeight="Bold">First Column</TextBlock>
    <TextBlock Grid.Column="1" Grid.Row="0" FontWeight="Bold">Second Column</TextBlock>
</Grid>

</StackPanel>

<TextBlock Margin="10" DockPanel.Dock="Top" Name="txt1"/>

Note   For the complete code sample, see How to: Share Sizing Properties Between Grids

If markup application authors have requirements for specific elements in XAML, such as constraints on text length, font family, or font size, they can convey this information to localizers with comments in the XAML code. The process for adding comments to source code is as follows:

1. Application developer adds localization comments to XAML source code.

2. During the build process, you can specify in the .proj file whether to leave the free-form localization comments in the assembly, strip out part of the comments, or strip out all the comments. The stripped-out comments are placed in a separate file. You specify your option using a LocalizationDirectivesToLocFile tag, eg:

   <LocalizationDirectivesToLocFile>value</LocalizationDirectivesToLocFile>

3. The values that can be assigned are:

   • None - Both comments and attributes stay inside the assembly and no separate file is generated.

   • CommentsOnly - Strips only the comments from the assembly and places them in the separate LocFile.

   • All - Strips both the comments and the attributes from the assembly and places them both in a separate LocFile.

4. When localizable resources are extracted from BAML, the localizability attributes are respected by the BAML Localization API.

5. Localization comment files, containing only free-form comments, are incorporated into the localization process at a later time.

The following example shows how to add localization comments to a XAML file.

<TextBlock x:Id = "text01"

FontFamily = "Microsoft Sans Serif"

FontSize = "12"

Localization.Attributes = "$Content (Unmodifiable Readable Text)

FontFamily (Unmodifiable Readable)"

Localization.Comments = "$Content (Trademark)

FontSize (Trademark font size)" >

Microsoft

</TextBlock>

In the previous sample the Localization.Attributes section contains the localization attributes and the Localization.Comments section the free-form comments. The following tables show the attributes and comments and their meaning to the localizer.

The basic property that defines the content flow direction in a WPF application is FlowDirection. This property can be set to one of two enumeration values, LeftToRight or RightToLeft. The property is available to all WPF elements that inherit from FrameworkElement.

The following examples set the flow direction of a TextBox element.

Left-to-right flow direction

<TextBlock Background="DarkBlue" Foreground="LightBlue" 
   FontSize="20" FlowDirection="LeftToRight">
        This is a left-to-right TextBlock
</TextBlock>

Right-to-left flow direction

<TextBlock Background="LightBlue" Foreground="DarkBlue"
   FontSize="20" FlowDirection="RightToLeft">
        This is a right-to-left TextBlock
</TextBlock>

The following graphic shows how the previous code renders.

Graphic That Illustrates FlowDirection

An element within a user interface (UI) tree will inherit the FlowDirection from its container. In the following example, the TextBlock is inside a Grid, which resides in a Window. Setting the FlowDirection for the Window implies setting it for the Grid and TextBlock as well.

The following example demonstrates setting FlowDirection.

<Window
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="FlowDirectionApp.Window1"
    Title="BidiFeatures" Height="200" Width="700" 
    FlowDirection="RightToLeft">

    <Grid>
      <Grid.ColumnDefinitions>
        <ColumnDefinition/>
        <ColumnDefinition/>
      </Grid.ColumnDefinitions>
      <TextBlock Grid.Column="0" >
          This is a right-to-left TextBlock
      </TextBlock>

      <TextBlock Grid.Column="1" FlowDirection="LeftToRight">
          This is a left-to-right TextBlock
      </TextBlock>
    </Grid>
</Window>

The top level Window has a RightToLeftFlowDirection, so all elements contained within it also inherit the same FlowDirection. For an element to override a specified FlowDirection it must add an explicit direction change such as the second TextBlock in the previous example which changes toLeftToRight. When no FlowDirection is defined, the default LeftToRight applies.

The following graphic shows the output of the previous example.

Graphic That Illustrates Explicitly Assigned FlowDirection

Many development platforms such as HTML, Win32 and Java provide special support for bidirectional content development. Markup languages such as HTML give content writers the necessary markup to display text in any required direction, for example the HTML 4.0 tag, "dir" that takes "rtl" or "ltr" as values. This tag is similar to the FlowDirection property, but the FlowDirection property works in a more advanced way to layout textual content and can be used for content other than text.

In WPF, a FlowDocument is a versatile UI element that can host a combination of text, tables, images and other elements. The samples in the following sections use this element.

Adding text to a FlowDocument can be done in more that one way. A simple way to do so is through a Paragraph which is a block-level element used to group content such as text. To add text to inline-level elements the samples use Span and Run. Span is an inline-level flow content element used for grouping other inline elements, while a Run is an inline-level flow content element intended to contain a run of unformatted text. A Spancan contain multiple Run elements.

The first document example contains a document that has a number of network share names; for example \\server1\folder\file.ext. Whether you have this network link in an Arabic or English document, you always want it to appear in the same way. The following graphic shows the link in an Arabic RightToLeft document.

Graphic That Illustrates Using the Span Element

Because the text is RightToLeft, all special characters, such as the "\", separate the text in a right to left order. That results in the link not being shown in the correct order, therefore to solve the problem, the text must be embedded to preserve a separate Run flowing LeftToRight. Instead of having a separate Run for each language, a better way to solve the problem is to embed the less frequently used English text into a larger Arabic Span.

The following graphic illustrates this.

Graphic That Illustrates Using the Run Element Embedded in a Span Element

The following example demonstrates using Run and Span elements in documents.

<Page
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    FlowDirection="RightToLeft">

  <FlowDocument>
    <Paragraph>
      <Span FlowDirection="RightToLeft" >
        ستجد الملف هنا:
        <Run FlowDirection="LeftToRight">
           \\server1\filename\filename1.txt</Run>
        ثم باقى النص!
      </Span>
    </Paragraph>
  </FlowDocument>
</Page>

The Span element works as a boundary separator between texts with different flow directions. Even Span elements with the same flow direction are considered to have different bidirectional scopes which means that the Span elements are ordered in the container’s FlowDirection, only the content within the Span element follows the FlowDirection of the Span.

The following graphic shows the flow direction of several TextBlock elements.

Graphic That Illustrates FlowDirection in Several TextBlock Elements

The following example shows how to use the Span and Run elements to produce the results shown in the previous graphic.

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
  <StackPanel >

    <TextBlock FontSize="20" FlowDirection="RightToLeft">
      <Run FlowDirection="LeftToRight">العالم</Run>
      <Run FlowDirection="LeftToRight" Foreground="Red" >فى سلام</Run>
    </TextBlock>

    <TextBlock FontSize="20" FlowDirection="LeftToRight">
      <Run FlowDirection="RightToLeft">العالم</Run>
      <Run FlowDirection="RightToLeft" Foreground="Red" >فى سلام</Run>
    </TextBlock>

    <TextBlock FontSize="20" Foreground="Blue">العالم فى سلام</TextBlock>

    <Separator/>

    <TextBlock FontSize="20" FlowDirection="RightToLeft">
      <Span Foreground="Red" FlowDirection="LeftToRight">Hello</Span>
      <Span FlowDirection="LeftToRight">World</Span>
    </TextBlock>

    <TextBlock FontSize="20" FlowDirection="LeftToRight">
      <Span Foreground="Red" FlowDirection="RightToLeft">Hello</Span>
      <Span FlowDirection="RightToLeft">World</Span>
    </TextBlock>

    <TextBlock FontSize="20" Foreground="Blue">Hello World</TextBlock>

  </StackPanel>

</Page>

In the TextBlock elements in the sample, the Span elements are laid out according to the FlowDirection of their parents, but the text within each Spanelement flows according to its own FlowDirection. This is applicable to Latin and Arabic – or any other language.

FlowDirection defines not only how text flows in a textual element but also the flow direction of almost every other UI element. The following graphic shows a ToolBar that uses a horizontal LinearGradientBrush to draw its background.

Graphic That Shows a ToolBar with a Left to Right Gradient

After setting the FlowDirection to RightToLeft, not only the ToolBar buttons are arranged from right to left, but even the LinearGradientBrush realigns its offsets to flow from right to left.

The following graphic shows the realignment of the LinearGradientBrush.

Graphic That Shows a ToolBar with a Right to Left Gradient

The following example draws a RightToLeftToolBar. (To draw it left to right, remove the FlowDirection attribute on the ToolBar.

<Page
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

  <ToolBar FlowDirection="RightToLeft" Height="50" DockPanel.Dock="Top">
    <ToolBar.Background>
      <LinearGradientBrush StartPoint="0,0.5" EndPoint="1,1">
        <LinearGradientBrush.GradientStops>
          <GradientStop Color="DarkRed" Offset="0" />
          <GradientStop Color="DarkBlue" Offset="0.3" />
          <GradientStop Color="LightBlue" Offset="0.6" />
          <GradientStop Color="White" Offset="1" />
        </LinearGradientBrush.GradientStops>
      </LinearGradientBrush>
    </ToolBar.Background>

    <Button FontSize="12" Foreground="White">Button1</Button>
    <Rectangle Width="20"/>
    <Button FontSize="12" Foreground="White">Button2</Button>
    <Rectangle Width="20"/>
    <Button FontSize="12" Foreground="White">Button3</Button>
    <Rectangle Width="20"/>
    <Button FontSize="12" Foreground="White">Button4</Button>
    <Rectangle Width="20"/>
  </ToolBar>
</Page>

Historically, Windows has supported number substitution by allowing the representation of different cultural shapes for the same digits while keeping the internal storage of these digits unified among different locales, for example numbers are stored in their well known hexadecimal values, 0x40, 0x41, but displayed according to the selected language.

This has allowed applications to process numerical values without the need to convert them from one language to another, for example a user can open an Microsoft Excel spreadsheet in a localized Arabic Windows and see the numbers shaped in Arabic, but open it in a European version of Windows and see European representation of the same numbers. This is also necessary for other symbols such as comma separators and percentage symbol because they usually accompany numbers in the same document.

Windows Presentation Foundation (WPF) continues the same tradition, and adds further support for this feature that allows more user control over when and how substitution is used. While this feature is designed for any language, it is particularly useful in bidirectional content where shaping digits for a specific language is usually a challenge for application developers because of the various cultures an application might run on.

The core property controlling how number substitution works in Windows Presentation Foundation (WPF) is the Substitution dependency property. The NumberSubstitution class specifies how numbers in text are to be displayed. It has three public properties that define its behavior. Following is a summary of each of the properties.

CultureSource:

This property specifies how the culture for numbers is determined. It takes one of three NumberCultureSource enumeration values.

• Override: Number culture is that of CultureOverride property.

• Text: Number culture is the culture of the text run. In markup, this would be xml:lang, or its alias Language property ( Language orLanguage). Also, it is the default for classes deriving from FrameworkContentElement. Such classes includeSystem.Windows.Documents.Paragraph, System.Windows.Documents.Table, System.Windows.Documents.TableCell and so forth.

• User: Number culture is the culture of the current thread. This property is the default for all subclasses of FrameworkElement such as Page,Window and TextBlock.

CultureOverride:

The CultureOverride property is used only if the CultureSource property is set to Override and is ignored otherwise. It specifies the number culture. A value of null, the default value, is interpreted as en-US.

Substitution:

This property specifies the type of number substitution to perform. It takes one of the following NumberSubstitutionMethod enumeration values.

• AsCulture: The substitution method is determined based on the number culture's NumberFormatInfo.DigitSubstitution property. This is the default.

• Context: If the number culture is an Arabic or Farsi culture, it specifies that the digits depend on the context.

• European: Numbers are always rendered as European digits.

• NativeNational: Numbers are rendered using the national digits for the number culture, as specified by the culture's NumberFormat.

• Traditional: Numbers are rendered using the traditional digits for the number culture. For most cultures, this is the same as NativeNational. However, NativeNational results in Latin digits for some Arabic cultures, whereas this value results in Arabic digits for all Arabic cultures.

What do those values mean for a bidirectional content developer? In most cases, the developer might need only to define FlowDirection and the language of each textual UI element, for example Language="ar-SA" and the NumberSubstitution logic takes care of displaying the numbers according to the correct UI. The following example demonstrates using Arabic and English numbers in a Windows Presentation Foundation (WPF) application running in an Arabic version of Windows.

<Page 
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >
  <StackPanel>
   <TextBlock Background="LightGreen" FontSize="32" 
      Language="ar-SA" FlowDirection="RightToLeft">1+2=3</TextBlock>
   <TextBox Background="LightGreen" FontSize="32" 
      Language="ar-SA" FlowDirection="RightToLeft">1+2=3</TextBox>
   <TextBlock Background="LightBlue" FontSize="32">1+2=3</TextBlock>
   <TextBox Background="LightBlue" FontSize="32">1+2=3</TextBox>
 </StackPanel>
</Page>

The following graphic shows the output of the previous sample if you are running in an Arabic version of Windows.

Graphic That Shows Arabic and English Numbers Displayed

The FlowDirection was important in this case because setting the FlowDirection to LeftToRight instead would have yielded European digits. The following sections discuss how to have a unified display of digits throughout your document. If this example is not running on Arabic Windows, all the digits display as European digits.

Defining Substitution Rules

In a real application you might need to set the Language programmatically. For example, you want to set the xml:lang attribute to be the same as the one used by the system’s UI, or maybe change the language depending on the application state.

If you want to make changes based on the application's state, make use of other features provided by Windows Presentation Foundation (WPF).

First, set the application component’s NumberSubstitution.CultureSource="Text". Using this setting makes sure that the settings do not come from the UI for text elements that have "User" as the default, such as TextBlock.

For example:

In the corresponding C# code, set the Language property for example, to "ar-SA".

If you need to set the Language property to the current user’s UI language use the following code.

CurrentCulture represents the current culture used by the current thread at run time.

Your final XAML example should be similar to the following example.

<Page x:Class="WindowsApplication.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Code Sample" Height="300" Width="300"
>
    <StackPanel>
      <TextBlock Language="ar-SA" 
         FlowDirection="RightToLeft">عربى: 1+2=3
      </TextBlock>
      <TextBlock Language="ar-SA" 
         FlowDirection="RightToLeft" 
         NumberSubstitution.Substitution="European">عربى: 1+2=3 
      </TextBlock>
    </StackPanel>
</Page>

Your final C# example should be similar to the following.

namespace BidiTest
{
    public partial class Window1 : Window
    {

        public Window1()
        {
            InitializeComponent();

            string currentLanguage = 
                System.Globalization.CultureInfo.CurrentCulture.IetfLanguageTag;

            text1.Language = System.Windows.Markup.XmlLanguage.GetLanguage(currentLanguage);

            if (currentLanguage.ToLower().StartsWith("ar"))
            {
                text1.FlowDirection = FlowDirection.RightToLeft;
            }
            else
            {
                text1.FlowDirection = FlowDirection.LeftToRight;
            }
        }
    }
}

The following graphic shows what the window looks like for either programming language.

Graphic That Displays Arabic Numbers

Using the Substitution Property

The way number substitution works in Windows Presentation Foundation (WPF) depends on both the Language of the text element and itsFlowDirection. If the FlowDirection is left to right, then European digits are rendered. However if it is preceded by Arabic text, or has the language set to "ar" and the FlowDirection is RightToLeft, Arabic digits are rendered instead.

In some cases, however, you might want to create a unified application, for example European digits for all users. Or Arabic digits in Table cells with a specific Style. One easy way to do that is using the Substitution property.

In the following example, the first TextBlock does not have the Substitution property set, so the algorithm displays Arabic digits as expected. However in the second TextBlock, the substitution is set to European overriding the default substitution for Arabic numbers, and European digits are displayed.

<Page x:Class="WindowsApplication.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Code Sample" Height="300" Width="300"
>
    <StackPanel>
      <TextBlock Language="ar-SA" 
         FlowDirection="RightToLeft">عربى: 1+2=3
      </TextBlock>
      <TextBlock Language="ar-SA" 
         FlowDirection="RightToLeft" 
         NumberSubstitution.Substitution="European">عربى: 1+2=3 
      </TextBlock>
    </StackPanel>
</Page>

This discussion gives you a step-by-step approach to localizing an application. First, you will prepare your application so that the text that will be translated can be extracted. After the text is translated, you will merge the translated text into a new copy of the original application.

Over the course of this discussion, you will use Microsoft build engine (MSBuild), which is a compiler that runs from the command line.

Also, you will be instructed to use a project file. For instructions on how to use MSBuild and project files, see Building and Deploying WPF Applications.

All the examples in this discussion use en-US (English-US) as the culture. This enables you to work through the steps of the examples without installing a different language.

In this step, you will prepare your application for localization. In the Windows Presentation Foundation (WPF) samples, a HelloApp sample is supplied that will be used for the code examples in this discussion. If you would like to use this sample, download the Extensible Application Markup Language (XAML) files from the LocBaml Tool Sample.

1. Develop your application to the point where you want to start localization.

2. Specify the development language in the project file so that MSBuild generates a main assembly and a satellite assembly (a file with the .resources.dll extension) to contain the neutral language resources. The project file in the HelloApp sample is HelloApp.csproj. In that file, you will find the development language identified as follows:

   <UICulture>en-US</UICulture>

3. Add Uids to your XAML files. Uids are used to keep track of changes to files and to identify items that must be translated. To add Uids to your files, run updateuid on your project file: 

   msbuild /t:updateuid helloapp.csproj

   To verify that you have no missing or duplicate Uids, run checkuid:

   msbuild /t:checkuid helloapp.csproj

   After running updateuid, your files should contain Uids. For example, in the Pane1.xaml file of HelloApp, you should find the following:

   <StackPanel x:Uid="StackPanel_1">

     <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>

     <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>

   </StackPanel>

After the application is configured to generate a neutral language resources satellite assembly, you build the application. This generates the main application assembly, as well as the neutral language resources satellite assembly that is required by LocBaml for localization. To build the application:

1. Compile HelloApp to create a dynamic-link library (DLL):

   msbuild helloapp.csproj

2. The newly created main application assembly, HelloApp.exe, is created in the following folder:

   C:\HelloApp\Bin\Debug\

3. The newly created neutral language resources satellite assembly, HelloApp.resources.dll, is created in the following folder:

   C:\HelloApp\Bin\Debug\en-US\

1. All the files necessary to build LocBaml are located in the WPF samples. Download the C# files from the LocBaml Tool Sample.

2. From the command line, run the project file (locbaml.csproj) to build the tool:

   msbuild locbaml.csproj

3. Go to the Bin\Release directory to find the newly created executable file (locbaml.exe). Example:C:\LocBaml\Bin\Release\locbaml.exe.

4. The options that you can specify when you run LocBaml are as follows:

   • parse or -p: Parses Baml, resources, or DLL files to generate a .csv or .txt file.

   • generate or -g: Generates a localized binary file by using a translated file.

   • out or -o [ filedirectory] : Output file name.

   • culture or -cul [ culture] : Locale of output assemblies.

   • translation or -trans [ translation.csv] : Translated or localized file.

   • asmpath or -asmpath: [ filedirectory] : If your XAML code contains custom controls, you must supply the asmpath to the custom control assembly.

   • nologo: Displays no logo or copyright information.

   • verbose: Displays verbose mode information.

   Note
   If you need a list of the options when you are running the tool, type LocBaml.exe and press ENTER.

Now that you have created the LocBaml tool, you are ready to use it to parse HelloApp.resources.dll to extract the text content that will be localized.

1. Copy LocBaml.exe to your application's bin\debug folder, where the main application assembly was created.

2. To parse the satellite assembly file and store the output as a .csv file, use the following command:

   LocBaml.exe /parse HelloApp.resources.dll /out:Hello.csv

   Note
   If the input file, HelloApp.resources.dll, is not in the same directory as LocBaml.exe move one of the files so that both files are in the same directory.

3. When you run LocBaml to parse files, the output consists of seven fields delimited by commas (.csv files) or tabs (.txt files). The following shows the parsed .csv file for the HelloApp.resources.dll:

   HelloApp.g.en-US.resources:window1.baml,Stack1:System.Windows.Controls.StackPanel.$Content,Ignore,FALSE, FALSE,,#Text1;#Text2;

   HelloApp.g.en-US.resources:window1.baml,Text1:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Hello World

   HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Goodbye World

   The seven fields are:

   1. BAML Name. The name of the BAML resource with respect to the source language satellite assembly.

   2. Resource Key. The localized resource identifier.

   3. Category. The value type. See Localization Attributes and Comments.

   4. Readability. Whether the value can be read by a localizer. See Localization Attributes and Comments.

   5. Modifiability. Whether the value can be modified by a localizer. See Localization Attributes and Comments.

   6. Comments. Additional description of the value to help determine how a value is localized. See Localization Attributes and Comments.

   7. Value. The text value to translate to the desired culture.

   The following table shows how these fields map to the delimited values of the .csv file:

   BAML name	Resource key	Category	Readability	Modifiability	Comments	Value
   HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	Ignore	FALSE	FALSE		#Text1;#Text2
   HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	None	TRUE	TRUE		Hello World
   HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	None	TRUE	TRUE		Goodbye World

   Notice that all the values for the Comments field contain no values; if a field doesn't have a value, it is empty. Also notice that the item in the first row is neither readable nor modifiable, and has "Ignore" as its Category value, all of which indicates that the value is not localizable.

4. To facilitate discovery of localizable items in parsed files, particularly in large files, you can sort or filter the items by Category, Readability, and Modifiability. For example, you can filter out unreadable and unmodifiable values.

Use any tool that you have available to translate the extracted content. A good way to do this is to write the resources to a .csv file and view them in Microsoft Excel, making translation changes to the last column (value).

The content that was identified by parsing HelloApp.resources.dll with LocBaml has been translated and must be merged back into the original application. Use the generate or -g option to generate a new .resources.dll file.

1. Use the following syntax to generate a new HelloApp.resources.dll file. Mark the culture as en-US (/cul:en-US).

   LocBaml.exe /generate HelloApp.resources.dll /trans:Hello.csv /out:c:\ /cul:en-US

   Note
   If the input file, Hello.csv, is not in the same directory as the executable, LocBaml.exe, move one of the files so that both files are in the same directory.

2. Replace the old HelloApp.resources.dll file in the C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll directory with your newly created HelloApp.resources.dll file.

3. "Hello World" and "Goodbye World" should now be translated in your application.

4. To translate to a different culture, use the culture of the language that you are translating to. The following example shows how to translate to French-Canadian:

   LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA

5. In the same assembly as the main application assembly, create a new culture-specific folder to house the new satellite assembly. For French-Canadian, the folder would be fr-CA.

6. Copy the generated satellite assembly to the new folder.

7. To test the new satellite assembly, you need to change the culture under which your application will run. You can do this in one of two ways:

   • Change your operating system's regional settings ( Start | Control Panel | Regional and Language Options).

   • In your application, add the following code to App.xaml.cs:

     XAML

     <Application
         xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
         xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
         x:Class="SDKSample.App"
         x:Uid="Application_1"
         StartupUri="Window1.xaml">
     </Application>
     

     C#

     VB

     using System.Windows; // Application
     using System.Globalization; // CultureInfo
     using System.Threading; // Thread
     
     namespace SDKSample
     {
         public partial class App : Application
         {
             public App()
             {
                 // Change culture under which this application runs
                 CultureInfo ci = new CultureInfo("fr-CA");
                 Thread.CurrentThread.CurrentCulture = ci;
                 Thread.CurrentThread.CurrentUICulture = ci;
             }
         }
     }
     

• All dependent assemblies that define custom controls must be copied into the local directory of LocBaml or installed into the GAC. This is necessary because the localization API must have access to the dependent assemblies when it reads the binary XAML (BAML).

• If the main assembly is signed, the generated resource DLL must also be signed in order for it to be loaded.

• The version of the localized resource DLL needs to be synchronized with the main assembly.