## 8.4 Related Routines

    void EZ_WidgetAddDnDDataEncoder(EZ_Widget *widget, Atom target,
                                    int tag, EZ_DnDEncoder encoder, void *edata,
                                    EZ_CallBack callback, void *cdata);
    void EZ_WidgetDeleteDnDDataEncoder(EZ_Widget *widget,
                        EZ_DnDEncoder encoder, void *edata);
    void EZ_WidgetDeleteAllDnDDataEncoders(EZ_Widget *widget);

    void EZ_ItemAddDnDDataEncoder(EZ_Item *item, Atom target,
                                  int tag, EZ_DnDEncoder encoder, void *edata,
                                  EZ_CallBack callback, void *cdata);
    void EZ_ItemDeleteDnDDataEncoder(EZ_Item *item,
                                 EZ_DnDEncoder encoder, void *edata);
    void EZ_ItemDeleteAllDnDDataEncoders(EZ_Item *item);

The tag argument used in `*Add*Encoder` is used to choose conversion methods. It is useful for the following situations.

- A drag source has multiple encoders for the same conversion target. For example, when transfering files, one may want either to copy a file or move a file to the destination specified by the drop site. This can be achieved by registering multiple encoders with different tags. For example, shift-press-drag-relase for copying the file and cntrl-press-drag-release for moving the file.

- Sometimes it is preferable to enforce a more strict drag and drop policy so that a careless drag and drop will not do any harm. For example, if you write a file manager and want to use DnD to remove files, it may be better to enforce a control-press-drag-release policy for the trash can.

- The tag value `~0` is reserved for a special purpose: drop at the root window of your display. Strictly speaking, the root window is not a valid drop site because it does not talk to the drag source. Nevertheless, for applications like file managers, it is useful to have a feature so a user can drop an item at the root window. Since the root window is not an official drop site, there will be no data transfers. The action is completely handled by the drag source. If you want to use this feature. Here are the tricks.

  - Write a special encoder which does not convert anything, but rather, acts like a callback. In the example of droping a file item over the background, you may want to create a Icon widget, set it up properly and display it. The encoder has to return `EZ_DND_SUCCESS` on success and `EZ_DND_FAILURE` on failure. The callbacks for this special encoder behave exactly the same as that of a regular encoder. It is invoked when the encoder returns `EZ_DND_SUCCESS`.

  - Register your special encoder with a tag value `~0`.

    void EZ_WidgetAddDnDDataDecoder(EZ_Widget *widget, Atom target,
                          int tag, EZ_DnDDecoder decoder, void *edata,
                          EZ_CallBack callback, void *cdata);
    void EZ_WidgetDeleteDnDDataDecoder(EZ_Widget *widget,
                          EZ_DnDDecoder decoder, void *data);
    void EZ_WidgetDeleteAllDnDDataDecoders(EZ_Widget *widget);

    void EZ_ItemAddDnDDataDecoder(EZ_Item *item, Atom target,
                         int tag, EZ_DnDDecoder decoder, void *edata,
                         EZ_CallBack callback, void *cdata);
    void EZ_ItemDeleteDnDDataDecoder(EZ_Item *item,
                         EZ_DnDDecoder decoder, void *data);
    void EZ_ItemDeleteAllDnDDataDecoders(EZ_Item *item);

    void EZ_GetDnDDropLocation(int *rootX, int *rootY,
                               int *winX, int *winY);

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