4.1 DeskSet Drag and Drop Handshaking

Drag and drop handshaking begins with the requestor application asking the owner application to convert the TARGETS atom. The owner responds with a list of atoms it understands. If the requestor recognizes enough atoms to continue the procedure, it continues. If the requestor does not recognize enough atoms to complete the process, then the transfer is aborted.

Two cases of handshaking with a DeskSet application are described below. Note that these handshaking descriptions are a simplistic view of dragging and dropping between DeskSet applications. It may be necessary to examine specific DeskSet application source code to pick up procedural nuances.

4.1.1 Handshaking--Simplest Case

The simplest case of drag and drop is when a receiver application asks the owner to send it selection data without regard to data format, alternative transport method, or any other considerations. This is described below:

1. The requestor asks the owner to convert the

   _SUN_ENUMERATION_COUNT atom. The owner responds by sending the number of source objects in the current selection.

   If the response to _SUN_ENUMERATION_COUNT is more than 1, then the programs must agree upon the selection object to be dragged and dropped. The owner converts the _SUN_ENUMERATION_ITEM target which specifies a selection item to process.

2. For each selection item, the requestor asks the owner to convert the TEXT target which instructs the owner to send the selection data in any format.

The requestor assumes that it can convert the data into a usable format. If it cannot convert the data, it will not accept the data and the transfer is terminated. Note that the requesting application bears the responsibility of converting the data to a usable format.

4.1.2 Handshaking with _SUN_AVAILABLE_TYPES

This example describes the handshaking protocol of a requesting application that wishes to specify the format of the requested data. This is an optional feature.

1. After obtaining the list of supported targets the requestor asks the owner to convert the _SUN_ENUMERATION_COUNT atom. The owner responds by sending the number of source objects in the current selection.

   If the response to _SUN_ENUMERATION_COUNT is more than 1, then the programs must agree upon the selection object to be dragged and dropped. The owner converts the _SUN_ENUMERATION_ITEM target which specifies a selection item to process. For each item in the selection, the program converts the targets described in steps 2 and 3.

2. The requestor application then asks the owner to convert _SUN_AVAILABLE_TYPES. The owner sends a list of data type atoms which specify the format in which the selection data may be supplied.

   The formats may be GIF, PostScript, audio, or some other format. If the applications do not wish to use an alternate transport method, then the requestor application asks the owner to convert the desired data type target. The owner responds by sending the stream of data representing the object selected in the type requested.

3. The requestor application writes the data into its address space and closes the selection transfer with the _SUN_SELECTION_END atom.

4.1.3 Specifying _SUN_ENUMERATION_ITEM

When multiple items are selected, the _SUN_ENUMERATION_ITEM target specifies which object is the subject of discussion in the selection negotiation. All targets that require the specification of _SUN_ENUMERATION_ITEM, and the setting of the object number as its side effect, should request these conversions as part of a MULTIPLE conversion.

The use of MULTIPLE adds a transaction-like nature to the set of target conversions, assuring that other target conversions delivered to the selection holder will not change the state of the selection.

Specifically, a sample conversion of a target should look like this:

begin multiple _SUN_ENUMERATION_ITEM = object number FILE_NAME _SUN_FILE_HOST_NAME _SUN_ENUMERATION_ITEM = -1 end multiple

The use of MULTIPLE ensures that another client cannot convert _SUN_ENUMERATION_ITEM on the same selection halfway through the conversions for your targets. If this were to happen, the results could prove unpredictable with conversion results being relative to different objects within the selection, and your client not knowing this.

Within the OpenWindows Version 3.x implementation of drag and drop, each drag and drop transfer acquires a unique selection rank. So, converting _SUN_ENUMERATION_ITEM on the same selection halfway through target conversion, may not be an immediate problem. But if your client is ever to use the same code to support cut/copy/paste, it is likely that your client could get conversion requests on a selection from more than one client at a time.

For a more complete discussion of MULTIPLE, and how it relates to selection target conversions, see the ICCCM.

4.2 DeskSet Drag and Drop Target Atoms

This section describes the atoms used in DeskSet applications.

4.2.1 ICCCM Target Atoms

These atoms are specified by the ICCCM and should be supported by all applications.

DELETE Converting this atom tells the selection owner to delete the selection. This is typically done when the drag and drop operation is a move command to something that can actually store the data (like a File Manager). An application like a Print Tool should always reject the DELETE atom. Owner application should return a zero-length property of type NULL if the deletion was successful.

TARGETS Returns a list of targets supported by the owner.

TIMESTAMP Timestamp is an integer timestamp used to acquire the selection.

FILE_NAME When converted, FILE_NAME requests the file name for the current object in the selection. The response is a name of a file that contains the selection data. This file name is not useful unless the answer to the _SUN_FILE_HOST_NAME is a host that the recipient can access. The FILE_NAME response will be relative to the machine named in _SUN_FILE_HOST_NAME. FILE_NAME is not needed if _SUN_ATM_FILENAME is not supported.

NAME The name of the application as represented in the title bar. Refer to the ICCCM for details.

INSERT_SELECTION Replace the object with the contents of the named selection.

4.2.2 DeskSet Target Atoms

_SUN_ALTERNATE_TRANSPORT_METHODS This target is like the TARGETS target--it returns a list of atoms which represent the alternate transports that the owner supports. Note that use of this and other ATM targets is very rare and almost always necessary.

_SUN_ATM_FILE_NAME This target indicates that the requestor is going to get the data via a file name. A file name consists of both a pathname (as returned by FILE_NAME) and a host name (as returned by _SUN_FILE_HOST_NAME).

_SUN_ATM_TOOL_TALK This atom specifies the ToolTalk services to pass data.

_SUN_AVAILABLE_TYPES This atom is like the TARGETS atom, but instead the owner responds with the data types in which it can provide data. This may be only one, or it may be several. Note that the responsibility for type translation lies with the requestor.

The table below lists the data types supported by DeskSet.

Table 4-1

Data Type	Data Type Atom	Type Description
Owners Choice	TEXT	Can be any data type of the owners choice.
Text	STRING	8-bit ISO 8859-1
Graphics	_SUN_TYPE_gif-file _SUN_TYPE_tiff-file _SUN_TYPE_postscript-file _SUN_TYPE_sun-raster _SUN_TYPE_xpm-file	GIF TIFF PostScript Sun Raster XPM
Audio	_SUN_TYPE_audio-file	SunSoft Audiotool

_SUN_DRAGDROP_DONE This target signifies the end of a drag and drop process. It is hidden in the toolkits so the requestor application never deals with them. The owner application does, however, see them.

_SUN_SELECTION_END Ends the selection process by indicating that the requestor is done with the current selection. Use SUN_SELECTION_END to notify the owner that you are done with the selection used in response to INSERT_SELECTION or _SUN_LOAD. See the section on _SUN_LOAD for more information.

_SUN_DATA_LABEL A string identifier that represents the current object which is not a filename. This could be something like the last component of the pathname.

_SUN_ENUMERATION_COUNT Specifies how many objects are in the current selection. This allows several icons to be selected and separately negotiated.

_SUN_ENUMERATION_ITEM Specifies which object is the subject of discussion in the selection negotiation. Objects are numbered from zero to _SUN_ENUMERATION_COUNT -1. References to objects outside this range should be refused. References to the item -1 should be treated as resetting the current item to unspecified.

This target only has meaning within the context of a selection that contains multiple disjointed objects. It should be: 1) converted with the number of the object in the selection you wish to refer to; 2) convert the desired targets; 3) converted again to set the current item back to 0.

_SUN_FILE_HOST_NAME The name of the host to which FILE_NAME is relative.

_SUN_LOAD When converted the owner returns a selection atom to use as a reference to the current object.

_SUN_SELECTION_ERROR If the requestor has decided that it cannot convert a selection, it should convert this target. This target has no side effects and returns no data, but can be used to inform the user that the drag and drop operation did not succeed. The

convention for informing the user of a drag and drop failure is to present an error message in the footer of the owner application, and send a pop-up message to the requestor application.

4.3 Drag and Drop and Editors

One of the primary uses of Drag and Drop with the File Manager is to drop files on cooperating applications as a shorthand for loading them in for editing. In this situation there are some difficult semantic differences that creep into the user model depending on the transport method chosen/negotiated by the applications involved in the drag and drop interaction.

Consider these two cases:

Case 1: Client A, a drag source, is running on machine X. Client B, an editor, is also running on machine X. The user drags a file from A, and drops it on B. B (the editor) realizes that the two clients share a file system, and decides to transport the data using file names and the file system as a short cut. B loads the file and runs successfully.

Case 2: Client A, a drag source, is running on machine X. Client B, an editor is also running on machine X. The user drags a file from A, and drops it on B. B (the editor) realizes that the two processes do not share a file system, and cannot rendezvous in this way. B decides to convert TEXT, or some more specific data type, and receives the data from A through the selection service. B loads the data and runs successfully.

Up to a point, the transfers look identical to the user, who is oblivious to the selection of transport method. The user edits the data, and then tries to execute the Save function in the editor.

In the first case, the data goes back to the place from which it came, providing an action semantically identical to loading in the file from some sort of dialog box.

In the second case, the data is either silently saved to some place within their local file system, or the user is presented with a question like "where in this file system do you want the data to go?" The users only option for getting the data back to where it came from would be to either drag it from the editor back to the source (assuming the editor supports sourcing drags), or to save the data into a local file system, and then use some sort of sourcing application to drag it back to the original file system and rename it to the original name.

None of the behaviors in the second case will make sense to the user, because they know nothing of the selection of transport method and how it will impact the usability of their application.

---

Note - There may be cases where the clients share a file system and still cannot rendezvous successfully through it. This might include selection holders whose selection resides in a special partition (databases) or whose contests are represented by more than one file (compound documents). It is important not to conclude that this is an X specific problem.

---

With the intent of fixing this behavior, we have defined some special mechanisms to get the data back to its original location, transparent to the user.

When a requestor application finds that it needs to obtain the source data through the selection service, and intends to allow the user to edit the data and then put it back, the recipient tries to convert the _SUN_LOAD target. If the selection holder supports the _SUN_LOAD target, it will respond with the name of a selection (called "H" for this discussion) that the holder guarantees will be unique and persistent for the life of the selection holder. This selection is associated with the original data in the drag and drop transfer.

The editor may manipulate the data as it sees fit. When it is time to save the data back to the original location, the editor creates a new selection rank and associates it with the data that it is currently holding (call the selection rank "S"). The editor then converts the INSERT_SELECTION target against the selection H. A selection can be guaranteed as unique by converting SUN_SELECTION_END against H when done. In the property associated with the target conversion, the editor places the name of the selection S.

The conversion of INSERT_SELECTION tells the selection holder to replace the contents of the current selection (selection H, representing the original data in storage) with the contents of the new selection (selection S, whose contents represent the edited version of the data). Refer to section 2.6.3.2 of the ICCCM.

The original selection may then make target conversions against selection S to get the data back from the editor.

4.4 Drag and Drop Example: XView Toolkit

The program xview_dnd2.c, located online at $OPENWINHOME/share/src/dig_samples/dnd_xview2, demonstrates how drag and drop can be implemented with the Xview toolkit. Once compiled, xview_dnd2.c allows you to drop a selection from a DeskSet application onto its rectangular drop target. xview_dnd2 then displays the following information:

• The operation (Drag MOVE)
• The number of atoms contained in the TARGETS atom
• The atoms listed in TARGETS, and used in the drop operation
• The length and format of the data represented in each atom, as well as the data itself.
• Atoms listed in TARGETS, but not used in the operation

Note that this program does not work with multiple selections.

Section 3.4, "Drag and Drop Programming Example: OLIT Toolkit," on page 3-7 shows a drag and drop example implemented with OLIT.

4.5 Further DeskSet Integration Information

For further information on integrating your application with DeskSet, call the SunSoft Catalyst Information Center (Appendix C, "Vendor Data Type Registration" has this number). Note, however, that the ICCCM currently does not specify the protocol supported by DeskSet. The current DeskSet protocol may change to comply with future ICCCM specifications. Refer to Appendix L of the X Protocol Reference Manual to see the current ICCCM.