This documentation is archived and is not being maintained.

Walkthrough: Implementing a UI Type Editor

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

This walkthrough explains how to author your own UI type editor for a custom type and display the editing interface by using a PropertyGrid.

Tasks explained in this walkthrough include:

  • Defining a custom type.

  • Defining a view control for your UI type editor.

  • Defining a class that derives from UITypeEditor.

  • Overriding the GetEditStyle method to inform the PropertyGrid of the type of editor style that the editor will use.

  • Overriding the EditValue method to handle the user interface, user input processing, and value assignment.

To copy the code in this walkthrough as a single listing, see How to: Create a Windows Forms Control That Takes Advantage of Design-Time Features.

In order to complete this walkthrough, you will need:

  • Sufficient permissions to be able to create and run Windows Forms application projects on the computer where the .NET Framework is installed.

Your custom UI type editor will display a custom type. This type could be complex or simple. For this walkthrough, you will define a simple type with custom design-time editing behavior. This type is called MarqueeLightShape, and it is an enum with two values, Square and Circle.

To define a custom enumeration type

  • In the body of your Windows Forms control's definition, define the MarqueeLightShape type.

    No code example is currently available or this language may not be supported.

Your custom UI type editor displays the editing interface using a Windows Forms control. This control is named LightShapeSelectionControl, and it derives from UserControl. Its constructor takes the current property value and a reference to the IWindowsFormsEditorService. The view control uses the CloseDropDown method on IWindowsFormsEditorService to close the drop-down window when the user clicks on a selection.

To define a view control

  • In the body of your Windows Forms control's definition, define the LightShapeSelectionControl control.

    No code example is currently available or this language may not be supported.

To implement UI type editor behavior, derive from the UITypeEditor base class. This class is called LightShapeEditor.

To define a UI type Editor Class

  1. Enable access to .NET Framework design-time support by referencing the System.Design assembly and importing the System.Drawing.Design and System.Windows.Forms.Design namespaces. For more information, see How to: Access Design-Time Support in Windows Forms.

  2. In the body of your Window Forms control's definition, define the LightShapeEditor class.

    No code example is currently available or this language may not be supported.

The GetEditStyle method indicates to the design environment which kind of user interface your UI type editor implements. The possible values are defined in the UITypeEditorEditStyle type. The LightShapeEditor implements a DropDown UI type editor.

To override the GetEditStyle method

  • In the body of the LightShapeEditor definition, override the GetEditStyle method to return DropDown.

    No code example is currently available or this language may not be supported.

The EditValue method establishes the interaction between the design environment and the user interface for editing your custom type. The EditValue method creates an instance of the view control or the modal dialog box with which the user edits the value. When the user is finished editing, the EditValue method returns the value to the design environment.

In the case of a view control like LightShapeSelectionControl, the EditValue method may pass a reference to the IWindowsFormsEditorService to the view control. The view control can use this reference to close itself when the user selects a value. This is not necessary for a modal dialog box, because a form can close itself.

To override the EditValue method

  • In the body of the LightShapeEditor definition, override the EditValue method.

    No code example is currently available or this language may not be supported.

You can provide a graphical representation of your property's value by overriding the PaintValue method.

To override the PaintValue method

  • In the body of the LightShapeEditor definition, override the PaintValue method. Also override the GetPaintValueSupported method to return true.

    No code example is currently available or this language may not be supported.

When your UI type editor is ready for use in your custom control, attach the LightShapeEditor to a property, implement the property based on the MarqueeLightShape type, and apply the EditorAttribute to the property.

To attach your UI type editor to a property

  • In the body of your control's definition, declare a MarqueeLightShape property named LightShape. Also declare an instance field named lightShapeValue of type MarqueeLightShape to back the property. Apply the EditorAttribute to the property.

No code example is currently available or this language may not be supported.

You can test your UI type editor by creating an instance of your custom control and attaching it to a PropertyGrid control using the SelectedObject property.

If you are using Visual Studio, you can create a new Windows Application project, reference your control's assembly, and add an instance of your control to the form. There is extensive support for this task in Visual Studio. Walkthrough: Automatically Populating the Toolbox with Custom Components
Walkthrough: Automatically Populating the Toolbox with Custom Components
Walkthrough: Automatically Populating the Toolbox with Custom Components
Walkthrough: Automatically Populating the Toolbox with Custom Components

When the properties for your control are displayed at design time, you can select the LightShape property. When it is selected, a drop-down arrow (Properties Window Down Arrow) appears. When you click on the arrow, your view control appears beneath the property entry. Click on the circle or square to select the value. After you click, the view control dismisses itself, and the value you selected appears in the PropertyGrid.

Note Note

When you develop your custom UITypeEditor, it is recommended that you set the build number to increment with each build. This prevents older, cached versions of your UITypeEditor from being created in the design environment.

Once you have authored your own UI type editor, explore other ways to interact with a PropertyGrid and the design environment:

Show: