Programming

Custom Forms Designer: Toolbox and ToolboxService - Part 1

Mark Treadwell — Fri, 26 Oct 2007 03:41:24 GMT

Reminder: All posts in this series can be found here.

The Toolbox and the DesignSurface work together to allow a developer to add new components and controls to the design surface. There are two interfaces that implement this functionality: IToolboxService and IToolboxUser.

IToolboxService defines an interface that provides methods and properties to manage and query the Toolbox capabilities in a development environment. All forms designer systems must implement the IToolboxService in their Toolbox in order to provide the expected Windows Forms UI functionality. This service is added to the ServiceContainer and can be accessed at any time. There are 15 methods and two properties in the interface which I will not cover here in detail. Many of those methods deal with adding, deleting and selecting Toolbox items.

IToolboxUser defines an interface for setting the currently selected toolbox item and indicating whether a designer supports a particular toolbox item. A forms designer will implement an IToolboxUser interface that consists of only two methods: GetToolSupported and ToolPicked. You use GetToolSupported to filter the items that can be added onto the designer.

Implementation: There are several steps you have to take to build a Toolbox for a Forms Designer system.

Create a user interface that displays the tools to the user. This is typically implemented as a classic TreeView, or as sliding tree control that behaves much like Windows Explorer, but without grid or connection lines. Building the desired functionality can take quite a bit of time. There is a nice Code Project article that has a mostly-complete solution with multi-level tabs. There are several design decisions you will have to make before you start coding. Besides the visual representation already noted, you must decide how you will discover, categorize, and load the tools. One of the MSDN Magazine articles describes three methods: hard coding (not recommended), configuration file, and attribute decorated classes loaded from a known location and checked using reflection.
Implement the IToolboxService. The three main members of this interface are GetSelectedToolboxItem, SerializeToolboxItem, and DeserializeToolboxItem. Other useful members include GetCursor, IsSupported, IsToolboxItem, and SelectedToolboxItemUsed.
Plug the IToolboxService implementation into the design-time environment.
Create a keyboard interface.
Handle Toolbox events, such as tool selection, keyboard, mouse clicks and drag and drop.

Usage: There are four ways a developer can add a component or control to a forms designer DesignSurface; one uses the keyboard, while the other three use the mouse. The Visual Studio Toolbox functions are described here. I will talk about the changes required to the sample application to implement the Visual Studio functionality in Part 2 of this post.

Keyboard: The Visual Studio Toolbox keyboard interface is described here. Essentially, you Ctrl+Tab/cursor to the Toolbox (or press Ctrl+Alt+X), cursor to the desired control and hit Enter. The control will be added to the DesignSurface. Ctrl+Up Arrow, Ctrl+Down Arrow, Left Arrow, and Right Arrow also have control functions within the Toolbox.
Mouse: Double-Click a Toolbox icon. The control will be added to the DesignSurface. This has the same effect as using the keyboard method.
Mouse: Single Click a Toolbox icon. Move the cursor over the DesignSurface, were it will turn to a Crosshair ready for you to click and drag the desired control location and size. Visual Studio customizes the Crosshair cursor with color overlay of the selected tool icon until the mouse has been clicked and released. This operation can be canceled with the Esc key.
Mouse: Drag and Drop a Toolbox icon. Click a control icon, drag it onto the DesignSurface, and drop it where you want it. This operation can be canceled with the Esc key.

To allow the icons from the Toolbox to be added to the DesignSurface using the mouse or keyboard, the Toolbox in the sample code hooks onto the KeyDown and MouseDown events. IToolboxUser.ToolPicked is called for the Enter key or a mouse double-click. The sample code shows how to serialize the ToolboxItem into a DataObject and to DoDragDrop for when a mouse single-click event occurs. IToolboxService.SerializeToolboxItem will be called on mouse up and the item will be added to the designer.

When a new control or component is added to the DesignSurface from the Toolbox, the NameCreationService is used to give it a unique name. My discussion of this service and my modifications to the sample code are described here.

Custom Forms Designer: ServiceContainer

Mark Treadwell — Tue, 23 Oct 2007 02:15:32 GMT

Reminder: All posts in this series can be found here.

Simply, it is a container for services. Services are classes that have a well-known interface, that have instantiations which be stored in service containers, can be obtained from a service provider, and are addressable by type. The ServiceContainer class is a service provider and implements IServiceProvider. You obtain a service by supplying the Type of the service you want to the service provider's GetService method. The ServiceContainer.GetService method is declared like this.

public virtual Object GetService(Type serviceType);

This is how you obtain a a reference to a service in a class derived from DesignSurfaceManager or DesignSurface. The cast is required because GetService returns an Object.

INameCreationService serviceNameCreation = (INameCreationService)(this.GetService(typeof(INameCreationService)));

Both DesignSurfaceManager and DesignSurface implement ServiceContainer. This may appear to lead to confusion, but you do not have to keep track of which container holds what service. One of the nice features of using the DesignSurfaceManager class is that it automatically merges services between it and the DesignSurfaces.

There is no documentation of how to use these multiple implementations, but it makes sense to put general, non-DesignSurface services such as IHelpService, IDesignerEventService, and INameCreationService in the central DesignSurfaceManager ServiceContainer. DesignSurface-specific services such as ISelectionService would logically be with each DesignSurface.ServiceContainer.

MSDN states the following about the DesignSurfaceManager.ServiceContainer Property: The DesignSurfaceManager class provides several design-time services automatically. You can override each of these services by replacing them in the protected ServiceContainer property. To replace a service, override the constructor, call base, and make any changes through the protected ServiceContainer property. All services added to the service container that implement the IDisposable interface are disposed when the design surface manager is disposed. The DesignSurfaceManager class provides the IDesignerEventService interface as the default service. IDesignerEventService provides a global eventing mechanism for designer events. With this mechanism, an application is informed when a designer becomes active. The service provides a collection of designers and a single place where global objects, such as the Properties window, can monitor selection change events.

What is interesting here is that MSDN itself does not state what the default design-time services are. A MSDN Magazine designer hosting article provides a table of the default DesignSurface design-time services. An important part of that table is listing which services are not replaceable due to their interrelationships. I wrote some code to see what services were running in the two containers for the sample application and found the following.

HostSurfaceManager.ServiceContainer Services
--------------------------------------------
IDesignerEventService
INameCreationService
IToolboxService

HostSurface.ServiceContainer Services
--------------------------------------------
IComponentChangeService
IDesignerEventService
IDesignerHost
IExtenderListService
IExtenderProviderService
IInheritanceService
IMenuCommandService
INameCreationService
IReferenceService
ISelectionService
IToolboxService
ITypeDescriptorFilterService

This list matches almost perfectly with the default design-time service table noted above. It was not surprising to see the three HostSurfaceManager services were also visible from the HostSurface because the System.ComponentModel.Design.DesignSurfaceManager has a small bit of code in its MergedServiceProvider GetService method that looks like the following:

Object service = this._primaryProvider.GetService(serviceType);
if (service == null)
{
  service = this._secondaryProvider.GetService(serviceType);
}
return service;

The primary provider for the HostSurface is its own ServiceContainer. The secondary provider for the HostSurface is the HostSurfaceManager.ServiceContainer. As shown in the code snippet, any HostSurface service is preferred over an identical one in the HostSurfaceManager. Any service unavailable in the HostSurface but present in the HostSurfaceManager is accessible as well.

Custom Forms Designer: Name Creation Service

Mark Treadwell — Thu, 18 Oct 2007 22:12:15 GMT

Reminder: All posts in this series can be found here.

The first code I will look at is from one of the simplest services supporting the Windows Forms designer. The Name Creation Service is called each time you drop a control/component onto the visual design surface. Your job is to return a unique name for the new control that also means something.

The standard process, per convention, is to take the control/component Type name, camel case it (lower case the first letter) since it will be a member variable, and then append a digit suffix to make it unique from all other controls/components on the form. The number ensures it remains unique for languages which are not case sensitive.

The sample code implements only the INameCreationService.CreateName method. I modeled my implementation off of the sample code for INameCreationService here. I found the sample CreateName code to be excessively complex:

    string INameCreationService.CreateName(IContainer container, Type type)
    {
      ComponentCollection cc = container.Components;
      int min = Int32.MaxValue;
      int max = Int32.MinValue;
      int count = 0;
      for (int i = 0; i < cc.Count; i++)
      {
        Component comp = cc[i] as Component;
        if (comp.GetType() == type)
        {
          count++;
          string name = comp.Site.Name;
          if (name.StartsWith(type.Name))
          {
            try
            {
              int value = Int32.Parse(name.Substring(type.Name.Length));
              if (value < min)
                min = value;
              if (value > max)
                max = value;
            }
            catch (Exception ex)
            {
              Trace.WriteLine(ex.ToString());
            }
          }
        }
      }
      if (count == 0)
        return type.Name + "1";
      else if (min > 1)
      {
        int j = min - 1;
        return type.Name + j.ToString();
      }
      else
      {
        int j = max + 1;
        return type.Name + j.ToString();
      }
    }

My implementation is simpler:

    String INameCreationService.CreateName(IContainer container, Type dataType)
    {
      if (dataType == null)
      {
        throw new ArgumentNullException("dataType");
      }
      // The base component name is the Type name with the first character lower case
      String name = Char.ToLower(dataType.Name[0]) + dataType.Name.Substring(1);
      int number = 1;
      // If the container parameter is null, no container search is needed
      if (container != null)
      {
        // Increment counter until we find a name that is not in use
        while (container.Components[name + number.ToString()] != null)
        {
          ++number;
        }
      }
      return (name + number.ToString());
    }

I also added implementations of INameCreationService.IsValidName and INameCreationService.ValidateName. The IsValidName method returns a Boolean and does not throw any exceptions. The ValidateName method can throw an exception to return the exact reason why the candidate name fails. Generally, the code structure of the two methods should be similar, differing primarily in how they communicate an error back to the developer.

    bool INameCreationService.IsValidName(String name)
    {
      // Cannot be null or empty
      if (String.IsNullOrEmpty(name))
      {
        return false;
      }
      // Cannot start with a number
      UnicodeCategory uc = Char.GetUnicodeCategory(name, 0);
      if (uc == UnicodeCategory.DecimalDigitNumber)
      {
        return false;
      }
      // Cannot have anything other than letters and numbers
      foreach (Char c in name)
      {
        uc = Char.GetUnicodeCategory(c);
        switch (uc)
        {
          case UnicodeCategory.UppercaseLetter:
          case UnicodeCategory.LowercaseLetter:
          case UnicodeCategory.TitlecaseLetter:
          case UnicodeCategory.DecimalDigitNumber:
            break;
          default:
            return false;
        }
      }
      return true;
    }

    void INameCreationService.ValidateName(String name)
    {
      // Cannot be null
      if (name == null)
      {
        throw new ArgumentNullException("name");
      }
      // Cannot be empty
      if (name.Trim().Length == 0)
      {
        throw new ArgumentException("name cannot be of zero length");
      }
      // Cannot start with a number
      UnicodeCategory uc = Char.GetUnicodeCategory(name, 0);
      if (uc == UnicodeCategory.DecimalDigitNumber)
      {
        throw new ArgumentException("name cannot start with a number");
      }
      // Cannot have anything other than letters and numbers
      foreach (Char c in name)
      {
        uc = Char.GetUnicodeCategory(c);
        switch (uc)
        {
          case UnicodeCategory.UppercaseLetter:
          case UnicodeCategory.LowercaseLetter:
          case UnicodeCategory.TitlecaseLetter:
          case UnicodeCategory.DecimalDigitNumber:
            break;
          default:
            throw new ArgumentException("name must contain only letters and numbers");
        }
      }
      return;
    }

While there is a little more refactoring possible, that will be good enough for now.

Custom Forms Designer: A Restart

Mark Treadwell — Thu, 18 Oct 2007 01:02:32 GMT

Reminder: All posts in this series can be found here.

Some time ago, I started work on hosting the Windows Forms design surface in a project. Since that was nearly three years ago, I believe it was in the early .NET 2.0 days. My priorities got redirected and the project languished. A new project is clearly targeted at achieving the same goal, so I am back to building a solid implementation to get a beta front end out the door.

Those old posts are still of good use to remind me of everything I have forgotten in the interim:

Microsoft has subsequently posted a much more complete MSDN Magazine sample:

The Perfect Host: Create And Host Custom Designers With The .NET Framework 2.0 (download code)

I am using this sample as the basis for a new project which has a Windows Forms design surface at its heart. The main application will control the execution of a suite of 30 or so training applications in a standalone network. The instructor will be able to control everything from a central computer, remote boot the computers, group the computers together into teams/rooms, remote start individual applications on the computers, assign the teams to specific training exercises, monitor the status of the exercises, and remote stop the applications, and remote shut down the computers.

The use of the Windows Forms design surface will allow me to use custom Windows controls to represent the computers, groups, and rooms. This removes a significant amount of the complexity from the application. The tradeoff is the implementation of the Windows Forms design surface details are nontrivial, but not too difficult.

The first thing I did with the sample was to customize the code to my layout tastes (Ctrl+E, D), deleting and adding blank lines as I scanned through the files. Recompile. Change the namespaces to fit our development scheme. Recompile after each. Extract extra types where there was more than one in a file, again to match our standards. Recompile. Change the executable names and compile locations. Recompile. Add our assembly attributes. Recompile. Clean up the using statements at the top of the code files. Recompile.

OK. Now I feel like I can do some coding.

Tafiti Search

Mark Treadwell — Fri, 21 Sep 2007 15:02:16 GMT

Microsoft announced the availability of a new Tafiti experimental search front-end based on Silverlight. I tried out the Halo 3 branded system, and it is visually very nice and functionally very smooth.

However, as a search engine front-end, it is currently a failure. I sent the team the following feedback:

Sorry guys, but I have to grade it as a complete failure.
1) You completely fail to operate under a common setting (popup blocker set at medium) in your own browser (IE7)
2) You cannot bypass #1 using a Ctrl-Click
While it looks spiffy, it is useless.

They need to test more usage scenarios.

More About a Generic Range Class

Mark Treadwell — Sat, 02 Jun 2007 18:41:57 GMT

Technorati Tags: generic range class, C#

First there was Jay Bazuzi and his article and follow-up with a simple Range class. I referred to those postings when I did a generic range class for a project I had. Now Sean Hederman has posted a CodeProject article with his generic range class. Very nice!

.NET Naming Debacle - 2

Mark Treadwell — Mon, 04 Dec 2006 00:23:00 GMT

Almost five months ago, I wrote that "Microsoft screwed up big for customer confusion" with the whole .NET 3.0 naming thing. I got a few defensive comments about how the whole effort was great. Well, let's see. Today I read a post from a member of the Microsoft Architecture Editorial Board (whatever that exactly is). You know it is not going well when the post starts out with, "There has been considerable confusion about the differences between various versions of the .NET framework."

My point exactly. It was an implied contract that (.NET Version) == (CLR Version). Now that they broke that implied contract and completely screwed up the explanations, they have mea culpa posts continuing to flow, even after five months have passed. It is difficult to explain yourself out of a marketing ploy that is counter intuitive.

Want more pretzel logic? Check this out.

Yes, the current plan is to keep CLR 2.0 for a long time and just keep gluing on additional bits. Will we be ending up with .NET 3.5 based on CLR 2.0 and be using C# 3.0? Kinda looks like it. Great ready for the Java versioning disaster to arrive in a .NET Framework near you soon!

Addendum: My take is that "Fx 3.0" should have been Version 2.1. "Fx 3.5" should be Version 2.2 (or 2.5 at best). Microsoft has dumped the minor versions of most everything and is stuck with must-major-version-everything-itis.

Windows PowerShell Jump Start

Mark Treadwell — Thu, 30 Nov 2006 10:45:00 GMT

There are several friendly pages to help you get going. Assuming you are starting with VBScript, Microsoft has a Converting VBScript Commands to Windows PowerShell Commands page which will be your friend as you explore. Learn from their Task-Based Guide to Windows PowerShell Cmdlets. Get working examples from the Script Center Script Repository, and do not forget the Tools and Utilities. Download the latest version here.

Google Code Search - Finding Hidden Evils

Mark Treadwell — Wed, 11 Oct 2006 19:50:00 GMT

It is sometimes amazing what those crazy programmers put in their comments!

Bad programmers! Bad! I personally try to not use “Hard K” words. Again /. is on it.

Google Code Search - Use and Misuse

Mark Treadwell — Sun, 08 Oct 2006 12:18:00 GMT

I have been playing around with this new (test) feature and have a few more comments.

First, it is irritating that it does not yet respect your search customizations. I like 100 results per page, but Code Search puts up 10 whether you want it or not.

Second, it is evident that quite a bit more of the published source code from books is now easily findable. The publishers switched from floppies to CD-ROM and later removed CD-ROMs from books to cut costs. They probably did not think their book code would be reachable this easily.

Third, there is quite a bit of application sample code that shows the default connection strings for databases. For example, this search page for “password” gives you the default data for an Oracle login with the helpful comment “a base string is created and options are added this uses the hr schema with the default password make sure to adjust this for your environment.” /. is on it.