PropertyGrid Class

Represents a control that allows users to inspect and edit the properties of an object.

Syntax

Visual Basic
C#

'Declaration
 
<TemplatePartAttribute(Name="PART_DragThumb", Type=System.Windows.Controls.Primitives.Thumb)>

<StyleTypedPropertyAttribute(Property="PropertyContainerStyle", StyleTargetType=Xceed.Wpf.Toolkit.PropertyGrid.PropertyItemBase)>

<XmlLangPropertyAttribute("Language")>

<UsableDuringInitializationAttribute(True)>

<RuntimeNamePropertyAttribute("Name")>

<UidPropertyAttribute("Uid")>

<TypeDescriptionProviderAttribute(MS.Internal.ComponentModel.DependencyObjectProvider)>

<NameScopePropertyAttribute("NameScope", System.Windows.NameScope)>

Public Class PropertyGrid 

   Inherits System.Windows.Controls.Control

'Usage
 
Dim instance As PropertyGrid

[TemplatePart(Name="PART_DragThumb", Type=System.Windows.Controls.Primitives.Thumb)]

[StyleTypedProperty(Property="PropertyContainerStyle", StyleTargetType=Xceed.Wpf.Toolkit.PropertyGrid.PropertyItemBase)]

[XmlLangProperty("Language")]

[UsableDuringInitialization(true)]

[RuntimeNameProperty("Name")]

[UidProperty("Uid")]

[TypeDescriptionProvider(MS.Internal.ComponentModel.DependencyObjectProvider)]

[NameScopeProperty("NameScope", System.Windows.NameScope)]

public class PropertyGrid : System.Windows.Controls.Control

Remarks

The PropertyGrid control allows you to autogenerate all properties by setting AutoGenerateProperties to true or to specify the specific properties you want to display by setting AutoGenerateProperties to false and then adding the properties you want to display to PropertyDefinitions.

You can use the standard editors that are provided with the PropertyGrid or you can use custom editors that target a Type, specific properties, or both. To use custom editors, add instances of EditorDefinition to EditorDefinitions.

The PropertyGrid also supports complex properties, which allows you to drill down into a nested property hierarchy.

You can supply editors for a property by using the System.ComponentModel.EditorAttribute. In order to provide an editor with an attribute, the editor MUST implement the ITypeEditor interface. Your editor can be a simple class or a complex UserControl. (See ITypeEditor for details and examples.)

PropertyGrid supports DefaultPropertyAttribute. When the SelectedObject changes, the property identified by this attribute will be the default selected property.

As of version 2.0, PropertyGrid supports the display of properties based on an IEnumerable source of items.

Based on the same pattern as the ItemsControl's ItemsSource and Items properties, you can provide an IEnumerable to PropertiesSource or directly add property items to the Properties property. Each item provided will be displayed as a distinct property. The PropertyNameBinding, PropertyValueBinding, and CategoryGroupDescription properties allow you to to control various aspects.

When preparing a PropertyItemBase instance to be displayed by the PropertyGrid, the PropertyGrid will try to create an editor for the PropertyItemBase instance unless the PropertyItemBase.Editor property is already initialized by the user (see PropertyGrid.PropertyContainerStyle property and PropertyGrid.PreparePropertyItem event).

If the Editor property is not initialized, the PropertyGrid.EditorDefinitions collection will be consulted to determine the corresponding editor to display.

The priority of the definition keys to be used in order to find the appropriate editor for the property item is as follows:

1. The value provided by the PropertyItemBase.DefinitionKey property.

2. The value of the binding result of PropertyGrid.PropertyNameBinding applied on the underlying item.

3. The value type (e.g., value.GetType()) of the binding result of PropertyGrid.PropertyValueBinding applied on the underlying item. (A lookup based on a Type instance will recursively perform the look-up using base classes to find any matching editor definition.)

4. If PropertyGrid.PropertyValueBinding is null, the type of the underlying item. (A lookup based on a Type instance will recursively perform the look-up using base classes to find any matching editor definition.)

When no specific EditorDefinitionBase is found in the PropertyGrid.EditorDefinitions collection, the PropertyGrid will try to automatically create an appropriate editor based on the type of the value. (See default editors.)

If no appropriate editor is found, the EditorDefintionBase found in the PropertyGrid.DefaultEditorDefinition will be used.

Finally, if no editor is created, a TextBlock will be used to display the value.

The following is a list of the default editors that are automatically instantiated based on the type of the targeted property (when using SelectedObject[s]) or the type of the Value of the property (when using Properties or PropertiesSource).

- bool: CheckBox
- DateTime: DateTimeUpDown
- Color: ColorPicker
- decimal: DecimalUpDown
- double: DoubleUpDown
- float: SingleUpDown
- byte: ByteUpDown
- sbyte: SByteUpDown*
- short: ShortUpDown
- ushort: UShortUpDown*
- int: IntegerUpDown
- uint: UIntegerUpDown*
- long: LongUpDown
- ulong: ULongUpDown*
- enum: ComboBox with fields in the enumeration
- FontFamily: ComboBox populated with the available font families
- FontWeight: ComboBox populated with the possible font weights
- FontStyle: ComboBox populated with the possible font styles
- FontStretch: ComboBox populated with the possible font stretches

For CLS compliance, these editor are not available on the public API.

When using SelectedObject[s] only:
- object: TextBox
- TimeSpan: DateTimeUpDown using a converter
- IList<T>:
a) When T is one of the primitive type or a string: PrimitiveTypeCollectionControl
b) When T is NOT a primitive type or a string : CollectionEditor

These are the available built-in EditorDefintionBase-derived classes that allow you to easily customize the display the editor of the properties.

- EditorTemplateDefinition

- EditorComboBoxDefinition

- EditorCheckBoxDefinition

- EditorColorPickerDefinition

- EditorTextDefinition

- EditorDateTimeUpDownDefinition

- EditorByteUpDownDefinition

- EditorDecimalUpDownDefinition

- EditorDoubleUpDownDefinition

- EditorIntegerUpDownDefinition

- EditorLongUpDownDefinition

- EditorShortUpDownDefinition

- EditorSingleUpDownDefinition

Each editor definition has its own custom properties that allow you to easily customize the display of the represented editor. With the exception of EditorTemplateDefinition, they all provide the EditingElementStyle that allows you to style and get a more in-depth customizing scenario.

Example

Using PropertiesSource

XAML

<xctk:PropertyGrid SelectedObjectName="Meeting"

				 PropertyNameBinding="{Binding Name}"

				 PropertyValueBinding="{Binding Department}" 

				 PropertiesSource="{Binding EmployeList}" />

Using Properties property.

XAML

<xctk:PropertyGrid SelectedObjectName="Meeting"

				 PropertyNameBinding="{Binding Name}"

				 PropertyValueBinding="{Binding Department}" >

      <xctk:PropertyGrid.Properties>

         <l:Employee Name="Tom" Department="Sales"/>

         <l:Employee Name="John" Department="Management"/>

         <l:Employee Name="Sean" Department="Sales"/>

      </xctk:PropertyGrid.Properties>

   </xctk:PropertyGrid>

Inheritance Hierarchy

System.Object
   System.Windows.Threading.DispatcherObject
      System.Windows.DependencyObject
         System.Windows.Media.Visual
            System.Windows.UIElement
               System.Windows.FrameworkElement
                  System.Windows.Controls.Control
                     Xceed.Wpf.Toolkit.PropertyGrid.PropertyGrid

Requirements

Reference

PropertyGrid Members
Xceed.Wpf.Toolkit.PropertyGrid Namespace