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 How to: Program Copy and Paste Behavior - redirect. You might also be able to customize the DSL definition.

There are two alternative procedures for adding a gesture handler to your DSL:

• Override the OnDragOver(DiagramDragEventArgs), OnDragDrop(DiagramDragEventArgs), and OnDoubleClick(DiagramPointEventArgs) methods in your shape classes. There are also other methods that you can override to provide finer control of your DSL’s response to mouse and keyboard actions. Always call the base method unless you know that you want to omit the default behavior.

• Define an extension gesture handler class using Managed Extensibility Framework (MEF). In addition, you can allow third parties to define handlers, which users can install separately from your DSL.

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(DiagramDragEventArgs)- 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(DiagramDragEventArgs) – 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(DiagramPointEventArgs) – 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 Overview.

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.

• ElementGroupPrototype Prototype – 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 
  }  }  }
  

See Also

Concepts

Customizing Copy Behavior

How to: Program Copy and Paste Behavior - redirect

Change History