PropertyGrid

The PropertyGrid control allows you inspect and edit properties of an object. This PropertyGrid allows you to autogenerate all properties or specify the specific properties you want to display. 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. The PropertyGrid also supports complex properties, which allows you to drill down into a nested property hierarchy.

• Specifying Properties
• Custom Editors
  • DataTemplates
  • Attributes
• Custom ItemsSource
• Expandable Properties

Specifying Properties

By default the propertyGrid will autogenerate all the properties for a given object. You can override this behavior by setting the AutoGenerateProperties property to False, and then provide a collection of PropertyDefinitions of the properties you would like to show.

<xctk:PropertyGrid x:Name="_propertyGrid" Width="450" Margin="10"
                                     AutoGenerateProperties="False">
                <!-- Only the following properties will be displayed in the PropertyGrid -->
                <xctk:PropertyGrid.PropertyDefinitions>
                    <xctk:PropertyDefinition Name="FirstName" />
                    <xctk:PropertyDefinition Name="FavoriteColor" />
                    <xctk:PropertyDefinition Name="PetNames" />
                </xctk:PropertyGrid.PropertyDefinitions>
            </xctk:PropertyGrid>

Custom Editors

By default the PropertyGrid comes with 14 built-in editors:

• CheckBoxEditor
• CollectionEditor
• ColorEditor
• DateTimeUpDownEditor
• DecimalUpDownEditor
• DoubleUpDownEditor
• EnumComboBoxEditor
• FontComboBoxEditor
• IntegerUpDownEditor
• ItemsSourceEditor
• PrimitiveTypeCollectionEditor
• TextBlockEditor
• TextBoxEditor
• TimeSpanEditor

Custom Editors with DataTemplates

You can override the default editors with your own custom editors with a DataTemplate. Simply define an EditorDefinition that either targets a Type, property name, or both and set the EditorDefinition.EditorTemplate to an instance of a DataTemplate. Be sure to bind your custom editor to the bound property item's Value property.

<xctk:PropertyGrid x:Name="_propertyGrid1" Width="450"  Margin="10">
                <xctk:PropertyGrid.EditorDefinitions>
                    
                    <!-- This EditorDefinition will provide a TextBox to any property that is of type HorizontalAlignment, replacing the default ComboBox editor. -->
                    <xctk:EditorDefinition TargetType="{x:Type HorizontalAlignment}">
                        <xctk:EditorDefinition.EditorTemplate>
                            <DataTemplate>
                                <TextBox Background="Green"  Text="{Binding Value}" /> <!-- Always bind your editor's value to the bound property's Value -->
                            </DataTemplate>
                        </xctk:EditorDefinition.EditorTemplate>
                    </xctk:EditorDefinition>
                    
                    <!-- This EditorDefinition will provide a TextBlock to any property that has any of the defined property names, replacing the default editor. -->
                    <xctk:EditorDefinition>
                        <xctk:EditorDefinition.PropertiesDefinitions>
                            <xctk:PropertyDefinition Name="Age" />
                            <xctk:PropertyDefinition Name="WritingFont" />
                            <xctk:PropertyDefinition Name="Spouse" />
                        </xctk:EditorDefinition.PropertiesDefinitions>
                        <xctk:EditorDefinition.EditorTemplate>
                            <DataTemplate>
                                <TextBlock Background="Yellow"  Text="{Binding Value}" />
                            </DataTemplate>
                        </xctk:EditorDefinition.EditorTemplate>
                    </xctk:EditorDefinition>
                    
                    <!-- This EditorDefinition will provide a TextBox to any property that is of type Boolean or that has any of the defined property names, replacing the default editor. -->
                    <xctk:EditorDefinition TargetType="{x:Type sys:Boolean}">
                        <xctk:EditorDefinition.PropertiesDefinitions>
                            <xctk:PropertyDefinition Name="DateOfBirth" />
                            <xctk:PropertyDefinition Name="LastName" />
                        </xctk:EditorDefinition.PropertiesDefinitions>
                        <xctk:EditorDefinition.EditorTemplate>
                            <DataTemplate>
                                <TextBox Background="Red"  Text="{Binding Value}" />
                            </DataTemplate>
                        </xctk:EditorDefinition.EditorTemplate>
                    </xctk:EditorDefinition>
                    
                </xctk:PropertyGrid.EditorDefinitions>
            </xctk:PropertyGrid>

Custom Editors with Attributes

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.

        public class CustomAttributEditorPerson
        {
            [Category("Information")]
            [DisplayName("First Name")]
            [Description("This property uses a TextBox as the default editor.")]
            //This custom editor is a Class that implements the ITypeEditor interface
            [Editor(typeof(FirstNameEditor), typeof(FirstNameEditor))]
            public string FirstName { get; set; }

            [Category("Information")]
            [DisplayName("Last Name")]
            [Description("This property uses a TextBox as the default editor.")]
            //This custom editor is a UserControl that implements the ITypeEditor interface
            [Editor(typeof(LastNameUserControlEditor), typeof(LastNameUserControlEditor))]
            public string LastName { get; set; }
        }

Using a custom class:

    //Custom editors that are used as attributes MUST implement the ITypeEditor interface.
    public class FirstNameEditor : Xceed.Wpf.Toolkit.PropertyGrid.Editors.ITypeEditor
    {
        public FrameworkElement ResolveEditor(Xceed.Wpf.Toolkit.PropertyGrid.PropertyItem propertyItem)
        {
            TextBox textBox = new TextBox();
            textBox.Background = new SolidColorBrush(Colors.Red);

            //create the binding from the bound property item to the editor
            var _binding = new Binding("Value"); //bind to the Value property of the PropertyItem
            _binding.Source = propertyItem;
            _binding.ValidatesOnExceptions = true;
            _binding.ValidatesOnDataErrors = true;
            _binding.Mode = propertyItem.IsReadOnly ? BindingMode.OneWay : BindingMode.TwoWay;
            BindingOperations.SetBinding(textBox, TextBox.TextProperty, _binding);
            return textBox;
        }
    }

Using a UserControl:

<UserControl x:Class="Samples.Modules.PropertyGrid.LastNameUserControlEditor"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Name="_uc">
        <StackPanel>
            <TextBox Text="{Binding Value, ElementName=_uc}" Background="YellowGreen"  />
            <Button Click="Button_Click">Clear</Button>
        </StackPanel>
</UserControl>

    public partial class LastNameUserControlEditor : UserControl, ITypeEditor
    {
        public LastNameUserControlEditor()
        {
            InitializeComponent();
        }

        public static readonly DependencyProperty ValueProperty = DependencyProperty.Register("Value", typeof(string), typeof(LastNameUserControlEditor), 
                                                                                                new FrameworkPropertyMetadata(null, FrameworkPropertyMetadataOptions.BindsTwoWayByDefault));
        public string Value
        {
            get { return (string)GetValue(ValueProperty); }
            set { SetValue(ValueProperty, value); }
        }        

        private void Button_Click(object sender, RoutedEventArgs e)
        {
            Value = string.Empty;
        }

        public FrameworkElement ResolveEditor(Xceed.Wpf.Toolkit.PropertyGrid.PropertyItem propertyItem)
        {
            Binding binding = new Binding("Value");
            binding.Source = propertyItem;
            binding.Mode = propertyItem.IsReadOnly ? BindingMode.OneWay : BindingMode.TwoWay;
            BindingOperations.SetBinding(this, LastNameUserControlEditor.ValueProperty, binding);
            return this;
        }
    }

Custom ItemsSource

Sometimes it is desirable to want to provide a collection of values represented by a ComboBox for a given property. The PropertyGrid supports this scenario by creating a class that implements the IItemsSource interface and decorating your property with the ItemsSourceAttribute.

        public class Person
        {
            [Category("Writing")]
            [DisplayName("Writing Font Size")]
            [Description("This property uses the DoubleUpDown as the default editor.")]
            [ItemsSource(typeof(FontSizeItemsSource))]
            public double WritingFontSize { get; set; }
        }

The custom ItemsSource class:

    public class FontSizeItemsSource : IItemsSource
    {
        public ItemCollection GetValues()
        {
            ItemCollection sizes = new ItemCollection();
            sizes.Add(5.0, "Five");
            sizes.Add(5.5);
            sizes.Add(6.0, "Six");
            sizes.Add(6.5);
            sizes.Add(7.0, "Seven");
            sizes.Add(7.5);
            sizes.Add(8.0, "Eight");
            sizes.Add(8.5);
            sizes.Add(9.0, "Nine");
            sizes.Add(9.5);
            sizes.Add(10.0);
            sizes.Add(12.0, "Twelve");
            sizes.Add(14.0);
            sizes.Add(16.0);
            sizes.Add(18.0);
            sizes.Add(20.0);
            return sizes;
        }
    }

Expandable Properties

Sometimes it is neccessary to show the properties of a complex object. The PropertyGrid supports this scenario and allows you to drill down into a property's heirarchy. To enable this behavior you must decorate your property with the ExpandableObject attribute.

        public class Person
        {
            [Category("Information")]
            [DisplayName("First Name")]
            [Description("This property uses a TextBox as the default editor.")]
            public string FirstName { get; set; }

            [Category("Conections")]
            [Description("This property is a complex property and has no default editor.")]
            [ExpandableObject]
            public Person Spouse { get; set; }
        }

Properties / Events

Property	Description
AdvancedOptionsMenu	Gets/Sets the contextual menu to use when the advanced menu button is clicked.
AutoGenerateProperties	Get/Sets if the propertyGrid should generate all properties for a given object. If False you must provide PropertyDefinitions for the properties you want to generate.
EditorDefinitions	Get/Sets a collection of custom editors to use in place of the default editors. (Breaking change as of v1.6.0: previously was CustomTypeEditors.)
Filter	Gets/Sets the filter used to filter the visible properties in the PropertyGrid.
FilterWatermark	Gets/Sets the watermark used in the filter field.
IsCategorized	Gets/Sets the layout of the PropertyGrid.
IsReadOnly	Gets or sets a value indicating whether the property grid is read-only.
NameColumnWidth	Gets/Sets the width of the property name column.
Properties	Gets the current collection of generated PropertyItems.
PropertyDefinitions	When AutoGenerateProperties = False, gets/sets the properties that will be generated by the PropertyGrid
SelectedObject	Gets/Sets the current object the PropertyGrid is inspecting,
SelectedObjectName	Gets/Sets the SelectedObject name.
SelectedObjectType	Gets/Sets the Type of the SelectedObject.
SelectedObjectTypeName	Gets/Sets the name of the Type of the SelectedObject.
SelectedPropertyItem	Gets the currently selected PropertyItem
ShowAdvancedOptions	Gets/Sets the visibility of the advanced options button next to the properties.
ShowSearchBox	Gets/Sets a value indicating whether the search box is displayed. By default, true.
ShowSortOptions	Gets/Sets a value indicating whether the show sort options are displayed (Categorized and Alphabetical). By default, true.
ShowSummary	Gets or sets a value indicating whether the summary pane is shown.
ShowTitle	Gets or sets a value indicating whether the PropertyGrid's title is displayed.

Event	Description
PropertyValueChanged	Raised when a property's value changes.
SelectedObjectChanged	Raised when SelectedObject changes.
SelectedPropertyItemChanged	Raised when SelectedProperty changes.

Get 50+ awesome WPF controls in the Plus Edition.
---