XAML Markup Reference for XRPack (Compact 2013)
3/26/2014
In the Windows Embedded Compact 2013 build system, the XAML Resource Packager (XRPack) extracts all of the necessary resources (strings, images, and XAML) for a XAML for Windows Embedded project and compiles them into a resource file. The build system then binds the resources in the file into the executable (.EXE) or dynamic-link library (.DLL) file. For more information about application packaging with XRPack, see XAML Resource Packager.
The code examples below cover some programming considerations for specific XAML elements in code that XRPack compiles.
Important
For readability, the following code examples do not contain security checking or error handling. Do not use the following code examples in a production environment.
xrpack:String
Xrpack:String attributes are processed and translated into resource bindings, creating resource string tables that the localization process uses.
The following examples show single-string resources with generated labels:
<ContentControl x:Name="ResourceStringBindingContentControl1" xrpack:String="Content:100" Content="Also 'My String' at runtime"/>
<Button x:Name="ResourceStringBindingButton1" xrpack:String="Content:101" Content="Some other String"/>
<CheckBox x:Name="ResourceStringBindingCheckBox1" xrpack:String="IsChecked:102" IsChecked="True"/>
The following example shows how to define a single string in the string table that can replace multiple strings in the XAML:
<TextBlock xrpack:String="Text:100" Text="100" />
<TextBlock xrpack:String="Text:100" Text="101" />
<TextBlock xrpack:String="Text:102" Text="102" />
XRPack generates the following string table from the XAML in the preceding example:
STRINGTABLE
BEGIN
100 "100"
102 "102"
END
The technique in the preceding example is useful when a project has multiple XAML files that contain controls with the same text that need to be localized. In this case, the text can be localized once in the string table to update all instances of the text that appear on controls.
The following example shows how to use multiple string resources for a control:
<TextBlock x:Name="ResourceStringBindingTextBlock1" xrpack:String="Text:100;Visibility:103" Text="My String" Visibility="Collapsed"/>
The following example shows how to define a resource ID label to use in code:
<Button x:Name="ResourceStringBindingButton1" xrpack:String="Content:101(IDR_MYLABEL)" Content="Some other String"/>
xrpack:ClassResourceId
An xrpack:ClassResourceId attribute is a class resource definition. You can use it with or without the x:class attribute to control resource identifier generation. If a file has no user-specified resource identifier, XRPack automatically generates one based on the x:Class or xrpack:ClassResourceId attributes. If the class resource definition contains full markup, as in the following example, you do not need to use the x:Class attribute:
xrpack:ClassResourceId="Class:101(IDR_USERLABEL)"
If MainPage.xaml contains the code in the preceding example, XRPack generates the following resource identifier and label:
#define IDR_USERLABEL 101 // MainPage.xaml
If the class resource definition contains partial markup, as in the following example, XRPack uses the specified identifier for the resource identifier and a generated name from the x:Class attribute:
xrpack:ClassResourceId="Class:192"
x:Class="TextBlock.MainPage"
If MainPage.xaml contains the code from the previous example, XRPack generates the following resource identifier and label:
#define IDR_TEXTBLOCK_MAINPAGE 192 // MainPage.xaml
If you do not use an xrpack:ClassResourceId attribute, XRPack generates a resource identifier and creates the label based on the x:Class attribute. For example, if MainPage.xaml contains the following code:
x:Class="Assets.Tulips"
then XRPack generates the following code:
#define IDR_ASSETS_TULIPS <generated number> // Tulips.xaml
In this case, if no x:Class attribute is present to supply the label, XRPack logs error XRPack0010, XRPACK_E_INVALID_ATTRIBUTE_MARKUP.
xrpack:Resource
Xrpack:Resource attributes map a resource ID to a specific resource, as shown in the following example:
<Image xrpack:Resource="Source:902(IDR_MYIMG)" Source="Images/My Image.png" />
XRPack compresses bitmaps that you embed in the resource package by default or if you set the /ImageCompress option on the command line. (The resource package is contained in the resource (.RES) file that is linked into the .EXE or .DLL file). The compressed image improves efficiency when XAML for Windows Embedded is rendering a scene that contains the bitmap. However, user applications cannot retrieve a compressed image from the resource package (for example, by calling LoadResource) in its original, uncompressed format.
References to Resources
When you use XRPack, all references to resources inside XAML tags must use their Uniform Resource Identifiers (URIs) rather than the identifiers assigned in the resource file. Blend uses this syntax, but legacy XAML files may contain code that does not use the URI. XRPack resolves all URIs and locates them in the file system using the relative path locations of the XAML file and the resources. If it cannot resolve a URI, XRPack generates an error.
The following example shows the syntax that XAML for Windows Embedded supports but that XRPack cannot compile.
Resources.rc:
AUTO_GIF_RES1 XAML_RESOURCE DISCARDABLE "..\\data\\images/\Resource1_GIF.gif"
MyXaml.xaml:
<Image Height="100.00" Width="100.00" x:Name="GIF" Source="AUTO_GIF_RES1" Opacity="100" VerticalAlignment="Stretch" />