Using Properties in ATF

Table of Contents Property Editing Overview Selection Property Editing Context Property Descriptors Value Editors Value Editing Controls Value Converters Property Editor Components Topics in this section

Property Editing Overview

Applications typically create and edit data, so editing data objects' properties is one of the fundamental purposes of an application. For instance, one of the main functions of a vector graphics editing application is to change graphical object's properties, such as line width, thickness, and color.

Applications usually provide property editor controls for the application's data objects. These editors may go by various names, such as object inspectors, but their function is the same. Typically the property editor displays a collection of properties belonging to the selected object or properties common to all selected objects. For each property, the editor must provide an appropriate value editor control for that property's data type. A color editor control is very different from a numerical editor control, for instance.

Because the property editor shows properties for a selection, it is dependent on the current context. Property editors can only be used when there is a selection and the active context is one in which properties can be edited. ATF uses the context to determine which property editors are appropriate. For more information, see Selection Property Editing Context and ATF Contexts.

If an application uses a data model for its application data based on the ATF Document Object Model (DOM), ATF provides a great deal of support for property editors of the attributes of the application's data types. The DOM defines the data types used in the application. Property editing support is even better when the DOM uses the XML Schema Definition (XSD) to specify the data types. A data type can have attributes, which are equivalent to properties. For an introduction to the DOM, see DOM in a Nutshell. For further details on the ATF DOM, see the ATF Programmer's Guide: Document Object Model (DOM), which you can download at ATF Documentation.

ATF provides several kinds of classes to handle property editing: a selection property editing context, property descriptors, value editors, value editing controls, value converters, and property editors. Although these classes integrate well with the ATF DOM, they can be useful for property editing even if the application does not use the ATF DOM.

Value editor classes names typically end in "Editor", value editing control classes in "Control", and value converter classes in "Converter".

Selection Property Editing Context

The default context for property editors is SelectionPropertyEditingContext, which is constructed when property editors are created. The SelectionPropertyEditingContext class supports property editing on any ISelectionContext, which provides properties and methods to get the selected items, last selected item, and so forth. This interface also provides events for selection changes. For details, see Selection Property Editing Context.

Property Descriptors

A property descriptor is a metadata class describing a property/attribute of a data type. It contains information about the property, such as its name, description, and an appropriate editor for the property, given its data type. Property descriptors provide the information needed to actually edit properties.

Property descriptors can be described in a variety of ways: from constructors and from XML Schemas in the ATF DOM.

For more information, see Property Descriptors.

Value Editors

Every data object property has a data type, which may be defined in the application's data model. ATF provides a large set of value editors for the various kinds of data types, listed in Value Editors and Value Editing Controls. For example, the BoundedIntEditor edits bounded integers. Value editors use a value editing control for the user to interact with in modifying the property value.

Value Editing Controls

Every value editor has a corresponding value editing control that users employ to set the desired property value. A value editing control for a Boolean value could simply be a CheckBox control, for instance. A bounded integer could use a spinner control. A color editor can use a color picker control. For details, see Value Editors and Value Editing Controls.

Value Converters

The value converter converts the property value between its internal data representation in a value editor and a form that that appears in a value editing control. For instance, a value converter for an integer value could go back and forth between an internal int value and a string representation of the integer that can be displayed in a value editing control. The conversion typically goes in both directions. For more information, see Value converters.

Property Editor Components

Property editor controls contain the value editing control components. There are two main classes: GridView and PropertyGridView, which both derive from PropertyView. PropertyGridView is used for two column style editors. GridView shows a spreadsheet view, listing properties of several items.

You don't need to use GridView and PropertyGridView directly. A GridView is usually provided by the GridPropertyEditor component, PropertyGridView by the PropertyEditor component. These components make these property editor controls very easy to use.

These property editors are designed to show the common properties of selected objects, so you must set up the selection context for the items whose properties you want to edit. These editors ultimately require a list of property descriptors for the properties to be edited.

For details, see Property Editor Components.

Topics in this section