The Procedures to Describe a Drag-and-Drop Process

In the VC environment, by describing XVCD and handling the mouse, you can perform drag and drop operations while editing an XML document. This document provides understanding about procedures related to performing the drag and drop operation by describing a XVCD in the VC environment.

1. Drag Source

The task on the drag source side may, from the beginning, be divided into the following stages:

Declare the start of the drag operation.
If needed, the operation may be performed according to the position to which the pointer moved during dragging.
After drag operation terminates with a drop, perform the termination process.

If a user starts a drag operation, an event object is issued. The event object issued on the drag-source side is represented by an XML document fragment consisting of event:drag-source elements. When the issued event object is processed, the operation is performed in a xvcd:action element.

The series of operations from drag start to termination for the drag-source side need to be described within one xvcd:action element. If the series of operations are divided and described within multiple xvcd:action elements, each operation is assumed for other drag sources.

From now on, the section provides an explanation about the description of the operation performed at each stage on the drag-source side.

1.1. Start Dragging

When a user starts dragging in the canvas, DRAG_DRAG_GESTURE event is issued. The issued event objects are listed below.

<event:drag-source type="gesture" action="Action type " />

The value which represents the following action types is specified in an action attribute of event:drag-start element: The action type is the value which indicates the action to be performed by the drop target.

copy: Copy action.
move: Move action.
link: Link action.

If DRAG_DRAG_GESTURE event is received in a xvcd:action element, a dragging operation should always be started. Use xvcd:start-drag instruction to start a dragging operation.

1.2. While Dragging

While dragging, the following event object is issued for the xvcd:action element which is called xvcd:start-drag instruction:

DRAG_DRAG_ENTER Event
Issued when the pointer moves into the particular drop-target area while dragging. The issued event objects are listed below.
```
<event:drag-source type="drag-enter" />
```
DRAG_DRAG_OVER Event
Issued when the pointer moves within the particular drop-target area while dragging. The issued event objects are listed below.
```
<event:drag-source type="drag-over" />
```
DRAG_DRAG_EXIT Event
Issued when the pointer moves out of the particular drop-target area while dragging. The issued event objects are listed below.
```
<event:drag-source type="drag-exit" />
```

If an operation for a received event needs to be performed, describe how to perform the proper operation.

1.3. End Dragging

When the drag and drop operation is complete, DRAG_DROP_END event is issued for the xvcd:action element called xvcd:start-drag instruction. The issued event objects are listed below.

<event:drag-source type="drop-end" result="Execution result" action="Action type" />

The following value that represents the execution result is specified in the result attribute of the event:drag-source element:

success: The drop succeeded.
failure: The drop failed.

The one value is specified from the same three values as when drag starts for the action type value set in the action attribute of the event:drag-source element. The value may be different than when drag starts.

If a DRAG_DROP_END event is received, describe the necessary operation to perform according to the value of the result attribute and the value of the action attribute.

1.4. XVCD Skeleton on the Drag-Source Side

Describes the typical pattern of XVCD operation as a skeleton on the drag-source side. If the operation during dragging is unnecessary, the description of the unnecessary portion may be omitted.

<xvcd:action event="event:drag-source">
    <instruction:param name="event:event"/>
    <instruction:variable name="source" select="$event:event/event:drag-source"/>

    <instruction:if test="$source/@type = 'gesture'">
        <xvcd:start-drag event="$event:event">
            <!--
                Describe the procedures to retrieve dragged XML document fragments or 
                new XML document fragments.
            -->
        </xvcd:start-drag>
        </instruction:if>

    <instruction:if test="$source/@type = 'drag-enter'">
        <!-- If an operation for a DRAG_DRAG_ENTER event is required, describe herein.-->
    </instruction:if>

    <instruction:if test="$source/@type = 'drag-over'">
        <!-- If an operation for a DRAG_DRAG_OVER event is required, describe herein.-->
    </instruction:if>

    <instruction:if test="$source/@type = 'drag-exit'">
        <!-- If an operation for a DRAG_DRAG_EXIT event is required, describe herein.-->
    </instruction:if>

    <instruction:if test="$source/@type = 'drop-end'">
        <instruction:if test="$source/@result = 'success'">
            <instruction:if test="$source/@action = 'copy'">
                <!-- Describe the copy operation when the drop is successful. -->
            </instruction:if>
            <instruction:if test="$source/@action='move'">
                <!-- Describe the move operation when the drop is successful. -->
            </instruction:if>
        </instruction:if>
    </instruction:if>

</xvcd:action>

2. Drop Target

The tasks on the drop-target side may, from the beginning, be divided into the following stages:

If necessary, perform the operation corresponding to the pointer moving over the drop target during dragging.
Perform the operation when the dragged data is dropped over the drop target.

If a user starts a drag operation, an event object is issued. The event object issued on the drop-target side is represented by an XML document fragment consisting of event:drop-target elements. When the issued event object is processed, the operation is performed in a xvcd:action element.

The series of operations from drag start to termination for the drop-target side need to be described within one xvcd:action element. If the series of operations are divided and described within multiple xvcd:action elements, each operation is assumed for other drop targets.

From now on, the section provides an explanation about the description of the operation performed at each stage on the drop-target side.

2.1. While Dragging

While dragging, the following event object is issued for the xvcd:action element of the drop target:

DROP_DRAG_ENTER Event
Issued when the pointer moves into the particular drop-target area while dragging. The issued event objects are listed below.

<event:drop-target type="drag-enter" action="Action type " >
    <dtf:string>
        <!-- Data representing the content to drag in text format -->
    </dtf:string>
    <dtf:fragment>
        <!-- Data representing the content to drag using an XML document fragment -->
    </dtf:fragment>
</event:drop-target>

DROP_DRAG_OVER Event
Issued when the pointer moves within the particular drop-target area while dragging. The issued event objects are listed below.

<event:drop-target type="drag-over" action="Action type " >
    <dtf:string>
        <!-- Data representing the content to drag in text format -->
    </dtf:string>
    <dtf:fragment>
        <!-- Data representing the content to drag using an XML document fragment -->
    </dtf:fragment>
</event:drop-target>

DROP_DRAG_EXIT Event
Issued when the pointer moves out of the particular drop-target area while dragging. The issued event objects are listed below.

<event:drop-target type="drag-exit" action="Action type " >
    <dtf:string>
        <!-- Data representing the content to drag in text format -->
    </dtf:string>
    <dtf:fragment>
        <!-- Data representing the content to drag using an XML document fragment -->
    </dtf:fragment>
</event:drop-target>

The value which represents the following action types is specified in the action attribute of each event:drop-target element: The action type is the value which indicates the action to be performed by the drop target.

copy: Copy action.
move: Move action.
link: Link action.

If an operation for a received event needs to be performed, describe how to perform the proper operation.

2.2. When Dropping

When the drop operation is complete, a DROP_DROP event is issued for the drag target of the drop operation. The issued event objects are listed below.

<event:drop-target type="drop" action="Action type " >
    <dtf:string>
        <!-- Data representing the content to drag in text format -->
    </dtf:string>
    <dtf:fragment>
        <!-- Data representing the content to drag using an XML document fragment -->
    </dtf:fragment>
</event:drop-target>

The one value is specified from the same three values as while dragging for the type of the action type value set in the action attribute of the event:drop-target element. The value may be different than while dragging.

If a DROP_DROP event is received, describe necessary operation to perform according to the value of the action attribute.

2.3. XVCD Skeleton on the Drop-Target Side

Describe the typical pattern of XVCD operation as a skeleton on the drop-target side.

Replace QName described in italics within the skeleton with the element name appropriate to the scene that is actually used. Also, if the operation during dragging is unnecessary, the description of the unnecessary portion may be omitted.

<xvcd:action event="event:drop-target[event:fragment/QName]">
    <instruction:param name="event:event" />
    <instruction:variable name="target" select="$event:event/event:drop-target" />

    <instruction:if test="$target/@type = 'drag-enter'">
        <!-- If an operation for a DROP_DRAG_ENTER event is required, describe herein.-->
    </instruction:if>

    <instruction:if test="$target/@type = 'drag-over'">
        <!-- If an operation for a DROP_DRAG_OVER event is required, describe herein.-->
    </instruction:if>

    <instruction:if test="$target/@type = 'drag-exit'">
        <!-- If an operation for a DROP_DRAG_EXIT event is required, describe herein.-->
    </instruction:if>

    <instruction:if test="$target/@type = 'drop'">
        <instruction:if test="$target/@action = 'copy'">
            <!-- Describe the copy operation when the drop is successful.-->
        </instruction:if>
        <instruction:if test="$target/@action = 'move'">
            <!-- Describe the move operation when the drop is successful.-->
        </instruction:if>
    </instruction:if>

</xvcd:action>