User Interface Type Editors Overview

User Interface Type Editors Overvie...

Switch on low bandwidth view

Collapse All

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Windows Forms Programming

User Interface Type Editors Overview

You can provide a custom design-time experience for complex property types by implementing a user interface (UI) type editor.

Displaying and Editing Custom Types

When you expose a custom type as a property, there are three ways to edit the property's value in a PropertyGrid:

You can edit your property in place as a string. This requires a TypeConverter for your custom type. For more information, see How to: Implement a Type Converter.
You can edit your property with a drop-down UI. This is especially useful for properties that can be set with a single click.
You can edit your property with a modal dialog box. If your property is particularly complex, a full dialog box may be necessary to edit it properly.

To enable either single-click or modal dialog box editing, you need to implement a UI type editor to interact with a PropertyGrid.

Drop-down Editors

Drop-down editors are ideal for types that can be set with a single click. For example, you edit the Dock and BackColor properties of the Control class in a PropertyGrid with a drop-down editor.

You access a drop-down UI type editor by clicking on the arrow button ( Properties Window Down Arrow ) that appears next to the selected property entry in a PropertyGrid. Your custom UI appears, attached to the PropertyGrid. The top of its window is positioned along the bottom of the property entry, and its width matches that of the property entry. This editor window must also be closed after the user makes a selection. Your implementation must call the DropDownControl method to position and size your UI type editor window in the design environment, and you must call the CloseDropDown method to close the window.

Modal Dialog Editors

Modal editors are useful for types that require a fully interactive UI. For example, collection editors like the TabPage Collection Editor of TabControl or the Edit Columns dialog box of the DataGridView control are modal editors.

You access a modal UI type editor by clicking on the ellipsis button ( VisualStudioEllipsesButton screenshot ) that appears next to the selected property entry in a PropertyGrid. Your modal dialog box appears, and the user interacts with it like a typical dialog box. Your implementation must call the ShowDialog method to position and size your dialog box in the design environment.

Implementing a UI Type Editor

To implement a custom UI type editor, you must at least perform the following tasks:

Define a class that derives from UITypeEditor.
Override the GetEditStyle method to inform the PropertyGrid of the type of editor style that the editor will use.
Override the EditValue method to handle the UI, user input processing, and value assignment.

You can add additional support for painting a value's representation in a PropertyGrid by performing the following tasks:

Override GetPaintValueSupported to indicate that the editor supports displaying the value's representation.
Override PaintValue to implement the display of the value's representation.
Override the UITypeEditor constructor method if the editor should have initialization behavior.

Note:
UI type editors are often implemented using types from the System.Windows.Forms namespace, but this is not a requirement. The standard UI type editors in the .NET Framework derive from UITypeEditor.

Deriving from the UITypeEditor Class

Your custom UI type editor must derive from the UITypeEditor class. Define a default constructor if your UI type editor requires special initialization.

Overriding the GetEditStyle Method

When you select a component or control in the designer, the Properties window is repainted with the property values of the selected component or control. When you select a property, the design environment queries the GetEditStyle method to determine how to represent the property entry.

Your override returns a value from the UITypeEditorEditStyle enumeration to communicate the appropriate style of UI type editor.

The following table shows the behavior associated with each UITypeEditorEditStyle value.

Member name	Behavior
None	Provides no interactive UI component. An appropriate TypeConverter is used to convert a string entry to a property value.
DropDown	Displays a down-arrow button () in the property entry. The UI is hosted in a drop-down window.
Modal	Displays an ellipsis button () in the property entry. The UI is a modal dialog box.

Overriding the EditValue Method

The EditValue method displays the UI and sets the value of the property to the value selected by the user.

Drop-down Editor

For a drop-down UI type editor, you query a service provider for the IWindowsFormsEditorService interface. This service provides position and size information for your UI. Your UI will typically be implemented as a Control. Your EditValue implementation creates an instance of this control, initializes it with the current property value, and then passes it to the DropDownControl method for execution by the design environment. When the user has selected a new value for the property, your EditValue implementation closes the UI by calling CloseDropDown. The return value from your EditValue implementation becomes the new property value displayed in a PropertyGrid.

Modal Editor

For a modal UI type editor, you query a service provider for the IWindowsFormsEditorService interface. This service provides position information for your dialog box. Your UI will typically be implemented as a class derived from Form. Your EditValue implementation creates an instance of this form, initializes it with the current property value, and then passes it to the ShowDialog method for execution by the design environment. If the return value from this call is OK, you retrieve the new property value from the form and use it as the return value. The return value from your EditValue implementation becomes the new property value displayed in a PropertyGrid.

ITypeDescriptorContext Parameter

The EditValue method receives an ITypeDescriptorContext parameter, which you can use to query for contextual information about the design environment. With this parameter, you can access the following members:

A PropertyDescriptor that represents the property's metadata
An Instance property that refers to the component that is selected in the PropertyGrid.
The component's IContainer.
OnComponentChanging and OnComponentChanged methods that alert the design environment when you change the state of a component.

Providing a Graphical Representation of the Property's Value

You can display a graphical representation of your property's value by overriding the PaintValue method. You can use the provided PaintValueEventArgs parameter to draw your representation in a small rectangle on the left side of the property's entry in a PropertyGrid.

Note:
Be sure to keep your graphical representation within the bounds defined by the Bounds property of the PaintValueEventArgs parameter.

Override the GetPaintValueSupported method to return true to alert the design environment that your UI type editor paints a custom representation of its value.

Drop-down Editors

Modal Dialog Editors

Deriving from the UITypeEditor Class

Overriding the GetEditStyle Method

Overriding the EditValue Method

Providing a Graphical Representation of the Property's Value

Tasks

Reference

Other Resources