Design Custom Editor for a Property

Introduction

In the previous article we discussed type converters. Type converters come handy when you want to accept property values in plain text form. However, at times you may not want to allow the user to enter text values directly. You may want to present a custom value picker in the form of a dropdown control or a dialog box. This is possible with the help of Type Editors and this article examines them with an example.

Type Editors

A type editor is a class that derives from UITypeEditor base class and provides a way to pick up property value from a custom dropdown control or dialog box. There are certain type converter classes that are inbuilt to the .NET framework. For example, when you create any property that is of type Color or Font the property window automatically displays appropriate value picker controls (see figure below).

Some of the common inbuilt type editors are:

• FontEditor
• ColorEditor
• DateTimeEditor
• FileNameEditor
• FolderNameEditor
• MultilineStringEditor

Using inbuilt type editors

Let's see a simple example that illustrates how you can consume the inbuilt type editors listed above. To work through the example you need to create a custom control class library with a class named SimpleControl. The class contains two three properties viz. Text, SourceFile and SourceFolder. The complete source code of the class is shown below:

public class SimpleControl : WebControl
{
public string Text
{
get
{
return ViewState["Text"] as string;
}
set
{
ViewState["Text"] = value;
}
}

public string SourceFile
{
get
{
return ViewState["SourceFile"] as string;
}
set
{
ViewState["SourceFile"] = value;
}
}

public string SourceFolder
{
get
{
return ViewState["SourceFolder"] as string;
}
set
{
ViewState["SourceFolder"] = value;
}
}
}

The class and properties are fairly straightforward. What we would like to do is:

• The Text property should open a multiline text entry region rather than normal single line editor
• The SourceFile property should open a file open dialog box in the property window
• The SourceFolder property should open a folder selector dialog box in the property window

As you might have guessed these type editors are inbuilt into the .NET framework and all we need to do is attach them to the respective properties. A type editor is attached to a property using [Editor] attribute. The usage of this attribute is shown below:

[Editor(<editor_class_type_info>),
<base_class_type_info>)]

The first parameter to the [Editor] attribute is the type information (Type instance) of the class that is being attached as a type editor and the second parameter is the type information of the base class of the type editor.

For the sake of our example decorate the Text, SourceFile and SourceFolder properties with the [Editor] attribute as shown below:

[Editor(typeof(MultilineStringEditor), 
typeof(UITypeEditor))]
[Editor(typeof(FileNameEditor), 
typeof(UITypeEditor))]
[Editor(typeof(FolderNameEditor), 
typeof(UITypeEditor))]

If you consume the SimpleControl on a web form you will notice that the SourceFile and SourceFolder properties show ellipses in the property window. Clicking on the ellipses open a file open dialog and folder selector dialog respectively.

The Text property shows a multiline text entry region.

Creating custom type editor

A type editor normally comes in two flavors viz. dropdown and dialog. In order to create a custom type editor you need to follow these steps:

• Create custom value picker
  • If you want a dropdown value picker then create a custom windows forms control representing the UI of the value picker
  • If you want a dialog from which the user should pick the value then create a windows form with the required UI
• Create a custom type editor class that inherits from UITypeEditor base class ad override certain methods
• Create a custom control that will consume your type editor
• Mark one or more properties of the custom control to use the custom type editor

As an example we will create a dropdown type editor for selecting predefined color values and a dialog based type editor for accepting a property value. We will call them as ColorTypeEditor and TagTypeEditor respectively.

By convention type editor classes are named as XXXXTypeEditor where XXXX is the data type they deal with.

Creating windows custom control and form

Add a new project of type Windows Forms Control Library to the existing solution. Rename the default control to ColorDropDown. Drag and drop a combo box on it and add three fixed color values namely Red, Blue and Yellow.

The control will have SelectedValue property as shown below:

public Color SelectedValue
{
get
{
switch (comboBox1.SelectedIndex)
{
case 0:
return Color.Red;
break;
case 1:
return Color.Blue;
break;
case 2:
return Color.Yellow;
break;
default:
return Color.Blue;
}
}
}

The SelectedValue property simple returns a Color value depending on the selection.

Now add a new Windows Form to the project and design it as shown below:

The form consists of a textbox and two buttons. Set the DialogResult property of the OK and Cancel buttons to Ok and Cancel respectively. The windows form contains Value property that simply returns value entered in the textbox.

public string Value
{
get
{
return textBox1.Text;
}
}

Creating custom type editor class

Now add a new class to the web control class library (where you created SimpleControl class) named ColorTypeEditor and inherit it from UITypeEditor base class.

In the ColorTypeEditor class we need to override certain base class methods. The first method being GetEditStyle().

public override UITypeEditorEditStyle 
GetEditStyle(ITypeDescriptorContext context)
{
return UITypeEditorEditStyle.DropDown;
}

The GetEditStyle() method governs whether we want dropdown value picker or a dialog box. The UITypeEditorEditStyle enumeration has three values viz. DropDown, Modal and None. For the ColorTypeEditor we want to display a dropdown with fixed color values to pick from and hence we return editor style as DropDown.

The second method to be overridden is EditValue() and is shown below:

public override object EditValue
(ITypeDescriptorContext context, 
IServiceProvider provider, object value)
{
IWindowsFormsEditorService editorservice = null;
if (provider != null)
{
editorservice = (IWindowsFormsEditorService)
provider.GetService(typeof
(IWindowsFormsEditorService));
}
if (editorservice != null)
{
ColorDropDown editor = new ColorDropDown();
editorservice.DropDownControl(editor);
return editor.SelectedValue;
}
else
{
return value;
}
}

The EditValue() method returns the selected value from the dropdown or dialog to the property window. It first gets a reference to what is called as windows forms editor service and then calls DropDownControl() method by passing an instance of the windows custom control we created earlier. This way the property window will present that control to the user while editing the property value. Finally the SelectedValue from the ColorDropDown control is returned to the caller.

Properties such as Color and Font show a preview of the selected value in a small rectangle followed by the actual value. To accomplish this you need to override two more methods namely GetPaintValueSupported() and PaintValue(). The GetPaintValueSupported() should return true if you want to implement this feature. The PaintValue() method actually draws the preview rectangle. For ColorTypeEditor these two methods are implemented as follows:

public override bool GetPaintValueSupported
(ITypeDescriptorContext context)
{
return true;
}

public override void PaintValue
(PaintValueEventArgs e)
{
WebControl c = e.Context.Instance 
as WebControl;
e.Graphics.FillRegion(new SolidBrush
(c.BackColor), new Region(e.Bounds));
base.PaintValue(e);
}

The PaintValue() method simply draws a filled region with the appropriate color using the Graphics object.

Next, add a type editor class for TagTypeEditor. The TagTypeEditor class will override only the first two methods as shown below:

public override UITypeEditorEditStyle 
GetEditStyle(ITypeDescriptorContext context)
{
return UITypeEditorEditStyle.Modal;
}

public override object EditValue
(ITypeDescriptorContext context, 
IServiceProvider provider, object value)
{
IWindowsFormsEditorService editorservice = null;
if (provider != null)
{
editorservice = (IWindowsFormsEditorService)
provider.GetService(typeof(
IWindowsFormsEditorService));
}
if (editorservice != null)
{
TagDialog editor = new TagDialog(
value.ToString());
editorservice.ShowDialog(editor);
return editor.Value;
}
else
{
return value;
}
}

The code shown above is similar to the previous case except with few differences. Notice the lines marked in bold characters. This time we set the editor style to Modal i.e. dialog box and use ShowDialog() method passing an instance of the Windows Form.

Consuming type editors in custom control

Now that our custom type editors are ready we can consume them in SimpleControl. Add two properties to the SimpleControl as shown below:

[Editor(typeof(ColorTypeEditor), 
typeof(UITypeEditor))]
public override Color BackColor
{
get
{
return base.BackColor;
}
set
{
base.BackColor = value;
}
}

[Editor(typeof(TagTypeEditor), 
typeof(UITypeEditor))]
public string Tag
{
get
{
return ViewState["tag"] as string;
}
set
{
ViewState["tag"] = value;
}
}

Notice how the [Editor] attribute is used to attach our custom type editors with the properties.

The following screen shots show how the custom type editors look like in the property window.