DOM Property Descriptors

Table of Contents Property Descriptors Specifying Property Descriptors in Constructors Specifying Property Descriptors in Annotations Other Uses of Annotations Topics in this section

DOM property descriptors describe type attributes, allow you to easily edit object attributes in property editors, and can be specified in constructors or annotations in the type definition file.

As part of their definition, a data model's types have attributes, which can be considered properties of objects of these types. Applications often have property editor controls to modify these object properties. Property descriptors are metadata for class properties that describe these attributes/properties.

Controls like property editors get all the information they need to edit properties from property descriptors. The DOM uses property descriptor classes to describe properties of DOM types: their attributes and child node types. After you create these descriptors, it's easy to implement property editing in your application using ATF property editing control components, such as PropertyEditor and GridPropertyEditor. For information on using properties in general, see the Property Editing in ATF section.

Property descriptor objects are added to DOM metadata: the DomNodeType for a type.

Property Descriptors

In .NET, property descriptors add metadata to class properties for controls, such as property editors. DOM property descriptors are custom descriptors that describe properties of DomNodes — the nodes' attributes and their children's nodes. You can create descriptors for properties to enable editing DOM nodes' properties in your application.

Information provided by a property descriptor can include such items as the display name of a property, descriptive text for tooltips, or the editor control used to edit that property. Creating a property descriptor allows viewing and editing a property in a property editor control with very little coding effort. Conversely, if information is not provided about a property in a property descriptor, the property is not visible in property editors.

The .NET System.ComponentModel namespace defines the basic PropertyDescriptor and PropertyDescriptorCollection classes. ATF extends this PropertyDescriptor to provide an abstract Sce.Atf.Dom.PropertyDescriptor class that is itself extended to describe attributes and children of DomNode objects. ATF's PropertyEditor, shown in the figure, and GridPropertyEditor components both use property descriptors for the information they need to display and edit properties.

ATF extends its abstract class Sce.Atf.Dom.PropertyDescriptor to define property descriptors for these items:

• Attributes: DomNode attributes map directly to properties. The AttributePropertyDescriptor class defines attribute descriptors.
• Child nodes. A DomNode can have child nodes, and these nodes can be associated with property descriptors in the ChildPropertyDescriptor class.
• Child attributes: Child attributes are the same as regular attributes, but are defined on a child node and include the child metadata ChildInfo. The ChildAttributePropertyDescriptor class defines these descriptors.

AttributePropertyDescriptor is the most commonly used of the three. ChildAttributePropertyDescriptor is used in certain circumstances; for an example, see Specifying Property Descriptors in Constructors. ChildPropertyDescriptor is rarely used.

You can create DOM property descriptors in two ways:

• Construct the descriptors, usually in the schema loader, after the schema is loaded. For details, see Specifying Property Descriptors in Constructors.
• Add annotations to the XML Schema type definition file. For information on creating these annotations, see Specifying Property Descriptors in Annotations.

Specifying Property Descriptors in Constructors

Applications can specify property descriptors by constructing them, typically in the schema loader's OnSchemaSetLoaded() method. For example, the ATF DOM Tree Editor Sample defines descriptors for the attributes "AnimationTransform" and "AnimalKinds" of "UIAnimationType" in this way:

UISchema.UIAnimationType.Type.SetTag(
    new PropertyDescriptorCollection(
        new PropertyDescriptor[] {
        new AttributePropertyDescriptor(
            Localizer.Localize("Animation transform"),
            UISchema.UIAnimationType.AnimationTransformAttribute,
            null,
            Localizer.Localize("Animation transform"),
            false,
            new NumericMatrixEditor(typeof(float), 3, 3)),
        new AttributePropertyDescriptor(
            Localizer.Localize("Animal kinds"),
            UISchema.UIAnimationType.AnimalKindsAttribute,
            null,
            Localizer.Localize("Kinds of animal to animate"),
            false,
            new CollectionEditor()),
    }));

The property descriptor AttributePropertyDescriptor is used here, because "AnimationTransform" and "AnimalKinds" are attributes of "UIAnimationType". As a result, the PropertyEditor component displays properties for these attributes when a "UIAnimationType" object type is selected.

There are several forms of the constructor for AttributePropertyDescriptor, and these forms specify various information about the attribute, such as its name in the property editor and the type of value editor to use for the attribute. For more details on using AttributePropertyDescriptor in the ATF Simple DOM Editor Sample, see Using the DOM.

Note that property descriptors are added to the UISchema.UIAnimationType.Type DomNodeType object with the NamedMetadata.SetTag() method. For more information on this and related methods, see NamedMetadata Tag Methods.

You can also define property descriptors on attributes for types of objects that are children of nodes, but you use ChildAttributePropertyDescriptor instead. For a description of how the ATF DOM Tree Editor Sample does this, see Type Tag Property Descriptors.

Specifying Property Descriptors in Annotations

You can also define property descriptors in annotations in the XML Schema using the <xs:annotation> and <xs:appinfo> tags. The advantage of doing this over specifying property descriptors in constructors is that all the type's information is in one place. Changing annotations doesn't require rebuilding the application either.

Here's an example from the ATF Timeline Editor Sample's timeline.xsd type definition file:

<xs:complexType name="eventType">
  <xs:annotation>
    <xs:appinfo>
      <scea.dom.editors.attribute name="start" displayName="Start" description="Start Time" />
      <scea.dom.editors.attribute name="description" displayName="Description" description="Event description" />
    </xs:appinfo>
  </xs:annotation>
  <xs:attribute name="start" type="xs:float"/>
  <xs:attribute name="description" type="xs:string"/>
</xs:complexType>

These annotations create property descriptors for the "start" and "description" attributes. Note that annotations are specified in addition to the attributes' definitions in <xs:attribute> tags at the end.

Using annotations requires special support from the schema loader to parse the annotations, typically in the XmlSchemaTypeLoader.ParseAnnotations() method. For a detailed description of how the ATF Timeline Editor Sample supports annotations, see XML Schema Annotations.

Other Uses of Annotations

You can define your own types of annotations for whatever additional information you want to add to a type. You would also need to add support for this type of annotation, usually by overriding XmlSchemaTypeLoader.ParseAnnotations().

For example, the ATF Timeline Editor Sample's timeline.xsd type definition file has a "scea.dom.editors" annotation for "groupType":

<xs:complexType name="groupType">
  <xs:annotation>
    <xs:appinfo>
      <scea.dom.editors menuText="Group" description="Group" image="TimelineEditorSample.Resources.group.png" category="Timelines" />
      <scea.dom.editors.attribute name="name" displayName="Name" description="Name" />
      <scea.dom.editors.attribute name="expanded" displayName="Expanded" description="Whether Group is Expanded" />
    </xs:appinfo>
  </xs:annotation>
  ...

The TimelineEditor sample overrides XmlSchemaTypeLoader.ParseAnnotations(), and this override method gets information from the annotation to create palette items. Note that this annotation applies to the entire type — not an attribute of the type. For details on how it handles this annotation, see Annotation Parsing in Timeline Editor Programming Discussion.

Topics in this section