EZwgl (8.1 How Drag and Drop Works)

## 8.1 How Drag and Drop Works

Each EZwgl application has an internal window (unmapped) for communication. Drag and Drop transactions are carried out by changing the window properties of these communication windows.

For each type of information an application transfers, there is an unique internal identifier (an Atom) that specifies the information type. This identifier is called a conversion target. It is the responsibility of an application to register the conversion targets before using them. Convertion targets are created by `XInternAtom` or `EZ_GetAtom`. These routines register a name to the X server. Once created, an atom remains unique till server shutdown.

The right mouse button (Button3) is the drag and drop button for EZwgl. When a user press-and-drag Button3 over a drag source, EZwgl initiates a new DnD transaction, executes the initialization encoder (registered to the special target `EZ_DND_DRAG_INIT_ATOM`), build a list of conversion targets the drag source converts, and broadcast to all EZwgl applications this list of targets. It then replace the default cursor by the drag cursor if the drag source has one, or a snapshot of the drag source will be made to follow the pointer, or if a drag icon is supplied, it pops out the drag icon. Whenever the pointer moves, the drag source broadcast its position to all EZwgl applications. If the drag is over a potential drop target, the border of the potential target lights up. When the drag is released over a drop target, the following sequence of actions will be initiated.

- The drag source invokes its drag setup encoder (a special encoder registered to the special target `EZ_DND_DRAG_START_ATOM`) and its callbacks; and then sends a message containing the setup message and the list of targets the source converts to the drop target.

- The target examine the list of targets the source supplied and examine the list of decoders registered to itself, bulids a list of matching targets both the source and the target convert and invokes its drop setup decoder (a special decoder registered to the special target `EZ_DND_DROP_START_ATOM`) and its callbacks.

- If there are no matching targets on the matching list, the target aborts its drop operation, invokes its drag clean up decoder (a decoder registered to the special target `EZ_DND_DROP_FINISH_ATOM`) and its callback, and sends a message to the drag source to abort. Otherwise, it sends a convertion request, start with the first available matching target.

- Upon reciving a conversion request, the drag source invokes its relevent encoder to do the conversion. If succesful, the encoded message is send to the target. Otherwise, it sends a message to the drop target that conversion for the requested target has failed.

- If the drop target receives a conversion failed message, it examine the list of matching targets. If there are more targets on the matching list, it starts step 3 again. Otherwise, It sends a message to the drag source to cancell the current drag, invokes its drop clean up procedures and aborts the current DnD transaction itself.

  If the drop target receives a conversion, it invokes its relevent DnD decoder to decode the message. If succesfull, it sends an acknowledgement message to the drag source and, if there is a callback for this decoder, it invokes the callback. If decoding fails, it'll try the next target on the matching list and start step 3 again.

- If the drag source receives an acknowledgement message, it invokes the callback for the current encoder if there is one; it then invokes the drag clean up procedures (an encoder registered to the special target `EZ_DND_DRAG_FINISH_ATOM`) and marks the current DnD transaction complete. If it receives a message to abort, it invokes the drag clean up procedures and aborts the current DnD transaction.

HTML Documentation Maintainance:`Arturo Espinosa <arturo@nuclecu.unam.mx>`