One of the greatest things in .Net is the System.Windows.Forms.PropertyGrid WinForms control.
This great class uses Reflection to access the visible properties of any object.
You can download the full c# source-code of this post HERE.
Let’s take a look how the PropertyGrid control looks in action:
In this screenshot I’ve bound the PropertyGrid, a WinForms control, to a Light object:
propertyGrid.SelectedObject = light;
Swush! The PropertyGrid is very simple to get started with and a great tool every .net programmer should know. Next we shall take a look at a very simple class we’d like to allow the user to edit:
using System;
namespace Blog.PropertyGrid
{
/// <summary>
/// This is just some really simple object
/// that contains some properties.
/// </summary>
public class DummyObject
{
/// <summary>
/// Gets or sets the name of this <see cref="DummyObject"/>.
/// </summary>
public string Name { get; set; }
/// <summary>
/// Gets or sets the position on the x-axis
/// of this <see cref="DummyObject"/>.
/// </summary>
public float X { get; set; }
/// <summary>
/// Gets or sets the position on the y-axis
/// of this <see cref="DummyObject"/>.
/// </summary>
public float Y { get; set; }
/// <summary>
/// Gets or sets some object that is usually loaden from a file.
/// </summary>
public object ObjectThatIsLoadenFromAFile { get; set; }
/// <summary>
/// Gets or sets a value that should not be set by the user
/// of the application but only by the programmer.
/// </summary>
public bool ThisIsADangerousInternalProperty { get; set; }
}
}
The following lines create a DummyObject and assign it to the PropertyGrid:
propertyGrid.SelectedObject = new DummyObject()
{
Name = "Bar Object",
X = 150.0f,
Y = 200.0f,
ThisIsADangerousInternalProperty = true
};
This should make the PropertyGrid look like this:
The next Step
Our next goal is to learn how to customize the entries in the PropertyGrid.
.net provides some nice Attributes in the System.ComponentModel namespace:
The CategoryAttribute, the DisplayNameAttribute, the DefaultValueAttribute, the BrowsableAttribute and more.
Let us apply these Attributes to our great Object:
using System;
using System.ComponentModel;
namespace Blog.PropertyGrid
{
/// <summary>
/// This is just some really simple object
/// that contains some properties.
/// </summary>
public class CustomizedDummyObject
{
/// <summary>
/// Gets or sets the name of this <see cref="CustomizedDummyObject"/>.
/// </summary>
[Category( "Identification" )]
[Description( "The name of the CustomizedDummyObject." )]
public string Name { get; set; }
/// <summary>
/// Gets or sets the position on the x-axis
/// of this <see cref="CustomizedDummyObject"/>.
/// </summary>
[DefaultValue( 0.0f )]
[Category( "Translation" )]
[Description( "The position of the CustomizedDummyObject on the x-axis." )]
public float X { get; set; }
/// <summary>
/// Gets or sets the position on the y-axis
/// of this <see cref="CustomizedDummyObject"/>.
/// </summary>
[DefaultValue( 0.0f )]
[Category( "Translation" )]
[Description( "The position of the CustomizedDummyObject on the y-axis." )]
public float Y { get; set; }
/// <summary>
/// Gets or sets some object.
/// </summary>
[DisplayName( "Object That Is Loaden From A File" )]
[Category( "Misc" )]
[Description( "The strange object that wants to be loaden from a file." )]
public object ObjectThatIsLoadenFromAFile { get; set; }
/// <summary>
/// Gets or sets a value that should not be set by the user
/// of the application but only by the programmer.
/// </summary>
[Browsable(false)]
public bool ThisIsADangerousInternalProperty { get; set; }
}
}
The Attributes explained
BrowsableAttribute
Using the BrowsableAttribute we tell the ‘ThisIsADangerousInternalProperty ‘ property to not be visible in the PropertyGrid.
DisplayNameAttribute
The name says it all, the DisplayNameAttribute sets how the property should be named within the PropertyGrid.
CategoryAttribute
Using the CategoryAttribute we can group our properties into categories.
DescriptionAttribute
Using the DescriptionAttribute we can give the user a hint what a property does.
DefaultValueAttribute
Using the DefaultValueAttribute we can tell the PropertyGrid what the default value of the property is. Non-default values are displayed using a bold font setting.
Let us bind the PropertyGrid to an instance of the CustomizedDummyObject class:
Much better, isn’t it? Be we’re not quite there yet. What about the mysterious “Object That Is Loaden From a File”?
To solve this issue I’d like to introduce you a concept I like to call ‘Object Property Wrappers‘.
Object Property Wrappers
When your objects get more and more complex, such as when you inherit from a base class, simply customizing your properties gets out of hand. Or what if you want to provide customization to a class you can’t or don’t want to change?
My solution to this problem is the IObjectPropertyWrapper interface:
using System;
using System.ComponentModel;
namespace Blog.PropertyGrid
{
/// <summary>
/// An <see cref="IObjectPropertyWrapper"/> is responsible
/// for exposing the properties of an Object which the user is intended to edit.
/// </summary>
interface IObjectPropertyWrapper : ICloneable, INotifyPropertyChanged
{
/// <summary>
/// Gets or sets the object this <see cref="IObjectPropertyWrapper"/> wraps around.
/// </summary>
[Browsable( false )]
object WrappedObject { get; set; }
/// <summary>
/// Receives the <see cref="Type"/> this <see cref="IObjectPropertyWrapper"/> wraps around.
/// </summary>
[Browsable( false )]
Type WrappedType { get; }
}
}
Implementation
Before we bound our PropertyGrid directly to our DummyObjects.
From now on we are going to bind the PropertyGrid to wrapper classes that implement the IObjectPropertyWrapper interface.
The above interface is the interface which is used in your application’s public interface.
The following abstract class is a basic implementation of the interface. This reduces the amount of work needed if we wish to create new Object Property Wrappers.
using System;
using System.ComponentModel;
namespace Blog.PropertyGrid
{
/// <summary>
/// Defines a basic implementation of the <see cref="IObjectPropertyWrapper"/> interface.
/// </summary>
/// <typeparam name="TObject">
/// The type of the object that is beeing wrapped by this IObjectPropertyWrapper.
/// </typeparam>
abstract class BaseObjectPropertyWrapper<TObject> : IObjectPropertyWrapper
{
#region [ Events ]
/// <summary>
/// Fired when any property of this IObjectPropertyWrapper has changed.
/// </summary>
/// <remarks>
/// Properties that wish to support binding, such as in Windows Presentation Foundation,
/// must notify the user that they have change.
/// </remarks>
public event System.ComponentModel.PropertyChangedEventHandler PropertyChanged;
#endregion
#region [Properties]
/// <summary>
/// Gets or sets the object this <see cref="IObjectPropertyWrapper"/> wraps around.
/// </summary>
/// <exception cref="ArgumentException">
/// If the Type of the given Object is not supported by this IObjectPropertyWrapper.
/// </exception>
[Browsable( false )]
public TObject WrappedObject
{
get { return _wrappedObject; }
set
{
if( value != null )
{
if( !this.WrappedType.IsAssignableFrom( value.GetType() ) )
{
throw new ArgumentException(
"The Type of the given Object is not supported by this IObjectPropertyWrapper.",
"value"
);
}
}
_wrappedObject = value;
OnPropertyChanged( "WrappedObject" );
}
}
/// <summary>
/// Gets or sets the object this <see cref="IObjectPropertyWrapper"/> wraps around.
/// </summary>
[Browsable( false )]
object IObjectPropertyWrapper.WrappedObject
{
get { return this.WrappedObject; }
set { this.WrappedObject = (TObject)value; }
}
/// <summary>
/// Receives the <see cref="Type"/> this <see cref="IObjectPropertyWrapper"/> wraps around.
/// </summary>
[Browsable( false )]
public Type WrappedType
{
get { return typeof( TObject ); }
}
#endregion
#region [ Methods ]
/// <summary>
/// Returns a clone of this <see cref="IObjectPropertyWrapper"/>.
/// </summary>
/// <remarks>
/// The wrapped object is not cloned, only the IObjectPropertyWrapper.
/// </remarks>
/// <returns>
/// The cloned IObjectPropertyWrapper.
/// </returns>
public abstract object Clone();
/// <summary>
/// Fires the <see cref="PropertyChanged"/> event.
/// </summary>
/// <param name="propertyName">
/// The name of the property whose value has changed.
/// </param>
protected void OnPropertyChanged( string propertyName )
{
if( PropertyChanged != null )
PropertyChanged( this, new PropertyChangedEventArgs( propertyName ) );
}
#endregion
#region [ Fields ]
/// <summary>
/// Stores the object this <see cref="IObjectPropertyWrapper"/> wraps around.
/// </summary>
private TObject _wrappedObject;
#endregion
}
}
Time to write a Wrapper
The following picture shows a PropertyGrid that is bound to a ‘DummyObjectPropertyWrapper’, an IObjectPropertyWrapper that exposes the properties of a DummyObject.
Remember that DummyObject has zero Attributes that describe its properties.
Here is the implementation:
using System;
using System.ComponentModel;
namespace Blog.PropertyGrid
{
/// <summary>
/// Defines the IObjectPropertyWrapper for the <see cref="DummyObject"/> type.
/// </summary>
class DummyObjectPropertyWrapper : BaseObjectPropertyWrapper<DummyObject>
{
/// <summary>
/// Initializes a new instance of the <see cref="DummyObjectPropertyWrapper"/> class.
/// </summary>
public DummyObjectPropertyWrapper()
{
}
/// <summary>
/// Initializes a new instance of the <see cref="DummyObjectPropertyWrapper"/> class.
/// </summary>
/// <param name="obj">The object the new DummyObjectPropertyWrapper wraps around.</param>
public DummyObjectPropertyWrapper( DummyObject obj )
{
this.WrappedObject = obj;
}
/// <summary>
/// Gets or sets the name of this <see cref="CustomizedDummyObject"/>.
/// </summary>
[Category( "Identification" )]
[Description( "The name of the CustomizedDummyObject." )]
public string Name
{
get { return this.WrappedObject.Name; }
set { this.WrappedObject.Name = value; }
}
/// <summary>
/// Gets or sets the position on the x-axis
/// of this <see cref="CustomizedDummyObject"/>.
/// </summary>
[DefaultValue( 0.0f )]
[Category( "Translation" )]
[Description( "The position of the CustomizedDummyObject on the x-axis." )]
public float X
{
get { return this.WrappedObject.X; }
set { this.WrappedObject.X = value; }
}
/// <summary>
/// Gets or sets the position on the y-axis
/// of this <see cref="CustomizedDummyObject"/>.
/// </summary>
[DefaultValue( 0.0f )]
[Category( "Translation" )]
[Description( "The position of the CustomizedDummyObject on the y-axis." )]
public float Y
{
get { return this.WrappedObject.Y; }
set { this.WrappedObject.Y = value; }
}
/// <summary>
/// Gets or sets some object that is usually loaden from a file.
/// </summary>
[DisplayName( "Object That Is Loaden From A File" )]
[Category( "Misc" )]
[Description( "The strange object that wants to be loaden from a file." )]
[Editor( typeof( System.Windows.Forms.Design.FileNameEditor ), typeof( System.Drawing.Design.UITypeEditor ) )]
public object ObjectThatIsLoadenFromAFile
{
get
{
return this.WrappedObject.ObjectThatIsLoadenFromAFile;
}
set
{
string fileName = (string)value;
// load object here...
// set object..
this.WrappedObject.ObjectThatIsLoadenFromAFile = fileName;
}
}
/// <summary>
/// Returns a clone of this <see cref="DummyObjectWrapper"/>.
/// </summary>
/// <returns>
/// The cloned IObjectPropertyWrapper.
/// </returns>
public override object Clone()
{
// We can initialize the clone here!
return new DummyObjectPropertyWrapper();
}
}
}
The EditorAttribute
The ObjectThatIsLoadenFromAFile property of our Property Wrapper has an additional attribute.
It’s the quite complex EditorAttribute. Using the EditorAttribute you can tell the PropertyGrid how it should ‘edit’ that specific property.
In this case the editor I use is of type System.Windows.Forms.Design.FileNameEditor, a class you can find in the System.Design.dll. When the user edits the property, by clicking on the ‘…’ button, the FileNameEditor opens an OpenFileDialog and returns a string back to you.
There are many useful Editors and you can even define your own or customize an existing.
A few last words
There is more to know about the PropertyGrid class, such as how TypeConverters work or how you can place complex objects within other objects using ExpandableObjectConverter.
Now I’d like to thank you for reading this far. Thanks! (:
You can download the full c# source-code of this post HERE.
The code also shows how you can localize your properties using custom Attributes and create IObjectPropertyWrappers using a ObjectPropertyWrapperFactory; both very useful tools.
blog . by . paul 