Using Resources for Drag and Drop

Drag and drop resources are generally specified by an application. Refer to the documentation for each application to determine which drag and drop resources you can customize.

Protocol Resources

There are two types of protocols that can be in effect during a drag and drop transaction: preregister and dynamic. Generally, the preregister protocol is more efficient, uses fewer system resources, and provides more attractive drag-over effects. The dynamic protocol provides more attractive and powerful drag-under effects. Motif applications based on Release 1.2 should support both protocols.

You can specify which protocol you want in effect for drag sources and drop sites with the following resources. However, due to other constraints, the system may not be able to use the protocol you requested.

• The dragInitiatorProtocolStyle resource requests the protocol style to be used when the client is the initiator of a drag
• The dragReceiverProtocolStyle resource requests the protocol style to be used when the client is a potential receiver of a drop

These resources can have the following values (the letters in parentheses are used as abbreviations for the values in the table below):

DRAG_NONE (N)

Does not participate in drag and drop.

DRAG_DROP_ONLY (X)

Does not support either the preregister or dynamic protocol, but does allow dropping. This value means that no drag-over or drag-under visual effects will be shown.

DRAG_PREREGISTER (P)

Supports only the preregister protocol.

DRAG_PREFER_PREREGISTER (PP)

Supports both protocols, but prefers the preregister protocol. This value is the default for receivers.

DRAG_PREFER_RECEIVER (R)

Prefers the protocol that the receiver specifies. This value is only effective for initiators and it is the default for initiators.

DRAG_PREFER_DYNAMIC (PD)

Supports both protocols, but prefers the dynamic protocol.

DRAG_DYNAMIC (D)

Supports only the dynamic protocol.

The following example specifies that an application named myapp uses the dynamic protocol both when it is a drag source and when it is a drag receiver.

myapp*dragInitiatorProtocolStyle: DRAG_DYNAMIC
myapp*dragReceiverProtocolStyle: DRAG_DYNAMIC

It may take some experimentation to find the best values for these resources for the applications you are running on your particular system configuration. Here are some guidelines:

• The default protocol style used for the receiver is DRAG_PREFER_PREREGISTER and for the initiator is DRAG_PREFER_RECEIVER, unless an application has changed it.
• To get the most sophisticated drag-over effects, set the initiator protocol style to DRAG_PREFER_PREREGISTER.
• To get the most sophisticated drag-under effects, set the receiver protocol style to DRAG_DYNAMIC or DRAG_PREFER_DYNAMIC.
• If there are a large number of drop sites, preregistering them all may take unnecessary time. Set the receiver protocol style to DRAG_DYNAMIC.
• If your system is heavily loaded, the DRAG_DYNAMIC protocol may cause unnecessary thrashing. Set the initiator protocol to DRAG_PREFER_PREREGISTER.
• If your system is on a busy network, setting the initiator and receiver protocols to DRAG_PREREGISTER may reduce network traffic.
• If the protocol is set to DRAG_DYNAMIC or DRAG_PREREGISTER, visual effects may be lost if the source and destination have incompatible protocols. Use DRAG_PREFER_PREREGISTER or DRAG_PREFER_DYNAMIC if possible.
• If your system has very limited resources, use the DRAG_DROP_ONLY value to avoid the time and memory requirements of drag-over and drag-under effects completely.

The following table shows how a conflict between the source and destination protocols is resolved.

Initiator Protocol  
Receiver Protocol
                    
P  
PP  
PD  
D  
X  
N
P                   
P  
P   
P   
X  
X  
N
PP                  
P  
P   
P   
D  
X  
N
R                   
P  
P   
D   
D  
X  
N
PD                  
P  
D   
D   
D  
X  
N
D                   
X  
D   
D   
D  
X  
N
X                   
X  
X   
X   
X  
X  
N
N                   
N  
N   
N   
N  
N  
N

The following resources allow you to provide your own default graphics for drag-over situations. These graphics are used only if an application has not specified its own graphics.

defaultSourceCursorIcon

The pixmap used for the source icon

defaultCopyCursorIcon

The operation icon used when the operation is a copy

defaultMoveCursorIcon

The operation icon used when the operation is a move

defaultLinkCursorIcon

The operation icon used when the operation is a link

defaultInvalidCursorIcon

The state icon used when the drag icon is over an invalid drop site

defaultValidCursorIcon

The state icon used when the drag icon is over a valid drop site

defaultNoneCursorIcon

The state icon used when the drag icon is not over a drop site

You can specify a pixmap and a mask to use for any part of the drag icon using the following resources:

pixmap

Specifies the pixmap to use.

mask

Specifies the mask for the pixmap, if desired.

Provide the name of the icon you are creating in addition to the resource. For instance, to specify a pixmap and mask for the invalid state icon, use the following resource specifications:

*defaultInvalidCursorIcon.pixmap: mypixmap
*defaultInvalidCursorIcon.mask: mypixmask

You can specify which of the three parts of the drag icon you want to see with the blendModel resource. This resource can take the following values:

BLEND_ALL

Use all three parts. This value is the default value.

BLEND_STATE_SOURCE

Use the source icon and the state icon.

BLEND_JUST_SOURCE

Use only the source icon.

BLEND_NONE

Do not display a drag icon.

You can specify how you want the source, state and operation icon to be located with respect to each other with the attachment resource. This resource is used for state and operation icons and ignored for the source icon. The attachment point for these icons is the lower right corner. Use the attachment style that gets the icons closest to the position you want, then use an offset for final adjustment.

The attachment resource can take the following values:

ATTACH_NORTH_WEST

Attaches to the upper left corner of the source icon. This value is the default value for the state and operation icons.

ATTACH_NORTH

Attaches to the top of the source icon.

ATTACH_NORTH_EAST

Attaches to the upper right corner of the source icon.

ATTACH_EAST

Attaches to the right side of the source icon.

ATTACH_SOUTH_EAST

Attaches to the lower right corner of the source icon.

ATTACH_SOUTH

Attaches to the bottom side of the source icon.

ATTACH_SOUTH_WEST

Attaches to the bottom left corner of the source icon.

ATTACH_WEST

Attaches to the left side of the source icon.

ATTACH_CENTER

Attaches to the center of the source icon.

ATTACH_HOT

Attaches the icon's hot spot to the source icon's hot spot. This value is best used when the application has provided special source icons just for the purpose of using this value. Otherwise, some odd-looking drag icons may result.

If you specify the attachment resource in a resource file, include the name of the icon to which it refers. For instance, to attach the valid state icon at the upper left corner of the source icon, use the following specification:

*defaultValidCursorIcon.attachment: ATTACH_NORTH_NORTHWEST

You can move the state and operation icons from the basic attachment point by using offsets. Select the attachment point nearest to the location you want, then make final adjustments with the the following offset resources:

offsetX

The horizontal offset in pixels. Positive is to the right, negative is to the left.

offsetY

The vertical offset in pixels. Positive is down, negative is up.

You can specify how you want the drop site's drag-under visual effects to appear with the animationStyle resource. This resource can take the following values:

DRAG_UNDER_HIGHLIGHT

The drop site is outlined when a valid drag is over it. This value is the default.

DRAG_UNDER_SHADOW_OUT

The drop site appears pushed out when a valid drag is over it.

DRAG_UNDER_SHADOW_IN

The drop site appears pushed in when a valid drag is over it.

DRAG_UNDER_NONE

The drop site does not change when a valid drag is over it.

DRAG_UNDER_PIXMAP

The drop site displays a special pixmap when a valid drag is over it.

Use the animationPixmap, animationMask, and animationPixmapDepth resources to specify the pixmap to use if the animation style is DRAG_UNDER_PIXMAP.

Color Resources

Use the following resources to set colors for the drag icon:

validCursoForeground

The color to use if the drag icon is over a valid drop site

invalidCursorForeground

The color to use if the drag icon is over an invalid drop site

noneCursorForeground

The color to use if the drag icon is not over a drop site

For example, the following specifications set the drag icon to blue when it is over a valid drop site, to red when it is over an invalid drop site, and to green when it is not over a drop site.

*validCursorForeground: Blue
*invalidCursorForeground: Red
*noneCursorForeground: Green