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.
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 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.
You access a drop-down UI type editor by clicking on the arrow button () 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 () 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.
To implement a custom UI type editor, you must at least perform the following tasks:
Define a class that derives from UITypeEditor.
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.
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.
Provides no interactive UI component. An appropriate TypeConverter is used to convert a string entry to a property value.
Displays a down-arrow button () in the property entry. The UI is hosted in a drop-down window.
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.
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.
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.
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
The component's IContainer.
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.
Override the GetPaintValueSupported method to return true to alert the design environment that your UI type editor paints a custom representation of its value.