UI Type Editors

A UI type editor is launched from the property browser and provides a custom user interface for editing a property. A UI type editor is useful when the standard UI provided by the property browser ”a plain text box ”is not adequate for editing a property type. For example, when editing a property of type System.Drawing. Color , a drop-down list that visually displays colors and enables a user to make a color selection is much more useful than a text box that accepts color names .

In the .NET Framework, a UI type editor is a class that derives from System.Drawing.Design.UITypeEditor . The System.Drawing.Design.ColorEditor for editing a color property and the System.Web.UI.Design.UrlEditor for editing a URL property are examples of UI type editors.

In this section, we'll show you how to implement your own UI type editor and customize the built-in System.ComponentModel.Design.CollectionEditor .

String Editor Example

The StringEditor class that we'll implement is a UI type editor that provides a dialog-based UI that makes editing long strings convenient , as shown in Figure 15-6. StringEditor can be associated with any property of type String .

Figure 15-6. The user interface provided by the StringEditor class

Listing 15-6 contains the code for the MyLabel control that uses StringEditor . The MyLabel control derives from the standard Label control, overrides its Text property, and associates StringEditor with the property by applying the EditorAttribute metadata attribute to the property. We'll describe EditorAttribute in more detail at the end of this section. The MyLabel control also has a designer and a component editor associated with it. We'll describe those two classes later in the "Component Editors" section.

Listing 15-6 MyLabel.cs

 usingSystem; usingSystem.ComponentModel; usingSystem.Drawing.Design; usingSystem.Web.UI; usingSystem.Web.UI.WebControls; namespaceMSPress.ServerControls{ [ Designer(typeof(MSPress.ServerControls.Design.MyLabelDesigner)), Editor(typeof(MSPress.ServerControls.Design.MyLabelComponentEditor), typeof(ComponentEditor)) ] publicclassMyLabel:Label{ [ Editor(typeof(MSPress.ServerControls.Design.StringEditor), typeof(UITypeEditor)) ] publicoverridestringText{ get{ returnbase.Text; } set{ base.Text=value; } } } } 

StringEditor causes the property browser in Visual Studio .NET to display an ellipsis next to the Text property of MyLabel , as shown in Figure 15-7. The ellipsis indicates that the associated UI type editor creates a modal dialog box for editing the property. Clicking the ellipsis invokes StringEditor to edit the property value.

Figure 15-7. Editing style displayed by the property browser for the Text property with which StringEditor is associated

Listing 15-7 shows the code for the StringEditor class, which launches a Windows Form and uses input from the form to update the property with which StringEditor is associated.

Listing 15-7 StringEditor.cs

 usingSystem; usingSystem.ComponentModel; usingSystem.Drawing; usingSystem.Drawing.Design; usingSystem.Windows.Forms; usingSystem.Windows.Forms.Design; namespaceMSPress.ServerControls.Design{ publicclassStringEditor:UITypeEditor{ publicoverrideobjectEditValue(ITypeDescriptorContextcontext, IServiceProviderserviceProvider,objectvalue){ if((context!=null)&& (serviceProvider!=null)){ IWindowsFormsEditorServiceedSvc= (IWindowsFormsEditorService) serviceProvider.GetService(typeof(IWindowsFormsEditorService)); 

 if(edSvc!=null){ StringEditorFormform=newStringEditorForm(); form.Value=(string)value; DialogResultresult=edSvc.ShowDialog(form); if(result==DialogResult.OK){ value=form.Value; } } } returnvalue; } publicoverrideUITypeEditorEditStyleGetEditStyle(ITypeDescriptorContextcontext){ if(context!=null){ returnUITypeEditorEditStyle.Modal; } returnbase.GetEditStyle(context); } } } 

StringEditor demonstrates the following steps in implementing a UI type editor:

• Derives from System.Drawing.Design.UITypeEditor

• Overrides the EditValue method to create the user interface, process user input, and assign a value to the property

• Overrides the GetEditStyle method to inform the property browser of the editing style the editor will use, such as a drop-down list or a modal dialog box

Let's examine the GetEditStyle and EditValue methods in more detail. The return type of the GetEditStyle method is the UITypeEditorEditStyle enumeration whose values DropDown , Modal , and None indicate the type of UI implemented by the UI type editor. You should return UITypeEditorEditStyle.DropDown if your UI type editor offers a drop-down UI for property editing. This value causes the property browser to display a drop-down button beside the property, as seen when editing the BackColor or ForeColor properties of a Web control. You should return UITypeEditorEditStyle.Modal if your editor offers a modal dialog box for property editing. This return value causes the property browser to display an ellipsis button beside the property. If you do not override the GetEditStyle method, the base class returns the default value UITypeEditorEditStyle.None , which tells the property browser that the editor does not offer a user interface for property editing.

The EditValue method is where you create and initialize the user interface with the current property value, process user input, and return an updated value for the property. This method has three parameters. The first parameter is the ITypeDescriptorContext object, which represents the context where your editor is used. Although more advanced editors use this parameter, the String ­Editor does not use the first parameter. The second parameter is an IServiceProvider object that provides design-time services, as shown in Figure 15-1. The third parameter represents the initial value of the property that the editor is associated with.

To obtain a design-time service, you must invoke the GetService method of the IServiceProvider object. StringEditor requests an IWindowsFormsEditorService because it wants to create a Windows Forms “based UI for property editing. The ShowDialog method of the IWindowsFormsEditorService class launches a dialog-based UI, while the DropDownControl method launches a drop-down UI. StringEditor invokes the ShowDialog method to launch a modal dialog box for property editing, as we describe in the next paragraph.

The remaining task in the EditValue method is to create an instance of the form (or control) to pass into the ShowDialog (or DropDownControl ) method and return a value for the property. You must independently implement a Windows Forms Form or Control that represents the UI that your editor wants to create. StringEditor creates an instance of the StringEditorForm (shown in a moment) and passes it into the ShowDialog method to create a modal dialog box. StringEditor returns the user-entered text in the dialog box as the value of the property (of type String ) with which the editor is associated.

The StringEditorForm class that creates the property editing UI offered by StringEditor is a System.Windows.Forms.Form that contains a multiline text box to enable the user to easily enter arbitrary text. The code for this class appears in the book's sample files. The main features are shown in the class outline in Listing 15-8. We used the Windows Forms designer to create the UI; the designer-generated code that creates the UI is not shown in the listing. String ­EditorForm defines a Value property that delegates to the Text property of the TextBox it contains. The Value property enables StringEditor to access the value of the user-entered text in the text box.

Listing 15-8 StringEditorForm.cs

 usingSystem; usingSystem.Collections; usingSystem.ComponentModel; usingSystem.Drawing; usingSystem.Windows.Forms; namespaceMSPress.ServerControls.Design{ publicclassStringEditorForm:System.Windows.Forms.Form{ privateSystem.Windows.Forms.TextBoxtextBox1; privateSystem.Windows.Forms.ButtonokButton; privateSystem.Windows.Forms.ButtoncancelButton; publicStringEditorForm(){ InitializeComponent(); } publicstringValue{ get{ returntextBox1.Text; } set{ textBox1.Text=value; } } #regionWindowsFormDesignergeneratedcode  #endregion } } 

Collection Editor Examples

A collection editor enables a page developer to edit a collection property in a WYSIWYG fashion. For example, the ListBox control uses a collection editor to provide a UI that enables a page developer to add, remove, or reorder the objects in the Items collection.

The System.ComponentModel.Design.CollectionEditor is a built-in UI type editor that provides the basic functionality to edit a property of type System.Collections.IList in a design-time environment. You can override the methods of CollectionEditor to customize it for a specific collection.

CollectionEditor infers the type of the collection items from the Items property of the collection. You can override the CreateCollectionItemType method in a derived collection editor to return the type of the collection.

If the collection allows more than one type of object, you can override the CreateNewItemTypes method to specify the types that are allowed in the collection. Listing 15-9 shows the code for HotSpotCollectionEditor , which is associated with the HotSpotCollection type that contains two types, CircleHotSpot and RectangleHotSpot . In Chapter 10, we used the HotSpotCollection type and its associated HotSpotCollectionEditor in the ImageMap example. Figure 10-5 shows the UI created by HotSpotCollectionEditor .

Listing 15-9 HotSpotCollectionEditor.cs

 usingSystem; usingSystem.ComponentModel; usingSystem.ComponentModel.Design; usingSystem.Reflection; namespaceMSPress.ServerControls.Design{ publicclassHotSpotCollectionEditor:CollectionEditor{ publicHotSpotCollectionEditor(Typetype):base(type){ } protectedoverrideType[]CreateNewItemTypes(){ Type[]types=newType[]{ typeof(CircleHotSpot), typeof(RectangleHotSpot) }; returntypes; } } } 

EditorAttribute

To associate an editor with a type, you must apply the System.ComponentModel.EditorAttribute metadata attribute to the type. You can also apply EditorAttribute to a property to associate an editor with the property. The second technique is useful when the property type does not have an associated editor or when you want to override the existing editor associated with the property type.

The constructor of EditorAttribute takes two arguments. The first argument specifies the type of the editor, and the second specifies the base type. The base type is UITypeEditor , which we examined earlier in this section, or System.ComponentModel.ComponentEditor , which we will describe in the next section.

The common syntax for the EditorAttribute uses an early-bound type reference to the editor, as shown in the following example:

 [ Editor(typeof(MSPress.ServerControls.Design.StringEditor), typeof(UITypeEditor)) ] publicoverridestringText{...} 

The type reference used in the constructor of EditorAttribute depends on the assembly location of the type relative to the assembly location of the editor associated with the type. The scenarios that require a late-bound reference (and their corresponding attribute syntax) are similar to those described in the "DesignerAttribute" section presented earlier in this chapter.