Export (0) Print
Expand All
Abortable Thread Pool
The Analytic Hierarchy Process
API Test Automation in .NET
Asynchronous HttpWebRequests, Interface Implementation, and More
Bad Code? FxCop to the Rescue
Basics of .NET Internationalization
Behind the Scenes: Discover the Design Patterns You're Already Using in the .NET Framework
BigInteger, GetFiles, and More
Binary Serialization of DataSets
Building Voice User Interfaces
Can't Commit?: Volatile Resource Managers in .NET Bring Transactions to the Common Type
CLR Inside Out: Base Class Library Performance Tips and Tricks
CLR Inside Out: Ensuring .NET Framework 2.0 Compatibility
CLR Inside Out: Extending System.Diagnostics
CLR Profiler: No Code Can Hide from the Profiling API in the .NET Framework 2.0
Concurrent Affairs: Build a Richer Thread Synchronization Lock
Custom Cultures: Extend Your Code's Global Reach With New Features In The .NET Framework 2.0
Cutting Edge: Collections and Data Binding
Const in C#, Exception Filters, IWin32Window, and More
Creating a Custom Metrics Tool
DataGridView
DataSets vs. Collections
Determining .NET Assembly and Method References
Experimenting with F#
File Copy Progress, Custom Thread Pools
Finalizers, Assembly Names, MethodInfo, and More
Got Directory Services?: New Ways to Manage Active Directory using the .NET Framework 2.0
High Availability: Keep Your Code Running with the Reliability Features of the .NET Framework
How Microsoft Uses Reflection
ICustomTypeDescriptor, Part 2
ICustomTypeDescriptor, Part 1
Iterating NTFS Streams
JIT and Run: Drill Into .NET Framework Internals to See How the CLR Creates Runtime Objects
Lightweight UI Test Automation with .NET
Low-Level UI Test Automation
Make Your Apps Fly with the New Enterprise Performance Tool
Managed Spy: Deliver The Power Of Spy++ To Windows Forms With Our New Tool
Memory Models: Understand the Impact of Low-Lock Techniques in Multithreaded Apps
Microsoft Java Virtual Machine Update
Microsoft .NET Framework Delivers the Platform for an Integrated, Service-Oriented Web, Part 2
Mini Dump Snapshots and the New SOS
Mutant Power: Create A Simple Mutation Testing System With The .NET Framework
NamedGZipStream, Covariance and Contravariance
.NET Internationalization Utilities
.NET Profiling: Write Profilers With Ease Using High-Level Wrapper Classes
No More Hangs: Advanced Techniques To Avoid And Detect Deadlocks In .NET Apps
The Perfect Host: Create and Host Custom Designers with the .NET Framework 2.0
Phoenix Rising
Scheme Is Love
Security Enhancements in the .NET Framework 2.0
Sepia Tone, StringLogicalComparer, and More
Software Testing Paradoxes
Stay Alert: Use Managed Code To Generate A Secure Audit Trail
Stream Decorator, Single-Instance Apps
StringStream, Methods with Timeouts
SUPERASSERT Goes .NET
Tailor Your Application by Building a Custom Forms Designer with .NET
Test Harness Design Patterns
ThreadPoolPriority, and MethodImplAttribute
ThreadPoolWait and HandleLeakTracker
Three Vital FXCop Rules
A Tidal Wave of Change
To Confirm is Useless, to Undo Divine
Touch All the Bases: Give Your .NET App Brains and Brawn with the Intelligence of Neural Networks
Transactions for Memory
Trustworthy Software
Tune in to Channel 9
UDP Delivers: Take Total Control Of Your Networking With .NET and UDP
UI on the Fly: Use the .NET Framework to Generate and Execute Custom Controls at Run Time
Unexpected Errors in Managed Applications
Unhandled Exceptions and Tracing in the .NET Framework 2.0
Using Combinations to Improve Your Software Test Case Generation
Wandering Code: Write Mobile Agents In .NET To Roam And Interact On Your Network
What Makes Good Code Good?
XML Comments, Late-bound COM, and More
Expand Minimize
19 out of 21 rated this helpful - Rate this topic

Writing Custom Designers for .NET Components

 

Shawn Burke
Microsoft Corporation

June 2001

Summary: This article covers the various features of designers, how to associate them with components, and how to use those features to create great design time user interface. (17 printed pages)

Contents

Introduction
What Is a Designer Anyway?
How Does a Component Get a Designer?
Modifying State for Design Time
Defining Component Relationships
Using a Designer to Change a Component's Properties, Attributes, or Events
Simplifying Common Tasks
Playing Nicely With Others
Conclusion

Introduction

The .NET Framework was built with extensibility in mind. Because the same engineers designed and implemented the runtime and design time portions of the .NET Framework, users will be able to exploit much tighter integration than in any other framework or class library.

One of the key aspects of this integration is the interplay between the runtime and design time portions of the code-base. While the runtime code can be kept separate from the design time code, the design time portion can exert a great deal of influence over a component's behavior and appearance at design time.

First, let's discuss the usage of the word "designer" for a moment. Generally, it means any .NET object that is responsible for managing the design time behavior of a component or family of components. But sometimes "designer" refers more globally to the design time UI in Microsoft® Visual Studio® .NET for designing Windows® Forms, Web Forms, or Components. For the purpose of this article "designer" refers to a designer for a specific component rather than the full VS. NET designer unless otherwise noted.

This article will cover the various features of designers, how to associate them with components, and how to use those features to create great design time UI.

What Is a Designer Anyway?

As mentioned above, a designer is an object that is responsible for managing the design time behavior and appearance of components on the design surface. Specifically, designers implement the System.ComponentModel.Design.IDesigner interface.

public interface IDesigner : IDisposable {

        IComponent Component {get;}        
        DesignerVerbCollection Verbs {get;}
        void DoDefaultAction();
        void Initialize(IComponent component);
}

Generally, you will never have to write one of these from scratch. All of the designers that are included in the .NET Framework SDK derive from the default implementation in System.ComponentModel.Design.ComponentDesigner. Any object that implements IComponent (which usually means it derives from Component) will automatically get ComponentDesigner as its designer. There are other types of designers that implement System.ComponentModel.Designer.IRootDesigner, called "root designers" that allow a component to be the "root" object in the Visual Studio .NET design environment. Types such as System.Windows.Forms.Form and System.Windows.Forms.UserControls have root designers that allow them to be shown in design view as well as code view in VS .NET. A given type can have multiple designers associated with it, but only one of each type. For the purpose of this article, the features of standard IDesigner implementations will be explored.

Most designers perform three basic tasks:

  • Creating or modifying design time UI for the component that is being designed
  • Modifying the sets of Properties, Attributes, and Events exposed by the component being designed
  • Adding actions, called Verbs, that can be performed on a component at design time

At design time, the VS .NET designer infrastructure attaches a designer to each component that is "sited." That is, each component that gets a name and connection that allows it to access underlying designer services. Each designer is then given an opportunity to participate in the interaction with the user, the VS .NET designer, and operations like code-generation and persistence.

Figure 1.

How Does a Component Get a Designer?

The power and flexibility of metadata (information attached to classes, properties, methods, or events) is utilized throughout the .NET Framework, and designers are no exception. Designers are associated with components using the System.ComponentModel.DesignerAttribute attribute. This attribute's constructor can take an Assembly-qualified string type name, or an actual type reference. The string form is convenient because it allows the designer portions of a component to be completely separated from the runtime portions. With the runtime and the designer in separate assemblies, component vendors can minimize the size of their runtime redistributables. Conversely, the DesignerAttribute constructor can take an actual Type reference if the designer is contained in the same Assembly or one that will always be available. Using the string format can also help avoid difficult circular build dependency issues, however, since the designer type doesn't have to be available at compile time. The samples here will use the type reference method for simplicity.

For example if the component was called MyCompany.SysComponent in MyCompany.dll, and the designer was called MyCompany.Design.SysComponentDesigner in MyCompany.Design.dll:

namespace MyCompany {
[Designer("MyCompany.Design.SysComponentDesigner, MyCompany.Design")]
public class SysComponent : Component {
}
}

namespace MyCompany.Design {
   internal class SysComponentDesigner : ComponentDesigner {
      // …
}
}

However, the designer can also be included in the assembly with the component itself, such as in a nested class, which can be public, protected, or internal:

namespace MyCompany {
[Designer(typeof(SysComponentDesigner))]
public class SysComponent : Component {
   
internal class SysComponentDesigner : ComponentDesigner{
// …
}
}
}

The benefit of using an actual type reference is that the compiler will complain if the reference is wrong; an assembly-qualified string name does not give you that benefit.

The System.ComponentModel.Design.IDesignerHost interface allows access to designers for components on the design surface. With an IServiceProvider (such as the ISite attached to an IComponent through its Site property at design time), any component's designer can be accessed with the IDesignerHost.GetDesigner method. Here we use Visual Basic .NET code to access the verbs on a given component. Verbs will be discussed later in this article.

Public Function GetComponentVerbs(ByVal comp As IComponent) As DesignerVerbCollection
        If (comp.Site <> Nothing) Then
            Dim host As IDesignerHost
            host = comp.Site.GetService(GetType(IDesignerHost))
            If (host <> Nothing) Then
                Dim designer As IDesigner
                designer = host.GetDesigner(comp)
                If (designer <> Nothing) Then
                    Return designer.Verbs
                End If
            End If
        End If
        Return New DesignerVerbCollection()
End Function

Modifying State for Design Time

In many cases, it is undesirable for a control or a component to act the same on the design surface as in a running application. For example, a timer control should not be processing timer events at design time, or a system monitor control should not be hooking system events. Designers provide a simple way of controlling this.

As an example, imagine a custom control that can accept drag/drop input, such as the RichEdit control. Clearly, on the design surface it would be confusing to be able to drag text or files into this control. To solve this, a designer can be made to disable drag/drop support in the control.

public class DragDropControlDesigner : ControlDesigner {
      public override void Initialize(IComponent c) {
         base.Initialize(c);
         ((Control)c).AllowDrop = false;
      }
   }

In this case, the designer sets the AllowDrop property of the Control that it is associated with false. Notice that Initialize is called on the base class before any actions are performed. This is very important; the call to the base Initialize method allows the base designer classes to set up their state before they are accessed. Also notice that the parameter to Initialize is an IComponent. This is the object instance of the component that is being designed. It is accessible from within all ComponentDesigner-based designers as the ComponentDesigner.Component property. If you are writing a designer based on ControlDesigner, it exposes a property called "Control," which allows you to access the Control that is being designed. In most circumstances, this instance value will be equal to the one returned from ComponentDesigner.Component, yet it saves the overhead and clutter of casting all the time. Theoretically, however, you could use this to write a designer for a non-Control based on ControlDesigner and override this Control property to return the UI for the component being designed.

ControlDesigner performs several operations similar to the above sample. Since the designer manipulates live instances of components, a Control must be both visible and enabled in order to be useful on the design surface. If it is not it would either be invisible or ineligible to receive mouse or keyboard input and therefore could not be moved around. So within ControlDesigner.Initialize, Visible and Enabled are both forced to true.

Defining Component Relationships

Some components have related components that may or may not be on the design surface. For example, ToolBar control buttons are actually components themselves. The same goes for TabPages on a TabControl. If one were to copy a Toolbar from one form and paste it onto another, it would not be very handy to copy only the ToolBar itself and leave the buttons behind. This scenario also applies to a GroupBox with child controls on it, or a MainMenu with submenu items. How can this be handled in a generic way?

On ComponentDesigner, there is a property called AssociatedComponents to solve just this problem. Whenever a drag or cut/copy operation operates on a component, the VS .NET designer recursively walks the AssociatedComponents property of each component's designer to determine the full set of objects to drag, cut, or copy.

In the example below, MainComp returns all of its SubComp members as its AssociatedComponents. SubComp components return only those SubComps that are sited in the VS .NET designer. Components sometimes initialize their state with items in their collections that aren't part of the designer generated elements. If a MainComp is cut and pasted to another form or component designer, it will include all of its SubComps and any sited SubComps of each SubComp. Wow, that's a mouthful!

[Designer(typeof(MainComp.MainCompDesigner))]
public class MainComp : Component {

   public SubCompCollection SubComponents {
      get {   
         return subCollection;
      }
   }

   internal class MainCompDesigner : ComponentDesigner {
      public override ICollection AssociatedComponents{
         get{
            return ((MainComp)base.Component).SubComponents;
         }
      }
   }
}

[DesignTimeVisible(false)]
[Designer(typeof(SubComp.SubCompDesigner))]
public class SubComp : Component {
   public SubCompCollection SubSubComponents {
      get {   
         return subCollection;
      }
   }
   internal class SubCompDesigner : ComponentDesigner {

      public override ICollection AssociatedComponents{
         get{
            // Only return sited subs in this case.  
            // For example, this component could have 
            // a number of sub components that were 
            // added by the component and aren't sited 
            // on the design surface.  We don't want 
            // to move those around.
            //
            ArrayList comps = new ArrayList();
            foreach (SubComp sc in 
               ((SubComp)Component).SubSubComponents) {
               if (sc.Site != null) {
                  comps.Add(sc);
               }
            }
            return comps;
         }
      }
   }
}

Using a Designer to Change a Component's Properties, Attributes, or Events

The most common application of designers is adjusting how a component appears on the design surface. There are many cases in which it is desirable to modify or add properties of a component at design time. The VS .NET designer already adds many properties to each component on the design surface, such as the "(Name)" property, or the "Locked" property. These properties don't actually exist on the component being designed. The attributes on properties can also be modified. Most often, a designer wants to intercept or "shadow" certain properties on components. By shadowing a property, the designer keeps track of the value the user sets and can choose whether to pass that change down to the actual component.

In the case of a Control.Visible and Control.Enabled, this prevents the Control from actually becoming invisible or disabled, or in the case of Timer.Enabled, it prevents it from waking up and beginning to send timer tick events. These properties are available at design time but don't affect the state of the component on the design surface. This "shadowing" can easily be done with any ComponentDesigner-based designer.

First, ComponentDesigner has three sets of methods that allow you to modify the properties exposed by a component that is being designed:

  • PreFilterProperties
  • PostFilterProperties
  • PreFilterAttributes
  • PostFilterAttributes
  • PreFilterEvents
  • PostFilterEvents

The general rule to follow is to add or remove items in the "PreFilter" methods, and modify existing items in the "PostFilter" methods. Always call the base method first in the PreFilter methods and call the base method last in the PostFilter methods. This ensures that all designer classes are given the proper opportunity to apply their changes. ComponentDesigner also has a built-in dictionary for storing and retrieving the shadowed values. This saves the designer author the trouble of creating member variables for all the shadowed properties.

Let's use a simplified version of ControlDesigner as an example. This designer will shadow the Visible and Enabled properties, and add a property called "Locked".

public class SimpleControlDesigner : ComponentDesigner {

   bool locked;

   public bool Enabled {
      get {
         return (bool)ShadowProperties["Enabled"];
      }
      set {
         // note this value is not passed to the actual
         // control
         this.ShadowProperties["Enabled"] = value;
      }
   }
   private bool Locked {
      get {
         return locked;
      }
      set {
         locked = value;            
      }
   }

   public bool Visible {
      get {
         return (bool)ShadowProperties["Visible"];
      }
      set {
         // note this value is not passed to the actual
         // control
         this.ShadowProperties["Visible"] = value;
      }
   }

   public void Initialize(IComponent c) {
      base.Initialize(c);
      Control control = c as Control;

      if (control == null) {
         throw new ArgumentException();
      }

      // pick up the current state and push it
      // into our shadow props to 
// initialize them.
      //
      this.Visible = control.Visible;
      this.Enabled = control.Enabled;

      control.Visible = true;
      control.Enabled = true;
   }

protected override void PreFilterProperties(
IDictionary properties) {
        base.PreFilterProperties(properties);
        
      // replace Visible and enabled with our shadowed versions.
      //
      properties["Visible"] = TypeDescriptor.CreateProperty(
               typeof(SimpleControlDesigner), 
               (PropertyDescriptor)properties["Visible"], 
               new Attribute[0]);
      properties["Enabled"] = TypeDescriptor.CreateProperty(
               typeof(SimpleControlDesigner), 
               (PropertyDescriptor)properties["Enabled"], 
               new Attribute[0]);

      // and add the locked property
      //
      properties["Locked"] = TypeDescriptor.CreateProperty(
               typeof(SimpleControlDesigner), 
               "Locked", 
               typeof(bool), 
               CategoryAttribute.Design, 
               DesignOnlyAttribute.Yes);
      }
    
}

Notice how the Initialize method is used to populate the shadow properties with the values from the components. Also notice that the "Locked" property has the "DesignOnlyAttribute.Yes" added to it, and that it is private. Even though it is marked as private, it can be accessed through reflection since the hookup was done from code that has access to the property. The DesignOnlyAttribute marks this property as valid at design time only so it won't be generated as code for the component (design only properties are persisted in a resource stream).

The TypeDescriptor.CreateProperty call creates a PropertyDescriptor based on either an existing PropertyDescriptor (as is the case with Visible and Enabled) or creates a new one. Because the properties are all defined on the SimpleControlDesigner class, "typeof(SimpleControlDesigner)" is specified as the component type for each property created. This tells the runtime which type of object instance to expect if this property is set or accessed. One caveat: be sure not to use "GetType()" instead of the static typeof expression if your designer class can be derived from. In the derived class, GetType() will return a different value and can cause problems accessing the property.

As far as other objects on the design surface are concerned, the properties defined on the designer are the exposed properties for the object. This shadowing has hidden the original Visible and Enabled properties from other objects in the design environment, including code generation and persistence for these objects. It is for this reason that we are able to provide the values the user intended rather than the values that have been applied to the live object instances living on the designer.

Simplifying Common Tasks

If your component has common actions that are performed on it, it is often useful to expose these actions as a "verb" from the component. To see verbs in action, drop a TabControl on the VS .NET Windows Forms designer and you will see two hyperlinks show up in the property browser. One says "Add Tab" and one says "Remove Tab." As the names suggest, these actions will add or remove a tab from the TabControl. You will also see these verbs on the context menu if you right-click on the TabControl itself.

Adding verbs is simple to do. The IDesigner interface has a "verbs" property that you can override and return a collection of DesignerVerb objects. DesignerVerbs are objects that contain a verb's string name, the delegate to invoke when the verb is invoked, and optionally a command ID if one is to be assigned. Normally, the VS .NET designer architecture dynamically assigns ID's to verbs. As an example, below is a designer for a control that derives from Button. It adds three verbs, "Red," "Green," and "Blue," that change the Control's back color to one of those values. Note ControlDesigner has a property called "Control" that returns the Control that the designer is attached to.

[Designer(typeof(ColorButton.ColorButtonDesigner))]
   public class ColorButton : System.Windows.Forms.Button
   {
       internal class ColorButtonDesigner : ControlDesigner {

            private DesignerVerbCollection verbs = null;

      private void OnVerbRed(object sender, EventArgs e) {
         Control.BackColor = Color.Red;
      }

      private void OnVerbGreen(object sender, EventArgs e){
         Control.BackColor = Color.Green;
      }

      private void OnVerbBlue(object sender, EventArgs e) {
         Control.BackColor = Color.Blue;
      }

      public override DesignerVerbCollection Verbs {
         get {
                   if (verbs == null) {
            verbs = new DesignerVerbCollection();
                       verbs.Add(
                            new DesignerVerb(
                                 "Red", 
                                 new EventHandler(OnVerbRed)));
                   verbs.Add(
                            new DesignerVerb(
                                "Blue", 
                                new EventHandler(OnVerbBlue)));
                   verbs.Add(
                            new DesignerVerb(
                                "Green", 
                                new EventHandler(OnVerbGreen)));
                    }
               return verbs;
         }
      }
      }
   }

Figure 2.

Playing Nicely With Others

When a designer makes modifications to the state of the component it is responsible for, other objects within the VS .NET designer may be interested in that change. For example, if your designer changes the background color of a Control to red, the property browser should show this updated information. Generally, changes in component state are broadcast through the IComponentChangeService. Many other services within the VS .NET designer listen to the IComponentChangeService, including the code persistence engine, undo/redo facilities, and the property browser, and update state if components that they are concerned about are included in the change notifications.

IComponentChangeService works by giving notice that a component is about to change, and then again after a component has changed. There are two primary notifications that can be raised by any client, OnComponentChanging and OnComponentChanged. OnComponentChanging must be fired before an OnComponentChanged, but OnComponentChanged does not need to be called after an IComponentChanging. This may occur if an action is aborted for some reason. IComponentChangeService also has several events for listening to notifications:

  • ComponentChanging
  • ComponentChanged
  • ComponentAdding
  • ComponentAdded
  • ComponentRemoving
  • ComponentRemoved
  • ComponentRename

The service only allows ComponentChanging and ComponentChanged to be fired manually. The other events are fired by the designer infrastructure when components are added, removed, or renamed on the VS .NET designer surface.

When you set a property value through a PropertyDescriptor, component change notifications are automatically sent, so that is the easiest way to do the proper notifications.

In the example above, if we were to use PropertyDescriptors to notify the change (so the property browser updates automatically), we would change the verb handlers to look like the following:

private void OnVerbGreen(object sender, EventArgs e){
PropertyDescriptor backColorProp = 
      TypeDescriptor.GetProperties(Control)["BackColor"];
   
   if (backColorProp != null) {
      backColorProp.SetValue(Control, Color.Green);
}
}

There are sometimes cases where changing the value of one property may affect the other, or cases where many property changes will be done at once. For performance reasons, it is often preferable to act directly on the object (rather than through the PropertyDescriptors), and fire the notifications later. Invoking or setting a property through a PropertyDescriptor is slower than accessing directly.

Think of radio buttons for a moment. When you change the value of a radio button to true, all the other instances of radio buttons on the same parent change their values to false. The runtime code handles this automatically, but it is polite to tell the designers about the change. In this case we shadow the Checked property so we can intercept the value change when it occurs. When the value is set to true, we iterate through the siblings of the radio button, and notify IComponentChangeService for any radio button siblings whose Checked properties have changed. We do this by using the GetService call on ComponentDesigner to get a hold of an instance of the IComponentChangeService and then calling on that instance.

internal class RadioButtonDesigner : ControlDesigner {

   public bool Checked  {
      get {
         // pass the get down to the control.
         //
         return ((RadioButton)Control).Checked;
      }
      set {
         // set the value into the control
         //
         ((RadioButton)Control).Checked = value;

         // if the value for this radio button
         // was set to true, notify that others have changed.
         //
         if (value) {
            IComponentChangeService ccs = 
               (IComponentChangeService)
            GetService(typeof(IComponentChangeService));
            if (ccs != null) {
               PropertyDesciptor checkedProp = 
                   TypeDescriptor.GetProperties(
typeof(RadioButton))["Checked"];
               foreach(RadioButton rb in 
                  Control.Parent.Controls) {
                  if (rb == Control || 
!(rb is RadioButton)) 
continue;
                  
                  ccs.OnComponentChanging(
rb, checkedProp);
                  ccs.OnComponentChanged(rb, 
                     chedkedProp, null, null);
               }
            }
         }
      }
   }

   protected override void PreFilterProperties(
                     IDictionary properties) {
      base.PreFilterProperties(properties);
      // shadow the checked property so we can intercept the set.
      //
      properties["Checked"] = 
TypeDescriptor.CreateProperty(               typeof(RadioButtonDesigner), 
               (PropertyDescriptor)properties["Checked"], 
               new Attribute[0]);
   }
}

Conclusion

Designers can be written for any object that implements IComponent and is sited on the design surface. This goes for Windows Forms controls, Web Forms controls, or any other type of components. Attaching designers allows components to have a different shape presented to the user and allows runtime and design time code to live separately, minimizing redistributable sizes and helping component authors have more control over how their components are used.

Including an extensible, object oriented set of design time interfaces and classes with the .NET Framework gives abilities for control and customization never before available in a framework. Using these capabilities to their fullest extent ensures that components can have usable, rich design time and runtime object models.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.