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.

propertygrid.jpg

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.

specifyingproperties.jpg

            <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.

customeditor_datatemplates.jpg

            <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.

customeditor_attributes.jpg

        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.

custom_itemssource.jpg

        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.

expandableobject.jpg

        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 more features in PropertyGrid and 50+ more awesome WPF controls in the Plus Edition.
---

Last edited May 9, 2013 at 8:51 PM by Kosmatos, version 38

Comments

BoucherS Aug 29 at 3:26 PM 
Hi mb2342, please have a look at https://wpftoolkit.codeplex.com/workitem/21218

BoucherS Aug 11 at 2:02 PM 
Hi mb2342,

I understand your reflexion on not having unsorted properties in the propertyGrid, but you should be respectful and not do any presumptions. We continue to develop the toolkit and add features to it, but we need to deal with was done by the original developper of the product and how the community uses to different properties of the currently deployed controls from the toolkit to limit the breaking changes.
You should be using the discussion tab or the issue tab to express your needs for any controls from the toolkit. We based our development on what the community really want. I don't think having an unsorted property mode in the propertyGrid would be a big thing, but you are one of the few (maybe the first) that need this and prefer not to use the PropertyOrder Attribute.
Issue https://wpftoolkit.codeplex.com/workitem/21218 has been created,

mb2342 Aug 8 at 11:31 PM 
An additional comment, cause i did not have the time to explain the expected behaviour in detail, in my previous post: If you have a look at the Windows.Forms PropertyGrid, you can see, how the user experience works, that i previously mentioned. They do it right. Play with the "PropertySort"-Property and see how a Model will be showed. They use the "Unsorted"-Principle that i previously mentioned. Hope it helps and pray for a better WPF property grid experience in future, cause the WPF is sooo wunderful but lacks sooo much of "Standards" every UI-Developer needs. Its a shame.

mb2342 Aug 8 at 10:51 PM 
Btw: I think beneath 80% out there sorting their properties in a model in the order they should appear. So, 80% have to do something special shit, just to get something what you can get if you order your properties right in the class.

mb2342 Aug 8 at 10:50 PM 
Why in the hell is the sorting so stupid ? If you want the order of the properties as they were declared in the class, you have to add and count manually a PropertySortAttribute. That means if your model resides somewhere else, you must deliver the extented wpf toolkit assembly just to NOT sort the properties. WTF ?

This is how it should be:

Declare a third sort order named "unsorted". Let it be the default. If there are no categories defined, sort the properties as they were declared (unsorted). If a category is defined, sort the properties unsorted under this category. When you select alphabetically they are sorted alphabetically. If a PropertyCustomSortAttribute exists, you can sort to that. Easy as that.

Really, i am a software developer since 12 years and there is absolutely nothing special here. If i recall correctly, some guys that develop on the E-WPF-TK are from MS. That depresses me. Its really easy to make the sorting of a property grid userfriendly and working as expected.

iBeta Mar 23 at 2:11 PM 
The Workflow PropertyInspector does not work with multiple objects, if the objects are user defined.
Makes it pretty useless except for single object inspection.
It is in the PLUS edition of the xceedingly greedy toolkit - but I'm not paying for something which should be implemented anyway.

jtu100 Jan 31 at 4:19 PM 
It's a shame you can't inspect complex type properties without having to modify them with ExpandableObject. Or is there a way? Seems like a very common use-case.

JonDemers Jan 10 at 8:57 PM 
It looks like I can do what I would like using System.Reflection.Emit TypeBuilder, and PropertyBuilder. But if there is a better way, I'd not mind knowing it.

JonDemers Jan 10 at 5:47 PM 
I'm fairly new to C# WPF, and am not sure if the property grid is usable for this, there are aspects to C# that I'm still learning to wrap my head around.
I have a list of dataclass where the data class has the following properties, Parent, Name, Value, ValueType. What I'd like to do is somehow convert things so that the property grid displays the data in the manner where Parent is Category, Name is the property name, and Value is the property value with the editor determined by the ValueType.
Basically, I have an xml file that contains config information blocks, and I need to display each block on its own. There are several different types of blocks, and their contents are somewhat fluid, so a specific class for each block really doesn't work well.
I'm hoping that there is a way to override the automatic property generation on the lists, but if I have to populate and depopulate manually I can also do that.
General Class structure is roughly:
public class ConfigBlock
{
public List<DataUnit> Data { get; set; } // This is the data that needs to be converted for display.
}

public class DataUnit
{
public string Parent { get;set; }
public string Name {get;set;}
public string Value {get;set}
public DataTypes ValueType {get;set}
}

public enum DataTypes
{
StringData,
IntData,
FloatData,
List1, // Value limited to items in a seperate list of strings. (drop-down menu)
List2, // Value limited to items in seperate list of strings (drop-down menu)
List3 // Value limited to items in seperate list of strings (drop-down menu)
}

Is there a way to do this? If you can point me in the right direction I'd be thankful. I've been trying to search for examples but am getting a bit confused and have gone down several wrong paths.

phillipderemer Dec 17, 2013 at 12:09 PM 
Hi I actualy have to complayne about some thing. I am making a kind of Form Designer so I developed a class implementing the System.ComponentModel.ICustomTypeDescriptor overloading the GetProperties Function but it isn't been called maybe you propertygrid goes to deep. I actualy used a windows form host to check if i am making a mistake on this one but the windows.forms.propertygrid shows the editable propertys here is some code to look at:

Public Class cPropertyView
Implements System.ComponentModel.ICustomTypeDescriptor

Private _PropertyDictionary As Object
Public Property PropertyDictionary() As Object
Get
Return _PropertyDictionary
End Get
Set(ByVal value As Object)
_PropertyDictionary = value
End Set
End Property

....

Public Function GetProperties(attributes() As Attribute) As ComponentModel.PropertyDescriptorCollection Implements ComponentModel.ICustomTypeDescriptor.GetProperties
Dim NewPropertyList As New System.ComponentModel.PropertyDescriptorCollection({})

Dim NewProp As New SelfProperty("NewProp", attributes)
NewProp.PropType = GetType(Integer)
NewProp.Value = 12
NewProp.DisName = "Number"
NewProp.Discript = "a Number of Type Integer."

NewPropertyList.Add(NewProp)

Return NewPropertyList
End Function
End Class

Public Class SelfProperty
Inherits System.ComponentModel.PropertyDescriptor

....

slartus Nov 7, 2013 at 5:03 AM 
Can I dynamically control the visibility of the properties?

like:

public Boolean NeedLogin {get; set;}

[DynamicPropertyFilter ("NeedLogin", "True")]
public String LoginPage {get; set;}

BoucherS Jul 29, 2013 at 6:53 PM 
Yes ICustomTypeDescriptor works, as long as properties that have a TypeDescriptor attribute.

mbuchwald Jul 16, 2013 at 3:50 PM 
Will this work with an object that is an ICustomTypeDescriptor and with properties that have a TypeDescriptor attribute?

SeeWold Jul 1, 2013 at 4:10 PM 
Does editor supports modal dialog form? if yes ,how?

Please reply.

Thanks & Regards,
SeeWold.

jmahaffe May 28, 2013 at 11:55 PM 
Is it possible to have do a "ShowAdvanced" flag on a per item basis? I can only see how to turn it on for all properties

AlexShulg May 16, 2013 at 3:59 AM 
hi ashwin893,
for custom sort properties use PropertyOrderAttribute:
[Xceed.Wpf.Toolkit.PropertyGrid.Attributes.PropertyOrder(10)]
[System.ComponentModel.DisplayName("My name")]
public string Name { get; set; }

ashwin893 May 15, 2013 at 8:22 AM 
<no name> tag appears on the Property Grid when Selected Index is -1.
Please help me how to remove the tag ?

ashwin893 May 15, 2013 at 8:21 AM 
I need some custom Sort of the properties which are shown in the Property Grid. Please help me out if there is any possibility.

ernest_le_vampire Dec 30, 2012 at 9:06 PM 
I think my question is the same as hamed63's.
Is it possible to have support for checked list box control?

bvisual Dec 5, 2012 at 9:36 PM 
I am having trouble getting the Browsable attribute to have any effect at all using 1.8.0 from NuGet, using .Net 4. Is it just me? I have tried in several projects ... the property remains visible, regardless of True or False.

emartin Aug 29, 2012 at 1:38 PM 
SoonDead and Hamed63: the following issue has been created to address your needs: http://wpftoolkit.codeplex.com/workitem/18554

I encourage any bug or feature request to be logged in the Issue Tracker instead.

SoonDead Aug 29, 2012 at 6:13 AM 
This would be everything I have ever wanted if it supported editing multiple objects at the same time!

I'm already thinking about writing a proxy that makes an object from the multiple items that are selected and feed it to this panel.

diptesh_raut Jul 24, 2012 at 11:08 AM 
This looks a great control for WPF based controls. I have some queries:
1. Does this property grid supports custom class containing different control objects?
For example, i have a class which contains one grid control object.
2. If yes, does it display all the properties and expandable properties of the grid control?
3. Also, i have observed that this property grid shows less number of properties as compared to in windows form property grid. Any way to get all the properties in the controls?
4. When collection editor will be available? How much generic it will be? Will i get an event on setting collection editor(this functionality is not available in win forms property grid control)?

Please reply.

Thanks & Regards,
Diptesh.

j2associates Jun 13, 2012 at 10:38 PM 
We needed minimum and maximum values for custom editors. Here is the xaml to use custom editors for integer fields and decimal fields:

<xctk:PropertyGrid Grid.Column="2" SelectedObject="{Binding}">

<!-- Editors -->
<xctk:PropertyGrid.EditorDefinitions>

<!-- Minimum 1, Maximum 50, DefaultValue = 1, Used for Rows and Columns -->
<xctk:EditorDefinition>
<xctk:EditorDefinition.PropertiesDefinitions>
<xctk:PropertyDefinition Name="Rows" />
<xctk:PropertyDefinition Name="Columns" />
</xctk:EditorDefinition.PropertiesDefinitions>
<xctk:EditorDefinition.EditorTemplate>
<DataTemplate>
<xctk:IntegerUpDown Value="{Binding Value}" Minimum="1" Maximum="50" DefaultValue="1" />
</DataTemplate>
</xctk:EditorDefinition.EditorTemplate>
</xctk:EditorDefinition>

<!-- Minimum 0, Maximum 1, DefaultValue 0.125, Increment 0.03125, Used for Gutters and Gaps -->
<xctk:EditorDefinition>
<xctk:EditorDefinition.PropertiesDefinitions>
<xctk:PropertyDefinition Name="TopMargin" />
<xctk:PropertyDefinition Name="LeftMargin" />
<xctk:PropertyDefinition Name="VerticalGutter" />
<xctk:PropertyDefinition Name="HorizontalGutter" />
</xctk:EditorDefinition.PropertiesDefinitions>
<xctk:EditorDefinition.EditorTemplate>
<DataTemplate>
<xctk:DecimalUpDown Text="{Binding Value}" Minimum="0" Maximum="1" DefaultValue="0.125" Increment="0.03125" />
</DataTemplate>
</xctk:EditorDefinition.EditorTemplate>
</xctk:EditorDefinition>

</xctk:PropertyGrid.EditorDefinitions>
</xctk:PropertyGrid>

tjc Jun 6, 2012 at 2:48 PM 
needs a BrushEditor

j2associates May 16, 2012 at 5:23 PM 
To prevent a property from being displayed in the property grid, decorate it with System.ComponentModel.BrowsableAttribute set to false
[Browsable(false)]
public int YourProperty { get; set; }

rajkishor09 May 9, 2012 at 1:32 PM 
Do we have display order of properties in property grid. By default it shows property in alphabetical order but I need to show property in customer manner like firstname, lastname, address, city and so on. any help on this?

Hamed63 Apr 23, 2012 at 6:14 AM 
Can you please support multiselection
a prperty like 'SelectedObjects'