Property Editing Architecture
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Visually editing object properties is an important feature of the WPF Designer for Visual Studio. This topic describes the architecture of the WPF Designer property editing system.
Property Entry
The PropertyEntry class represents the property itself. The PropertyValue class represents the underlying value of a property.
Category Editors
A category editor allows the end user to edit multiple properties within a category at the same time. The properties that are associated with a category editor are not shown elsewhere in the Properties window. Properties that are not edited by that category editor will be visible and editable. You can specify which properties within a category are edited by a category editor.
Property Value Editors
A property value editor defines how a particular type is displayed and edited in the Properties window of a visual designer. Property value editors play a role in the WPF Designer, similar to that of the UITypeEditor class in the System.ComponentModel architecture. The WPF Designer editors, however, are independent of the System.ComponentModel and Windows Forms architecture.
A PropertyValueEditor has the parts listed in the following table.
Property value editor part |
Description |
|---|---|
Inline editor (also called the view) |
An editor that is hosted in the same physical space as the view in the hosting Properties window. For example, the Margin property editor. |
Extended editor |
An editor that is not normally hosted in-place. This is the equivalent of the drop-down style editor in the System.ComponentModel architecture. For example, the HorizontalAlignment property editor. |
Dialog box |
An editor that is implemented in its own dialog box. For example, the RowDefinitions property editor. |
You can use defaults for the view and inline editor parts. A PropertyValueEditor is not required to provide an extended editor part.
Each part is a WPF DataTemplate. Each part is independent of the others and can be used independently.
The hosting Properties window provides the frame around the view and editors. This allows the host to provide a consistent style across editors and allows different hosts to provide different styles. For example, Expression Blend and Visual Studio both provide a different appearance and behavior for their respective Properties windows.
WPF data binding and a standard set of WPF RoutedCommand objects provide the communication mechanism between the host and the PropertyValueEditor parts.
In the simplest case, a value editor part can be a DataTemplate that contains standard WPF controls. In more complex cases, a type part can be a DataTemplate that references your custom control.
You can implement three different types of property value editors, which are listed in the following table.
Property value editor type |
Description |
|---|---|
Simple |
The property value editor consists of an inline editor. |
Extended |
The property value editor consists of an inline editor and an extended editor. |
Dialog |
The property value editor consists of an inline editor and a dialog box. |
Infrastructure Classes
Infrastructure classes are required for any property value editor implementation. These classes are listed in the following table and consist of the core infrastructure for hosting or authoring value editors.
Infrastructure class |
Description |
|---|---|
Represents the value of a property. |
|
The base class for value editors. |
|
RoutedCommand types and default implementations of handlers for those commands. |
|
The abstract base class for dialog box value editors.
|
Property Value Editor Implementation
The following sections describe aspects of implementing a property value editor.
Value, StringValue, and Collection
The PropertyValue model has three properties that relate to the value of the property. The PropertyValue properties are listed in the following table.
PropertyValue property |
Description |
|---|---|
An object representation of the data. |
|
A string representation of the data, which can be used for display or serialization. |
|
A collection representation of the data. |
StringValue is a string representation of the data that can be used for display or serialization. Value and StringValue cache any set calls.
The cache for StringValue is flushed when Value is set. A common scenario is to support the dynamic update of the property being designed (as the user types), where the StringValue is data bound to the text entry. However, the underlying property is set only when the dynamic text meets certain criteria.
PropertyValueEditor Requirements
A correctly implemented property value editor must satisfy the following requirements.
The property value editor must be designed so that the inline editor and extended editor parts can be used independently.
A property value editor must not store state. Property value editors are stateless, might be cached by a host implementation, and can be re-used across multiple property values.
A property value editor must not assume that only one value editor part (view/inline/extended) control is active at a given time. For example, a dialog box could have the view part, inline part, and extended UI part active at the same time.
A control implemented as part of a property value editor must not store state. A control implemented as part of a value editor should not assume that it will only be bound to one property value. Controls may be recycled to change different property values. Any information that is cached should be flushed if the data model is updated.
A control implemented as part of a property value editor must not make any assumptions about the host or its parent controls. The only communication mechanisms that should be used are the PropertyValue data model, by way of the DataContext, and the standard set of commands.