The protocols refer to how the initiator and receiver clients use the toolkit to communicate with each other. There are two drag protocol styles that are available. The drop protocol is based on the Xt selection protocol.
The toolkit on the initiator side is in charge during the drag. The protocol in effect determines how it will find the information about drop sites that it needs to manage visuals, and how extensively the initiator and receiver clients are involved during the drag.
There are two kinds of drag protocol styles:
Uses messages from the toolkit to the receiver to find out drop site information. The toolkit on the receiver side can reply to the messages, or the application can take action based on these messages. The receiver manages the drag-under effects.
The code for the initiator is the same regardless of the protocol. The code for the receiver applications is the same except that in the dynamic mode, or in the preregister mode when the initiator and receiver are the same client, the receiver's XmNdragProc is called.
The drag protocol in use can change during the course of a drag. When the drag icon enters or leaves a top-level window, the source and potential drop receiver negotiate a mutually acceptable drag protocol, as described in Section 17.3.2.
The toolkit uses pixmap source icons if the client provides them. If not, the toolkit uses bitmap source icons if the client provides them. If the client provides neither, the toolkit uses XmScreen icons. The XmScreen icons can be either the default icons or ones provided by the client or user.
With the dynamic drag protocol, the initiator and receiver communicate with messages through the toolkit.
As the drag icon moves within the receiver's window, messages are sent from the toolkit on the initiator side to the toolkit on the receiver side. Based on these messages, the receiver determines whether the drag icon is entering, within, or leaving a drop site. Although the toolkit on the receiver side initializes state and operation information, the receiver can check and update this information further if it registers an XmNdragProc for the drop site. The initiator receives the updated message in one of its drag-related callbacks (described later in this chapter), and can take action accordingly.
The dynamic drag protocol allows the receiver to provide more sophisticated visual effects using the XmNdragProc than the toolkit can provide alone.
With the dynamic drag procotol
The dynamic protocol is the default for drag and drop operations.
When a receiver supports the preregister protocol, the toolkit on the receiver side stores drop site information in a database. The toolkit on the initiator side manages all drag-under effects based on the information in the drop site database. By setting some DropSite resources appropriately, the receiver can have the toolkit use different highlighting or pixmaps, but the receiver only participates directly in the drag-under effects when it is the same as the initiator and an XmNdragProc procedure has been registered with the drop site.
With the preregister protocol
The user can specify which drag protocol to use or the application can specify the drag protocol in resource file.
The preregister drag protocol can be used with a minimum of additional coding in an application, because the toolkit manages the drag-over visual effects using the default drag icons specified in the XmScreen object. Or the application can override the default XmScreen icons with custom icons, but still allow the toolkit to manage the effects.
The dynamic drag protocol requires more work for the application program, but allows a receiver application to provide visual effects beyond the capabilities of the toolkit.
The drag protocol in use has an effect on the system performance as described later in this section.
Two Display resources specify which protocol the toolkit should try to use when a client is an initiator or receiver. These resources can be set by the client in a resource file or by the user.
These resources can take the following values (the letter in brackets following the value is used in Table 17-1):
Does not participate in drag and drop. There are no drag-under effects. The drag-over effects depend on the value of XmNdragInitiatorProtocolStyle.
Does not support either the preregister mode or the dynamic mode, but does data transfer after the drop occurs. There are no drag-over or drag-under visual effects.
Supports the preregister mode only. The visual effects are managed by the toolkit.
Supports both protocols, but prefers the preregister protocol. This is the default for receivers. The visual effects are determined by the protocol actually used.
Used by initiators only. Uses the protocol that the receiver specifies. This is the default for initiators. The visual effects are determined by the protocol actually used.
Supports both protocols, but prefers the dynamic mode. The visual effects are determined by the protocol actually used.
Supports the dynamic protocol only. The drag-over and drag-under visual effects are managed by the clients.
For example:
myclient*dragInitiatorProtocolStyle: DRAG_PREFER_DYNAMIC myclient*dragReceiverProtocolStyle: DRAG_PREFER_DYNAMIC
If the initiator and receiver have specified the same protocol, that
protocol is used. If they specify different protocols, the protocol that is
used is shown in the following table.
Table 15. Initiator and Receiver Protocols
| 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 XmGetXmDisplay function returns the Display object ID associated with a specific display. XtGetValues can be used to check the protocol style resources.
If an XmNdragProc is specified for a drop site, it will be performed only if the protocol is dynamic, or, if the protocol is preregister, only if the initiator and receiver are the same client. In this case, the application should set the XmNdragReceiverProtocolStyle resource to the value XmDRAG_PREFER_DYNAMIC in the application-class defaults file rather than use the default value.
When the resulting protocol is preregister, a preregister visual style is used, and the server is grabbed by the initiator. With the dynamic protocol, the initiator and the receiver exchange messages. The visual look of the two protocols is very similar. The most significant visual difference between the two protocols is associated with sophisticated drag-under effects, such as autoscroll drag, or any drag-under operation that depends on widget data not displayed at the initiation of the drag. These effects are only available with the dynamic protocol, or with the preregister protocol, under the condition that the initiator and the receiver are the same client.
When the resulting protocol is dynamic, a dynamic visual style is always used. The drag-over visual can be a pixmap with an arbitrary size whose depth and colormap are the same as those of the widget associated with the drag source. When a pixmap is used in dynamic mode, a shaped window is used to contain it. The pixmap, if desired, is specified in the DragContext XmNsourcePixmapIcon resource. Otherwise, the drag-over visual is implemented with the X cursor, which must be a bitmap, and often has limited size (use XQueryBestSize to find out the largest size available per screen). This cursor is specified using XmNsourceCursorIcon.
Consequently, when the resulting protocol is XmDRAG_NONE or XmDRAG_DROP_ONLY, the visual style depends upon the value of XmNdragInitiatorProtocolStyle. When it is XmDRAG_DYNAMIC or XmDRAG_PREFER_DYNAMIC, the dynamic visual style is used; otherwise, the preregister visual style is used.
When a drop is made, the receiver checks what action should happen:
See the Chapter 16 for details on how UTM implements a drop.