Implementing a Property Editor

Table of Contents Define Application Data and Properties Set up Property Editing Context Create Property Descriptors Describing Data Properties Using Value Editors, Value Converters, and Value Editing Controls Using Property Editor Components Add Property Editing Components to MEF Catalog and Initialize Topics in this section

You can implement a property editor in your application by following these steps:

1. Define the data whose properties you want to examine.
2. Set up a context for property editing.
3. Create property descriptors for the data's properties/attributes.
4. Use existing or create new value editors, value converters, and value editing controls.
5. Use existing or create new property editing components to display properties of selected items.
6. Add property editing components to the application's MEF type catalog and initialize them.

Define Application Data and Properties

You can describe data in your application many ways. If application data is defined in an ATF DOM, you can create property editors in a fairly straightforward fashion.

You can also generate your own non-DOM data and examine it with property editors, which is what the ATF Tree List Editor Sample does. For a detailed description of how this sample works, see Tree List Editor Programming Discussion.

The rest of this section discusses how to implement property editors for application data in an ATF DOM, using the steps above.

When using an ATF DOM, you create a type definition file describing all the data types and their attributes/properties. You can do this in a variety of ways, but ATF provides the best support for property editors (and other things) when you define the data using the XML Schema Definition (XSD) language. ATF Simple DOM Editor Sample and ATF Simple DOM No XML Editor Sample both show using property editors with DOM data, with and without using an XML Schema. For details on these samples, see Simple DOM Editor Programming Discussion and Simple DOM No XML Editor Programming Discussion.

For details on using the ATF DOM for your data model, see the ATF Programmer's Guide: Document Object Model (DOM), which you can download at ATF Documentation.

Set up Property Editing Context

Your application provides ways to edit its data's properties, and must provide a context in which to do this. There are several key interfaces the context should implement, including ISelectionContext, which provides properties and methods to get the selected items and last selected item, change the selection, and so forth. It also provides events for selection changes. You may also want to implement ITransactionContext, so that property editing changes can be undone and redone as part of transactions.

Several samples provide EditingContext classes, and some of these derive from or directly use Sce.Atf.Dom.EditingContext, which implements both HistoryContext and ISelectionContext. HistoryContext derives from TransactionContext, which implements ITransactionContext.

Handling the selection changing events in ISelectionContext hooks into the event handling system that ultimately generates a list of property descriptors for the selected items' properties. Property editors use this list to display the common properties of selected items. If you provide the context, this processing happens for you.

For more information on using a context for property editing, see Selection Property Editing Context. For general information on contexts, see ATF Contexts.

Create Property Descriptors Describing Data Properties

Property descriptors can be created in two ways:

• With constructors, as described in Constructing Property Descriptors.
• From XML Schema annotations, as shown in Creating Property Descriptors with XML Schema Annotations.

The samples demonstrate both approaches. For instance, the ATF FSM Editor Sample shows constructing property descriptors in its schema loader. The ATF Timeline Editor Sample shows specifying property descriptors in XML Schema annotations.

Using Value Editors, Value Converters, and Value Editing Controls

Property descriptors define which value editors and value converters are used for each data type. Each value editor specifies which value editing control users interact with to change the property's value.

If you are using existing ATF classes for the value editors, value converters, and value editing controls, you don't need to do anything else. For a list of existing value editors, see Value Editors and Value Editing Controls. For a list of existing ATF value converters, see ATF Value Converters. For existing value editing controls, see Value Editors and Value Editing Controls.

If your data does not fit any of these existing value processing classes, you need to define your own:

• For information on creating value editors, see Value Editors.
• For information on creating value converters, see Value Converters.
• For information on creating controls, see Controls in ATF.

Using Property Editor Components

The property editor components serve as containers for property editing controls:

• GridPropertyEditor displays items with properties in a spreadsheet type control, allowing you to see the properties of all selected items.
• PropertyEditor displays items with properties in a two-column control, so you can see the properties of only one selected item, with its categories or child properties.

These components automatically create the property editing controls, embed them, and display the values of currently selected items.

For general information on these components, see Property Editor Containers.

Add Property Editing Components to MEF Catalog and Initialize

Your application needs to incorporate the Managed Extensibility Framework (MEF) to use the property editor components. For information on MEF, see MEF with ATF.

You must add the property editor components to your MEF catalog, as in this code from the Main() function of ATF Timeline Editor Sample:

TypeCatalog catalog = new TypeCatalog(
    ...
    typeof(PropertyEditor),                 // property grid for editing selected objects
    typeof(GridPropertyEditor),             // grid control for editing selected objects
    typeof(PropertyEditingCommands),        // commands for PropertyEditor and GridPropertyEditor
    ...

This sample also adds the PropertyEditingCommands component to provide property editing commands that can be used inside PropertyEditor and GridPropertyEditor from context menus. For more information on PropertyEditingCommands, see its entry in the table in Using Standard Command Components.

After the components are added, call MefUtil.InitializeAll() to initialize them.

Before you set up the MEF catalog, you should also make this call:

DomNodeType.BaseOfAllTypes.AddAdapterCreator(new AdapterCreator<CustomTypeDescriptorNodeAdapter>());

Doing this guarantees that the properties you set up in the property descriptors are the ones that appear in the property editors. If this statement were removed, the properties visible in a property editor for an item would be properties of the selected object and classes it derives from — not the properties you provide in your property descriptor.

For more information, see Metadata Driven Property Editing.

Topics in this section