Volume 6A: Motif Programming Manual

CHARACTER_POSITION@SPAN@Start and end of selection in bytes LINE_NUMBER@SPAN@Start and end

line numbers COLUMN_NUMBER@SPAN@Start and end column numbers LENGTH@INTEGER@Number of

bytes in selection USER@TEXT@Name of user running owner PROCEDURE@TEXT@Name of selected procedure

MODULE@TEXT@Name of selected module PROCESS@INTEGER, TEXT@Process ID of owner

TASK@INTEGER, TEXT@Task ID of owner CLASS@TEXT@Class of owner (WM_CLASS)

NAME@TEXT@Name of owner (WM_NAME) CLIENT_WINDOW@WINDOW@Top−level window of owner

DELETE@NULL@True if owner deleted selection INSERT_SELECTION@NULL@Insert specified selection

INSERT_PROPERTY@NULL@Insert specified property

_ Motif uses some new objects to encapsulate information about various aspects of a drag and drop transfer. These

objects act like widgets, in that they are created by the programmer, they have resources that can be set and retrieved,

and they interact with the application using callbacks. However, they are unlike traditional widgets in that they are not

visible components of the user interface. The DragContext object is used to store information during a drag, while the

DropTransfer object keeps track of information during a drop. The DragIcon object is used to represent the pointer

shape that is used during a drag and drop transfer. The DropSite object maintains information about all of the drop

sites in an application. The new Display and Screen objects also provide resources that control the behavior of drag

and drop, although they are not specifically part of drag and drop.

The following sections describe all the components of a drag and drop transfer and present the Motif objects that are

used to implement drag and drop. As we describe the objects, we mention many of their resources, callbacks, and

related functions so that you can see how everything fits together. We describe each of the objects in much greater

detail later in the chapter when we talk about how they can be used to customize different aspects of drag and drop.

However, this chapter does not attempt to describe all of the possible ways in which drag and drop can be customized.

We present some common situations and leave you to explore all of the details on your own. For complete

information about each Motif object used to implement drag and drop, see the appropriate reference pages in Volume

SixB, Motif Reference Manual.

19.2.1 The Drag Source

The widget that contains the data being manipulated with drag and drop is known as the drag source. When the user

starts a drag, the application that contains the drag source is considered the initiator of the transfer. The data provided

by a drag source depends on the type of object the source represents. For example, a Text widget provides textual

data, while a DrawingArea could provide some form of graphical data.

A drag source can be designed to support and transfer any type of data. There can even be multiple formats for a given

piece of data if appropriate. A drag source also specifies the operations (move, copy, or link) that it allows. The type

of data, and in some cases the widget that contains the data, affects the operations that are supported. For example, the

List widget only supports copy operations because it is a read−only component.

In order for a drag and drop transfer to work, the drag source and the drop site need to understand the same type of

data. The drag source announces the data targets it can supply to the drop site. A drag source that supports textual data

might offer the data using COMPOUND_TEXT, STRING, and TEXT targets, while a graphical drag source could

provide PIXMAP, FOREGROUND, and BACKGROUND targets. When the drop occurs, the drop site can request

the data in any of the targets supported by the drag source, so the drag source needs to know how to convert between

supported types.

In order for a widget to be a drag source, the widget must be able to recognize a ButtonPress event for the second

mouse button. Essentially, you need to set up a translation and action or an event handler for this event that invokes a

function that starts the drag. The following code fragment shows the definition of a translation and an action for a drag

source:

static char dragTranslations[] =

19 Drag and Drop 19.2.1 The Drag Source

516

"#override <Btn2Down>: StartDrag()";

static XtActionsRec dragActions[] =

{ {"StartDrag", (XtActionProc) StartDrag} };

Just as with any translation and action, the application needs to call XtParseTranslationTable() and

XtAppAddActions(). The parsed translation table can be used to set the XmN-translations resource for the

drag source widget.

The Motif toolkit uses the DragContext object to store information about a drag source once a drag has started. This

object also keeps track of state information about the transfer as it is happening. The routine that starts a drag calls

XmDragStart() to create the DragContext and get things rolling. The DragContext object has resources that need

to be set at creation time to provide information about the drag source. The XmN-dragOperations resource

specifies the operations supported by the drag source, while XmN-exportTargets and

-XmNnumExportTargets indicate the data targets that are supported.

The DragContext also has a number of resources that control the visual effects used during the drag. Many of these

resources specify various attributes of the drag icon for the transfer. For example, the XmN-sourceCursorIcon,

XmN-operationCursorIcon, and XmN-stateCursorIcon resources indicate the images that are used for

different parts of the drag icon. If these resources are not specified, the DragContext uses default icons. There are also

resources that allow you to specify different foreground and background colors for the drag icon. We describe the drag

icon in more detail in Section #sdragicon.

The DragContext also provides callback routines that can be used to monitor the drag and provide custom visual

effects. All of the routines use special callback structures that provide information about the current state of the drag.

Section #sdragcallbk provides more information about these callbacks.

The XmN-convertProc is a procedure that must be specified when a DragContext is created. This procedure is

used to convert the drag source data to the format requested by the drop site when the drop occurs. The procedure is

either an XtConvertSelectionProc or an XtConvertSelectionIncrProc, depending on whether or not

the drag source is using incremental transfer. If the XmN-incremental resource is set to True, the data is

transferred incrementally. Both of these procedures are part of the underlying Xt selection mechanism that is not

completely hidden by the Motif drag and drop abstraction. See Volume Four, X Toolkit Intrinsics Programming

Manual, for more information on these procedures.

The following code fragment shows the creation of a DragContext object with a minimal set of resources:

Atom exportList[1];

Widget widget, dc;

Arg args[5];

int n;

Boolean ConvertProc();

XEvent *event;

...

n = 0;

exportList[0] = COMPOUND_TEXT;

XtSetArg (args[n], XmNexportTargets, exportList); n++;

XtSetArg (args[n], XmNnumExportTargets, XtNumber (exportList)); n++;

XtSetArg (args[n], XmNdragOperations, XmDROP_COPY); n++;

XtSetArg (args[n], XmNconvertProc, ConvertProc); n++;

dc = XmDragStart (widget, event, args, n);

19 Drag and Drop 19.2.1 The Drag Source

517