Click here to Skip to main content
11,935,066 members (51,233 online)
Click here to Skip to main content
Add your own
alternative version


419 bookmarked

Add Custom Properties to a PropertyGrid

, 22 Aug 2006 Apache
Rate this:
Please Sign up or sign in to vote.
Extend a PropertyGrid with an Item collection; easy customization of properties with custom editor, custom converter and databinding.

Sample project

Sample project


For my last project, I looked at the PropertyGrid control that has a very nice look and feel. Immediately, I noticed how difficult it was to use it. Looking over the Internet, I found lots of people wishing for something easier to use, like the TreeView or the ListView. So I started developing an extended version of the PropertyGrid that includes an Item collection.

Using the Code

The control is made of three basic classes:

  • Class CustomProperty, that represents a single property.
  • Class CustomPropertyDescriptor, that is used internally by the PropertyGrid to retrieve property attributes.
  • Class CustomPropertyCollection, that represents a collection of CustomPropertys.

In the end, we have the control PropertyGridEx that inherits from PropertyGrid and exposes an Item collection. To use the component, add it to the Toolbox and then to your form. Compared to the classic PropertyGrid, we have a new property to set, called ShowCustomProperties.


The property must be set to True, or the component will have the same behavior as the classic PropertyGrid.

The Item Collection

We are now ready to fill our custom properties.

With Properties
    .Item.Add("My String", "My Value", False, _
              "Simple type", "This is a string", True)
    .Item.Add("My Integer", 100, False, "Simple type", _
              "This is an integer", True)
    .Item.Add("My Double", 10.4, False, "Simple type", _
              "This is a double", True)
    .Item.Add("My Font", New Font("Arial", 9), False, _
              "Classes", "This is a font class", True)
    .Item.Add("My Color", New Color(), False, _
              "Classes", "This is a color class", True)
    .Item.Add("My Point", New Point(10, 10), False, _
              "Classes", "This is point class", True)
End With

The CustomProperty class exposes several properties that you can use to personalize your PropertyGrid:

  • Name, a string representing the property name;
  • Value, an object representing the value of the property;
  • IsReadOnly, a boolean that indicates if the property is editable or not;
  • Category, a string that represents the category in which the property is shown;
  • Description, a string that represents the description of the property, shown at the bottom of the component;
  • Visible, a boolean that indicates if the property is shown or not;

Finally, remember to Refresh the PropertyGrid after any modification to the collection.

Common Properties

The Filename Editor

It is also possible to create a CustomProperty that shows a dialog to modify a filename. The trick is achieved by the class UIFilenameEditor that inherits from System.Drawing.Design.UITypeEditor. You can create a property, with the well known FileDialog as a Type Editor, in the following way:

With Properties   
    .Item.Add("Filename", "", False, "Misc", "", True)
    .Item(.Item.Count - 1).UseFileNameEditor = True
    .Item(.Item.Count - 1).FileNameDialogType _
                         = FileDialogType.LoadFileDialog
    .Item(.Item.Count - 1).FileNameFilter = _
         "Text files (*.txt)|*.txt|All files (*.*)|*.*"
End With

Following is the resulting PropertyGrid. Please notice the Ellipsis symbol beside the value of the property, to access the UIFilenameEditor.

Filename Editor

Custom Choices Type Converter

It's a very commonly requested feature to have a list of values from which the user can choose, while editing a property. To implement a dropdown list, do the following:

Dim Languages As String() = New String() {"English", _
                                          "Italian", _
                                          "Spanish", _
With Properties   
    .Item.Add("Language", "", False, "Misc", "")
    .Item(.Item.Count - 1).Choices _
                         = New CustomChoices(Languages, True)
End With

You can use arrays of String, Integer, Double and Object to initialize the Choices property. Following is the resulting PropertyGrid initialized with an array of Strings.

Custom Choices TypeConverter


Most of the times, developers have enumerations declared in their code. The component automatically shows a dropdown list with the values from the Enum.

Public Enum MyEnum
End Enum

With Properties 
    .Item.Add("Enum", MyEnum.FirstEntry, False, "Misc")
End With

Following is the resulting PropertyGrid.

Enum Property

Expandable Object Converter

Using this TypeConverter, it is possible to expand nested properties. Here is an example that shows the application settings.

With Properties 
    .Item.Add("My settings", My.MySettings.Default, False, "Misc")
    .Item(.Item.Count - 1).IsBrowsable = True
    .Item(.Item.Count - 1).BrowsableLabelStyle = _
End With

Following is the resulting PropertyGrid.

Expandable Property

Password fields

Using masked fields, it is possible to hide the value of a property. The result is produced by the attribute PasswordPropertyTextAttribute, new to the .NET Framework v2.0. Here is an example on how to use it.

With Properties 
    .Item.Add("My Password", "password", False)
    .Item(.Item.Count - 1).IsPassword = True
End With

Following is the resulting PropertyGrid.

Password Property

Dynamic property binding

Using PropertyGridEx, it is possible to bind object properties to the component. This is done by a method of the collection that accepts a value argument by reference. In this way, it is possible to freely mix reference type and value type properties. The following example binds the AutosizeProperties and the DrawFlatToolbar property of the grid.

Any modification to the value of these properties is automatically reflected into the object they belong to.
With Properties 
    .Item.Add("Autosize properties", Properties, "AutoSizeProperties", False, _
              "Dynamic Properties", "This is a dynamic bound property", True)
    .Item.Add("Draw flat toolbar", Properties, "DrawFlatToolbar", False, _
              "Dynamic Properties", "This is a dynamic bound property", True)
End With

Following is the resulting PropertyGrid.

Dynamic Properties

Multiple object properties

One more feature provided with this control is the ability of editing multiple object properties at the same time. This is done by a collection of objects attached to the SelectedObjects property of the base component. The behavior is that the grid only displays the properties that are common to all the objects that are in the array. To activate the multiple objects functionality, the property of the grid ShowCustomPropertiesSet must be set to True.

With Properties
    .ShowCustomPropertiesSet = True

    .ItemSet(0).Add("My Point", New Point(10, 10), False, "Appearance")
    .ItemSet(0).Add("My Date", New Date(2006, 1, 1), False, "Appearance")

    .ItemSet(1).Add("My Point", New Point(10, 10), False, "Appearance")
    .ItemSet(1).Add("My Date", New Date(2007, 1, 1), False, "Appearance")
    .ItemSet(1).Add("My Color", New Color(), False, "Appearance")

End With

Following is the resulting PropertyGrid.

Multi object Properties

Databinding of a Property to a Datasource

The databinding of a single property to a data-source is the latest addition to this component. The wrapper created accepts for a CustomProperty, three members:

  • Datasource, the datasource to bind to.
  • DisplayMember (optional), the field used to bind the list shown in the dropdown control.
  • ValueMember (optional), the field used to bind the value returned by the CustomProperty.
The CustomProperty will return the following values:
  • Value, that represents the value shown as System.String.
  • SelectedItem, that represents the object selected as System.Object.
  • SelectedValue, that represents the value selected as System.Object.
The following example creates three properties that bind a DataTable, an array of Objects, and an array of Strings.
With Properties
    .Item.Add("Datatable", "", False, "Databinding", _
              "This is a UITypeEditor that implement a listbox", True)

    .Item(.Item.Count - 1).ValueMember = "book_Id"
    .Item(.Item.Count - 1).DisplayMember = "title"      
    .Item(.Item.Count - 1).Datasource = LookupTable

    .Item.Add("Array of objects", ListValues(2).Text, False, "Databinding", _
              "This is a UITypeEditor that implement a listbox", True)

    .Item(.Item.Count - 1).ValueMember = "Value"
    .Item(.Item.Count - 1).DisplayMember = "Text"
    .Item(.Item.Count - 1).Datasource = ListValues   

    .Item.Add("Array of strings", Languages(1), False, "Databinding", _
              "This is a UITypeEditor that implement a listbox", True)

    .Item(.Item.Count - 1).Datasource = Languages    
End With

Please notice that the result is very different from the one achieved by using the "Custom Choices" functionality, that uses a TypeConverter. The databinding feature uses a UITypeConverter that implements a ListBox control.

Following is the resulting PropertyGrid.

Properties Databinding

Custom Event Editor

Using PropertyGridEx, it is possible to bind the 3-dots button used in Modal editors with a custom event handler. This is done by a method of the CustomProperty that accepts a Delegate as argument. The following is an example:

With Properties 
    .Item.Add("My Custom Event", "(Click me)", False, "Misc", _
              "The component accept custom event handler.", True) 
    .Item(.Item.Count - 1).OnClick = AddressOf Me.CustomEventItem_OnClick     
End With

The event will be handled by this function:

Private Function CustomEventItem_OnClick(ByVal sender As Object, _
                                         ByVal e As EventArgs) As Object 
    MsgBox("You clicked on property '" & sender.CustomProperty.Name & "'", _
           MsgBoxStyle.Information, _
           "Custom Events as UITypeEditor") 
    Return "(Click me again)" 
End Function 

Please notice that the result value of the function will be the new value of the property. Following is the resulting PropertyGrid.

Add some style to the control

Looking on Internet and on CodeProject, I found a lot of articles regarding this component. Unfortunately, I had to merge everything together to have an easier PropertyGrid to use. In this section, you'll find small features I've found and added in this project.

  • AutoSizeProperties - Move automatically the splitter to better fit all the properties shown.
  • MoveSplitterTo - Move the splitter as indicated by the user in the parameter.
  • DocComment - Expose the comments area as a control.
  • DrawFlatToolbar - Draw a flat toolbar or a VS like toolbar.

Please notice that the last property switches the drawing of the toolbar within a Professional Renderer with custom colors and a System Renderer.

Final Notes

I hope that you find this article useful. If you found this article stupid, annoying, incorrect, etc., express this fact by rating the article as you see fit.


Thanks to Pascal Higelin for providing the Property Binding feature and the C# version.
Thanks to Suresh Kavan, for the idea and the test case for the data-binding feature.



  • 22nd August 2006
    • Added XML Editor sample.
  • 31st May 2006
    • Added custom event editor.
    • Added DocComment interface.
  • 5th May 2006
    • Added serialization.
    • Added property databinding.
    • Article updated.
  • 28th April 2006
    • Added C# version.
    • Added dynamic property binding.
    • Added multiple objects feature.
  • 10th April 2006
    • Added password property and improved ToolStrip look.
    • Added expandable object converter.
    • Added custom choices type converter.
    • Added file name editor.
  • 31st March 2006 – First submission.


This article, along with any associated source code and files, is licensed under The Apache License, Version 2.0


About the Author

Danilo Corallo
Software Developer (Senior)
Italy Italy
I am 35 years old and I've been working with C++, Visual Basic .NET, C# and ASP.NET. I have a large experience in Industrial Automation solutions, but I've worked also as Web developer and DBA. I like to share knowledge and projects with other people.

You may also be interested in...

Comments and Discussions

GeneralChild Nodes Pin
malcomm14-Dec-10 17:23
membermalcomm14-Dec-10 17:23 
GeneralIssues with saving color properties Pin
malcomm13-Dec-10 16:14
membermalcomm13-Dec-10 16:14 
QuestionOrdering categories in non-alphabetical order? Pin
Brazilian.Engineer6-Oct-10 7:45
memberBrazilian.Engineer6-Oct-10 7:45 
QuestionAbility to control sort order of Categories in PropertyGridEx ??? Pin
Brazilian.Engineer1-Oct-10 16:30
memberBrazilian.Engineer1-Oct-10 16:30 
QuestionEnable Enter or Tab Key to move to the next item? Pin
BrianGoodheim26-Sep-10 11:49
memberBrianGoodheim26-Sep-10 11:49 
Questionis it possible to disable auto-sort? Pin
mryux20051-Sep-10 22:16
membermryux20051-Sep-10 22:16 
AnswerRe: is it possible to disable auto-sort? Pin
dusan.fedorcak7-Sep-10 4:53
memberdusan.fedorcak7-Sep-10 4:53 
Generalmulti selection drop down box Pin
Member 228177124-Aug-10 11:53
memberMember 228177124-Aug-10 11:53 
GeneralQuestion about nesting. Pin
Troy Lundin12-Apr-10 11:52
memberTroy Lundin12-Apr-10 11:52 
GeneralNeither example nor base control will build in VS 2005 Pin
sysop@HAL9K.com15-Mar-10 9:32
membersysop@HAL9K.com15-Mar-10 9:32 
GeneralNice Work Pin
Xavius19-Feb-10 5:19
memberXavius19-Feb-10 5:19 
QuestionDrag-drop text onto PropertyGridEx Pin
BrianGoodheim5-Jan-10 5:41
memberBrianGoodheim5-Jan-10 5:41 
QuestionTradeoff between PropertyGridEx1 setup overhead and memory overhead: Best practice design? Pin
BrianGoodheim11-Nov-09 7:37
memberBrianGoodheim11-Nov-09 7:37 
GeneralGettingProperties Pin
yura19894-Nov-09 3:31
memberyura19894-Nov-09 3:31 
QuestionHow do you serialize color? Pin
TV Mogul11-Oct-09 14:39
memberTV Mogul11-Oct-09 14:39 
GeneralTag value from dropdown GridIdem Pin
gnunez9728-Sep-09 11:04
membergnunez9728-Sep-09 11:04 
GeneralValidations Pin
Deepak Sakpal18-Aug-09 19:21
memberDeepak Sakpal18-Aug-09 19:21 
Questionthe question about value's updata Pin
oneriang11-Aug-09 23:01
memberoneriang11-Aug-09 23:01 
QuestionAfter adding categories and descriptions for selectedObject, propertyGridEx won't databind? Pin
BrianGoodheim2-Jul-09 8:02
memberBrianGoodheim2-Jul-09 8:02 
AnswerRe: After adding categories and descriptions for selectedObject, propertyGridEx won't databind? Pin
BrianGoodheim2-Jul-09 15:48
memberBrianGoodheim2-Jul-09 15:48 
GeneralGetting value of dropdown when valuemember is defined. Pin
Elfman_NE18-Jun-09 5:01
memberElfman_NE18-Jun-09 5:01 
GeneralProperty value is not valid message Pin
swapnil10121-May-09 5:07
memberswapnil10121-May-09 5:07 
GeneralDatabinding to rows not columns Pin
Cherene12-Mar-09 10:16
memberCherene12-Mar-09 10:16 
GeneralRe: Databinding to rows not columns Pin
EnlightenedGoat13-Mar-09 6:01
memberEnlightenedGoat13-Mar-09 6:01 
QuestionIs there an Event that fires when a CustomProperty in a CustomProperyCollection changes? Pin
EnlightenedGoat10-Mar-09 7:11
memberEnlightenedGoat10-Mar-09 7:11 
Questionwhy it runs so slowly when enable unmanaged code debugging?? Pin
zhaochunyan2-Feb-09 22:12
memberzhaochunyan2-Feb-09 22:12 
QuestionShow Scrollbar in Customproperty.Description Pin
leplay25-Jan-09 21:29
memberleplay25-Jan-09 21:29 
GeneralDisplay SubClasses Pin 0:07 0:07 
QuestionAdd sub property???? Pin
ron19778-Jan-09 1:53
memberron19778-Jan-09 1:53 
QuestionPropertyGridEx: Why are some objects not being updated? Pin
BrianGoodheim28-Dec-08 15:15
memberBrianGoodheim28-Dec-08 15:15 
AnswerRe: PropertyGridEx: Why are some objects not being updated? Pin
Danilo Corallo29-Dec-08 8:30
memberDanilo Corallo29-Dec-08 8:30 
GeneralRe: PropertyGridEx: Why are some objects not being updated? Pin
BrianGoodheim30-Dec-08 11:06
memberBrianGoodheim30-Dec-08 11:06 
GeneralWhen component is being loaded, "System.NotSupportedException" exists Pin
Member 84677310-Nov-08 18:48
memberMember 84677310-Nov-08 18:48 
GeneralEvent on the PropertyValueChanged for a collection Pin
LaNono28-Oct-08 1:00
memberLaNono28-Oct-08 1:00 
GeneralListbox value to change based on selection of values in another listbox Pin
smudre17-Sep-08 22:05
membersmudre17-Sep-08 22:05 
QuestionSorting Sub Properties Pin
tfierens30-Aug-08 21:36
membertfierens30-Aug-08 21:36 
AnswerRe: Sorting Sub Properties Pin
tfierens31-Aug-08 4:36
membertfierens31-Aug-08 4:36 
GeneralDisplay name / property name Pin
Stonkie13-Jun-08 13:46
memberStonkie13-Jun-08 13:46 
GeneralRe: Display name / property name Pin
Stonkie13-Jun-08 13:54
memberStonkie13-Jun-08 13:54 
GeneralProperty Grid ..Grid Item Pin
topksharma198219-May-08 0:44
membertopksharma198219-May-08 0:44 
GeneralVB.NET version : Pin
Michael Sync14-May-08 7:57
memberMichael Sync14-May-08 7:57 
QuestionUsing PropertyGrid Ex to add a Trackbar- is it possible? :o? Pin
Member 223871427-Apr-08 21:29
memberMember 223871427-Apr-08 21:29 
AnswerRe: Using PropertyGrid Ex to add a Trackbar- is it possible? :o? Pin
mikkojay15-Sep-09 12:06
membermikkojay15-Sep-09 12:06 
GeneralBind propertyGridEx to a custom object Pin
viverna23-Apr-08 23:54
memberviverna23-Apr-08 23:54 
GeneralNeed help with TAG value.. Pin
Member 475451610-Mar-08 21:53
memberMember 475451610-Mar-08 21:53 
QuestionCollection being displayed as child nodes instead Pin
Len202010-Feb-08 9:06
memberLen202010-Feb-08 9:06 
GeneralCustom choices but editable (like a combo box that lets the user edit the text) Pin
Joseph LeBlanc24-Jan-08 14:48
memberJoseph LeBlanc24-Jan-08 14:48 
GeneralRe: Custom choices but editable (like a combo box that lets the user edit the text) Pin
Member 985063716-Dec-13 6:50
memberMember 985063716-Dec-13 6:50 
QuestionInvoke Click event on Custom Control property Pin
Ashok Baria22-Jan-08 7:17
memberAshok Baria22-Jan-08 7:17 
AnswerRe: Invoke Click event on Custom Control property Pin
Squale11-Feb-08 22:18
memberSquale11-Feb-08 22:18 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web03 | 2.8.151126.1 | Last Updated 22 Aug 2006
Article Copyright 2006 by Danilo Corallo
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid