Skip to content

Property Descriptors

Jump to bottom
Gary edited this page Jan 29, 2015 · 2 revisions

Table of Contents

PropertyDescriptor Class

The property descriptors ATF uses all derive from the System.ComponentModel.PropertyDescriptor class, a public abstract class. From this base class, ATF derives Sce.Atf.Controls.PropertyEditing.PropertyDescriptor. This ATF class is also abstract, so ATF in turn derives classes from it. In this documentation, PropertyDescriptor refers to ATF's Sce.Atf.Controls.PropertyEditing.PropertyDescriptor unless System.ComponentModel.PropertyDescriptor is specified.

PropertyDescriptor has a variety of constructors to specify the PropertyDescriptor's associated information. Here is a list of all the various parameters; the last three are not required:

  • Name (string): Property name.
  • Type (System.Type): Type of the property.
  • Category (string): Category of the property.
  • Description (string): Description of the property.
  • ReadOnly (bool): Whether or not the property is read-only.
  • Editor (object): The value editor used to edit the property. For details on value editors, see Value Editors.
  • Type converter (System.ComponentModel.TypeConverter): The value type converter used for this property. For more information, see Value converters.
  • Attributes (System.Attribute[]): An array of System.Attribute custom attributes. These may be provided, but are not used by ATF. Instead, attributes are specified in the AttributePropertyDescriptor class, as described in AttributePropertyDescriptor Class.
Note that the "Editor" and "Type converter" objects, when provided, indicate precisely which value editor and value type converter to use for the property.

All of the above parameters for the constructor are available as C# properties of PropertyDescriptor, except for the value editor. The PropertyDescriptor.GetEditor(Type editorBaseType) method gets the value editor for the given type, returning the value editor provided in the constructor, if there was one and it is compatible with the given Type. If no editor was provided, a default value editor and value type converter are supplied, based on the specified Type.

ATF derives two classes from PropertyDescriptor: AttributePropertyDescriptor and ChildPropertyDescriptor. These classes are used with the ATF DOM. Applications may also derive their own property descriptors, as in the ATF Tree List Editor Sample.

AttributePropertyDescriptor Class

In addition to the parameters for PropertyDescriptor, the AttributePropertyDescriptor constructor has an AttributeInfo parameter, which is required. The AttributeInfo class contains information used by the ATF DOM. A DOM's data type definitions describe attributes, that is properties, of data types. AttributeInfo has metadata that includes the underlying attribute type (AttributeType) and any restrictions the attribute was defined with in the DOM, such as bounds limitations for integer type attributes.

AttributePropertyDescriptor is the main type of property descriptor used in ATF. The samples show numerous examples of using it to specify property descriptors for application data types.

ChildPropertyDescriptor Class

In the DOM, data elements are stored in a tree of DOM nodes. A data type can specify that it has children of a certain type — ChildPropertyDescriptor describes properties of types of child nodes. Child information includes the child's data type and whether the child is a list of nodes. ChildInfo also contains any restriction rules, such as limits on the number of children.

ParseXml Method

When an application uses the XML Schema Definition (XSD) language to specify the DOM data types, the data type definitions may include annotations that add information about the data type. In particular, the annotations can specify property descriptors. PropertyDescriptor.ParseXml() parses the XML Schema for these types of annotations and creates property descriptors. For more details on these annotations, see Creating Property Descriptors with XML Schema Annotations.

Specifying Property Descriptors

You can specify property descriptors two ways: constructing property descriptors directly or, with the ATF DOM, using XML Schema annotations. For more information, see DOM Property Descriptors and the ATF Programmer’s Guide: Document Object Model (DOM), which you can download at ATF Documentation.

Constructing Property Descriptors

You can create a property descriptor object directly with its constructor.

Using the DOM

The example here uses AttributePropertyDescriptor objects with the ATF DOM. When an application using the DOM starts up, it reads the data type definitions from a type definition file using a class called a schema type loader. The schema type loader creates metadata class objects for the type information, such as AttributeInfo objects. The loader can add information about the data types. In particular, it can define a property descriptor for an attribute of a data type.

Here's an example from the ATF Simple DOM Editor Sample that defines property descriptors for an "eventType" data type's attributes. It creates three AttributePropertyDescriptor objects, placing them in a PropertyDescriptorCollection object: 

Schema.eventType.Type.SetTag(
    new PropertyDescriptorCollection(
        new PropertyDescriptor[] {
            new AttributePropertyDescriptor(
                Localizer.Localize("Name"),
                Schema.eventType.nameAttribute,
                null,
                Localizer.Localize("Event name"),
                false),
            new AttributePropertyDescriptor(
                Localizer.Localize("Time"),
                Schema.eventType.timeAttribute,
                null,
                Localizer.Localize("Event starting time"),
                false),
            new AttributePropertyDescriptor(
                Localizer.Localize("Duration"),
                Schema.eventType.durationAttribute,
                null,
                Localizer.Localize("Event duration"),
                false),
    }));

These constructors for the AttributePropertyDescriptor objects use this form of the constructor: 

public AttributePropertyDescriptor(
    string name,
    AttributeInfo attribute,
    string category,
    string description,
    bool isReadOnly);

These AttributePropertyDescriptor constructor examples specify the property descriptor's name, AttributeInfo, description, and read only properties; they leave category unspecified as null. The AttributeInfo object, as in Schema.eventType.nameAttribute, is a type metadata object, created by the schema type loader.

AttributePropertyDescriptor also has a constructor with an editor parameter: 

public AttributePropertyDescriptor(
    string name,
    AttributeInfo attribute,
    string category,
    string description,
    bool isReadOnly,
    object editor);

This constructor form is used in this example from the schema type loader in the ATF Simple DOM Editor Sample to specify an editor object BoolEditor() for a Boolean editor: 

new AttributePropertyDescriptor(
	"Compressed".Localize(),
	Schema.animationResourceType.compressedAttribute,
	null,
	"Whether or not animation is compressed".Localize(),
	false,
	new BoolEditor()),

Finally, the AttributePropertyDescriptor constructor can also specify the value type converter: 

public AttributePropertyDescriptor(
    string name,
    AttributeInfo attribute,
    string category,
    string description,
    bool isReadOnly,
    object editor,
    TypeConverter typeConverter);

This constructor from the ATF Simple DOM Editor Sample creates a value type converter for an enumerated type: 

string[] primitiveKinds = new string[]
{
    "Lines",
    "Line_Strips",
    "Polygons",
    "Polylist",
    "Triangles",
    "Triangle_Strips",
    "Bezier_Curves",
    "Bezier_Surfaces",
    "Subdivision_Surfaces"
};
...
new AttributePropertyDescriptor(
    Localizer.Localize("Primitive Kind"),
    Schema.geometryResourceType.primitiveTypeAttribute,
    null,
    Localizer.Localize("Kind of primitives in geometry"),
    false,
    new EnumUITypeEditor(primitiveKinds),
    new EnumTypeConverter(primitiveKinds))

The variable primitiveKinds contains a string array that the constructors for the value type editor and converter, EnumUITypeEditor and EnumTypeConverter, both use as the parameter.

Not Using the DOM

The ATF Tree List Editor Sample defines its own data types without a DOM in its DataItem class, which defines a method GetProperties() to get a collection of property descriptors. The class PropertyPropertyDescriptor derives from the System.ComponentModel.PropertyDescriptor class. The GetProperties() method constructs PropertyPropertyDescriptor objects and adds them to a PropertyDescriptorCollection collection: 

public override PropertyDescriptorCollection GetProperties()
{
    var props = new PropertyDescriptorCollection(null);

    foreach (var property in GetType().GetProperties())
    {
        var propertyDesc =
            new PropertyPropertyDescriptor(property, GetType());

        propertyDesc.ItemChanged += PropertyDescItemChanged;

        foreach (Attribute attr in propertyDesc.Attributes)
        {
            if (attr.GetType().Equals(typeof(PropertyEditingAttribute)))
                props.Add(propertyDesc);
        }
    }

    return props;
}

For more information about the programming in this sample, see Tree List Editor Programming Discussion.

Creating Property Descriptors with XML Schema Annotations

If you use the XML Schema Definition (XSD) language to define your data types in the DOM, you can specify property descriptors in annotations. The annotation's attributes provide the same information as property descriptor constructor parameters.

The <scea.dom.editors.attribute> tag is used for an annotation that describes a property descriptor.

The ATF Timeline Editor Sample's data definition includes a "timelineRef" type, which contains an annotation defining property descriptors: 

<xs:complexType name="timelineRefType">
  <xs:annotation>
    <xs:appinfo>
      <scea.dom.editors menuText="Reference" description="Timeline Reference"
                        image="TimelineEditorSample.Resources.group.png" category="Timelines" />
      <scea.dom.editors.attribute name="name" displayName="Name" description="Name" />
      <scea.dom.editors.attribute name="start" displayName="Start" description="Start Time" />
      <scea.dom.editors.attribute name="description" displayName="Description" description="Event description" />
      <scea.dom.editors.attribute name="color" displayName="Color" description="Display Color"
        editor="Sce.Atf.Controls.PropertyEditing.ColorEditor,Atf.Gui"
        converter="Sce.Atf.Controls.PropertyEditing.IntColorConverter" />
      <scea.dom.editors.attribute name="ref" displayName="File Name" description="File name of timeline reference"
        editor="Sce.Atf.Controls.PropertyEditing.FileUriEditor,Atf.Gui.WinForms:Timeline files (*.timeline)|*.timeline"/>
    </xs:appinfo>
  </xs:annotation>
  <xs:attribute name="name" type="xs:string" />
  <xs:attribute name="start" type="xs:float"/>
  <xs:attribute name="description" type="xs:string"/>
  <xs:attribute name="color" type="xs:integer" default="-32640"/>
  <xs:attribute name="ref" type="xs:anyURI" />
</xs:complexType>

The <xs:attribute> tags at the end specify the actual attributes of the "timelineRef" type, which includes their raw data type. For instance, the "name" attribute is a string, and the "start" attribute is a floating point number.

The <scea.dom.editors.attribute> tags define the property descriptors for each attribute/property and do not specify its data type; that is already specified in the <xs:attribute> tags.

The first three <scea.dom.editors.attribute> tags only specify three properties:

  • "name": the attribute's name.
  • "displayName": the property name, displayed in the value editor.
  • "description": an optional full description of the attribute.
The last two property descriptor definitions include two more properties, followed by optional parameters:
  • "editor": an optional fully qualified name (by namespace) of a UITypeEditor control for editing, followed by its assembly name and optional parameters.
  • "converter": an optional fully qualified name (by namespace) of a TypeConverter value converter class used for this property, followed by optional parameters.
For instance, the value editor for the "ref" property is given by 
editor="Sce.Atf.Controls.PropertyEditing.FileUriEditor,Atf.Gui.WinForms:Timeline files (*.timeline)|*.timeline"

This specifies the full path of the value editor class, a URI editor, followed by its assembly. After the colon is an optional parameter: a file filter string.

The value type converter for the "color" property is given by 

converter="Sce.Atf.Controls.PropertyEditing.IntColorConverter"

Topics in this section

Property Editing in ATF

About

Learning

© 2014-2015, Sony Computer Entertainment America LLC
Clone this wiki locally