top of page

Technical details

 

Current version: 4

 

All constants mentioned below are the string names of X atoms, capitalized as shown.  This avoids the need for hard-coded values, which would require a global registry.

 

Atoms and Properties

 

XdndAware

 

This window property must be of type XA_ATOM and must contain the highest version number of the protocol supported by the target.  (Version numbers start at zero.  The maximum version number is 0xFF> because there is only one byte allocated for it in the XdndEnter message.  At one new version every three months, which is very rapid turnover, this will last 64 years.)

 

The property must be set on each top-level X window that contains widgets that can accept drops.  (new in version 3)  The property should not be set on subwindows.  The target must dispatch the messages to the appropriate widget.  Since window managers often insert extra layers of windows, this requires searching down the subwindow tree using XTranslateCoordinates().

 

XdndSelection

 

This is the name of the X Selection that is used when the target wants to examine the data during the drag phase and when it wants to retrieve the data after a drop.

 

Data types

 

All data types are referred to by their corresponding X Atoms.  The atom names are the corresponding MIME types, in all lower case. (RFC's for MIME: 2045, 2046, 2047, 2048, 2049)

 

For text, the charset attribute can be appended to the MIME type. (e.g. Japanese → text/plain;charset=ISO-2022-JP)  If the charset attribute is not

specified, it is assumed to be ISO-8859-1.  (new in version 4)

 

Note that any data type may be transferred via the INCR protocol.

 

XdndTypeList

 

If the source supports more than 3 data types, this window property must be set on the source window, must be of type XA_ATOM, and must contain a list of all the supported data types.

 

Actions (new in version 2)

 

All actions are referred to by their corresponding X Atoms.  The predefined actions are

 

  • XdndActionCopy

  • XdndActionMove

  • XdndActionLink

  • XdndActionAsk

  • XdndActionPrivate

 

The XdndAction prefix is reserved for future expansion, but any other name can be used for other actions as long as both the source and the target recognize it and agree on what it means.  The predefined atom None is not allowed as an action.

 

The default is XdndActionCopy, and this is assumed to be the action when using version 0 or 1.

 

In general, XdndActionMove is implemented by first requesting the data and then the special target DELETE defined in the X Selection protocol.  (File managers will obviously just use mv or its equivalent.)  DELETE should be sent before XdndFinished.

 

Refer to the Theory and Notes sections for more information.

 

XdndActionList (new in version 2)

 

If the source sends XdndActionAsk, this window property must be set on the source window, must be of type XA_ATOM, and must contain a list of all the supported actions.  The first one should be the default so the user doesn't have to change the selection in the radio group too often.

 

XdndActionDescription (new in version 2)

 

If the source sends XdndActionAsk, this window property must be set on the source window, must be of type XA_STRING, and must contain a list of ASCII strings separated by NULL's that the target should display when describing the choices to the user.  These strings must be in the same order as the atoms in the XdndActionList property.

 

The option to cancel the operation must always be provided in the dialog displayed to the user, via a Cancel button, but should not be included in XdndActionList.

 

XdndProxy (new in version 4)

 

If this window property exists, it must be of type XA_WINDOW and must contain the ID of the proxy window that should be checked for XdndAware and that should receive all the client messages, etc.  In order for the proxy window to behave correctly, the appropriate field of the client messages, window or data.l[0], must contain the ID of the window in which the mouse is located, not the proxy window that is receiving the messages.  The only place where the proxy window should be used is when checking XdndAware and in the calls to XSendEvent().

 

The proxy window must have the XdndProxy property set to point to itself.  If it doesn't or if the proxy window doesn't exist at all, one should ignore XdndProxy on the assumption that it is left over after a crash.

 

Client Messages

 

Note:  All unused flags must be set to zero in every message.  This allows one to define new flags without incrementing the version number.

 

XdndEnter

 

Sent from source to target when the mouse enters a window that supports XDND.

 

  • data.l[0] contains the XID of the source window.

 

  • data.l[1]:

    • Bit 0 is set if the source supports more than three data types.

    • The high byte contains the protocol version to use (minimum of the source's and target's highest supported versions).

    • The rest of the bits are reserved for future use.

 

 

  • data.l[2,3,4] contain the first three types that the source supports.  Unused slots are set to None.  The ordering is arbitrary since, in general, the source cannot know what the target prefers.

 

If the Source supports more than three data types, bit 0 of data.l[1] is set.  This tells the Target to check the property XdndTypeList on the Source window for the list of available types.  This property should contain all the available types.

 

XdndPosition

 

Sent from source to target to provide mouse location.

 

  • data.l[0] contains the XID of the source window.

 

  • data.l[1]:

    • The de facto standard is for buttons 4,5,6,7 to trigger scrolling.  If one of these buttons is pressed, bit 10 is set.  Bits 8 and 9 store the index (minus 4) of the button that triggered the XdndPosition message.  Bits 0-7 contain the state of the modifier keys exactly the way X provides them in the event's state attribute.

    • The rest of the bits are reserved for future use.

 

  • data.l[2] contains the coordinates of the mouse position relative to the root window.

 

  • data.l[2] = (x << 16) | y;

 

  • data.l[3] contains the time stamp for retrieving the data. (new in version 1)

 

  • data.l[4] contains the action requested by the user. (new in version 2)

 

XdndStatus

 

Sent from target to source to provide feedback on whether or not the drop will be accepted, and, if so, what action will be taken.

 

  • data.l[0] contains the XID of the target window.

(This is required so XdndStatus messages that arrive after XdndLeave is sent will be ignored.)

 

  • data.l[1]:

    • Bit 0 is set if the current target will accept the drop.

    • Bit 1 is set if the target wants XdndPosition messages while the mouse moves inside the rectangle in data.l[2,3].

    • The rest of the bits are reserved for future use.

 

  • data.l[2,3] contains a rectangle in root coordinates that means "don't send another XdndPosition message until the mouse moves out of here".  It is legal to specify an empty rectangle.  This means "send another message when the mouse moves".  Even if the rectangle is not empty, it is legal for the source to send XdndPosition messages while in the rectangle.  The rectangle is stored in the standard Xlib format of (x,y,w,h):

    • data.l[2] = (x << 16) | y;

    • data.l[3] = (w << 16) | h;

 

  • data.l[4] contains the action accepted by the target.  This is normally only allowed to be either the action specified in the XdndPosition message, XdndActionCopy, or XdndActionPrivate.  None should be sent if the drop will not be accepted. (new in version 2)

 

XdndLeave

 

Sent from source to target to cancel the drop.

 

  • data.l[0] contains the XID of the source window.

  • data.l[1] is reserved for future use (flags).

 

XdndDrop

 

Sent from source to target to complete the drop.

 

  • data.l[0] contains the XID of the source window.

  • data.l[1] is reserved for future use (flags).

  • data.l[2] contains the time stamp for retrieving the data. (new in version 1)

 

XdndFinished (new in version 2)

 

Sent from target to source to indicate that the source can toss the data because the target no longer needs access to it.

 

  • data.l[0] contains the XID of the target window.

 

  • data.l[1]:

    • Bit 0 is set if the current target accepted the drop and successfully performed the accepted drop action. (new in version 5) (If the version being used by the source is less than 5, then the program should proceed as if the bit were set, regardless of its actual value.)

    • The rest of the bits are reserved for future use.

 

  • data.l[2] contains the action performed by the target.  None should be sent if the current target rejected the drop, i.e., when bit 0 of data.l[1] is zero.  (new in version 5)

 

(Note:  Performing an action other than the one that was accepted with the last XdndStatus message is strongly discouraged because the user expects the action to match the visual feedback that was given based on the XdndStatus messages!)

 

<< Previous | Next >>

 

bottom of page