EZwgl (8.2 DnD Setup and Clean Up Procedures)

## 8.2 DnD Setup and Clean Up Procedures

EZwgl reserves five special convertion targets:

     EZ_DND_DRAG_INIT_ATOM,
     EZ_DND_DRAG_START_ATOM, EZ_DND_DRAG_FINISH_ATOM,
     EZ_DND_DROP_START_ATOM, EZ_DND_DROP_FINISH_ATOM

They are global atoms set by EZwgl at the initialization time. Encoders/decoders registered to these targets are treated as setup/clean up procedures for DnD.

Encoder for target `EZ_DND_DRAG_INIT_ATOM` is the drag initialization encoder. This encoder and its callback are invoked when the user press-and-move the DnD mouse button over a drag source. The encoder behaves like a callback. Its main purpose is to setup a drag icon. It should not do any conversions as the encoded message will never be used.

Encoder for target `EZ_DND_DRAG_START_ATOM` is the drag setup encoder. This encoder is invoked when the drag is droped at a drop site. The encoded message will be the first message sent to the drop site, along with a list of targets the source converts. Drag setup actions are in the following order.

- Build the list of targets it converts.

- Invoke setup encoder.

- Invoke setup encoder callback.

- Send the encoded message and the list of targets to the drop site.

The list of targets is available to the setup encoder and its callback. One can get this list by calling

    void EZ_DnDGetDragConversionTargets(Atom **targets_ret,
                                        int **ntargets_ret,
                                        unsigned int **action_tag)

The setup encoder and its callback are free to modify the list of targets. For example, the callback may popup a dialogue, ask the user for some infomation and select one or more targets based on the response.

Encoder for target `EZ_DND_DRAG_FINISH_ATOM` is the drag cleanup encoder. This encoder is invoked whenever a DnD transaction is deemed complete, success or not. The encoded message is never used.

Decoder for target `EZ_DND_DROP_START_ATOM` is the the drop setup decoder. It is invoked right after the drop site has received the initial drag setup message (list of targets plus possiblly a short message) from the drag source. The order of actions at the setup time are:

- {Build a list of matching targets it decodes.}

- {Invoke the setup decoder to decode the setup message sent by the drag source.}

- {Invoke the callback of the setup decoder.}

The list of matching decoders is available for both the decoder and its callback. One can get this list by calling

    void EZ_DnDGetMatchedConversionTargets(Atom **targets_ret,
                                           int **ntargets_ret,
                                           unsigned int **action_tag_ret)

The decoder and its callback are free to modify this list.

Encoder for target `EZ_DND_DROP_FINISH_ATOM` is the drop cleanup decoder. This decoder is invoked whenever a DnD transaction is deemed complete, success or not.

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