Image Viewer Drag and Drop

Summary

ImageViewer supports drag and drop operations as a drag source and a drag target in both a native browser mode and a custom mode (via ImageViewerDragInteractiveMode.DragMode).

ImageViewer as the Drag Source

Dragging is available through an instance of ImageViewerDragInteractiveMode set as the current interactive mode of the viewer. When the mode starts, it will set the viewer's HTML5 draggable attribute to true to allow dragging to occur. Currently, the only officially-supported target of a drag operation may only be another ImageViewer. Dragging to other HTML elements is not allowed.

ImageViewerDragInteractiveMode.DragMode offers two choices for drag action:

ImageViewerDragMode.Item: (default) uses a custom LEADTOOLS drag and drop solution that uses the InteractiveService to decipher dragging actions. This provides guaranteed and consistent support across all LEADTOOLS-supported browsers, including most mobile device browsers.
ImageViewerDragMode.HTMLNative makes use of the HTML5 Drag Drop API, which has weak support in most browsers but uses the native "dragenter", "dragleave", etc, events and other supported features when available.

Using ImageViewerDragMode.Item is recommended for a more consistent experience for users. Universally available events of all browsers are used to create the basic effects of the native drag and drop experience, including cursor changes, event data, and custom drag images.

ImageViewer as the Drop Target

To act as the drop target, the target ImageViewer must have ImageViewer.AllowDrop set to true. After that, the viewer is ready to accept and act upon the standard dragenter, dragover, dragleave, and drop events, as well as simulated drag and drop events from a source ImageViewer that uses ImageViewerDragMode.Item.

ItemDragDrop Event

When the drag and drop events occur within the bounds of the imageviewer, ImageViewer.ItemDragDrop is fired with an instance of ImageViewerItemDragDropEventArgs. This object includes the type of operation (enter, leave, over, drop) from the ImageViewerItemDragDropOperation enumeration. It is recommended to use the value from ImageViewerItemDragDropEventArgs.Operation to understand the current drag drop action instead of viewing the original event type, as the reported event may be a "move", "up", or "down" event when using ImageViewerDragMode.Item.

If ImageViewerItemDragDropEventArgs.CustomDragElement is null, the source ImageViewer is using ImageViewerDragMode.HTMLNative.

There are differences in the reported arguments in some cases when using ImageViewerDragMode.HTMLNative and ImageViewerDragMode.Item:

HTMLNative mode will only report ImageViewerItemDragDropOperation.DragEnter or ImageViewerItemDragDropOperation.DragLeave when it enters or leaves the ImageViewer. Item mode will send these events when entering or leaving an ImageViewer or any of the items.
If the drag drop action does not occur directly over any item in the viewer, HTMLNative mode will set ImageViewerItemDragDropEventArgs.TargetItem to the target viewer's active item. Item mode will have the value set to null.

ImageViewerItemDragDropEventArgs.Effect can be used to indicate whether or not a drop operation is allowed at this location. By default, the Effect value will be set to "copy" if the target ImageViewer believes a drop is allowabled, or "none" if it does not. Within the ImageViewer.ItemDragDrop callback the user may change this value to affect the cursor style.

When ImageViewerItemDragDropOperation.Drop is set in the args object, a drop is occurring. In this case, setting ImageViewerItemDragDropEventArgs.Effect to "copy" will do the default behavior of copying the source item's URL to the target item. If any other action is needed, set Effect to "none" and do any actions within the callback.

ImageViewerItemDragDropEventArgs.CustomDragElement (get)

If this value is not null, the source ImageViewer that caused the ImageViewer.ItemDragDrop event to fire is using ImageViewerDragMode.Item, and the value should be the currently-used drag element. This element moves with the cursor. If this value is null, ImageViewerDragMode.HTMLNative is used, and the drag image is handled by the browser based on the browser's support for the HTML5 Drag Drop API.

Note that this value is only a get; to set the custom drag element, see ImageViewerDragInteractiveMode.CustomDragElement.

ImageViewerDragMode

In JavaScript, drag and drop operations can be handled by the HTML5 Drag Drop API. Browser support for this feature, particularly on mobile devices, is weak. For this reason, ImageViewerDragMode provides two drag and drop solutions to use with ImageViewerDragInteractiveMode.DragMode:

ImageViewerDragMode.Item: (default) uses a custom LEADTOOLS drag and drop solution that uses the InteractiveService to decipher dragging actions. This provides guaranteed and consistent support across all LEADTOOLS-supported browsers, including most mobile device browsers.
ImageViewerDragMode.HTMLNative: makes use of the HTML5 Drag Drop API, which has weak support in most browsers but uses the native "dragenter", "dragleave", etc, events and other supported features when available.

Specifically, ImageViewerDragMode.Item will listen for the "down", "move", and "up" events on the items of the source ImageViewer to create the effect of dragging. ImageViewerDragInteractiveMode.CustomDragElement simulates the effect of a drag image from the native API.

Any target ImageViewer instances will listen for the "down", "move", and "up" events (as well as any native drag events) whenever ImageViewer.AllowDrop is true. If the target ImageViewer detects these events inside its bounds while the target ImageViewer is dragging, it will create the proper drag actions to set in ImageViewerItemDragDropEventArgs and send them to ImageViewer.ItemDragDrop.

ImageViewerItemDragDropEventArgs.CustomDragElement (get, set)

This property is only available when ImageViewerDragInteractiveMode.DragMode is set to ImageViewerDragMode.Item. In this mode, the interactive mode will use the "down", "move" and "up" events to simulate the HTML5 Drag Drop API. ImageViewerItemDragDropEventArgs.CustomDragElement allows the user to set a custom element to be moved with the cursor while dragging.

By default, the custom drag element is set to an internally-created copy of the source ImageViewerItem's content image, canvas, or element. At any time, ImageViewerItemDragDropEventArgs.CustomDragElement can be set to any HTMLElement. The set element will be centered horizontally and vertically to the mouse and moved as the mouse moves. If null is passed, the ImageViewerItemDragDropEventArgs.CustomDragElement will go back to using the internally-created copy of the item's content. ImageViewerItemDragDropEventArgs.CustomDragElement will only return null if the Item mode is no longer used.

This provides opportunities for setting the ImageViewerItemDragDropEventArgs.CustomDragElement within ImageViewer.ItemDragDrop to signify a certain state, then returning to the default image when leaving the state.

When a new ImageViewerItemDragDropEventArgs.CustomDragElement is set, the HTML data-drag attribute is set on the element with the source ImageViewerItem's URL, similar to the behavior of the native Drag Drop API's DataTransfer object.

When using your own ImageViewerItemDragDropEventArgs.CustomDragElement, you are responsible for disposal and cleanup of the provided elements. The internally-created element will always be cleaned up when the drag operation finishes.

The ImageViewerItemDragDropEventArgs.CustomDragElement can be accessed from ImageViewerItemDragDropEventArgs.CustomDragElement as a way for the target ImageViewer to determine if ImageViewerDragMode.Item is being used and for comparisons.