Select your preferred language

Creating Specialized Type Editors.

The property grid is one of the most useful controls when creating applications that need to provide a simple to use yet powerful method of editing any object model. It's flexibility is such that you can customize the way it displays or edits properties of an object and, as has been shown in previous articles, you can persuade the property grid not to frighten or confuse users that are not used to programming concepts. An example of this is the use of friendly names for properties instead of camel-cased property names.

One of the best features available to users of the Property Grid is it's ability to host specialized type editors that provide a graphical or intuitive interface for editing values that may be cryptic when edited as text. Examples of type editors can be seen in Figure 1.

Figure 1. Popup (left) and dialog based type editors.

You can see from Figure 1 that there are two distinct sorts of type editor. The popup style that is displayed in the property grid, right next to the value it's editing and, for more complex objects such as collections, a dialog based editor that enables you to provide a more complex user interface.

Type editors are invoked by the property grid using a button that is displayed next to the value when the property is selected. Figure 2 shows these buttons next to the selected Anchor and Nodes properties.

Figure 2. Dropdown and dialog edit buttons.

The editor for a property may be specified by the use of the EditorAttribute attribute. This attribute may be applied to a type or class so that all instances of a particular type will be edited in the same way or to an individual property. The first application of the EditorAttribute is used in the case of Color structures so that every time a Color is used in an object, the same editor is used to pick from the palette or colour selector dropdown. The second example would be used if you wanted to provide some specific editing ability for a class or type that has a special usage. For example, it's possible to edit an integer value by simply entering a number and there is no specific graphical editor for it. However, if the value represented something like transparency you might wish to provide a slider to enable the user to set the transparency in a more intuitive manner.

Type editors are based on the UITypeEditor class which is somewhat of a misnomer because the UITypeEditor does no editing and has no UI. It just provides information about what sort of editing style is to be used and invokes the correct control or dialog. The UITypeEditor also provides the property grid with the opportunity to render a graphical representation of the property. This is seen when Image files are edited by the property grid and the value has a tiny thumbnail version of the current image displayed next to the property name.

A Dropdown style editor.

This example shows a dropdown editor that is displayed next to the property. This editor will enable you to modify an integer value used to represent a transparency using a slider.

Step 1. Create the user interface. The IDE is used to create a simple control with a slider and a text box that shows transparency as a percentage. Note that colours store the transparency or alpha as a value in the range 0-255 so a little bit of conversion will be done to display the percentages correctly. Figure 3 shows the editor control.

Figure 3. The edit control under construction.

This listing shows the code behind the control. The Transparency property is edited by the slider or text-box value.

The UITypeEditor implementation

The control is managed by an object derived from UITypeEditor. The methods of this object enable the property grid to invoke the control for editing and find out how to display the editor or thumbnail view of the property.

This listing shows the UITypeEditor derived class.

Associate the editor with the property.

The test application defines a very simple class with a couple of integer values. One of these will be left untouched awhile the other will be associated with the editor and so modified by our drop-down control.

This listing shows the test object. Note the use of the EditorAttribute.

Test the Type Editor.

The simple application in this listing hosts the property grid and edits the TestObject class. Note how even though the two properties are integers, the editing and visual appearance of the properties are totally different.

Things you must not do.

A control displayed as a dropdown must be relatively uncomplicated and just concentrate on editing one simple value. You should not call out of the dropdown, like perhaps bringing up the ColorDialog or some custom dialog as this causes the dropdown to exit immediately without changing the edited value. For complex types such as a class having sub-properties that require special editing features, the Dialog style of editor may be used.

Create a matching TypeConverter

You'll have noticed that after the editor has been added to the transparency property the displayed value for the transparency seems to have a disparity with the way it's shown during editing. This is due to the fact that the transparency value is shown as an integer between 0 and 255 in the property grid but as a value of 0-100% in the editor. To make the display and the editor consistent you need to add a type converter to the property so that the displayed data matches the edited representation. Essentially, a type converter enables the user to type in a value as a string and convert it to a value or for the property grid to display a value as a string. An example of this is the DateTime type converter that takes an integer value that represents the number of 100  nanosecond ticks since the beginning of January the year 1 AD and displays this number as a date and time string. The same type converter enables the user to type in a date and time which is converted to the very large integer value.

A type converter has a few methods that enable the calling code to ascertain whether a value can be converted from one type to another and to do the actual conversion. These are CanConvertFrom, CanConvertTo, ConvertFrom and ConvertTo which are pretty self explanatory. In the context of the property grid, the TypeConverter will most often be asked if it's possible to convert to type X from a string or convert type X to a string. This enables a numerical value to be shown as a string of characters representing the number or parse the number out of the string.

Our ideal type converter will show the transparency value as percentage and enable the user to type in some value and have that converted from a string to the correct 0-255 integer. This listing shows the transparency type converter code.

Associate the type converter with the property.

The TestObject.Transparency can now be modified to associate the new type converter with it using the TypeConverterAttribute. This listing shows the revised code.

When you see this code in action you'll notice that the percentage values displayed are not always the same as those typed in. This is due to rounding in integer math and nothing to worry about.

Dialog based editors.

The dialog based editor works along the same lines as the dropdown except that the UI is a dialog and the UITypeEditor based class reflects this.

The dialog based editor in this example edits the transparency in much the same way as the dropdown but has a UI that shows the transparency as you change it as seen in Figure 4.

Figure 4. The dialog based transparency editor.

To use this type of editor, the UITypeEditor based class is set up in a slightly different manner. The GetEditStyle method returns UITypeEditorEditStyle.Modal and the EditValue method uses the ShowDialog method to call the editor. This listing shows the editor dialog and this revised listing shows the UITypeEditor derived class.

You can find the Source Code files here.

Return to the main index.