ILOG .NET Visualization Blog

Creating Default Anchors for custom User Symbols

Robert Dupuy — Thu, 26 Jun 2008 12:22:25 +0000

This article describes how to create default anchors on custom user symbols with ILOG Diagrammer for .NET.

First, we need to make sure that we know what anchors and user symbols are. Let’s briefly define these two notions:

A user symbol is a graphic object built with the ILOG Diagrammer for .NET Diagram Designer. This designer, fully integrated into Visual Studio, is a WYSIWYG editor that produces C# or VB.NET code. Using this editor, you can build complex interactive symbols by assembling available shapes and symbols.
An anchor is a point on a graphic object where a link can be connected. Each graphic object has a collection of anchors on which it’s possible to connect links.

Now that we know what we’re talking about, we can imagine the following scenario: A user has created a custom user symbol using our designer, and he wants to specify the exact location where links could be connected to this symbol. For example, when designing an electrical symbol, one need to specify that wires can be connected to the component terminals. Here is an example of such a symbol:

Let’s create this symbol in Visual Studio:

Launch Visual Studio 2005 or 2008.
Select File->New->Project->ILOG Diagrammer Symbol Library and name the project ElectricalSymbolsLibrary.
In the solution explorer, right click on the project, and choose Add New Item->UserSymbol (ILOG Diagrammer) and name the symbol Transistor.cs.
Choose Diagrammer->Import File and import transistor.ivn after extracting it from the following archive. Click Yes in the dialog asking if you want to import the file as vector graphics.

You should now have your transistor symbol visible in the designer:

Let’s now use this new symbol in a diagram so that we can try to connect links to it. To add a diagram to the project, right-click in the solution explorer on the project and choose Add->New Item->Diagram (ILOG Diagrammer). Compile the project (Build->Build Solution) to update the toolbox. Open the toolbox, your new transistor symbol should be available:

Drag a transistor symbol from the toolbox to the design surface. Repeat the operation to have several symbols in the diagram. You should now have something like this:

Let’s now try to connect the transistors together by creating links between them. Open the toolbox and locate the Connectors tab. Click on one of the links available in the tab, then move the mouse over one of the transistors. The anchors where the link can be connected are highlighted:

We can see that by default a user symbol has four anchors, each one located at the middle of the bounding box sides. Obviously, that’s not what we want here. One way to get the right anchors is to edit each transistor instance by modifying its anchors collection: After removing the default anchors (set the UseDefaultAnchors property to false), add three BoundsAnchor to the anchors collection (right-click on the transistor, and choose Edit Anchors…). Then, we need to move each anchor at the desired location. To do this, choose the Edit Anchors () icon from the Diagrammer toolbar and move the mouse over the transistor. It’s now possible to move the three anchors previously added to their right location by clicking each anchor and dragging it to its desired location. Then, if we go back to the link mode connection by clicking on a link in the toolbox Connectors tab, we can see by passing the mouse over it, that our transitor has now its anchors placed at their right location:

The main drawbacks of this approach are:

The anchors are not part of the symbol itself, since they have been added after the symbol creation. If you create an instance of this symbol by code, your new anchors will not be available.
We’re not using the default anchors feature of the graphic objects, and thus, anchors are created and added to the component model even though there are no links connected to them. This can be a performance issue if you have many objects with many anchors.

An alternative to this approach is to define the default anchors directly when designing the transistor. How can we do this ? Let’s go back to the designer view of our transistor by double clicking the Transistor.cs file in the Solution Explorer. The trick is that all the real anchors (not the default ones) defined in the sub objects of our transistor will be exposed as default anchors for our user symbol. Thus, we simply need to add three anchors on the sub objects composing our transistor. Let’s see how to do it.

If you look at the Document Outline view in Visual Studio, you will see that our transistor is composed of several shapes:

The interesting objects are the polyline1, polyline2 and line1 objects. On each one, we will add a new PolyPointsAnchor, which is a type of anchor whose location is bound to a vertex of a polyline object. Right-click on the polyline1 object in the designer view, and choose Edit Anchors. Add a PolyPointsAnchor and click the OK button. Repeat the operation for the polyline2 and line1 objects. Note that in our example, the anchors are located on the first vertex of each polyline, which is the default for PolyPointsAnchor objects.

Let’s compile the project and switch back to our diagram view to test our transistor by double clicking the Diagram1.cs file in the Solution Explorer. To start with a fresh diagram, remove existing instances of the transistors. Then drag and drop a new transistor from the toolbox and try to connect a link to see that the highlighted anchors are the expected ones:

We’ve successfully changed the default anchors of our transistor, without having to write a single line of code.

Creating Bezier Curves in an Ajax DiagramView (Part 2)

Patrick Ruzand — Fri, 20 Jun 2008 09:32:20 +0000

In the previous article, I have explained the fundations of the Ajax interaction framework of ILOG Diagrammer for .NET. It is now time to dive into the implementation details.

From the first article, we know an AjaxDiagramView interactor inherits from the System.Web.UI.ExtenderControl class. As such, it is composed of two parts: an ASP.NET server control and a JavaScript client control.

The server control

The ASP.NET server control is responsible for describing the client resources to the underlying ASP.NET framework (the script resources to deploy, the optional initialization tasks to perform on the client, etc.), and for handling the possible actions coming from the client control. In our case, the server control implementation handles the client action (i.e. create an ILOG.Diagrammer.Graphic.BezierCurve instance and add it to the view content) via an asynchronous callback. Let’s first begin with the implementation of the client resources description.

For this purpose, the ILOG.Diagrammer.Web.UI.ViewInteractor class defines the following methods:

ScriptBehaviorDescriptor CreateScriptBehaviorDescriptor(Control targetControl)
IEnumerable GetScriptReferences()

The CreateScriptBehaviorDescriptor method must be overriden to return a ScriptBehaviorDescriptor instance that specifies the name of the client-side class of the interactor (in other words the name of the JavaScript class).
The GetScriptReferences method returns the script resources needed by your client control. This is needed by ASP.NET to be able to automatically deploy the required client resources.

Here is a first implementation of the MakeBezierCurveInteractor class that illustrates the implementation of these methods :

public class MakeCurveInteractor : ViewInteractor {        

  protected override ScriptBehaviorDescriptor CreateScriptBehaviorDescriptor(Control targetControl) {
    return new ScriptBehaviorDescriptor("AjaxBezierSample.MakeCurveBehavior",
                                        targetControl.ClientID);
  }                

  protected override IEnumerable GetScriptReferences() {
    IEnumerable references = base.GetScriptReferences();
    List list = new List(references);
    list.Add(new ScriptReference("AjaxBezierSample.script.MakeCurveBehavior.js",
                                 Assembly.GetExecutingAssembly().FullName));
    return list;
  }

which means the client control implementation is the AjaxBezierSample.MakeCurveBehavior class defined in the MakeCurveBehavior.js file, packaged as an embedded resource in the application assembly (packaging a script resource in the assembly requires the .js file be built with the Embedded Resource build action, and the resource declared in the AssemblyInfo.cs).

The next step, and it completes the server control implementation, is to handle the action. As explained above, we made the choice to process the interaction via an asynchronous ASP.NET callback, which is possible because the ViewInteractor base class implements the ASP.NET 2.0 ICallbackEventHandler interface. Therefore, our custom interactor must override the ViewInteractor.RaiseCallBackEvent method that is called when a callback request is received by our control.

The implementation is quite straightforward: it first reads the curve definition points from the method parameter (passed by the client control as a JSON string), converts these points from the view coordinate system to the view graphic container coordinate system, then creates the corresponding Diagrammer for .NET graphic object (a BezierCurve instance) and finally adds it to the view graphic container.

Here is the code:

        protected override void RaiseCallbackEvent(string eventArgument) {
            ProcessRequest(eventArgument);
            base.RaiseCallbackEvent(eventArgument);
        }
        protected virtual void ProcessRequest(string eventArgument) {
            if (string.IsNullOrEmpty(eventArgument))
                return;
            DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(BezierArg));
            BezierArg args = null;
            using (Stream input = new MemoryStream(Encoding.Unicode.GetBytes(eventArgument))) {
                args = serializer.ReadObject(input) as BezierArg;
            }
            if (args != null) {
                Point2D[] points = args.points;
                if (points.Length == 0)
                    return;
                Transform t = View.Transform.Inverse();
                t.TransformPoints(points);
                BezierCurve curve = new BezierCurve(points);
                IManageChildren container = View.Content as IManageChildren;
                if (container != null) {
                    container.AddChildren(new GraphicObject[] { curve });
                }
            }
        }

The server control implementation is done. It’s now time to wear our JavaScript developer suit for the client side control implementation. From now on, all class names refer to the Microsoft JavaScript Library.

The client control

Implementing the client part of a ViewInteractor consists on writing a JavaScript class inheriting from the ILOG.Diagrammer.Web.UI.ViewBehavior class which offers the basic services to communicate with the server control. In the Microsoft JavaScript world, writing a new class consists on :

defining the namespace
defining the class object
implementing the class methods via the class object prototype
registering the class in the class hierarchy

In terms of code, it means:

defining the name space:

Type.registerNamespace(‘AjaxBezierSample’);

This line of code creates a new namespace called ‘AjaxBezierSample’ and registers it in the Type object.

defining the class object:

AjaxBezierSample.MakeCurveBehavior = function(element) {
  …
  AjaxBezierSample.MakeCurveBehavior.initializeBase(this, [element]);
};

The namespace object being created, we define the MakeCurveBehavior class object (the constructor) and call the initializeBase() method to initialize the base class. Latter, we will add to the constructor the fields initialization code.

implementing the class methods via the class object prototype

AjaxBezierSample.MakeCurveBehavior.prototype = {
  initialize : function() {
    AjaxBezierSample.MakeCurveBehavior.callBaseMethod(this, ‘initialize’);
  },
  dispose : function() {
    AjaxBezierSample.MakeCurveBehavior.callBaseMethod(this, ‘dispose’);
  },
  …
}

The methods of the class are defined on the prototype following the prototype model. For more information on the prototype model, see the title=”Prototype model”>MSDN documentation. For the time being, we only need to call the initialize() and dispose() methods of the base class.

registering the class in the class hierarchy

AjaxBezierSample.MakeCurveBehavior.registerClass(‘AjaxBezierSample.MakeCurveBehavior’, ILOG.Diagrammer.Web.UI.ViewBehavior);

Finally, we register our new class in the class hierarchy, specifying its fully qualified name (that is the class name prefixed with the namespace) and the base class it inherits from. This skeleton is the minimum code required to fully define a new ViewBehavior subclass.

The last step is to eventually implement the code needed to create bezier curves.

Drawing Bezier curves in DHTML

As explained in the first part of this article, the interaction ghost of the bezier curves will be implemented either in VML or SVG depending on the browser. The ghost will be composed of three primitive objects:

a circle that represents the edited passage point.
two rectangles that represent the control points.

These primitives will be added to a parent container positionned in absolute above the image. To ease the primitives update, both the primitives and the container will have a corresponding class field (a reference to the corresponding node in the DOM).

The code below shows the updated constructor (with the primitive fields) and the DOM initialization :

AjaxBezierSample.MakeCurveBehavior = function(element) {
    this._ghostContainer = null;
    this._ptMarker = null;
    this._ctrl1 = null;
    this._ctrl2 = null;
    this._useVML = Sys.Browser.agent == Sys.Browser.InternetExplorer;
    this._curveCount = 0;
    this._svg  = null;
    ...
    AjaxBezierSample.MakeCurveBehavior.initializeBase(this, [element]);
};        

AjaxBezierSample.MakeCurveBehavior.prototype = {        

    initialize : function() {
        AjaxBezierSample.MakeCurveBehavior.callBaseMethod(this, 'initialize');
        ...
        this.initDOM();
    },
    initDOM : function() {
        this._ghostContainer = document.createElement("div");
        this.get_element().appendChild(this._ghostContainer);
        this._ghostContainer.style.zIndex = 3;
        this._ghostContainer.style.position = "absolute";
        this._ghostContainer.style.left="0px";
        this._ghostContainer.style.top="0px";
        this._ghostContainer.style.width="100%";
        this._ghostContainer.style.height="100%";
        if (!this._useVML) {
            this._svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
            this._ghostContainer.appendChild(this._svg);
        }
        var parentNode = this._useVML ? this._ghostContainer : this._svg;
        // passage point marker
        this._ptMarker = this.createMarker(parentNode);
        // control points markers
        this._ctrl1 = this.createControlPt(parentNode, 'ctrl1');
        this._ctrl2 = this.createControlPt(parentNode, 'ctrl2');
    },        

    createMarker : function(parentNode) {
        var marker = this._useVML ? this._createMarkerVML(parentNode) : this._createMarkerSVG(parentNode);
        return marker;
    },        

    _createMarkerVML : function(parentNode) {
        var marker = document.createElement("oval");
        parentNode.appendChild(marker);
        marker.id = "ptmarker";
        marker.style.behavior = "url(#default#VML)";
        marker.strokeweight = 1;
        marker.filled = 'true';
        marker.fillcolor = 'black';
        marker.style.position = "absolute";
        marker.style.width = "7px";
        marker.style.height = "7px";
        marker.style.display='none';
        return marker;
    },        

    _createMarkerSVG : function(parentNode) {
        var marker = document.createElementNS("http://www.w3.org/2000/svg", "circle");
        parentNode.appendChild(marker);
        marker.style.display = 'none';
        marker.setAttributeNS(null, 'id', "ptmarker");
        marker.setAttributeNS(null, 'r', 3);
        marker.setAttributeNS(null, "fill", 'black');
        marker.setAttributeNS(null, "stroke", "none");
        return marker;
    },        

    createControlPt : function(parentNode, id) {
        var ctrl = this._useVML ? this._createControlVML(parentNode, id) : this._createControlSVG(parentNode, id);
        return ctrl;
    },        

    _createControlVML : function(parentNode, id) {
        var ctrl = document.createElement("rect");
        parentNode.appendChild(ctrl);
        ctrl.id = id;
        ctrl.style.behavior = "url(#default#VML)";
        ctrl.strokeweight = 1;
        ctrl.filled = 'false';
        ctrl.style.position = 'absolute';
        ctrl.style.width = '11px';
        ctrl.style.height = '11px';
        ctrl.style.display='none';
        return ctrl;
    },        

    _createControlSVG : function(parentNode, id) {
        var ctrl = document.createElementNS("http://www.w3.org/2000/svg", "rect");
        parentNode.appendChild(ctrl);
        ctrl.id = id;
        ctrl.setAttributeNS(null, "width", "11px");
        ctrl.setAttributeNS(null, "height", "11px");
        ctrl.setAttributeNS(null, "stroke-width", 1);
        ctrl.setAttributeNS(null, "fill", "none");
        ctrl.setAttributeNS(null, "stroke", "black");
        ctrl.style.display='none';
        return ctrl;
    },

Handling interactions

The interaction process follows the following sequences:

When the left mouse button is pressed, a new passage point and two control points are created.
When the mouse is dragged, the position of the control points is adjusted accordingly.
On a double-click, the curve is validated and a request is sent to the server with the curve points.
When the ESC key is pressed, the interaction is cancelled.

Therefore, the interactor has to listen the mousedown, mousemove, mouseup and keydown events. For this purpose, we define four handlers that will be wired/unwired depending on the value of the active property.

The code below shows the handler initialization and the required methods to wire/unwire the handlers on a active property change:

AjaxBezierSample.MakeCurveBehavior = function(element) {        

    this._mouseDownHandler = null;
    this._mouseMoveHandler = null;
    this._mouseUpHandler = null;
    this._keyDownHandler = null;
    this._propertyChangedHandler = null;
    this._startPoint = null;
    this._points = null;
    this._size = 0;
    ...        

    AjaxBezierSample.MakeCurveBehavior.initializeBase(this, [element]);
};
AjaxBezierSample.MakeCurveBehavior.prototype = {        

    initialize : function() {
        ///

Creating a Nice Diagram Display with WPF : It’s So Easy

Ed Kiraly — Wed, 18 Jun 2008 20:26:23 +0000

In this short 7 minute presentation, Patrick Megard leads us through the basic steps in creating a diagram display using ILOG Diagrammer for .NET’s and Visual Studio 2008’s WPF features.

The following movie is best viewed in full screen mode:

Presented by Patrick Megard.

Creating Bezier curves in an Ajax DiagramView (Part 1)

Patrick Ruzand — Tue, 10 Jun 2008 13:39:35 +0000

In this series of two articles, I am going to show how to create a new interactor for the ILOG Diagrammer for .NET 1.5 AjaxDiagramView web control. To illustrate this, we will write an interactor to be able to create Bezier curves within the browser. I will first introduce the concepts involved in the Ajax interactions implementation (in the part 1) and then explain the implementation following a step-by-step approach. The latter will be the purpose of the second part.

ILOG Diagrammer for .NET 1.5 supports Ajax editing capabilities by means of a set of predefined interaction tools (called interactor) and provides an extensible framework to implement your own interactor. The interactor framework is based on Microsoft ASP.NET AJAX, the Microsoft Ajax extension which is now part of the .NET framework since the 3.5 release. This new extension introduces new ASP.NET classes that allow to easily attach client-side behaviors (implemented in JavaScript) to a web control. Such client-side extensions of a web control are called Extender Control and described by the System.Web.UI.ExtenderControl class (from the System.Web.Extensions dll).
The purpose of this abstract class is to “enable you to programmatically add AJAX functionality to an ASP.NET server control.” (from the MSDN documentation). Basically, this class which inherits from the System.Web.UI.Control class defines new methods whose purpose is to register the required JavaScript resources to be deployed on the client. It also provides a description of the client-side class and the possible initialization tasks (the purpose of the GetScriptDescriptors() method).
To implement the client-side control of an ExtenderControl, the ASP.NET AJAX extension (and the .NET Framework 3.5) provides a very rich JavaScript class hierarchy by means of the Microsoft Ajax Library. From this class hierarchy, the Sys.UI.Behavior class is the base class for ExtenderControl client implementations.

So, how does all this work in ILOG Diagrammer for .NET ? In fact, interactors are implemented as Extender controls (they inherits from System.Web.UI.ExtenderControl) via the ILOG.Diagrammer.Web.UI.ViewInteractor class. In addition to implementing the ExtenderControl abstract class, this class provides facilities to process the interaction on the server either via a postback (it implements IPostBackEventHandler) or an async callback (it implements also ICallbackEventHandler).

Now the foundations are cristal-clear :-), let’s focus on our interactor. As initially mentioned, the goal is to be able to create Bezier curves within the browser. That means the user will define the passage points and control points by clicking within the AjaxDiagramView and once the interaction ends, the points will be sent to the server so that our interactor server implementation processes the data and creates a new ILOG.Diagrammer.Graphic.Curve objects and adds it to the view graphic container. Also, to reduce flickering effects, the request will be performed via an async callback.

Finally, one last point before we start coding. To improve the user experience, we want to draw a visual feedback of the curve being edited. So how to render bezier curves in a browser ? The idea is to use a vector graphic rendering engine from the browser. There are several solutions for that but unfortunately none are cross-browser so we will have to make browser-specific implementations. Under IE, we will use inline VML which is natively supported by IE. Under Firefox, we will use inline SVG. Now we have our inline vector graphic APIs for the browsers, we are ready to start the implementation.

Note: the second article can be found here.

Displaying a Microsoft Project XML file using Diagrammer for .NET, WPF and LinQ (Part 2)

Emmanuel Tissandier — Thu, 29 May 2008 13:55:57 +0000

In the part 1 of this post, we have seen how to use ILOG Diagrammer for .NET, WPF and Linq to display the content of a Microsoft Project XML file into a graph showing the tasks and the constraints between them, we are now going to see how to use more WPF features to display the critical path of the project.
The critical path of the project is simply the set of tasks that are critical. The task is considered as critical if a delay in the task will delay the end of the project. This set of tasks and the constraints between them usually creates a path in the network, called the critical path although sometime you might see several paths.
For our example, we will fist try to display the critical tasks with a red background and give some information on different type of tasks.

We add 3 new boolean properties to our Task class, a Milestone property for tasks that are milestones, a Summary property for tasks that represents a group of tasks, and a Critical property for critical tasks.

 public bool Milestone { get; set; }
 public bool Summary { get; set; }
 public bool Critical { get; set; }

and we change the Linq query to fill these properties from the XML file:

project.Tasks
      = (from task in document.Descendants("{http://schemas.microsoft.com/project}Task")
          where (int)task.Element("{http://schemas.microsoft.com/project}ID") != 0
          select new Task()
           {
               Project = project,
               UID = (int)task.Element("{http://schemas.microsoft.com/project}UID"),
               Name = (string)task.Element("{http://schemas.microsoft.com/project}Name"),
               Start = (DateTime)task.Element("{http://schemas.microsoft.com/project}Start"),
               Finish = (DateTime)task.Element("{http://schemas.microsoft.com/project}Finish"),
               Milestone = (bool)task.Element(”{http://schemas.microsoft.com/project}Milestone”),
               Critical = (bool)task.Element(”{http://schemas.microsoft.com/project}Critical”),
               Summary = (bool)task.Element(”{http://schemas.microsoft.com/project}Summary”),
               PredecessorLinks =
                         (from link in task.Descendants(”{http://schemas.microsoft.com/project}PredecessorLink”)
                         select
                           new PredecessorLink
                           {
                               PredecessorUID = (int)link.Element(”{http://schemas.microsoft.com/project}PredecessorUID”)
                           }).ToList() 

              }).ToList();

Now that our Task has 3 new properties we can modify the style of nodes with data triggers to take advantage of this. The data trigger in a style will allow changing the style depending on data. In our case, milestones will be white, summary tasks in blue and all critical tasks in red.
Here is the new style for nodes with 3 data triggers.

The definition of data triggers is very straight forward. The data trigger evaluates the value specified by the Binding (for example {Binding Summary}) and see if it matches the value specified in the Value property (in our case true), if the two things match, then the setters are applied, in our case the background color is changed.

Two things to understand here, first the binding specified in the data trigger is evaluated on the data context of the Node. In the Diagram control the data context for node is the item in the data source, in our case a Task object, that is why I can directly bind to the properties of a Task (like {Binding Milestone}), no need to specify any source for the binding.
The second point is the order of the triggers. I place the last trigger that changes the background to red for critical tasks at the end because a milestone or a summary task can also be critical. The last data trigger will win in such a case and thus all critical tasks will be red.
We now have the following result, showing the critical tasks :

We can also use data triggers in data templates. For example, for a milestone task it is not necessary to display the start and finish date since the dates are the same.
In order to achieve this we add a data trigger in the data template of nodes:

The trigger here applies to task with Milestone property set to true, it changes the label of the start date to “Milestone Date” and hides the part that corresponds to the end date.

Here is the result for a one of the milestones:

Let’s now use data triggers for links. In order to make the critical path more obvious, we will try to draw the links between two critical tasks in red. Painting a critical task in red was easy; we have simply added a data trigger in the style. For links it is a little bit more complex because there is no instance in the data source that represents a link. To answer this problem, The Wpf diagram component creates a convenient data context for each link that is an instance of the class Diagram.LinkContext. This class has two properties, StartItem and EndItem that represents the items in the data source (for us the tasks) that are at the displayed at the begining and end of the link. Thus we can easily use data triggers in a link of the diagram.
We want the link to be red if both the origin and destination tasks are critical, so we need to use a MultiDataTrigger that is a kind of data trigger with multiple conditions:

Here is the new style for links:

I hope I have shown how the combination of the diagram control with its graph layout algorithms and the styling and templating features of WPF can help to easily create nice looking diagrams.

If you want to test the project, here is the source code and Visual Studio 2008 solution. In order to compile and run you will need and evaluation of ILOG Diagrammer for .NET that you can get at http://www.ilog.com/products/diagrammernet/eval.

Licensing in .NET explained - Part 2

Robert Dupuy — Thu, 22 May 2008 09:21:16 +0000

In the first part of this article, we’ve seen how to deal with licensed components from the user point of view. In the second part, I’ll try to explain the whole licensing process, that is:

Authoring licensed components.
Creating licences at design-time.
Creating licences at compile-time.
Creating licences at run-time.

Authoring licensed components

I’ll not spend too much time on that topic, as it’s widely documented on the web (see for example this article).

The process is simple. After creating your component, you have to:

Apply a LicenseProviderAttribute to the class.
Call LicenseManager.Validate from the class constructor to get a licence.
Dispose the licence in the component finalizer.

The licence provider specified by the LicenseProviderAttribute attribute in step 1 is used during step 2: Calling LicenseManager.Validate in your component constructor will create an instance of this license provider, and will call its GetLicense method to get a licence. If no licence can be found, LicenseManager.Validate will throw an exception, making your component unusable.

Specifying the licence provider has also another usage: It’s used by Visual Studio to know whether a component is licensed or not. Indeed, as we’ve seen in the first part of this article, Visual Studio manages a licenses.licx file containing all the licensed components used in a project.

Microsoft provides the LicFileLicenseProvider class, a ready-to-use licence provider. But if you need to implement your own logic, you have to create a new licence provider by subclassing the LicenseProvider class. That’s what we’ve done here at ILOG for our .NET products (ILOG Gantt for .NET and ILOG Diagrammer for .NET) because we wanted to implement ILM (ILOG License Manager). Subclassing the LicenseProvider class is relatively simple, as you just need to override the GetLicense method. We’ll see later how to implement this method.

The LicenseProvider will be used in three different contexts:

At design-time.
At compile-time.
At run-time.

Creating licences at design-time

Here we assume that we’re building an application that contains licensed components using Visual Studio. The typical way to do it is to drag and drop a toolbox item onto the design surface, which results in the instantation of the component. As the licence checking is done in the component constructor, a licence has to be provided at that time. Let’s see how to handle this case in the LicenseProvider.GetLicense method through a partial implementation:

public override License GetLicense(
    LicenseContext context,
    Type type,
    object instance,
    bool allowExceptions)
{
    //
    // The context parameter indicates the context
    // in which the component is used.
    //
    bool runtime = context.UsageMode == LicenseUsageMode.Runtime;                 

    if (runtime)
    {
        //
        // Will see later what to do here
        //
    }
    else
    {
        //
        // Here we are designing our application, so we need to
        // get a licence that we will store in the context.
        //                 

        //
        // We're calling the GetDesignTimeLicenseKey() method to get a licence.
        // The code for this method is not provided here, but a simple
        // implementation could be to look in the registries or in a specific
        //  file to check that a valid licence has been installed on this computer.
        // The implementation of this method depends on the licensing schema
        // you want to set up.
        //
        string licenseKey = GetDesignTimeLicenseKey(type);                 

        //
        // If no licence was found, error
        //
        if (licenseKey == null)
        {
            if (allowExceptions)
                throw new LicenseException();
            return null;
        }                

        //
        // Save the licenseKey in the context. It will be possible at runtime to
        // retrieve it.
        //
        context.SetSavedLicenseKey(type, licenseKey);                

        //
        // We create and return a new CustomLicence object using
        // the licenseKey. The code for the CustomLicense class is
        // straightforward, as it's a simple implementation of the License
        // class. It's given below.
        //
        return new CustomLicense(licenseKey);
    }
}               

class CustomLicense : License
{
    private string _key;
    public CustomLicense(string Key)
    {
        _key = key;
    }
    public override string LicenseKey
    {
        get
        {
            return _key;
        }
    }
}

To sum up, the creation of a licence at design time is a 3 steps process:

Get the licence key installed on the computer. It can be a licence file, or a registry key…It depends on the way you want to manage the installation of licence keys on development computers.
Sets the licence key into the licence context. This will make it possible to retrieve the licence key at runtime.
Create a License object using this licence key.

Note : The License class is a .NET class that encapsulates the licence key, which is a simple string.

The LicenseContext used by Visual Studio and passed as the first parameter of the GetLicense method is said to be a “design-time” context, that is, a context whose UsageMode property returns LicenseUsageMode.DesignTime.

Creating licences at compile-time

Once the application has been designed, it needs to get compiled. As we’ve seen in the first part of this article, Visual Studio invokes the licence compiler to compile the licenses.licx file into an assembly resource file.

The licence compiler takes a .licx file as input and produces a resource file as output. It parses the .licx file and create an instance of each type found in it. The LicenseContext used by the licence compiler is a design-time context, an instance of the DesignTimeLicenseContext class. For each component created, a corresponding licence is also created and is stored in the licence context in a hash table. This hash table is then dumped it into a resource file.

This resource file will be used differently at run-time depending on the application type your’re creating, as explained in the first part of this article.

Creating licences at run-time

As for design-time and compile-time, licence checking will take place at run-time each time a licensed component gets instantiated. The difference is that the LicenseContext used will be a run-time licence context, that is, a context whose UsageMode property returns LicenseUsageMode.RunTime. This context will be able to retrieve the licences compiled with the licence compiler. Here is the a partial implementation of the LicenseProvider.GetLicense method:

public override License GetLicense(
    LicenseContext context,
    Type type,
    object instance,
    bool allowExceptions)
{
    //
    // The context parameter indicates the context in
    // which the component is used.
    //
    bool runtime = context.UsageMode == LicenseUsageMode.Runtime;                 

    if (runtime)
    {
        //
        // At runtime, look into the context to find the licence.
        // Depending on the application type, the context may look into
        // the application resources (Windows Forms), or the
        // App_Licenses.dll assembly (Web sites)...
        //
        string licenceKey = context.GetSavedLicenseKey(type, null);                

        if (licenceKey != null)
            return new CustomLicense(licenceKey);           

        if (allowExceptions)
            throw new LicenseException();
        else
            return null;
    }
    else
    {
        //
        // Already covered in the "design-time" section
        //
    }
}

The interesting part here is the call to the LicenseContext.GetSavedLicenseKey method. It will look into the context to see if a licence for the specified type can be found. Depending on the application type (assembly based applications, web sites, windows forms hosted in IE), the context will look in the appropriate location to find the licence.

Conclusion

We’ve seen in this article how the licences were created during the three phases of an application development: design-time, compile-time, run-time. Of course the code given was simpified for the purpose of this article, but you can imagine to enrich it by adding cryptography or anything that can make your licence management more secure.

Displaying a Microsoft Project XML file using Diagrammer for .NET, WPF and LinQ (Part 1)

Emmanuel Tissandier — Mon, 19 May 2008 10:42:17 +0000

Diagrammer for .NET 1.5 introduces a set of new WPF controls that can present information as a graph display made of nodes and links. In this post, I will show how you can use these controls to display the content of a Microsoft Project XML file. We will use .NET 3.5 and Linq to read the data and provide it to the ILOG WPF Diagram control.

The XML that you can export from Microsoft Project 2003 contains all the information on the project plan such as all the tasks, resources, calendars and more. Here we will only take care of the tasks and the predecessor constraints between tasks. Predecessor constraints are the constraints between tasks such as “task A starts after task B”. The graph that we will create will have nodes representing the tasks and links representing the predecessor constraints between tasks. The result will give something similar to the “Network Diagram” view of Microsoft Project that represents nicely the flow of tasks in the project plan.

First of all, a few words on the Microsoft Project XML format. The format defines a tag that contains all the tasks, each task is represented by a tag that contains the task information.


...

  
    Unique id of task
    The name
    The start date 
    The finish date
     ...
    

...

When a task has predecessors, a tag appears for each predecessor in the tag:



  ...
  
    1
    1
  
  ...

 corresponds to the unique id (UID tag) of the predecessor and  gives the type of the constraint (0 for a “Finish to Finish” constraint, 1 for “Finish to Start”, 2 for “Start to Finish” and 3 for “Start to Start”).
That’s all we need to know to be able to read the data.
We now define very simple .NET classes that correspond to this structure, a class Project that represents the project, a Task and a PredecessorLink class:
public class Project
{
    public List Tasks { get; set; }
} 

public class PredecessorLink
{
    public int PredecessorUID { get; set; }
} 

public class Task
{
    public Project Project { get; set; }
    public int UID { get; set; }
    public string Name { get; set; }
    public DateTime Start { get; set; }
    public DateTime Finish { get; set; }
    public List PredecessorLinks { get; set; }
}
Thanks to Linq for XML, we can now read the data from the XML file and directly create the Project, Task and PredecessorLink instances.
XDocument document = XDocument.Load("./Engineering.xml");
Project project = new Project();
project.Tasks
      = (from task in document.Descendants("{http://schemas.microsoft.com/project}Task")
          where (int)task.Element("{http://schemas.microsoft.com/project}ID") != 0
          select new Task()
           {
               Project = project,
               UID = (int)task.Element("{http://schemas.microsoft.com/project}UID"),
               Name = (string)task.Element("{http://schemas.microsoft.com/project}Name"),
               Start = (DateTime)task.Element("{http://schemas.microsoft.com/project}Start"),
               Finish = (DateTime)task.Element("{http://schemas.microsoft.com/project}Finish"),
               PredecessorLinks =
                         (from link in task.Descendants("{http://schemas.microsoft.com/project}PredecessorLink")
                         select
                           new PredecessorLink
                           {
                               PredecessorUID = (int)link.Element("{http://schemas.microsoft.com/project}PredecessorUID")
                           }).ToList() 

              }).ToList();
The LinQ code above will iterate over the  elements in the XML document and create a Task instance, then for each Task he will create the list of PredecessorLink. Note that since the XML document defines a default namespace (http://schemas.microsoft.com/project), we need to specify this namespace when querying the document with Linq and this makes the code not really easy to read.
So far we have only been playing with data, we will now start to use WPF to render this information. We have a Project instance that contains a list of Task, each task containing information on its predecessors. That is almost all the information that is required to use the Diagrammer for .NET WPF Diagram control.
Let’s start the XAML code by using the Diagram control:

    
        
   

We have named our control “diagram”, we can now specify the data source in the code behind:
  diagram.Source = project.Tasks;
The diagram control now knows about the data source, but this information is not enough to create a graph display. At this point the result of the application is the following:



Not so impressive…

The Diagram control does not know the relation between the tasks and thus it has layout the task as a simple vertical list with no links between them. We have not defined any graphical representation for the nodes that’s why we get a simple rectangle with the name of the class (in this case this is the result of calling ToString() on the Task instances). Let’s make this look nicer.

First we need to tell the Diagram that there are some relations between them. For this we use the PredecessorBinding property of the Diagram control.

This PredecessorBinding property tells the control how from a Task (an item in the data source) he can find a list of predecessor Tasks (predecessor items in the data source). With this information, the Diagram control can create links between the nodes and layout the graph. So far the Task class does not have a property that returns the predecessor tasks, we only have the predecessor links. Let’s use LinQ again to create a property that returns the list of predecessor tasks:
public class Task
{
    public Project Project { get; set; }
    public int UID { get; set; }
    public string Name { get; set; }
    public DateTime Start { get; set; }
    public DateTime Finish { get; set; }
    public List PredecessorLinks { get; set; }
    public List Predecessors
    {
      get
      {
        return
          (from pred in PredecessorLinks
           join task in Project.Tasks on pred.PredecessorUID equals task.UID
           select task).ToList();
      }
    }
    public override string ToString()
    {
       return Name;
    }
}
The new Predecessors property now returns the list of predecessor tasks by doing a LinQ join between the PredecessorUID in the PredecessorLink and the UID of tasks.
We can now change the XAML and use this new method:
    PredecessorsBinding=”{Binding Predecessors}”>
Now the control knows about the relation between tasks. Note that we have also overridden the ToString method of the Task so that it returns the name of the task. Now we get the following graph that displays the constraints between tasks nicely layout:



Now that the data is present, we can exercise our graphic designer skills using the styling and templating features of WPF to make this graph look better.

The Diagram control has created instances of the Node and Link classes for nodes and links. We can then define a WPF style for these two classes:
 


The style for link defines the color and thickness of links through the Stroke and StrokeThickness properties. It also defines a start and end arrow with different shapes. The style for nodes defines the colors for the background and border of the node.

We are now going to display more information in the node that the simple name of the task. This is done through a WPF DataTemplate. The DataTemplate that we will specify through the NodeTemplate property of the Diagram control represents the graphical template that will be instantiated for each node. Here we will display not only the name but also the start and finish date of the task.

  
    
      
      
      
    
    
    
      
      
    
    
      
      
    
  

This data template defines a grid with 3 rows, first row will display the name of the task, the second row the start date and the last row the finish date.
The Diagram control layouts the graph using a graph layout algorithm. ILOG Diagrammer for .NET provides a large set of graph layout algorithms that can be use to represents graph, in a Diagram the default algorithm is a Hierarchical layout algorithm. This algorithm suits perfectly for our needs because it shows nicely the flow of information in the graph. We will only modify some of the layout properties to get a nicer result. Let’s use orthogonal links and links evenly spaced on the side of nodes. We do this by specifying the layout algorithm through the GraphLayout property of the Diagram class in XAML.

After adding a gradient for the background of the diagram through the Background property, the XAML is now:
 

  
  
    
      
      
    
   

  
  
    
  

And the resulting graph is now much better.


We have seen how easy it is to create a graph display using LinQ, WPF styling and templating and the Diagram control. In a second post I will show how you can go further and tailor the graph with WPF features such as data triggers and more features of the Diagram class. In particular, we will see how to display the critical path of the project plan.

Diagrammer .NET Tips and Tricks Explained Through the “UML Class Diagram” Sample - Part 2

Eric Durocher — Mon, 19 May 2008 09:15:17 +0000

In the previous post, we explained how to assemble built-in ILOG Diagrammer for .NET objects to build a complex UML Type symbol. The first post described how to define the appearance of the symbol, now we will define its behavior. To do this, we will need to do a bit of C# coding.

If you want to look at the code in Visual Studio, download the second version of the source code and open the UMLClassDiagram.sln solution. To see the code of the UMLType symbol, right-click the UMLType.cs item in the Solution Explorer and choose View Code.

Making the Symbol Functional: Adding Properties

Let’s start with an easy one: the TypeName property. We want the UML type name to be displayed in the title of our UML Type symbol. The code for the TypeName property looks like this:

        [Description("The name of the UML type")]
        [Category("UML")]
        public string TypeName
        {
            get
            {
                return nameRect.Text;
            }
            set
            {
                nameRect.Text = value;
            }
        }

What we did here is add a C# property to our user symbol. The property just gets/sets the Text property of the title rectangle of the symbol. This is a frequently used technique: users of your symbol do not have access to its inner elements, so you must selectively expose some of the properties of the inner elements to the outside world if you want users to be able to customize these properties.

Note the [Description(...)] and [Category(...)] attributes: you have probably used these attributes before if you designed .NET components. These attributes can (and should) be used on ILOG Diagrammer .NET user symbols as well.

To try the new property, build the solution (Build > Build Solution), then double-click the Diagram1.cs item in the Solution Explorer. If you select a UMLType instance, you will see the new TypeName property in the property grid, and you can change its value to verify that it works correctly.

(Note: Remember to always rebuild your solution when you change a symbol: the diagrams or the other symbols that use it will be automatically updated.)

Let’s continue with the SplitterSposition property now. This property controls the vertical position of the splitter, and also the sizes of the upper and lower content areas that will contain the attributes and the methods respectively.

        private float splitterPosition = 0.5f;

        [Description("The vertical position of the splitter (between 0 and 1).")]
        [Category("UML")]
        [DefaultValue(0.5f)]
        public float SplitterPosition
        {
            get
            {
                return splitterPosition;
            }
            set
            {
                if (value != splitterPosition)
                {
                    splitterPosition = value;
                    grid.Rows[0].Size = 100 * splitterPosition;
                    grid.Rows[2].Size = 100 - (100 * splitterPosition);
                }
            }
        }

As you can see, the SplitterPosition property adjusts the sizes of the top and bottom rows of the GridPanel so that the splitter is at the desired position. The position is a floating-point value between 0 and 1 (0 = top, 1 = bottom). Note the [DefaultValue(0.5f)] attribute which makes sure that the property will not be serialized if it has its default value.

As before, you can try the new property: in the Diagram1 designer view, change the SplitterPosition property of a UMLType instance and see how the splitter position changes.

Let’s continue with something a little bit more tricky: the Attributes and Operations properties. We will explain only the Attributes property since the Operations property is almost identical. First, we have to create a simple class that describes a UML attribute.

    public class UMLAttribute
    {
        private string name;

        public string Name
        {
            get { return name; }
            set { name = value; }
        }
    }

Our UML Attribute class is really simple, it has only a Name property. We can add more properties if we want (like the attribute type, scope, etc) but the Name property is enough for our explanations, so let’s keep it simple.

The next step is to define a collection of attributes. The collection will be a specialized subclass of the generic System.Collections.ObjectModel.Collection class. What we want to achieve is the following: when the user adds a UMLAttribute to the collection, a graphical item will be added in the corresponding list of our UML Type symbol. So, the collection must be able to notify its UML Type owner when an element is added to it. Here is the code of the collection.

       internal class UMLAttributeCollection : Collection
        {
            private UMLType owner;

            internal UMLAttributeCollection(UMLType owner)
            {
                this.owner = owner;
            }

            protected override void InsertItem(int index, UMLAttribute item)
            {
                base.InsertItem(index, item);
                owner.AttributeAdded(index, item);
            }

            protected override void RemoveItem(int index)
            {
                base.RemoveItem(index);
                owner.AttributeRemoved(index);
            }

            protected override void SetItem(int index, UMLAttribute item)
            {
                base.SetItem(index, item);
                owner.AttributeRemoved(index);
                owner.AttributeAdded(index, item);
            }

            protected override void ClearItems()
            {
                for (int i = 0; i < Count; i++)
                    owner.AttributeRemoved(0);
                base.ClearItems();
            }
        }

We rely on the base class Collection for the implementation of the collection, but we override the InsertItem, RemoveItem, SetItem and ClearItems methods to notify the “owner” of the collection, that is, the UML Type. When the content of the collection is modified, we call the AttributeAdded or AttributeRemoved method. These methods will be responsible for creating and deleting the actual graphical items displayed in our symbol:

        private void AttributeAdded(int index, UMLAttribute attribute)
        {
            AttributeSymbol symbol = new AttributeSymbol();
            symbol.AttributeName = attribute.Name;
            attributesList.Items.Insert(index, symbol);
        }

        private void AttributeRemoved(int index)
        {
            UMLAttribute attribute = attributes[index];
            attributesList.Items.RemoveAt(index);
        }

The graphical items that represent the UML attributes are ILOG Diagrammer .NET user symbols (the AttributeSymbol class). This is a really simple user symbol that contains a “blue square” icon and a text object, and that has an AttributeName property to change the text. We will not describe this sub-symbol in details, you can look at it by double-clicking the AttributeSymbol.cs item in the Solution Explorer (or right-click > View Code to see the code).

(Note: do not confuse the UMLAttribute class with the AttributeSymbol class. The UMLAttribute class is the logical representation used to define and persist a UML attribute, whereas the AttributeSymbol class is the graphical representation of a UML attribute.)

OK, now we finally have all the pieces to create our Attributes property:

        private UMLAttributeCollection attributes;

        public UMLType()
        {
            ...
            attributes = new UMLAttributeCollection(this);
        }

        [Description("The attributes of the UML type.")]
        [Category("UML")]
        [DesignerSerializationVisibility(DesignerSerializationVisibility.Content)]
        public Collection Attributes
        {
            get
            {
                return attributes;
            }
        }

The attributes member variable will hold the actual collection that backs the property. This collection is created in the constructor of the UML Type class. Finally, we define the Attribute property. The property is read-only, it just returns the collection. To add a UML attribute, users will add items to the collection like this:

            UMLAttribute attribute = new UMLAttribute();
            attribute.Name = "Attribute1";
            umlType1.Attributes.Add(attribute);

One thing to note is the DesignerSerializationVisibility attribute. The Attributes property is read-only, and by default the .NET framework does not serialize read-only properties, so we need to explicitly tell the .NET framework that the property must be serialized. The DesignerSerializationVisibility.Content value tells the framework that the property value is created automatically by the class, and that only its content (that is, the UMLAttribute values contained in it) must be serialized/deserialized.

You can now try the new Attributes property in our sample diagram. Select a UML Type instance and click the “…” button in the Attributes row of the property grid. You get a dialog that lets you add, remove and modify the UMLAttribute instances of the collection. Once you click OK, the UML Type symbol is updated to show the new UML attributes.

Licensing in .NET explained - Part 1

Robert Dupuy — Tue, 13 May 2008 11:57:14 +0000

Authoring licensed .NET components is explained in several places over the web. But I was not able to find an article that would cover all the aspects of licensing in .NET. That’s why I decided to write this article, and I hope things will be clearer after reading it.

First, what is the purpose of licensing ? It’s a mechanism that makes sure that only users with a valid licence can use a component. The .NET framework has a built-in licensing mechanism that makes it easy to author licensed components. From the component user point of view, it also has a great support in Visual Studio, which makes the use of licensed components easy. In this first article, we’ll focus on how to use licensed components.

Using Licensed Components with Visual Studio

Using licensed components inside Visual Studio is completely transparent for the user. The usual way to use components in Visual Studio is to drag and drop them from the toolbox onto a design surface: When a toolbox item is dropped onto a design surface, Visual Studio creates an instance of the component represented by the toolbox item and adds it to the designer. If the component created is a licensed component, Visual Studio also adds a licences.licx file to the Visual Studio project.

The licences.licx file contains the type names of the licensed components used in a Visual Studio project. Here is an example:

ILOG.Views.Gantt.Windows.Forms.ActivityTable, ILOG.Gantt
ILOG.Views.Gantt.Windows.Forms.ResourceTable, ILOG.Gantt
ILOG.Views.Gantt.Windows.Forms.GanttChart, ILOG.Gantt

The licences.licx file is updated each time a new licensed component is added to the designer. You can also create or edit this file by hand. You must do this for example if you don’t create the components by dragging them from the toolbox.

The .licx files are associated in Visual Studio with the licence compiler tool (lc.exe). When building your project, the license compiler is run with the licence file as parameter. Compiling the licences produces a resource file that will be used at runtime by the application. Let’s see now in details how the compiled licences are used at runtime, depending on the application type you’re building.

Assembly-based Applications

This category of applications regroups all the applications that are assembly based, that is, applications whose ouput produce an assembly. It contains Windows Forms applications, WPF applications, Silverlight applications, as well as class libraries. It also contains Web project applications. For these applications, the compiled licences are automatically embedded in the resources of the application assembly when the project gets compiled. For example, let’s say I have a Windows Forms application called GanttEditor.exe that’s using licensed components. After compiling the application, we can check that a licence resource has been added to the application resources. To do this, I use Reflector, my favorite .NET disassembler :

The licences.licx file has been compiled into a resource called GanttEditor.exe.licenses.

Web Sites Applications

In Visual Studio, a Web Site is a special project, as there’s no real project file. Instead, all the files located under the web site directory are part of the web site. When a licensed component is dropped into a Web Form designer, Visual Studio creates a licenses.licx file and adds it to the web site directory. This licence file is compiled into an assembly named App_Licenses.dll, located in the web site Bin directory. This assembly will be loaded at runtime to locate the licences. Note that you can force the generation of the App_Licenses.dll assembly by right-clicking the licenses.licx file in the solution explorer, and choosing the “Build Runtime Licenses” menu item.

Using Licensed Components without Visual Studio

For some reasons, you may not use Visual Studio to create your application. In this case, you’ll have to integrate the licence into your application by yourself. These are the steps to follow:

Create and edit you own licenses.licx file.
Compile the licenses.licx file using the licence compiler (lc.exe).
Integrate the compiled licence file into the application.

The last step depends on the type of application you’re building. For example, in a Windows Forms application, you have to put the compiled licence as an emdedded resource of the application (using the /resource option of the c# compiler if it’s a c# application). When hosting Windows Forms controls in IE, the process is different, and is described in the next section.

Windows Forms controls hosted in Internet Explorer

Embedding a Windows Forms control in Internet Explorer can be painful for two reasons:

Code Access Security : When running into Internet Explorer, the hosted control doesn’t have the same permissions as if it was run as a desktop application. Configuring the CAS is not a simple task, as well as finding the minimum permissions required by a control to work properly inside IE.
Licence Management : You have to compile the licences by yourself.

Let’s illustrate how to manage licences with a very simple example: You want to embed a GanttChart (located in the ILOG.Gantt.dll assembly) into the default.htm page. As the GanttChart is a licensed component, you’ll have to provide an entry for it in the licenses.licx file:

ILOG.Views.Gantt.Windows.Forms.GanttChart, ILOG.Gantt

Then, you’ll have to compile this file using the licence compiler:

lc.exe /target:default.htm /complist:licenses.licx /i:ILOG.Gantt.dll

the /target parameter must be the page in which the licence will be used,

the /complist parameter is the .licx file to compile,

the /i parameter indicates the assemblies needed to compile the licence.

The licence compiler will produce a file named default.htm.licenses. Now, we need to use this file in the HTML page as shown below:


...

...

...

...

...

The <OBJECT> tag is used to insert the control in the HTML page, and the <LINK> tag is used to indicate where the licence can be found.

Conclusion

We’ve seen two different ways to use licensed components in .NET: With or without Visual Studio. When using Visual Studio, it takes care of everything. When not using it, you need to do things by yourself.

Now, from a developper point of view, it would be interesting to understand how the licence compiler works, and how to author licensed components. That will be the subject of a second article.

Diagrammer .NET Tips and Tricks Explained Through the “UML Class Diagram” Sample - Part 1

Eric Durocher — Fri, 25 Apr 2008 12:45:38 +0000

This is the first of a series of posts in which we will walk through the UML Class Diagram sample of ILOG Diagrammer for .NET and explain various features, tips and tricks.

The full UML Class Diagram Editor sample can be run from the ILOG web demos server as a ClickOnce application: click here, then click the Install button. The sample is also available in the product itself with full source code. Here is a screenshot of the full sample:

For clarity, we describe in this post a simplified version of the sample. Here is the source code of this simplified version (the code will be completed as we go). You can load it in Visual Studio and follow the explanations by looking at the finished project. (Note: this is a Visual Studio 2005 / ILOG Diagrammer for .NET 1.0 project, but you can load and convert it in Visual Studio 2008 and/or use it with ILOG Diagrammer for .NET 1.5 as well).

The “UML Type” Symbol: Bulding a Complex User Symbol Easily

In this first post, we will introduce the “UML Type” symbol that represents a type (a class, an enum, etc) in a UML class diagram. The UML Type symbol looks like this:

The symbol has a title that contains the name of the UML type. The name can be set using the TypeName property of the symbol. Below are two areas separated by a horizontal splitter. The top area contains the attributes (i.e., the properties in the C# terminology) of the class, and the bottom area contains the operations (i.e. the methods). The content of these areas is set using the Attributes and Operations properties of the symbol respectively. The values of these properties are collections, so you can add any number of attributes and operations. Scrollbars are available if the items do not all fit in the visible area.

In ILOG Diagrammer for .NET, you create user symbols using Visual Studio. ILOG Diagrammer for .NET is closely integrated with Visual Studio and provides an editor (the VS terminology is “Designer”) that lets you visually assemble your user symbols.

To examine the UMLType symbol, start Visual Studio and load the UMLClassDiagram solution. Build the solution (use Build > Build Solution), then double-click on the UMLType.cs item in the Solution explorer.

Here is a screen shot of Visual Studio with the UMLType symbol loaded in the designer:

Let’s zoom in to see the Document Outline (use View > Other Windows > Document Outline to show it if it is not visible). The Document Outline shows the structure of the symbol:

ILOG Diagrammer for .NET user symbols are composite objects (or “containers”), that is, they are made of basic elements and other nested containers. Let us look at the elements of the UML Type symbol:

dockPanel: this is the main container of the symbol. It is an instance of the DockPanel class, which is an ILOG Diagrammer for .NET container that has a built-in layout, very similar to a Windows Forms Panel.
nameRect: this is the rectangle that displays the type name at the top of the symbol. Its Dock property is set to Top so that it is automatically placed at the top of the DockPanel. In ILOG Diagrammer for .NET, all graphic objects can have text displayed inside them. So, a common way to add text in a symbol is to add a Rect (rectangle) object, and to set its text. This also lets you define easily the background of the text using the Fill property of the rectangle (here we use a blue/white gradient).
grid: this nested container is used to layout the attributes and operations areas, and also the horizontal splitter. It is an instance of the GridPanel class, a ILOG Diagrammer for .NET container that has a layout similar to a Windows Forms TableLayoutPanel. The GridPanel makes it easy to allocate the available space in the symbol to the two variable areas: we defined three rows, the first and last rows have a height that is a percentage of the available height (initially, 50/50), and the second row (that contains the splitter) has a fixed height of 4. The GridPanel is also configured to have only one column that takes the whole horizontal space, so the children all span the entire width of the symbol. The GridPanel itself has its Dock property set to Fill, so it fill all the available space in the DockPanel (below the title rectangle).
attributesList and operationsList are two objects of type List. This is not a built-in ILOG Diagrammer for .NET type: the List class is itself a user symbol (also defined in the UML Class Diagram sample). The List symbol implements a scrolled list: we need one for both the attributes area and the properties area, so a good design is to create a user symbol that does this and reuse the symbol (twice in this case). The details of the List symbol will be explained in a future post.
separator: this is the horizontal splitter between the attributes and operations area. It is simply a Rect object, with a gradient fill and a height of 4 pixels.

Now that we looked at the graphic structure of the symbol, let’s try it. The project contains a Diagram1 class. This is the ILOG Diagrammer container object that is displayed in the main application form. Double-click the Diagram1.cs item in the Solution Explorer to edit it: it already contains a test instance of the UMLType symbol. You can create other instances of the symbol by drag-and-dropping the UMLType item from the Toolbox window. For now, we cannot do much with the symbol except moving and resizing it. See how the Attributes and Operations area resize when you resize the symbol.

In this first post, we explained the basic principles for building ILOG Diagrammer for .NET user symbols, and scratched the surface of some features: user symbols, panels, layout, VS integration. In the following posts, we will continue to walk through the same sample and explain more ILOG Diagrammer for .NET features as we go. The next post will be about defining the behavior to the symbol by adding C# properties in the symbol’s code.