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:
You can edit your property in place as a string. This requires afor your custom type. For more information, see .
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 are ideal for types that can be set with a single click. For example, you edit theand properties of the class in a PropertyGrid with a drop-down editor.
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 themethod to position and size your UI type editor window in the design environment, and you must call the 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 ofor the Edit Columns dialog box of the 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 themethod 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.
Override themethod to inform the PropertyGrid of the type of editor style that the editor will use.
Override themethod 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:
Overrideto indicate that the editor supports displaying the value's representation.
Overrideto implement the display of the value's representation.
Override the UITypeEditor constructor method if the editor should have initialization behavior.
UI type editors are often implemented using types from thenamespace, 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 theenumeration 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 theinterface. 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. 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 , 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 anparameter, which you can use to query for contextual information about the design environment. With this parameter, you can access the following members:
Athat represents the property's metadata
Anproperty that refers to the component that is selected in the PropertyGrid.
and 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 providedparameter to draw your representation in a small rectangle on the left side of the property's entry in a PropertyGrid.
Be sure to keep your graphical representation within the bounds defined by theproperty 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.