Volume 6A: Motif Programming Manual

sites for graphical data. However, when these components are in a menu, they do not function as drag sources. These

components are not drop sites because they are meant to be read−only components in a user interface. Most

applications would not want the user to be able to change the label on a button by dropping text on it. However, if you

want to provide this type of functionality, it is easy to register a Label or a button as a drop site using the technique we

describe in Section #sdropsite.

The user can drag the text of either a single item or the current selection in a List widget. If the pointer is over a

selected item when the drag is started, the text of the selected item is used for the drag. If multiple items are selected,

the text of all of the selected items is used, where the items are separated by newlines. If the drag is started over an

unselected item, the text of that item is transferred by drag and drop. The List widget is not a drop site because its

items are not meant to be modified by the user. If you want to allow the user to modify a List by dropping items in it,

however, you can register the widget as a drop site.

The Text and TextField widgets are the only Motif widgets that have built−in drop site functionality. The user can

drop textual data from any drag source in these widgets. The widgets also function as drag sources, so the user can

move and copy the current selection within and between Text and TextField widgets.

Applications that simply use the built−in drag and drop capabilities of the Motif widgets can still customize various

aspects of the functionality. This section explores the different types of customization that are possible.

19.3.1 Specifying the Drag Protocol

Motif supports two different protocols for communication between applications during a drag. The dynamic protocol

passes messages between the two applications about the location of drop sites, while the preregister protocol keeps

track of drop site information in a database. Since the preregister protocol does not require communication between

applications, it can provide better performance on a heavily−loaded network. However, the dynamic protocol offers

the advantage of sophisticated drag−under visual effects.

The programmer or the user can specify the drag protocol for an application by setting the

XmN-dragInitiatorProtocolStyle and XmN-dragReceiverProtocolStyle resources defined by the

Display object. Motif creates a Display object automatically for an application when it creates the first shell on a

particular display. If an application uses multiple displays, it has a Display object for each one. An application can

retrieve the Display object for a specified display using XmGetXmDisplay().

The XmN-dragInitiatorProtocolStyle and XmN-dragReceiverProtocolStyle resources indicate

the preferred drag protocol for an application when it is acting as an initiator and as a receiver, respectively, in a drag

and drop transfer. Each resource can be set to one of the following values:

XmDRAG_PREREGISTER

This value means that the application can only support the preregister drag protocol.

XmDRAG_DYNAMIC

This value indicates that the application can only support the dynamic drag protocol.

XmDRAG_NONE

This value means that drag and drop is disabled for the application.

XmDRAG_DROP_ONLY

This value specifies that the application does not support either drag protocol, but it does support drag and

19 Drag and Drop 19.3.1 Specifying the Drag Protocol

525

drop transfers. The user can transfer data using drag and drop, but there are no visual effects during the drag.

XmDRAG_PREFER_DYNAMIC

This value means that the application supports both the preregister and dynamic protocols, but it prefers to use

the dynamic protocol.

XmDRAG_PREFER_PREREGISTER

This value means that the application supports both drag protocols, but it prefers to use the preregister

protocol. The value is the default value for XmN-dragReceiverProtocolStyle.

XmDRAG_PREFER_RECEIVER

This value indicates that the application supports both the preregister and dynamic protocols, but it defers to

the preference of the receiving application. The value can only be specified for the

XmN-dragInitiatorProtocolStyle resource, and it is the default value for the resource.

The actual protocol that is used during a drag and drop transfer is based on the preferences specified by the

initiating and receiving applications. The protocol can change during a drag as the drag icon enters and leaves

top−level windows. shows how the protocol is resolved based on the preferred protocols for the initiator and

the receiver. tab(@); l | c s s s ^ | l | l | l |l l | lp9 | lp9 | lp9 | lp9. T{

Initiator

Protocol Style

T}@Receiver Protocol Style

@Preregister@Prefer Preregister@Prefer Dynamic@Dynamic

_

Preregister@Preregister@Preregister@Preregister@Drop Only Prefer

Preregister@Preregister@Preregister@Preregister@Dynamic Prefer

Receiver@Preregister@Preregister@Dynamic@Dynamic Prefer

Dynamic@Preregister@Dynamic@Dynamic@Dynamic Dynamic@Drop

Only@Dynamic@Dynamic@Dynamic

_ If two applications cannot find an agreeable protocol style, the XmDRAG_DROP_ONLY style is used. In this

case, there are no drag−over or drag−under visuals except for the initial drag icon. An application can also

explicitly set the protocol resources to XmDRAG_DROP_ONLY, in which case the application does not provide

any visual effects during the drag.

If an application sets XmN-dragInitiatorProtocolStyle or

XmN-dragReceiverProtocolStyle to XmDRAG_NONE, the application does not participate in drag

and drop as an initiator or a receiver, respectively. This value is useful for disabling drag and drop

functionality, as we discuss in the next section.

The actual protocol used for a drag and drop transfer controls the visual effects that the user sees during the

drag. Under the preregister protocol, the server is grabbed so the drag icon can be a pixmap of arbitrary size.

The drag icon uses the depth and colormap of the drag source widget, so it can be a color image. When the

dynamic protocol is used, the drag icon is implemented using the X cursor, so it must be a bitmap and is

limited in size (use XQueryBestCursor() to determine the largest size for a particular hardware

configuration).

An application should support both the dynamic and preregister protocols so that the user can select the

protocol based on his needs. Since the toolkit supports both protocols by default, an application can easily

support both as well. The code for handling drag sources is the same under both protocols. Drop sites can

specify an optional XmN-dragProc routine that is invoked under the dynamic protocol and can be used to

provide sophisticated drag−under effects.

19 Drag and Drop 19.3.1 Specifying the Drag Protocol

526