XAML Syntax Overview

This overview describes the different ways to declare objects and set properties in Extensible Application Markup Language (XAML).

This topic contains the following sections:

• What Is XAML?
• XAML Is Case-Sensitive
• Declaring Objects
• Setting Properties
• Events

What Is XAML?

Extensible Application Markup Language (XAML) is a declarative language. You can create visible user interface (UI) elements in the declarative XAML markup. You can then use JavaScript in a separate code-behind file to respond to events and manipulate the objects you declared in XAML. An XML-based declarative language is very intuitive for creating interfaces from prototype to production, especially for people with a background in Web design and technologies.

XAML files are XML files that generally have the .xaml file name extension. The following example shows the contents of a typical Microsoft Silverlight XAML file.

<Canvas
  xmlns="https://schemas.microsoft.com/client/2007"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">
  <Rectangle
    Width="100"
    Height="100"
    Fill="Blue" />
</Canvas>

XAML Is Case-Sensitive

XAML as a language is case-sensitive. This is another consequence of XAML being based on XML, which is also case-sensitive per the XML language definitions. The case-sensitivity of XAML is worth calling out particularly for Silverlight, because both the HTML language that is used for other aspects of the markup on a hosting Web page and the JavaScript scripting language that is used for scripting within the Silverlight 1.0 object model are not case-sensitive. The names of XAML elements and attributes are case-sensitive. The value of an attribute is potentially case-sensitive; this will depend on how the attribute value is handled for particular properties. For example, if the attribute value declares an enumeration value, the built-in behavior that looks up the enumeration value is not case-sensitive. In contrast, the value of the Name property, as well as utility methods for working with objects based on the name that the Name property declares, will treat the name string as case-sensitive.

Declaring Objects

There are two ways to declare objects and set properties in XAML:

• Object element syntax: Uses opening and closing tags to declare an object as an XML element. You can use this syntax to declare root objects or to set property values.
• Attribute syntax: Uses an inline value to declare an object. You can use this syntax to set the value of a property.

This does not mean that you always have the choice of using either object element syntax or attribute syntax. Certain objects can be created only by using object element syntax. Other objects can be created only by being initially set to a property value. Objects that can be created with either object element or attribute syntax are comparatively rare in Silverlight.

Declaring an Object by Using Object Element Syntax

To declare an object with object element syntax, you write the following two XML element tags, where objectName is the name of the object that you want to instantiate. In this documentation, you will often see the term "XAML element", which is shorthand for the particular markup that is used to create a XAML object in object element syntax.

The following example uses object element syntax to declare a Canvas object.

<Canvas>
</Canvas>

Some objects, such as Canvas, can contain other objects.

<Canvas>
  <Rectangle>
  </Rectangle>
</Canvas>

As a convenience (and as part of the general XAML relationship to XML), if the object does not contain other objects, you can declare the object element by using one self-closed tag instead of an opening/closing pair, as shown by the <Rectangle /> tag in the following example.

<Canvas>
  <Rectangle />
</Canvas>

Declaring an Object by Using Attribute Syntax

In some cases where the value of a property is not simply a language primitive such as a string, you can use attribute syntax to both instantiate the object type that sets the property and to set key properties that define the new object. See the following sections for information about how to use attribute syntax for certain properties to declare an object and to set its properties in one step.

Setting Properties

You can set properties on objects that you declared by using object element syntax. There are multiple ways to set properties in XAML:

• By using attribute syntax.
• By using property element syntax.
• By using content element syntax.
• By using implicit collection syntax.

As with object declaration, this list of techniques does not imply that a given property could be set with any of the techniques. Some properties support only one of the techniques (typically, they would support just attribute syntax, or just property element syntax). Some properties might support combinations; for example, a property that supports content element syntax might also support property element syntax or attribute syntax. This depends both on the property and on the object type that the property uses. The possibilities for XAML syntax are provided in the Syntax sections of reference pages for each Silverlight property that can be set in XAML. There are also Silverlight properties that cannot be set in XAML by any means, and must instead be set using scripting.

Setting a Property by Using Attribute Syntax

Use the following syntax, where objectName is the object you want to instantiate, property is the name of the property that you want to set on that object, and propertyValue is the value to set.

This syntax enables you to declare an object and set a property on that object in one step.

The following example uses attribute syntax on three attributes to set the width, height, and fill of a Rectangle object.

<Canvas>
  <Rectangle					
    Width="100" Height="100" Fill="Blue" />
</Canvas>

Setting a Property by Using Property Element Syntax

Some properties can be set by using property element syntax. In fact, certain properties that take objects instead of a language primitive value require property element syntax. To use property element syntax, you create XML elements for the property that you want to set. In standard XML, this element is simply an element that happens to have a dot in its name. However, in XAML, the dot in the element name identifies the element as a property element. A property element is used to set a property of its parent element instead of establishing successive child elements of parents. In the following syntax, property is the name of the property that you want to set and propertyValueAsObjectElement is a new object element that declares a new object, which is of the value type that the property expects.

The following example uses property element syntax to set the fill of a Rectangle with a SolidColorBrush object element. (The Color property of SolidColorBrush is also set by using attribute syntax. The rendered result of this XAML is identical to the preceding XAML example that set Fill using attribute syntax.)

<Canvas>
  <Rectangle
    Width="100" 
    Height="100"> 
    <Rectangle.Fill> 
      <SolidColorBrush Color="Blue"/> 
    </Rectangle.Fill>
  </Rectangle>
</Canvas>

Setting a Property by Using Content Element Syntax

For a small subset of Silverlight object/property combinations, you can omit the property name and set the property simply by nesting a value within the owning type's object element tags. This is known as content element syntax. If content element syntax is available, the syntax will be shown in the XAML syntax section for the property in the Silverlight reference documentation. For example, the Text property page for TextBlock shows an alternate XAML syntax that uses content element syntax instead of attribute syntax to set the string value of Text.

The following example sets the Text property of a TextBlock without explicitly specifying the Text property.

    <TextBlock>
      Hello!
    </TextBlock>

Setting a Property by Using Implicit Collection Syntax

For Silverlight properties that take a collection, you can omit the collection object element and simply specify its contents instead. This is known as implicit collection syntax. The following example shows how you can omit the GradientStopCollection for a LinearGradientBrush and simply specify its GradientStop objects. The GradientStopCollection is included in the first LinearGradientBrush but omitted from the second.

    <Rectangle Width="100" Height="100"
      Canvas.Left="0" Canvas.Top="30">
      <Rectangle.Fill>
        <LinearGradientBrush>
          <LinearGradientBrush.GradientStops>
            
            <!-- Here the GradientStopCollection tag is specified. -->
            <GradientStopCollection>
              <GradientStop Offset="0.0" Color="Red" />
              <GradientStop Offset="1.0" Color="Blue" />
            </GradientStopCollection>
          </LinearGradientBrush.GradientStops>
        </LinearGradientBrush>
      </Rectangle.Fill>  
    </Rectangle>
    
    
    
    <Rectangle Width="100" Height="100"
      Canvas.Left="100" Canvas.Top="30">
      <Rectangle.Fill>
        <LinearGradientBrush>
          <LinearGradientBrush.GradientStops>
          
            <!-- Notice that the GradientStopCollection tag
                 is omitted. -->
            <GradientStop Offset="0.0" Color="Red" />
            <GradientStop Offset="1.0" Color="Blue" />
          </LinearGradientBrush.GradientStops>
        </LinearGradientBrush>
      </Rectangle.Fill>  
    </Rectangle> 

If the Silverlight property is a content property and also takes a collection, you can omit both the collection object element and the property element tags that name the property that takes that collection. This syntax will be indicated as an option in the XAML syntax section of the reference pages for the property. The following example shows the implicit collection syntax usage for the GradientStops property set in the previous example.

    <Rectangle Width="100" Height="100"
      Canvas.Left="200" Canvas.Top="30">
      <Rectangle.Fill>
        <LinearGradientBrush>
          <GradientStop Offset="0.0" Color="Red" />
          <GradientStop Offset="1.0" Color="Blue" />
        </LinearGradientBrush>
      </Rectangle.Fill>  
    </Rectangle> 

When to Use Attribute or Property Element Syntax to Set a Property

All properties that support being set in XAML will support attribute or property element syntax, but not typically both. Some properties support both syntax types, and some properties support additional syntax options such as the content element syntax for Text shown previously. The type of syntax supported by a property depends on the type of object the property accepts. If the property value is a primitive type, such as a Double, Integer, or String, the property supports attribute syntax.

The following example uses attribute syntax to set the width of a Rectangle. The Width property supports attribute syntax, because the property value is a Double.

<Rectangle Width="100" />

You can use attribute syntax to set a property if the object type you use to set that property can be created on basis of a string. For primitives, this is always the case. However, certain other object types can also be created by simply using a string specified as an attribute value (instead of requiring object element syntax). This technique uses an underlying type conversion. The string value of the attribute is parsed, and some or all of the string information is used to set the properties that are crucial for the definition of the new object. Potentially, a specific type converter can also create different objects, depending on how it uniquely processes atoms of information in the string. Object types that support this behavior will have a special grammar listed in the syntax section of the documentation. Generally, the grammar that can be used to define a XAML attribute can also be used to set the analogous property to a new object in JavaScript by passing a string value.

The following example uses attribute syntax to set the fill of a Rectangle. The Fill property supports attribute syntax when you use a SolidColorBrush to set it. This is because the Brush abstract type that backs the Fill property supports a type-converted grammar that can take a string and create a SolidColorBrush (see Brush and SolidColorBrush for details).

<Rectangle Fill="Blue" />

You can use property element syntax to set a property if the object you use to set that property supports object element syntax. If the object supports object element syntax, the property also supports property element syntax. The following example uses property element syntax to set the fill of a Rectangle. The Fill property supports property element syntax when you use a SolidColorBrush to set it, because SolidColorBrush supports object element syntax and satisfies the property's requirements that its value is set with a type of Brush. (The SolidColorBrush also has its Color property set, using attribute syntax. The rendered result of this XAML is identical to the preceding XAML example that set Fill using attribute syntax.)

<Rectangle>
  <Rectangle.Fill>
    <SolidColorBrush Color="Blue"/>
  </Rectangle.Fill>					
</Rectangle>

SolidColorBrush happens to be the only case where you could have chosen either property element syntax or attribute syntax for Fill. For the other Brush types that you could have used to set the Fill, there is no type converter behavior available to create that particular type of Brush. Therefore, if you want to set a Fill by using an ImageBrush, you must use the property element syntax for Fill and declare an ImageBrush as an object element to provide the property value.

<Rectangle>
  <Rectangle.Fill>
    <ImageBrush ImageSource="forest.jpg"/>
  </Rectangle.Fill>					
</Rectangle>

Events

XAML is a declarative language for objects and their properties, but it also includes a facility for attaching event handlers to objects in the markup. You provide the name of the event that you add the handler for as an attribute name on the object where the event is handled. For the attribute value, you provide the name of an event-handler function that you define in script. The XAML reader uses this name to create a delegate representation in the loaded object tree and adds the specified handler to an internal handler list.

The following XAML example shows how to add a handler for the Loaded event for the Canvas.

<Canvas
  xmlns="https://schemas.microsoft.com/client/2007"
  Loaded="onLoaded" />

The function named onLoaded is defined in a JavaScript file. This JavaScript file is associated with the XAML file through the src parameter of the <SCRIPT> tag. This reference is included in the HTML page where the Silverlight plug-in that loads the XAML is created, as shown in the following example.

...
<!-- Reference the JavaScript file where the event functions are defined 
     from the plug-in host HTML page. -->
<script type="text/javascript" src="eventfunctions.js"></script>
... 

For more information about events, see Silverlight Events.

See Also

Silverlight Object Models and Scripting to the Silverlight Plug-in
Overviews and How-to Topics