Professional Documents
Culture Documents
12/19/13
Properties and events as they appear as XAML members of a WPF type are often inherited from base types. For example, consider this example: < B u t t o nB a c k g r o u n d = " B l u e ". . . / > . The Background property is not an immediately declared property on the Button class, if you were to look at the class definition, reflection results, or the documentation. Instead, Background is inherited from the base Control class. The class inheritance behavior of WPF XAML elements is a significant departure from a schema-enforced interpretation of XML markup. Class inheritance can become complex, particularly when intermediate base classes are abstract, or when interfaces are involved. This is one reason that the set of XAML elements and their permissible attributes is difficult to represent accurately and completely using the schema types that are typically used for XML programming, such as DTD or XSD format. Another reason is that extensibility and type-mapping features of the XAML language itself preclude completeness of any fixed representation of the permissible types and members.
Content Models
A class might support a usage as a XAML object element in terms of the syntax, but that element will only function properly in an application or page when it is placed in an expected position of an overall content model or element tree. For example, a MenuItem should typically only be placed as a child of a MenuBase derived class such as Menu.
msdn.microsoft.com/en-us/library/ms788723(d=printer,v=vs.110).aspx
2/12
12/19/13
tree. For example, a MenuItem should typically only be placed as a child of a MenuBase derived class such as Menu. Content models for specific elements are documented as part of the remarks on the class pages for controls and other WPF classes that can be used as XAML elements.
12/19/13
an attributed TypeConverter, the string value of the attribute is submitted to the type converter as a conversion input, and the converter will return a new object instance. 3. If there is no TypeConverter, a direct conversion to the property type is attempted. This final level is a direct conversion at the parser-native value between XAML language primitive types, or a check for the names of named constants in an enumeration (the parser then accesses the matching values).
< ! T h i sw i l ln o tc o m p i l e ,b e c a u s eV i s i b i l i t yi sn o taf l a g w i s ee n u m e r a t i o n . > . . . < T r i g g e rP r o p e r t y = " V i s i b i l i t y "V a l u e = " C o l l a p s e d , H i d d e n " > < S e t t e r. . ./ > < / T r i g g e r > . . . Flagwise enumerations that support attributes that are settable in XAML are rare in WPF. However, one such enumeration is StyleSimulations. You could, for instance, use the comma-delimited flagwise attribute syntax to modify the example provided in the Remarks for the Glyphs class; S t y l e S i m u l a t i o n s=" B o l d S i m u l a t i o n "could become S t y l e S i m u l a t i o n s=" B o l d S i m u l a t i o n , I t a l i c S i m u l a t i o n " . KeyBinding.Modifiers is another property where more than one enumeration value can be specified. However, this property happens to be a special case, because the ModifierKeys enumeration supports its own type converter. The type converter for modifiers uses a plus sign (+) as a delimiter rather than a comma (,). This conversion supports the more traditional syntax to represent key combinations in Microsoft Windows programming, such as "Ctrl+Alt".
12/19/13
For some scenarios, property names are sometimes provided as the value of an attribute, rather than the attribute name. That property name can also include qualifiers, such as the property specified in the form ownerType.dependencyPropertyName. This scenario is common when writing styles or templates in XAML. The processing rules for property names provided as an attribute value are different, and are governed by the type of the property being set or by the behaviors of particular WPF subsystems. For details, see Styling and Templating. Another usage for property names is when an attribute value describes a property-property relationship. This feature is used for data binding and for storyboard targets, and is enabled by the PropertyPath class and its type converter. For a more complete description of the lookup semantics, see PropertyPath XAML Syntax.
12/19/13
For properties where both attribute and property element syntax are supported, the two syntaxes generally have the same result, although subtleties such as whitespace handling can vary slightly between syntaxes.
Collection Syntax
The XAML specification requires XAML processor implementations to identify properties where the value type is a collection. The general XAML processor implementation in .NET is based on managed code and the CLR, and it identifies collection types through one of the following: Type implements IList. Type implements IDictionary. Type derives from Array (for more information about arrays in XAML, see x:Array Markup Extension.) If the type of a property is a collection, then the inferred collection type does not need to be specified in the markup as an object element. Instead, the elements that are intended to become the items in the collection are specified as one or more child elements of the property element. Each such item is evaluated to an object during loading and added to the collection by calling the Add method of the implied collection. For example, the Triggers property of Style takes the specialized collection type TriggerCollection, which implements IList. It is not necessary to instantiate a TriggerCollection object element in the markup. Instead, you specify one or more Trigger items as elements within the S t y l e . T r i g g e r s property element, where Trigger (or a derived class) is the type expected as the item type for the strongly typed and implicit TriggerCollection. XAML < S t y l ex : K e y = " S p e c i a l B u t t o n "T a r g e t T y p e = " { x : T y p eB u t t o n } " > < S t y l e . T r i g g e r s > < T r i g g e rP r o p e r t y = " B u t t o n . I s M o u s e O v e r "V a l u e = " t r u e " > < S e t t e rP r o p e r t y=" B a c k g r o u n d "V a l u e = " R e d " / > < / T r i g g e r > < T r i g g e rP r o p e r t y = " B u t t o n . I s P r e s s e d "V a l u e = " t r u e " > < S e t t e rP r o p e r t y=" F o r e g r o u n d "V a l u e = " G r e e n " / > < / T r i g g e r > < / S t y l e . T r i g g e r s > < / S t y l e > A property may be both a collection type and the XAML content property for that type and derived types, which is discussed in the next section of this topic. An implicit collection element creates a member in the logical tree representation, even though it does not appear in the markup as an element. Usually the constructor of the parent type performs the instantiation for the collection that is one of its properties, and the initially empty collection becomes part of the object tree. Note The generic list and dictionary interfaces (IList<T> and IDictionary<TKey, TValue>) are not supported for collection detection. However, you can use the List<T> class as a base class, because it implements IList directly, or Dictionary<TKey, TValue> as a base class, because it implements IDictionary directly. In the .NET Reference pages for collection types, this syntax with the deliberate omission of the object element for a collection is occasionally noted in the XAML syntax sections as Implicit Collection Syntax. With the exception of the root element, every object element in a XAML file that is nested as a child element of another element is really an element that is one or both of the following cases: a member of an implicit collection property of its 6/12 msdn.microsoft.com/en-us/library/ms788723(d=printer,v=vs.110).aspx
12/19/13
element is really an element that is one or both of the following cases: a member of an implicit collection property of its parent element, or an element that specifies the value of the XAML content property for the parent element (XAML content properties will be discussed in an upcoming section). In other words, the relationship of parent elements and child elements in a markup page is really a single object at the root, and every object element beneath the root is either a single instance that provides a property value of the parent, or one of the items within a collection that is also a collection-type property value of the parent. This single-root concept is common with XML, and is frequently reinforced in the behavior of APIs that load XAML such as Load. The following example is a syntax with the object element for a collection (GradientStopCollection) specified explicitly. XAML < L i n e a r G r a d i e n t B r u s h > < L i n e a r G r a d i e n t B r u s h . G r a d i e n t S t o p s > < G r a d i e n t S t o p C o l l e c t i o n > < G r a d i e n t S t o pO f f s e t = " 0 . 0 "C o l o r = " R e d "/ > < G r a d i e n t S t o pO f f s e t = " 1 . 0 "C o l o r = " B l u e "/ > < / G r a d i e n t S t o p C o l l e c t i o n > < / L i n e a r G r a d i e n t B r u s h . G r a d i e n t S t o p s > < / L i n e a r G r a d i e n t B r u s h > Note that it is not always possible to explicitly declare the collection. For instance, attempting to declare TriggerCollection explicitly in the previously shown Triggers example would fail. Explicitly declaring the collection requires that the collection class must support a default constructor, and TriggerCollection does not have a default constructor.
< B u t t o n > Ia ma < B u t t o n . B a c k g r o u n d > B l u e < / B u t t o n . B a c k g r o u n d > b l u eb u t t o n < / B u t t o n > This is illegal essentially because if this syntax were made explicit by using property element syntax for the content property, then the content property would be set twice:
msdn.microsoft.com/en-us/library/ms788723(d=printer,v=vs.110).aspx 7/12
12/19/13
< B u t t o n > < B u t t o n . C o n t e n t > Ia ma< / B u t t o n . C o n t e n t > < B u t t o n . B a c k g r o u n d > B l u e < / B u t t o n . B a c k g r o u n d > < B u t t o n . C o n t e n t >b l u eb u t t o n < / B u t t o n . C o n t e n t > < / B u t t o n > A similarly illegal example is if the content property is a collection, and child elements are interspersed with property elements:
< S t a c k P a n e l > < B u t t o n > T h i se x a m p l e < / B u t t o n > < S t a c k P a n e l . R e s o u r c e s > < S o l i d C o l o r B r u s hx : K e y = " B l u e B r u s h "C o l o r = " B l u e " / > < / S t a c k P a n e l . R e s o u r c e s > < B u t t o n > . . .i si l l e g a lX A M L < / B u t t o n > < / S t a c k P a n e l >
12/19/13
Mixing Property Elements and Object Elements in an Object with a Content Property
The XAML specification declares that a XAML processor can enforce that object elements that are used to fill the XAML content property within an object element must be contiguous, and must not be mixed. This restriction against mixing property elements and content is enforced by the WPF XAML processors. You can have a child object element as the first immediate markup within an object element. Then you can introduce property elements. Or, you can specify one or more property elements, then content, then more property elements. But once a property element follows content, you cannot introduce any further content, you can only add property elements. This content / property element order requirement does not apply to inner text used as content. However, it is still a good markup style to keep inner text contiguous, because significant whitespace will be difficult to detect visually in the markup if property elements are interspersed with inner text.
XAML Namespaces
None of the preceding syntax examples specified a XAML namespace other than the default XAML namespace. In typical WPF applications, the default XAML namespace is specified to be the WPF namespace. You can specify XAML namespaces other than the default XAML namespace and still use similar syntax. But then, anywhere where a class is named that is not accessible within the default XAML namespace, that class name must be preceded with the prefix of the XAML namespace as mapped to the corresponding CLR namespace. For example, < c u s t o m : E x a m p l e / >is object element syntax to instantiate an instance of the E x a m p l eclass, where the CLR namespace containing that class (and possibly the external assembly information that contains backing types) was previously mapped to the c u s t o mprefix. For more information about XAML namespaces, see XAML Namespaces and Namespace Mapping for WPF XAML.
Markup Extensions
XAML defines a markup extension programming entity that enables an escape from the normal XAML processor handling of string attribute values or object elements, and defers the processing to a backing class. The character that identifies a markup extension to a XAML processor when using attribute syntax is the opening curly brace ({), followed by any character other than a closing curly brace (}). The first string following the opening curly brace must reference the class that provides the particular extension behavior, where the reference may omit the substring "Extension" if that substring is part of the true class name. Thereafter, a single space may appear, and then each succeeding character is used as input by the extension implementation, up until the closing curly brace is encountered. The .NET XAML implementation uses the MarkupExtension abstract class as the basis for all of the markup extensions supported by WPF as well as other frameworks or technologies. The markup extensions that WPF specifically implements are often intended to provide a means to reference other existing objects, or to make deferred references to objects that will be evaluated at run time. For example, a simple WPF data binding is accomplished by specifying the { B i n d i n g } markup extension in place of the value that a particular property would ordinarily take. Many of the WPF markup extensions enable an attribute syntax for properties where an attribute syntax would not otherwise be possible. For example, a Style object is a relatively complex type that contains a nested series of objects and properties. Styles in WPF are typically defined as a resource in a ResourceDictionary, and then referenced through one of the two WPF markup extensions that request a resource. The markup extension defers the evaluation of the property value to a resource lookup and enables providing the value of the Style property, taking type Style, in attribute syntax as in the following example: < B u t t o nS t y l e = " { S t a t i c R e s o u r c eM y S t y l e } " > M yb u t t o n < / B u t t o n > msdn.microsoft.com/en-us/library/ms788723(d=printer,v=vs.110).aspx
9/12
12/19/13
< B u t t o nS t y l e = " { S t a t i c R e s o u r c eM y S t y l e } " > M yb u t t o n < / B u t t o n > Here, S t a t i c R e s o u r c eidentifies the StaticResourceExtension class providing the markup extension implementation. The next string M y S t y l eis used as the input for the non-default StaticResourceExtension constructor, where the parameter as taken from the extension string declares the requested ResourceKey. M y S t y l eis expected to be the x:Key value of a Style defined as a resource. The StaticResource Markup Extension usage requests that the resource be used to provide the Style property value through static resource lookup logic at load time. For more information about markup extensions, see Markup Extensions and WPF XAML. For a reference of markup extensions and other XAML programming features enabled in the general .NET XAML implementation, see XAML Namespace (x:) Language Features. For WPF-specific markup extensions, see WPF XAML Extensions.
Attached Properties
Attached properties are a programming concept introduced in XAML whereby properties can be owned and defined by a particular type, but set as attributes or property elements on any element. The primary scenario that attached properties are intended for is to enable child elements in a markup structure to report information to a parent element without requiring an extensively shared object model across all elements. Conversely, attached properties can be used by parent elements to report information to child elements. For more information on the purpose of attached properties and how to create your own attached properties, see Attached Properties Overview. Attached properties use a syntax that superficially resembles property element syntax, in that you also specify a typeName.propertyName combination. There are two important differences: You can use the typeName.propertyName combination even when setting an attached property through attribute syntax. Attached properties are the only case where qualifying the property name is a requirement in an attribute syntax. You can also use property element syntax for attached properties. However, for typical property element syntax, the typeName you specify is the object element that contains the property element. If you are referring to an attached property, then the typeName is the class that defines the attached property, not the containing object element.
Attached Events
Attached events are another programming concept introduced in XAML where events can be defined by a specific type, but handlers may be attached on any object element. In the WOF implementation, often the type that defines an attached event is a static type that defines a service, and sometimes those attached events are exposed by a routed event alias in types that expose the service. Handlers for attached events are specified through attribute syntax. As with attached events, the attribute syntax is expanded for attached events to allow a typeName.eventName usage, where typeName is the class that provides Add and Remove event handler accessors for the attached event infrastructure, and eventName is the event name.
12/19/13
element
x m l n s = " h t t p : / / s c h e m a s . m i c r o s o f t . c o m / w i n f x / 2 0 0 6 / x a m l / p r e s e n t a t i o n " The default (WPF) XAML namespace x m l n s : x = " h t t p : / / s c h e m a s . m i c r o s o f t . c o m / w i n f x / 2 0 0 6 / x a m l " The XAML language XAML namespace The partial class declaration that connects markup to any code-behind defined for the partial class End of object element for the root. Object is not closed yet because the element contains child elements
x : C l a s s = " E x a m p l e N a m e s p a c e . E x a m p l e C o d e "
>
12/19/13
< ! < B u t t o nL a b e l . B a c k g r o u n d = " B l u e " > D o e sn o tw o r k < / B u t t o n >> Label is another derived class of Control, and if you had specified L a b e l . B a c k g r o u n dwithin a Label object element, this usage would have worked. However, because Label is not the class or base class of Button, the specified XAML processor behavior is to then process L a b e l . B a c k g r o u n das an attached property. L a b e l . B a c k g r o u n dis not an available attached property, and this usage fails.
See Also
Concepts
XAML Overview (WPF) Dependency Properties Overview TypeConverters and XAML XAML and Custom Classes for WPF
Other Resources
msdn.microsoft.com/en-us/library/ms788723(d=printer,v=vs.110).aspx
12/12