User Interface Type Editors Overview
Caution
This content was written for .NET Framework. If you're using .NET 6 or a later version, use this content with caution. The designer system has changed for Windows Forms and it's important that you review the Designer changes since .NET Framework article.
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 (.gif "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 (.gif "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 |
|---|---|
Provides no interactive UI component. An appropriate TypeConverter is used to convert a string entry to a property value. |
|
Displays a down-arrow button ( |
|
Displays an ellipsis button ( |
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.
See Also
Tasks
How to: Create a UI Type Editor
How to: Create a Windows Forms Control That Takes Advantage of Design-Time Features