How to: Add a Drag-and-Drop Handler

You can add handlers for drag-and-drop events to your DSL, so that users can drag items onto your diagram from other diagrams or from other parts of Visual Studio. You can also add handlers for events such as double-clicks. Together, drag-and-drop and double-click handlers are known as gesture handlers.

This topic discusses drag-and-drop gestures that originate on other diagrams. For move and copy events within a single diagram, consider the alternative of defining a subclass of ElementOperations. For more information, see Customizing Copy Behavior. You might also be able to customize the DSL definition.

In this topic

• The first two sections describe alternative methods of defining a gesture handler:

  • Defining Gesture Handlers by Overriding ShapeElement methods. OnDragDrop, OnDoubleClick, OnDragOver, and other methods can be overridden.

  • Defining Gesture Handlers by using MEF. Use this method if you want third-party developers to be able to define their own handlers to your DSL. Users can choose to install the third-party extensions after they have installed your DSL.

• How to Decode the Dragged Item. Elements can be dragged from any window or from the desktop, as well as from a DSL.

• How to Get the Original Dragged Item. If the dragged item is a DSL element, you can open the source model and access the element.

• Using Mouse Actions: Dragging Compartment Items. This sample demonstrates a lower-level handler that intercepts mouse actions on a shape’s fields. The example lets the user re-order the items in a compartment by dragging with the mouse.

Defining Gesture Handlers by Overriding ShapeElement Methods

Add a new code file to your DSL project. For a gesture handler, you usually must have at least the following using statements:

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Diagrams;
using System.Linq;

In the new file, define a partial class for the shape or diagram class that should respond to the drag operation. Override the following methods:

• OnDragOver- This method is called when the mouse pointer enters the shape during a drag operation. Your method should inspect the item that the user is dragging, and set the Effect property to indicate whether the user can drop the item on this shape. The Effect property determines the appearance of the cursor while it is over this shape, and also determines whether OnDragDrop() will be called when the user releases the mouse button.

  partial class MyShape // MyShape generated from DSL Definition.
  {
      public override void OnDragOver(DiagramDragEventArgs e)
      {
        base.OnDragOver(e);
        if (e.Effect == System.Windows.Forms.DragDropEffects.None 
             && IsAcceptableDropItem(e)) // To be defined
        {
          e.Effect = System.Windows.Forms.DragDropEffects.Copy;
        }
      }
  

• OnDragDrop – This method is called if the user releases the mouse button while the mouse pointer rests over this shape or diagram, if OnDragOver(DiagramDragEventArgs e) previously set e.Effect to a value other than None.

  public override void OnDragDrop(DiagramDragEventArgs e)
      {
        if (!IsAcceptableDropItem(e))
        {
          base.OnDragDrop(e);
        }
        else 
        { // Process the dragged item, for example merging a copy into the diagram
          ProcessDragDropItem(e); // To be defined
        }  
      }
  

• OnDoubleClick – This method is called when the user double-clicks the shape or diagram.

  For more information, see How to: Intercept a Click on a Shape or Decorator.

Define IsAcceptableDropItem(e) to determine whether the dragged item is acceptable, and ProcessDragDropItem(e) to update your model when the item is dropped. These methods must first extract the item from the event arguments. For information about how to do that, see How to get a reference to the dragged item.

Defining Gesture Handlers by using MEF

MEF (Managed Extensibility Framework) lets you define components that can be installed with minimal configuration. For more information, see Managed Extensibility Framework (MEF).

To define a MEF gesture handler

1. Add to your Dsl and DslPackage projects the MefExtension files that are described in Extend your DSL by using MEF.

2. You can now define a gesture handler as a MEF component:

     // This attribute is defined in the generated file
     // DslPackage\MefExtension\DesignerExtensionMetaDataAttribute.cs:
     [MyDslGestureExtension]
     public class MyGestureHandlerClassName : IGestureExtension
     {
       /// <summary>
       /// Called to determine whether a drag onto the diagram can be accepted.
       /// </summary>
       /// <param name="diagramDragEventArgs">Contains a link to the item that is being dragged</param>
       /// <param name="targetMergeElement">The shape or connector that the mouse is over</param>
       /// <returns>True if the item can be accepted on the targetMergeElement.</returns>
       public bool CanDragDrop(ShapeElement targetMergeElement, DiagramDragEventArgs diagramDragEventArgs)
       {
         MyShape target = targetMergeElement as MyShape;
         if (target == null) return false;
         if (target.IsAcceptableDropItem(diagramDragEventArgs)) return true; 
         return false;
       }
       public void OnDragDrop(ShapeElement targetDropElement, DiagramDragEventArgs diagramDragEventArgs)
       {
         MyShape target = targetMergeElement as MyShape;
         if (target == null || ! target.IsAcceptableDropItem(diagramDragEventArgs)) return;
         // Process the dragged item, for example merging a copy into the diagram:
         target.ProcessDragDropItem(diagramDragEventArgs);
      }
   
   

   You can create more than one gesture handler component, such as when you have different types of dragged objects.

3. Add partial class definitions for the target shape, connector or diagram classes, and define the methods IsAcceptableDropItem() and ProcessDragDropItem(). These methods must begin by extracting the dragged item from the event arguments. For more information, see How to get a reference to the dragged item.

How to decode the dragged item

When the user drags an item onto your diagram, or from one part of your diagram to another, information about the item that is being dragged is available in DiagramDragEventArgs. Because the drag operation could have started at any object on the screen, the data can be available in any one of a variety of formats. Your code must recognize the formats with which it is capable of dealing.

To discover the formats in which your drag source information is available, run your code in debugging mode, setting a breakpoint at the entry to OnDragOver() or CanDragDrop(). Inspect the values of the DiagramDragEventArgs parameter. The information is provided in two forms:

• IDataObject Data – This property carries serialized versions of the source objects, usually in more than one format. Its most useful functions are:

  • diagramEventArgs.Data.GetDataFormats() – Lists the formats in which you can decode the dragged object. For example, if the user drags a file from the desktop, the available formats include the file name ("FileNameW").

  • diagramEventArgs.Data.GetData(format) – Decodes the dragged object in the specified format. Cast the object to the appropriate type. For example:

    string fileName = diagramEventArgs.Data.GetData("FileNameW") as string;

    You can also transmit objects such as model bus references from the source in your own custom format. For more information, see How to Send Model Bus References in a Drag and Drop.

• ElementGroupPrototypePrototype – Use this property if you want users to drag items from a DSL or a UML model. An element group prototype contains one or more objects, links, and their property values. It is also used in paste operations and when you are adding an element from the toolbox. In a prototype, objects and their types are identified by Guid. For example, this code allows the user to drag class elements from a UML diagram or UML Model Explorer:

  private bool IsAcceptableDropItem(DiagramDragEventArgs e)
  {
    return e.Prototype != null && e.Prototype.RootProtoElements.Any(element => 
          element.DomainClassId.ToString() 
          == "3866d10c-cc4e-438b-b46f-bb24380e1678"); // Accept UML class shapes.
   // Or, from another DSL: SourceNamespace.SourceShapeClass.DomainClassId
  }
  

  To accept UML shapes, determine the Guids of the UML shape classes by experiment. Remember that there is usually more than one type of element on any diagram. Remember also that an object dragged from a DSL or UML diagram is the shape, not the model element.

DiagramDragEventArgs also has properties that indicate the current mouse pointer position and whether the user is pressing the CTRL, ALT, or SHIFT keys.

How to get the original of a dragged element

The Data and Prototype properties of the event arguments contain only a reference to the dragged shape. Usually, if you want to create an object in the target DSL that is derived from the prototype in some way, you need to obtain access to the original, for example, reading the file contents, or navigating to the model element represented by a shape. You can use Visual Studio Model Bus to help with this.

To prepare a DSL project for Model Bus

• Make the source DSL accessible by Visual Studio Model Bus:

  1. Download and install the Visual Studio Model Bus extension, if it is not already installed. For more information, see Visualization and Modeling SDK.

  2. Open the DSL definition file of the source DSL in DSL Designer. Right-click the design surface and then click Enable Modelbus. In the dialog box, choose one or both of the options. Click OK. A new project "ModelBus" is added to the DSL solution.

  3. Click Transform All Templates and rebuild the solution.

To send an object from a source DSL

• In your ElementOperations subclass, override Copy() so that it encodes a Model Bus Reference (MBR) into the IDataObject. This method will be called when the user starts to drag from the source diagram. The encoded MBR will then be available in the IDataObject when the user drops in the target diagram.

  
  
  using Microsoft.VisualStudio.Modeling;
  using Microsoft.VisualStudio.Modeling.Shell;
  using Microsoft.VisualStudio.Modeling.Diagrams;
  using Microsoft.VisualStudio.Modeling.Integration;
  using Microsoft.VisualStudio.Modeling.Integration.Shell;
  using System.Drawing; // PointF
  using  System.Collections.Generic; // ICollection
  using System.Windows.Forms; // for IDataObject
  ...
  public class MyElementOperations : DesignSurfaceElementOperations
  {
      public override void Copy(System.Windows.Forms.IDataObject data, System.Collections.Generic.ICollection<ModelElement> elements, ClosureType closureType, System.Drawing.PointF sourcePosition)
      {
        base.Copy(data, elements, closureType, sourcePosition);
  
        // Get the ModelBus service:
        IModelBus modelBus =
            this.Store.GetService(typeof(SModelBus)) as IModelBus;
        DocData docData = ((VSDiagramView)this.Diagram.ActiveDiagramView).DocData;
        string modelFile = docData.FileName;
        // Get an adapterManager for the target DSL:
        ModelBusAdapterManager manager =
            (modelBus.FindAdapterManagers(modelFile).First());
        ModelBusReference modelReference = manager.CreateReference(modelFile);
        ModelBusReference elementReference = null;
        using (ModelBusAdapter adapter = modelBus.CreateAdapter(modelReference))
        {
          elementReference = adapter.GetElementReference(elements.First());
        }
  
        data.SetData("ModelBusReference", elementReference);
      }
  ...}
  

To receive a Model Bus Reference from a DSL in a target DSL or UML project

1. In the target DSL project, add project references to:

   • The source Dsl project.

   • The source ModelBus project.

2. In the gesture handler code file, add the following namespace references:

   using Microsoft.VisualStudio.Modeling;
   using Microsoft.VisualStudio.Modeling.ExtensionEnablement;
   using Microsoft.VisualStudio.Modeling.Diagrams;
   using Microsoft.VisualStudio.Modeling.Diagrams.ExtensionEnablement;
   using Microsoft.VisualStudio.Modeling.Integration;
   using SourceDslNamespace;
   using SourceDslNamespace.ModelBusAdapters;
   

3. The following sample illustrates how to get access to the source model element:

     partial class MyTargetShape // or diagram or connector 
     {
       internal void ProcessDragDropItem(DiagramDragEventArgs diagramDragEventArgs)
       {
         // Verify that we're being passed an Object Shape.
         ElementGroupPrototype prototype = diagramDragEventArgs.Prototype;
         if (prototype == null) return;
         if (Company.InstanceDiagrams.ObjectShape.DomainClassId
           != prototype.RootProtoElements.First().DomainClassId)
           return;
         // - This is an ObjectShape.
         // - We need to access the originating Store, find the shape, and get its object.
   
         IModelBus modelBus = targetDropElement.Store.GetService(typeof(SModelBus)) as IModelBus;
   
         // Unpack the MBR that was packed in Copy:
         ModelBusReference reference = diagramDragEventArgs.Data.GetData("ModelBusReference") as ModelBusReference;
         using (SourceDslAdapter adapter = modelBus.CreateAdapter(reference) as SourceDslAdapter)
         {
           using (ILinkedUndoTransaction t = LinkedUndoContext.BeginTransaction("doing things"))
           {
             // Quickest way to get the shape from the MBR:
             ObjectShape firstShape = adapter.ResolveElementReference<ObjectShape>(reference);
   
             // But actually there might be several shapes - so get them from the prototype instead:
             IElementDirectory remoteDirectory = adapter.Store.ElementDirectory;
             foreach (Guid shapeGuid in prototype.SourceRootElementIds)
             {
               PresentationElement pe = remoteDirectory.FindElement(shapeGuid) as PresentationElement;
               if (pe == null) continue;
               SourceElement instance = pe.ModelElement as SourceElement;
               if (instance == null) continue;
   
               // Do something with the object:
           instance...
             }
             t.Commit();
           }
         }
     }
   

To accept an element sourced from a UML model

• The following code sample accepts an object dropped from a UML diagram.

    using Microsoft.VisualStudio.ArchitectureTools.Extensibility;
    using Microsoft.VisualStudio.ArchitectureTools.Extensibility.Uml;
    using Microsoft.VisualStudio.ArchitectureTools.Extensibility.Presentation;
    using Microsoft.VisualStudio.Modeling;
    using Microsoft.VisualStudio.Modeling.Diagrams;
    using Microsoft.VisualStudio.Modeling.Diagrams.ExtensionEnablement;
    using Microsoft.VisualStudio.Uml.Classes;
    using System;
    using System.ComponentModel.Composition;
    using System.Linq;
  ...
  partial class TargetShape
  {
    internal void ProcessDragDropItem(DiagramDragEventArgs diagramDragEventArgs)
    {
          EnvDTE.DTE dte = this.Store.GetService(typeof(EnvDTE.DTE)) as EnvDTE.DTE;
          // Find the UML project
          foreach (EnvDTE.Project project in dte.Solution.Projects)
          {
            IModelingProject modelingProject = project as IModelingProject;
            if (modelingProject == null) continue; // not a modeling project
            IModelStore store = modelingProject.Store;
            if (store == null) return;
  
            foreach (IDiagram dd in store.Diagrams())
            {
                // Get Modeling.Diagram that implements UML.IDiagram:
                Diagram diagram = dd.GetObject<Diagram>(); 
  
                foreach (Guid elementId in e.Prototype.SourceRootElementIds)
                {
                  ShapeElement shape = diagram.Partition.ElementDirectory.FindElement(elementId) as ShapeElement;
                  if (shape == null) continue;
                  // This example assumes the shape is a UML class:
                  IClass classElement = shape.ModelElement as IClass;
                  if (classElement == null) continue;
  
                  // Now do something with the UML class element ...
                }
          }
        break; // don't try any more projects 
  }  }  }
  

Using Mouse Actions: Dragging Compartment Items

You can write a handler that intercepts mouse actions on a shape’s fields. The following example lets the user re-order the items in a compartment by dragging with the mouse.

To build this example, create a solution by using the Class Diagrams solution template. Add a code file and add the following code. Adjust the namespace to be the same as your own.

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Design;
using Microsoft.VisualStudio.Modeling.Diagrams;
using System.Collections.Generic;
using System.Linq;

// This sample allows users to re-order items in a compartment shape by dragging.

// This example is built on the "Class Diagrams" solution template of VMSDK (DSL Tools).
// You will need to change the following domain class names to your own:
// ClassShape = a compartment shape
// ClassModelElement = the domain class displayed using a ClassShape
// This code assumes that the embedding relationships displayed in the compartments
// don't use inheritance (don't have base or derived domain relationships).

namespace Company.CompartmentDrag  // EDIT.
{
 /// <summary>
 /// Manage the mouse while dragging a compartment item.
 /// </summary>
 public class CompartmentDragMouseAction : MouseAction
 {
  private ModelElement sourceChild;
  private ClassShape sourceShape;
  private RectangleD sourceCompartmentBounds;

  public CompartmentDragMouseAction(ModelElement sourceChildElement, ClassShape sourceParentShape, RectangleD bounds)
   : base (sourceParentShape.Diagram)
  {
   sourceChild = sourceChildElement;
   sourceShape = sourceParentShape;
   sourceCompartmentBounds = bounds; // For cursor.
  }
   
  /// <summary>
  /// Call back to the source shape to drop the dragged item.
  /// </summary>
  /// <param name="e"></param>
  protected override void OnMouseUp(DiagramMouseEventArgs e)
  {
   base.OnMouseUp(e);
   sourceShape.DoMouseUp(sourceChild, e);
   this.Cancel(e.DiagramClientView);
   e.Handled = true;
  }

  /// <summary>
  /// Ideally, this shouldn't happen. This action should only be active
  /// while the mouse is still pressed. However, it can happen if you
  /// move the mouse rapidly out of the source shape, let go, and then 
  /// click somewhere else in the source shape. Yuk.
  /// </summary>
  /// <param name="e"></param>
  protected override void OnMouseDown(DiagramMouseEventArgs e)
  {
   base.OnMouseDown(e);
   this.Cancel(e.DiagramClientView);
   e.Handled = false;
  }

  /// <summary>
  /// Display an appropriate cursor while the drag is in progress:
  /// Up-down arrow if we are inside the original compartment.
  /// No entry if we are elsewhere.
  /// </summary>
  /// <param name="currentCursor"></param>
  /// <param name="diagramClientView"></param>
  /// <param name="mousePosition"></param>
  /// <returns></returns>
  public override System.Windows.Forms.Cursor GetCursor(System.Windows.Forms.Cursor currentCursor, DiagramClientView diagramClientView, PointD mousePosition)
  {
   // If the cursor is inside the original compartment, show up-down cursor.
   return sourceCompartmentBounds.Contains(mousePosition) 
    ? System.Windows.Forms.Cursors.SizeNS // Up-down arrow.
    : System.Windows.Forms.Cursors.No;
  }
 }

 /// <summary>
 /// Override some methods of the compartment shape.
 /// *** GenerateDoubleDerived must be set for this shape in DslDefinition.dsl. ****
 /// </summary>
 public partial class ClassShape
 {
  /// <summary>
  /// Model element that is being dragged.
  /// </summary>
  private static ClassModelElement dragStartElement = null;
  /// <summary>
  /// Absolute bounds of the compartment, used to set the cursor.
  /// </summary>
  private static RectangleD compartmentBounds;

  /// <summary>
  /// Attach mouse listeners to the compartments for the shape.
  /// This is called once per compartment shape.
  /// The base method creates the compartments for this shape.
  /// </summary>
  public override void EnsureCompartments()
  {
   base.EnsureCompartments();
   foreach (Compartment compartment in this.NestedChildShapes.OfType<Compartment>())
   {
    compartment.MouseDown += new DiagramMouseEventHandler(compartment_MouseDown);
    compartment.MouseUp += new DiagramMouseEventHandler(compartment_MouseUp);
    compartment.MouseMove += new DiagramMouseEventHandler(compartment_MouseMove);
   }
  }


  /// <summary>
  /// Remember which item the mouse was dragged from.
  /// We don't create an Action immediately, as this would inhibit the
  /// inline text editing feature. Instead, we just remember the details
  /// and will create an Action when/if the mouse moves off this list item.
  /// </summary>
  /// <param name="sender"></param>
  /// <param name="e"></param>
  void compartment_MouseDown(object sender, DiagramMouseEventArgs e)
  {
   dragStartElement = e.HitDiagramItem.RepresentedElements.OfType<ClassModelElement>().FirstOrDefault();
   compartmentBounds = e.HitDiagramItem.Shape.AbsoluteBoundingBox;
  }

  /// <summary>
  /// When the mouse moves away from the initial list item, but still inside the compartment,
  /// create an Action to supervise the cursor and handle subsequent mouse events.
  /// Transfer the details of the initial mouse position to the Action.
  /// </summary>
  /// <param name="sender"></param>
  /// <param name="e"></param>
  void compartment_MouseMove(object sender, DiagramMouseEventArgs e)
  {
   if (dragStartElement != null)
   {
    if (dragStartElement != e.HitDiagramItem.RepresentedElements.OfType<ClassModelElement>().FirstOrDefault())
    {
     e.DiagramClientView.ActiveMouseAction = new CompartmentDragMouseAction(dragStartElement, this, compartmentBounds);
     dragStartElement = null;
    }
   }
  }

  /// <summary>
  /// User has released the mouse button. 
  /// </summary>
  /// <param name="sender"></param>
  /// <param name="e"></param>
  void compartment_MouseUp(object sender, DiagramMouseEventArgs e)
  {
    dragStartElement = null;
  }

  /// <summary>
  /// Forget the source item if mouse up occurs outside the
  /// compartment.
  /// </summary>
  /// <param name="e"></param>
  public override void OnMouseUp(DiagramMouseEventArgs e)
  {
   base.OnMouseUp(e);
   dragStartElement = null;
  }


  /// <summary>
  /// Called by the Action when the user releases the mouse.
  /// If we are still on the same compartment but in a different list item,
  /// move the starting item to the position of the current one.
  /// </summary>
  /// <param name="dragFrom"></param>
  /// <param name="e"></param>
  public void DoMouseUp(ModelElement dragFrom, DiagramMouseEventArgs e)
  {
   // Original or "from" item:
   ClassModelElement dragFromElement = dragFrom as ClassModelElement;
   // Current or "to" item:
   ClassModelElement dragToElement = e.HitDiagramItem.RepresentedElements.OfType<ClassModelElement>().FirstOrDefault();
   if (dragFromElement != null && dragToElement != null)
   {
    // Find the common parent model element, and the relationship links:
    ElementLink parentToLink = GetEmbeddingLink(dragToElement);
    ElementLink parentFromLink = GetEmbeddingLink(dragFromElement);
    if (parentToLink != parentFromLink && parentFromLink != null && parentToLink != null)
    {
     // Get the static relationship and role (= end of relationship):
     DomainRelationshipInfo relationshipFrom = parentFromLink.GetDomainRelationship();
     DomainRoleInfo parentFromRole = relationshipFrom.DomainRoles[0];
     // Get the node in which the element is embedded, usually the element displayed in the shape:
     ModelElement parentFrom = parentFromLink.LinkedElements[0];

     // Same again for the target:
     DomainRelationshipInfo relationshipTo = parentToLink.GetDomainRelationship();
     DomainRoleInfo parentToRole = relationshipTo.DomainRoles[0];
     ModelElement parentTo = parentToLink.LinkedElements[0];

     // Mouse went down and up in same parent and same compartment:
     if (parentTo == parentFrom && relationshipTo == relationshipFrom)
     {
      // Find index of target position:
      int newIndex = 0;
      var elementLinks = parentToRole.GetElementLinks(parentTo);
      foreach (ElementLink link in elementLinks)
      {
       if (link == parentToLink) { break; }
       newIndex++;
      }

      if (newIndex < elementLinks.Count)
      {
       using (Transaction t = parentFrom.Store.TransactionManager.BeginTransaction("Move list item"))
       {
        parentFromLink.MoveToIndex(parentFromRole, newIndex);
        t.Commit();
       }
      }
     }
    }
   }
  }

  /// <summary>
  /// Get the embedding link to this element.
  /// Assumes there is no inheritance between embedding relationships.
  /// (If there is, you need to make sure you've got the relationship
  /// that is represented in the shape compartment.)
  /// </summary>
  /// <param name="child"></param>
  /// <returns></returns>
  ElementLink GetEmbeddingLink(ClassModelElement child)
  {
   foreach (DomainRoleInfo role in child.GetDomainClass().AllEmbeddedByDomainRoles)
   {
    foreach (ElementLink link in role.OppositeDomainRole.GetElementLinks(child))
    {
     // Just the assume the first embedding link is the only one.
     // Not a valid assumption if one relationship is derived from another.
     return link;
    }
   }
   return null;
  }
 }
}

See Also

Concepts

Customizing Copy Behavior

Deploying Domain-Specific Language Solutions