In part 1 and part 2 of this series, we explained some common techniques for creating complex ILOG Diagrammer for .NET user symbols, and we used a UMLType symbol as an example.

This post will focus on the description of the List user symbol that is used to display the attributes and operations of the UML type. This List symbol is pretty general, and could be reused in other situations.

You can look at the same source code as in the previous post to follow the explanations, since the List symbol was already there.

Here are the graphic elements of the List symbol:

The symbol is made of a DockPanel that contains a StackPanel (which will in turn contain the list items), and three groups of graphic objects that make up a scrollbar (the ‘up’ button, the thumb and the ‘down’ button). We do not want to use a predefined ILOG Diagrammer for .NET VScrollBar object here because it is a little too big for including it in our UMLType symbol.

Let’s look at the code to see how the List symbol works. First, we need a property to add items to the list:

        [DesignerSerializationVisibility(DesignerSerializationVisibility.Content)]
        public Collection<GraphicObject> Items
        {
            get
            {
                return stacker.Objects;
            }
        }

The Items property just returns the Objects property of the nested StackPanel, so the items of the list will be added directly to the stacker. Note the DesignerSerializationVisibility attribute that makes sure the items will be serialized even though the collection property itself is read-only.

Now, we want our list to be scrollable (vertically only to keep it simple). For this, we add another property that will define the scroll position:

        [DefaultValue(0)]
        public int ScrollPosition
        {
            get
            {
                return scrollPosition;
            }
            set
            {
                if (value != scrollPosition)
                {
                    scrollPosition = value;
                    InvalidateLayout();
                }
            }
        }

The ScrollPosition is an integer, as it specifies a number of items (not a position in pixels): this is simpler since we always want to scroll one whole item at a time.

As you can see, the ScrollPosition does not do much by itself, it just sets an internal member variable to the specified value and calls InvalidateLayout(). The idea is to use the built-in layout mechanism of Diagrammer for .NET to really do the scrolling. The InvalidateLayout() call tells Diagrammer for .NET to call the DoLayout() method of our symbol just before the symbol is next painted on the screen. This makes sure that the scrolling logic will not be executed several times unnecessarily.The DoLayout() method is overridden as follows:

        protected override void DoLayout()
        {
            dockPanel1.SuspendLayout();
            Rectangle2D bounds = new Rectangle2D(0, 0, Rectangle.Width, dockPanel1.Height);
            stacker.Bounds = bounds;
            stacker.PerformLayout();
            if (Items.Count != 0)
            {
                int pos = scrollPosition;
                if (pos >= Items.Count)
                    pos = Items.Count - 1;
                if (pos < 0)
                    pos = 0;
                bounds.Y = -Items[pos].Y;
                stacker.Bounds = bounds;
            }
            dockPanel1.ResumeLayout(true);
            UpdateArrows();
        }

What we do here is to move and resize the StackPanel that contains the items according to the ScrollPosition property and to the size of the List symbol. Basically, the top of the stacker is shifted vertically so that the item whose index is ScrollPosition is just at the top of the list. Note the SuspendLayout()/ResumeLayout() calls on the DockPanel that make sure that the parent’s layout is re-computed only once during this process. Finally, a method called UpdateArrows() is called: it enables or disables the up/down arrows according to the scroll position.

Let’s talks about the scrollbar now. The idea is simple: the ‘up’ bottom will decrease the ScrollPosition by 1, the ‘down’ button will increase it, and the thumb will modify the ScrollPosition proportionally to the move.If you look at the code,you will see that it is actually more complex than that:

•  We added timers so that, when you keep the left mouse button pressed in the ‘up’ or ‘down’ arrows, the list continues to scroll.
• We must ‘capture’ the mouse to make sure that, when we click in the thumb for instance, the mouse events will continue to move the thumb even if the mouse is not over it any more.

Just a final word: as it is, the List symbol is good enough as an element of the UMLType symbol, but it would need a little more polishing before it can be used as a standalone, general list object. In particular, it should behave as a container when it is used in the Visual Studio designer: see this other post that explains how to do this.

Note: this article requires the ILOG Diagrammer for .NET Patch 14 available on the ILOG Diagrammer for .NET support site.

What are Smart Tags

In short, Smart Tags are shortcuts for PropertySheet items accessible from the Visual Studio Design surface and specific to the current selected item. They are natively supported in the Visual Studio WinForms designer through the little arrow icon located at the top-right corner of the current selected object. Clicking on this icon pops up a menu (the Smart Tags panel) populated with items (the Smart Tags items). These items expose a reduced set of design-time configuration entries like properties or verbs (a verb describes a specific action to perform accessible from the PropertySheet). The following image shows the ListBox Smart Tags panel :

In Visual Studio, Smart Tags are exposed by means of DesignerActionItem instances. A DesignerActionItem defines the action to perform when the item is activated. It can be a simple property setter like what the Property Sheet provides, or a more advanced action handled through a method invocation. DesignerActionItem’s are accessible from the component’s ComponentDesigner through its DesignerActionList. When a component is selected, the Design environment asks the component designer for its DesignerActionList and populates the Smart Tags panel with the DesignerActionItem’s.

Smart Tags in ILOG Diagrammer for .NET

ILOG Diagrammer for .NET extends the Smart Tags support to GraphicObject instances, which means that you can define Smart Tags the same way you do in a WinForms custom control. For example, the following pictures shows the Smart Tags items of a ClosedCurve :

To illustrate the article, we will use the UMLType user symbol described in the “Diagrammer Tips and Tricks” series and the following VS2008 Project.

As for a WinForms control, adding support for Smart Tags to an ILOG Diagrammer for .NET UserSymbol first requires a ComponentDesigner associated with the UserSymbol. For GraphicObject instances, the ILOG Diagrammer for .NET framework provides the GraphicObjectDesigner class that provides a set of services for GraphicObject design-time support. It is the base class we inherit from to implement our UMLType designer.

We then need to define the action items we want to add to the Smart Tag panel. For the UMLType user symbol, the TypeName, Attributes and Operations properties are good candidates. To show the different kind of possible action items, the TypeName property (which is of type String) will be exposed in the Smart Tags panel as a standard property in the same way it is exposed in a Property Sheet (that is as a description-textbox pair). The two others (which are specialized Collection) will be exposed as Verbs, which on the UI side are similar to hyperlinks that perform some actions (in our case, it pops up the Collection editor).

In term of implementation, it translates into the following steps :

• subclass DesignerActionList
• override the GetSortedActionItems() method to populate the list with the action items.
• handles the actions corresponding to the action items.
• Subclass GraphicObjectDesigner
• override the CreateActionList method to return an instance of the DesignerActionList subclass.

Implementing the DesignerActionList

The purpose of a DesignerActionList is to provide a list of Smart Tags items to the user symbol designer and to handle the action defined by the items. Populating the list of Smart Tags items is the purpose of the DesignerActionList.GetSortedActionItems() method which should be overriden to return the items that apply to the component. Let’s start with the TypeName property we want to expose since it is the simplest Smart Tags item type.

A property Smart Tags item is defined by the DesignerActionPropertyItem class in the System.ComponentModel.Design namespace. This class easily allows to expose a property in the Smart Tags panel so that it can be edited in-place. The constructor signature is defined as:

public DesignerActionPropertyItem(
    string memberName,
    string displayName,
    string category,
    string description)

The most important parameter is the memberName argument, which refers to the associated property of the DesignerActionList subclass. It means that the UMLType TypeName property must be duplicated on the DesignerActionList as a facade to the underlying UMLType component. Here is a first draft of the UMLTypeActionList implementation:

    class UMLTypeActionList : DesignerActionList {
        public UMLTypeActionList(IComponent component)
            : base(component) {
        }          

        public string TypeName {
            get { return ((UMLType)Component).TypeName; }
            set { UMLTypeDesigner.SetProperty(GetService(typeof(IDesignerHost)) as IDesignerHost,
                                              Component,
                                              value,
                                              "TypeName",
                                              "The name of the UML type.");
            }
        }          

        public override DesignerActionItemCollection GetSortedActionItems() {
            DesignerActionItemCollection items = new DesignerActionItemCollection();
            // The "TypeName" property
            items.Add(new DesignerActionPropertyItem("TypeName",
                                                     "Type name",
                                                     "UML",
                                                     "The name of the UML type."));
            return items;
        }
    }

In the code above, the TypeName property setter invokes the UMLTypeDesigner.SetProperty method, which is a convenient method allowing to perform an undoable property setting.

In order to be able to test our action list implementation, we need to implement the UMLType designer and associate it with the UMLType component so that the Design-time API supports it. As mentioned above, the UMLType designer inherits from the GraphicObjectDesigner class and in this simple use case, the only method we need to override is the CreateActionList() factory method that returns an instance of the UMLTypeActionList class. Here is the implementation:

    public class UMLTypeDesigner : GraphicObjectDesigner {
        protected override System.ComponentModel.Design.DesignerActionList CreateActionList() {
            return new UMLTypeActionList(this.Component);
        }
    }

Finally, the last step is to associate this designer class to the UMLType class by means of the DesignerAttribute class attribute:

    [Designer(typeof(UMLTypeDesigner), typeof(IDesigner))]
    public partial class UMLType : UserSymbol
    {
      ...
    }

Running the sample at this stage gives the following result (after having added our assembly to the Visual Studio Toolbox while in diagram editing mode) :

Ok. But what about use cases where you need more than just editing a property value ? For example, you may need to define complex actions like defining a data binding-like wizard-driven process that can be started from the Smart Tags panel. To address these use cases, the design-time API provides the DesignerActionMethodItem class which instead of relying on a property invokes a specified method that will handle the action. This is what we are going to use for the Operations and Attributes UMLType members. Instead of being exposed as a Property action item, they will be displayed as an “HyperLink”. When clicked, a modal dialog displaying the associated UITypeEditor (here the standard collection editor) will be shown.

Invoking the UITypeEditor from a Smart Tags item.

In the WinForms design-time API documentation, a UITypeEditor is defined as an editor “that can provide a user interface for representing and editing the values of objects of the supported data types”. In the sample we are writing, we will use the UITypeEditor associated with the Operations and Attributes properties and invoke its EditValue() method to edit the object’s value. Typical UITypeEditor implementations are meant to work with a PropertyGrid component, and as such are (in most cases) expecting an IWindowsFormsEditorService, as explains the Microsoft documentation (”This service is typically used to display a form from the EditValue method of a UITypeEditor”). Since a IWindowsFormsEditorService instance is available only from the PropertyGrid control, we have to write our own implementation. Let’s name it EditorService, and for convenient reasons, it will also implements the ITypeDescriptorContext and the ServiceProvider interfaces since the UITypeEditor.EditValue method expects such services.

As previously mentioned, the corresponding Attributes or Operations DesignerActionMethodItem’s should display a modal dialog holding the associated UITypeEditor (the CollectionEditor in this case). For this purpose, our IWindowsFormsEditorService implementation (the EditorService class) must implement the ShowDialog(Form dialog) method to basically invoke the Form.ShowDialog method on the dialog parameter. This method allows to specify the dialog owner via the owner’s Win32 HWND. In our case, the dialog owner to specify is simply the Smart Tags window that is exposed in the ILOG Diagrammer for .NET library by means of the ILOG.Diagrammer.Design.IDropDownOwner interface (introduced in patch 14). This interface is implemented by the DesignerHost RootComponent’s designer and represents a possible candidate for dialog ownership.

While it may appear quite complex, the following piece of code will clear up everything:

        DialogResult IWindowsFormsEditorService.ShowDialog(Form dialog) {
            IDesignerHost host =
              (IDesignerHost)((IServiceProvider)this).GetService(typeof(IDesignerHost));
            IDropDownOwner rootDesigner = null;
            if (host != null)
                rootDesigner = host.GetDesigner(host.RootComponent) as IDropDownOwner;
            if (rootDesigner == null) {
                IUIService srv =
                  (IUIService)((IServiceProvider)this).GetService(typeof(IUIService));
                if (srv != null)
                    return srv.ShowDialog(dialog);
            }
            if (rootDesigner != null) {
                IWin32Window owner = rootDesigner.DropDownOwner;
                if (owner != null)
                    return dialog.ShowDialog(owner);
            }
            return dialog.ShowDialog(_component as IWin32Window);
        }

The implementation first retrieves the IDesignerHost, then tries to get the RootComponent’s designer as a IDropDownOwner. Then, if successful, it invokes dialog.ShowDialog() method passing the Smart Tags window HWND as the dialog owner (the return value of rootDesigner.DropDownOwner).

So, with this EditorService class, we now have everything we need to write the Attributes and Operations DesignerActionMethodItem instances.

The DesignerActionMethodItem constructor is defined as:

public DesignerActionMethodItem(
    DesignerActionList actionList,
    string memberName,
    string displayName,
    string category,
    string description,
    bool includeAsDesignerVerb
)

where memberName specifies the method to invoke on the DesignerActionList instance.

The following code shows the implementation corresponding to the Attributes property (you can refer to the full source code for the Operations property and the complete EditorService implementation).

    class UMLTypeActionList : DesignerActionList {
        ...
        public void EditAttributes() {
            EditorService.EditValue(Component.Site, Component, "Attributes");
        }
        public override DesignerActionItemCollection GetSortedActionItems() {
            DesignerActionItemCollection items =
                new DesignerActionItemCollection();
            // The "TypeName" property
            ...
            // The 'Edit Attributes...' verb
            items.Add(new DesignerActionMethodItem(this,
                                    "EditAttributes",
                                    "Edit Attributes...",
                                    "UML",
                                    "The attributes of the UML type.",
                                    true));
        }
    }

And here is the final result:

In this article, we have seen how to support Smart Tags from a custom ILOG Diagrammer for .NET User Symbol. Using the same design-time API as the Windows Forms controls, it integrates seamlessly with the Visual Studio design surface and greatly improves the user experience of your symbols.

The following movie is best viewed in full screen mode:

Presented by Patrick Megard.