XAML Usage Syntax

XAML Usage

In the .NET Framework Class Library for Silverlight, some types and members have a XAML usage section. The XAML usage is included whenever there is a XAML usage that is technically possible, and also when there is a clear scenario for using XAML.

There are different types of XAML usage sections based on the XAML language specification. For example, there can be XAML Object Element Usage, XAML Attribute Usage, XAML Property Element Usage, and XAML Implicit Collection Usage sections. The following shows an example of a XAML Object Element Usage section for the Button control:

<Button .../>
-or-
<Button>
  singleObject
</Button>

The following shows an example of a XAML Attribute Usage section for the Image.Source property:

<Image Source="uri"/>

The following shows an example of a XAML Property Element Usage section for the UIElement.Clip property:

<uiElement>
  <uiElement.Clip>
    singleGeometry
  </uiElement.Clip>
</uiElement>

XAML usage sections include styles, such as the following:

• The element that is relevant to a particular XAML usage is typically bold.

• Placeholders are typically italic.

• The surrounding text typically indicates a literal part of the usage.

Note:
MSDN online and other help viewers may not display some of the style conventions within the XAML usage section.

For C# and other languages, the syntax shown in the Syntax section is a definition syntax. A definition syntax is a syntax that emulates the code that defines the type or its members within the compiled assembly. For XAML, no equivalent definition syntax exists. This is because the fundamentals of XAML rely on markup elements being backed by existing defined types in assemblies, and showing a "definition" for XAML would be inaccurate. Therefore, XAML syntax is shown as usage syntax. (Visual Basic also shows a usage syntax, but shows the definition syntax as well.)

XAML Values

In many cases, the placeholders and strings in a XAML usage section of the .NET Framework Class Library for Silverlight are defined in a XAML Values section below the XAML usage section. This is similar to the Parameters section that describes the parameters you must pass to a method, based on the parameter names in the Syntax section.

The following shows an example of a XAML Values section for the Button control:

• singleObject
  A single object element that declares the content.

Not all of the placeholders in a XAML usage section are defined in the XAML Values section. Some of the terms are generalized. For more information, see the following sections later in this topic: Generalized Placeholders, Native Text Syntaxes, and Prefixes and Mappings for Silverlight Libraries.

Content Models

Many of the UI elements in Silverlight support a content model. The content model defines how other UI elements can be placed as child elements of a parent element. For a broader example of a content model, consider the <table> element in HTML 1.0. The intended content model for an HTML table is that the child elements of <table> might include elements such as <tr>, <td>, <th>, or <caption>. Basic HTML does not enforce its content model strongly. However, XAML generally enforces the content models based on the underlying types and properties. Introducing an element that violates the content model will typically result in a XAML parse exception.

The XAML usage for object elements that support a content model presents some simplification of the content model. Most content models definitions use some base type in the underlying code, meaning that the content is a placeholder because it can be any XAML-usable object element that derives from a particular base class. For example, the following is the XAML usage for the Border control:

<Border>
  singleChild
</Border>

singleChild is a placeholder that is defined in the XAML Values section. Even without looking at XAML Values, you already know something about the content model because the placeholder starts with single. This means that Border can support a maximum of one object element child. Therefore the following is invalid markup that violates the content model for Border:

<Border>
  <Rectangle .../>
  <Ellipse .../><!--parse exception-->
</Border>

Not all XAML elements fit the Border content model. As explained in its XAML Values section, the single child for Border must be an object element that derives from the base class UIElement.

A similar convention is oneOrMore. This string indicates that the class supports a content model where the content property is a collection property. Collections are explained in the next section.

Collections

Because XAML is tied to an underlying type system, whenever there is a content model that supports more than one child element, the property that backs the content model is a collection type. Because of XAML language features that optimize the markup form, neither the content property nor any element that represents the collection type are present in many XAML collection syntaxes. Instead, you often see a XAML usage such as the following for DoubleAnimationUsingKeyFrames:

<DoubleAnimationUsingKeyFrames>
  oneOrMoreDoubleKeyFrames
</DoubleAnimationUsingKeyFrames>

This XAML usage indicates that you can include multiple key frames, each of which are added to an underlying collection, as shown in the following example (this example is actual markup and does not have placeholders):

<DoubleAnimationUsingKeyFrames
  Storyboard.TargetName="AnimatedTranslateTransform"
  Storyboard.TargetProperty="X" Duration="0:0:6"
>
  <LinearDoubleKeyFrame Value="500" KeyTime="0:0:3" />
  <DiscreteDoubleKeyFrame Value="400" KeyTime="0:0:4" />
  <SplineDoubleKeyFrame KeySpline="0.6,0.0 0.9,0.00" Value="0" KeyTime="0:0:6" />
</DoubleAnimationUsingKeyFrames>

XAML usage for the collections is generally shown in the form that omits implicit syntax elements. There might be a valid syntax where objects are specified explicitly, but this is generally not shown for simplicity and for best-practice reasons.

For more information about collections in XAML, see XAML Overview.

Markup Extensions

Markup extensions are a XAML language concept whereby the XAML parser can escape the typical string processing of XAML and instead invoke a self-contained string syntax. Each syntax is supported by a particular markup extension class or implementation. The following are specific reference topics for the markup extensions that exist in Silverlight XAML:

• Binding

• x:Null

• RelativeSource

• StaticResource

• TemplateBinding

For more information about markup extensions, see "Markup Extensions" section of XAML Overview.

A few APIs in the .NET Framework Class Library for Silverlight do include a markup extension as part of their XAML usage. These APIs are cases where setting the property with a particular extension is the primary intended usage scenario, and therefore showing the extension in the usage is more helpful for the beginning user. For example, the following is the XAML usage presented for the FrameworkElement.DataContext property:

<frameworkElement DataContext="binding"/>
- or -
<frameworkElement DataContext="{StaticResource keyedObject}"/>

FrameworkElement.DataContext is a property that takes an object and thus might conceivably use a property element syntax that wraps an object value to set it. However, the scenario for FrameworkElement.DataContext is that you would never define a "new" object as an object element here. Instead, you would use one of two possible techniques that are hinted at by these placeholders and then explained in the XAML Values in more detail. The following are the descriptions in the XAML Values section of the FrameworkElement.DataContext topic:

• binding: A binding expression that can reference an existing data context, or a property within the data context. See Data Binding or Binding Markup Extension.

• keyedObject: The x:Key value of an object that exists in an in-scope Resources collection. Typically, this is an object element instantiation of a custom type defined elsewhere in your code, and requires a custom XAML namespace mapping within the ResourceDictionary.

Type Converters

Type converters are a key part of XAML, because type converters enable simple string attribute usages instead of complicated object element usages. Type converters for XAML generally process a string and convert the string to produce an object. This technique is similar to markup extensions. The difference is that type converters are either associated with a particular type (a type that is used as a property value), or with a particular property, whereas a markup extension can conceivably provide a value anywhere in markup, regardless of which property it sets or the related types.

Consider the DataGridLength structure and its type conversion behavior. The following shows the XAML Attribute Usage section for DataGridLength:

<object property="absolutePixelValue"/>
- or -
<object property="Auto"/>
- or -
<object property="SizeToCells"/>
- or -
<object property="SizeToHeader"/>

The XAML Attribute Usage section lists the possible values for properties. absolutePixelValue is a placeholder that is defined in the XAML Values section. The other values are literal strings that map to behaviors. A XAML parser accesses type converter classes while constructing the object tree to determine which strings are valid for conversion to the relevant object type.

Another type converter to consider is the one used for all values that use the Point type. A Point is simply a data structure that reports an object position in a two-dimensional coordinate space. In other words, a Point reports X and Y coordinate values. The following shows the XAML Attribute Usage section for Point:

<object property="X,Y"/>
-or-
<object property="X Y"/>

The purpose of the XAML usage shown on Point is to show that there are X and Y components to a Point provided in XAML, and that either a comma or space can be the delimiter between X and Y. More specifics (such as that the numeric types for X and Y can have decimal separators) are available in the XAML Values section in the Point topic.

Notice the object property placeholders. There is no realistic way to convey the full range of properties that can use the Point type, so object and property are shown as generalized placeholders.

Note:

In XAML for Silverlight, some type converters are reported by the TypeConverterAttribute applied to a type or a property. An example is the DataGridLength type. However, some of the most commonly accessed type converters for Silverlight are implemented at the native level. This means that if you look at the relevant type or property, you will not find a TypeConverterAttribute. Point is an example of this case.

Generalized Placeholders

XAML usage sections use various generalized placeholders. The following table describes the object, property, eventhandler, dateTimeString, and enumMemberName placeholders.

Native Text Syntaxes

XAML usage sections in the .NET Framework Class Library for Silverlight use various native text syntaxes. A native text syntax is a string-conversion behavior that is not necessarily represented by a CLR TypeConverter / class-level TypeConverterAttribute and is instead built in to the Silverlight XAML parser's native implementation. These native type syntaxes identify the type that the item will be converted to. The following table describes the double, int, bool, string, xamlName, and uriString placeholders.

Native Text Syntax	Description
double	The double placeholder indicates that the attribute uses a string value that is natively converted into a Double value. This placeholder itself does not connote further possible restrictions by a particular property. For example, some properties might not accept negative values, or values outside of a particular range. These restrictions are typically not specific to the XAML usage, so in the .NET Framework Class Library for Silverlight, you might find information about these restrictions in the Remarks section or Property Value section, instead of in a XAML-specific section. Important Note: Many values of Double are handled natively in Silverlight at a level that is deeper than XAML parsing. In these cases, the Silverlight usage of Double does not preserve the full level of mathematical precision that is implied by the CLR definition of Double. For properties that relate to the Silverlight coordinate space and layout (for example, FrameworkElement.Width, or any transforms that act on layout-related properties), do not use values that exceed 32678 (or -32678 if negative values are permitted). For other values of type Double, try to avoid using values that exceed 1,000,000 (positive or negative), or values that significantly exceed the level of precision for Single. These same considerations might also introduce rounding errors if extensive arithmetic is performed on Double values.
int	The int placeholder indicates that the attribute uses a string value that is natively converted into an integer value. In practical usages, it typically does not matter whether the underlying implementation is Int16 or Int32, although this can be discovered by looking at the C# or Visual Basic syntax. This placeholder does not connote further possible restrictions by a particular property. For example, some properties might not accept negative values, or values outside of a particular range. These restrictions are typically not specific to the XAML usage, so in the .NET Framework Class Library for Silverlight, you might find information about these restrictions in the Remarks section or Property Value section, instead of in a XAML-specific section.
bool	The bool placeholder indicates that the attribute uses a string value that is natively converted into a Boolean value, either true or false. The string values for specifying a Boolean value in XAML are treated as case-insensitive, and it does not matter which language is used for a possible code-behind of that XAML. Note: There are a small number of Silverlight properties that use a nullable Boolean. The XAML syntax for these is not shown as bool alone, because you can explicitly set the value to null in XAML with {x:Null} for these cases.
string	The string placeholder indicates a literal string. Typically, this is used for cases where the underlying property value type is String, and there are no particular constraints on the string format. Note: Any string-type syntax that displays in UI is possibly a string that needs to be localized. Rather than specifying these strings as literal strings in XAML, consider using the localization techniques described in How to: Make XAML Content Localizable.
xamlName	The xamlName placeholder indicate a literal string that must conform to the XamlName Grammar. These should NOT be localized.
uriString	The uriString placeholder indicates that the attribute uses a string value that is either converted natively or converted by using a TypeConverter into a Uri. These MAY need to be localized, depending on your application. The uriString often does not include a protocol if you are referencing a relative URL. It can also reference parts of the XAP. For more information, see Resources.

Enumerations

Some members in the .NET Framework Class Library for Silverlight use enumerations. The following shows the XAML usage format for all enumerations that have a XAML scenario:

<object property="enumMemberName"/>

This XAML usage is entirely placeholders. The object property placeholders are used because there is no accurate way to determine which property is being set. However, some enumerations are intended for properties with a particular name. The enumMemberName placeholder indicates that you should specify a string that is the name of one of the enumeration's named constants. The following shows a XAML example that sets the Visibility property of a button to the Visible enumeration constant:

<Button Visibility="Visible"/>

When using enumerations in XAML, be sure to remember the following:

• Do not use the qualified form. Instead, use the unqualified constant member name. For example, the following usage does not work: <Button Visibility="Visibility.Visible"/>.

• Do not use the value of the constant. In other words, do not rely on the integer value of the enumeration. Although this technique sometimes works, it is not a recommended practice either in XAML or in code. For example, the following usage is not recommended: <Button Visibility="1"/>.

• Enumerations in Silverlight can be flagwise, meaning that they are attributed with FlagsAttribute. If you need to specify a combination of values for these enumerations as a XAML attribute value, use the name of each enumeration constant, with a comma (,) between each name, and no intervening space characters.

Common Base Types

For property members and event members of a type that is mainly intended as a base type for other practical UI types, the XAML usage sometimes use an italicized placeholder for the parent type, with an initial lowercase letter.

For example, the UIElement type is a very common base type, which literally hundreds of types in Silverlight derive from. The XAML Attribute Usage section for the UIElement.Visibility property looks like the following:

<uiElement Visibility="Visible"/>
-or-
<uiElement Visibility="Collapsed"/>

uiElement is a placeholder that represents all of the possible classes that inherit from UIElement and that can support the object element usage for the member being documented. The Button class is one example. The uiElement placeholder is used because all of the classes that inherit the UIElement.Visibility property point to this topic in the .NET Framework Class Library for Silverlight, so some kind of placeholder is necessary. (Note that the literal <UIElement Visibility="Visible"/> with that capitalization and formatting is not accurate and usable XAML, because UIElement is abstract.)

Other base types that are indicated by placeholders in XAML usage include frameworkElement and control.

XAML Usage for Members of Open Types

With the exception of certain base classes as mentioned in the previous section, XAML usage for members of a type are generally shown as if that member was used on an instance of the defining type. For example, the XAML usage in documentation for Grid.ShowGridLines is <Grid ShowGridLines="True"/>, which is markup that you could paste directly into XAML. However, because Grid is an open type, the object element where you might set the Grid.ShowGridLines property is not necessarily literally Grid. The object element could be a class that derives from Grid. This Grid-derived class might appear in future versions of the Silverlight libraries, as part of the Silverlight Toolkit, or as a component of third-party libraries. The Grid-derived class then inherits the existing Grid.ShowGridLines, just like Button inherits Visibility. Therefore, you may also need to consider the capitalized Grid usage as a possible placeholder for any Grid-derived type, if the member is then inherited by other classes. The derived class is typically not in the default XAML namespace, and would require a XAML namespace definition and a prefix.

Open types that are in a XAML namespace that already requires a prefix have similar considerations. In this case, the prefix shown in XAML usage might only apply to the usage of the defining type. Derived types might not be in the same XAML namespace. Using the inherited member first requires that the derived type itself can be resolved by a prefix, which might be a different prefix that is shown in the usage. Once the type is resolved, the inherited member can be resolved based on that type; there is no need to apply a specific prefix to the attributes. For example, HeaderedItemsControl defines members that are inherited by the Legend class that is defined in the Silverlight Toolkit. The usage shown for these members is shown with the object element as sdk:HeaderedItemsControl per the base class definition, for example <sdk:HeaderedItemsControl Header="string"/>. But when used on a Legend, the true usage might be <toolkit:Legend Header="Header Text"/> (note the toolkit: prefix).

Property Element Syntax Versus Attribute Syntax

For some properties, it is technically possible to set the value by using either a property element syntax or an attribute syntax. Generally speaking, the XAML usage in .NET Framework Class Library for Silverlight shows the recommended usage. The recommended usage is the least verbose usage, the usage that best aligns with real-world XAML scenarios, or both. If attribute usage is possible, generally only the attribute usage is shown.

You could still attempt to use a more verbose property element form for many properties, and there are legitimate reasons for doing so. One reason is that you can place a Name attribute on an object element that provides a property element's value, which you cannot do for an attribute, and this might make it easier to reference the object value at run time. Also, you might prefer the verbose form as a matter of markup style, or you might use and modify XAML produced by a tool that emits a verbose XAML form for some properties.

There are certain properties where both property element and attribute usages are shown because one of those usages involves a type converter. The type converter usage uses the attribute syntax, other possible usages that do not involve the type converter use the property element syntax. For example, this is the case with any of the properties that use the Brush type.

There are certain properties where both property element and attribute usages are shown because the attribute usage shows a markup extension involved in the usage and that usage is clearly one of the major XAML usage scenarios for the property.

Prefixes and Mappings for Silverlight Libraries

The .NET Framework Class Library for Silverlight includes references for assemblies and types that are outside the core Silverlight assemblies. These types are usable in XAML, but using them requires that you map the XAML namespaces and assemblies to a prefix, or that you rely on Visual Studio design surface behavior that maps the XAML namespace to a prefix automatically. These prefixes are often part of the XAML usages sections and typically follow a convention. If you follow that same convention for consistent mappings at the root level, you can copy and paste the syntax from .NET Framework Class Library for Silverlight topics into your XAML page. The actual XAML namespace mapping is not typically shown in XAML usages; typically the mapping is on the root only, and the root is not shown.

The following shows an example of the XAML Object Element Usage section for the TreeView control, which has the sdk prefix. The sdk prefix is defined to map the XAML namespace https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk, which includes the assembly and CLR namespace where TreeView is defined. Thus, the XAML usage as shown in the TreeView topic is <sdk:TreeView .../>.

The prefix conventions and mappings are described in a separate topic. For more information, see Prefixes and Mappings for Silverlight Libraries.

Note:
If you are targeting Silverlight 3, then the prefix conventions for XAML usages from the SDK client libraries are different; this is also documented in Prefixes and Mappings for Silverlight Libraries.

See Also

Concepts