Volume 7A: XView Programming Manual

19

Drag and Drop

This chapter describes the XView packages that support drag and drop. Drag and drop

allows data to be moved within an application or between applications. Using drag and drop,

objects are selected, then moved or copied to a new location. The selected object is the drag

and drop source. Selecting the source is referred to as sourcing the drag. An area within the

source application or within another application receives the drop in a pre-registered drop-

site.

This chapter describes packages that are new for XView Version 3. The function

xv_decode_drop() that supports dragging and dropping is now obsolete. Note that

xv_decode_drop() will not work correctly once an application is compiled for V3. The

function is still provided for backwards compatibility for XView Version 2 programs.

Many OPEN LOOK applications use drag and drop operations. For example, an application

may allow text in a text subwindow to be sourced and copied or moved to a new location

within the text subwindow. Similarly, a File Manager’s file icon can be selected and dragged

to the Print Tool icon for printing. OPEN LOOK defines many uses for drag and drop, includ-

ing loading files into an application. Figure 19-1 shows a file being dragged into an editor

and Figure 19-2 shows the application loading the file (receiving the drop).

Drag and drop supports drop previewing where the drop-site image changes to show that it is

a valid drop-site. It also supports drag feedback where the pointer image changes to indicate

that an item is being dragged. The data transfer for an XView drag and drop operation is nor-

mally implemented using selections. You need to be familiar with the selection package to

use drag and drop. The selection package is described in Chapter 18, Selections. Note that

the operation of drag and drop using OPEN LOOK differs from selections in the following

ways:

• Drag and drop is a single gesture rather than a series of separate actions.

• Drag and drop operates on complete pre-registered data objects. Using drag and drop, the

application decides which areas may be selected, and then the user may select and drag

the area.

Drag and Drop

Drag and Drop 433

File Manager

File Edit Goto:

/ home

Chapters

Balloons.rs

Cat.rs

romance.doc

chapter1.doc chapter2.doc jester.rs

Edit

File View Edit

Figure 19-1. Dragging a file onto an application

File Manager

File Edit Goto:

/ home

Chapters

Balloons.rs

Cat.rs

romance.doc

chapter1.doc chapter2.doc jester.rs

Edit

It was a dark and stormy night. All

of the beagles were safely in their

kennels. The bats flew around the

tower squeaking frantically.

Dosalina stood at the open window

wistfully gazing out over the moors.

File View Edit

Figure 19-2. Loading a file by dropping

434 XView Programming Manual

19.1 Drag and Drop Objects

Drag and drop is facilitated using two objects: DRAGDROP and DROP_SITE_ITEM; a

DRAGDROP object represents the source of the drag. A DROP_SITE_ITEM object indicates a

destination that is a valid drop-site. All applications need to include the file

<xview/dragdrop.h> to use these packages. All DRAGDROP attributes are prefixed by DND and

all DROP_SITE_ITEM attributes are prefixed by DROP_SITE. Both Figure 19-3 and Figure

19-4 show the class hierarchy for these objects.

Generic

Object

(Selection)

Selection

Owner

DRAGDROP

Figure 19-3. DRAGDROP class hierarchy

Generic

Object

Drop Site

Figure 19-4. DROP_SITE_ITEM class hierarchy

Drag and drop operations involve three steps which the following sections describe:

• The application that is to receive the drop must register a region or several regions as

valid drop-sites. This lets the application inform other applications that it is interested in

receiving drops.

• The application containing the source for the drag and drop determines the point at which

to initiate the drag operation. For example, a drag operation could be initiated when text

or a file icon is selected and dragged. A

DRAGDROP object is created by the source appli-

cation. The drag begins when the application calls the procedure dnd_send_drop().

• An application that has registered a drop-site must be prepared to receive a drop.

Drag and Drop

Drag and Drop 435

19.2 Registering Drop-sites

An application that is to receive a drop must register a region or several regions as valid

drop-sites. This allows drag sources to determine the validity of potential drop-sites and

enables the application to receive the events for previewing and dropping. For example, a

graphic icon or any other window may be registered as a drop-site. The drop-sites may con-

sist of one region or of several regions described by one or more rectangles within the appli-

cation. If an application does not register an area as a drop-site, it cannot receive or preview

drops.

An object instantiated from the DROP_SITE_ITEM package describes a drop-site. A drop-site

item is subclassed from the GENERIC package and is not a visible object. The following

example demonstrates how to make the rectangle representing an entire window a drop-site:

drop_site = (Xv_drop_site)xv_create(window, DROP_SITE_ITEM,

DROP_SITE_ID, 1234,

DROP_SITE_REGION, xv_get(window, WIN_RECT),

DROP_SITE_EVENT_MASK, DND_ENTERLEAVE | DND_MOTION,

DROP_SITE_DEFAULT, TRUE,

NULL);

Instances of DROP_SITE_ITEM are owned by window-based objects. The attribute

DROP_SITE_ID is an uninterpreted ID that may be used by the application to distinguish one

drop-site from the next. This attribute is useful when more than one drop-site is set on an

object (see Section 19.2.2, “Handling Events,” for details on using this attribute). Section

19.2.1, “Adding and Deleting Regions,” describes regions and the attribute

DROP_SITE_REGION. The attribute DROP_SITE_EVENT_MASK is a mask set on the drop-site

item. It is used to specify if the region(s) within the drop-site should receive preview events

(see Section 19.2.2, “Handling Events,” for more details).

DROP_SITE_DEFAULT establishes a default drop-site for drops forwarded from the window

manager. Such drops include drops on icons and window manager decorations. Only one

drop-site default should be specified per base frame; specifying more than one will have

unpredictable results. Setting this attribute provides only a hint to the window manager. The

drop-site default is used most often as a way to have drops forwarded from iconified applica-

tions.

19.2.1 Adding and Deleting Regions

Individual drop-site regions should correspond to those objects within the window that may

receive drops. For example, if there is a 64x64 icon at (10,10) within a canvas that is an

acceptable drop-site, then a drop-site item should be created. The drop-site item’s region

should be set to a rectangle with coordinates at (10,10) and a size of 64x64. If the position of

the objects within the window change or the objects are clipped by other objects, it is the

responsibility of the application to update the drop-site item to correspond to the new posi-

tion of these items. For example, if an object is deleted, its region should be removed. If an

object is being clipped by its containing window border, or a sibling window border, and is

no longer viewable, its region should be removed or updated to reflect the viewable portion

of the drop-site. If an object moves, relative to the base frame, the drop-site item region

436 XView Programming Manual

needs to be updated by deleting the old region and adding the new, updated region. Drop-

sites obscured by other application windows need not be updated. When the window that

owns a drop-site is unmapped, the drop-sites it owns are also unmapped (made “invisible”) to

drop sources. They are returned when the window is mapped again.

If an application does not keep the region information up-to-date, users may be given false

indication that old drop-site areas can receive drops.

If a drop-site item’s owner is destroyed with xv_destroy(), any drop-site regions atta-

ched to it are also destroyed.

The attribute DROP_SITE_REGION associates a region to a drop-site item.

DROP_SITE_REGION appends regions to any existing regions within the drop-site item. The

coordinates in the rect should be relative to the drop-site item’s owner’s window. An

xv_get() of a region returns a pointer to an allocated Rect * structure. This should be

freed using xv_free() once the application has finished using it.

The attribute DROP_SITE_REGION_PTR is similar to DROP_SITE_REGION except that it

accepts a NULL-terminated array of regions. It appends to any existing regions within the

drop-site item. A NULL rect is defined to be one with width or height equal to 0.

The DROP_SITE_DELETE_REGION attribute removes a region from the drop-site item. When

a NULL is passed as a value for this attribute, all regions in the drop-site are removed.

The DROP_SITE_DELETE_REGION_PTR attribute removes a list of regions from the drop-site

item. Passing a NULL as an argument removes all regions in the drop-site. Typically, when a

region needs to be updated, xv_set() should be called with two attributes:

DROP_SITE_DELETE_REGION_PTR with a NULL value, followed by DROP_SITE

_REGION_PTR

. Note that the order of these two attributes is important.

19.2.2 Handling Events

The drop-site item’s owner is a window. The event procedure for the owner window receives

the drag and drop action events and handles them accordingly. Drag and drop semantic

events are shown in Table 19-1.

Table 19-1. Drag and Drop Semantic Events

Event Purpose

ACTION_DRAG_PREVIEW Preview event.

ACTION_DRAG_MOVE Move the source data to the drop-site window.

ACTION_DRAG_COPY Copy the source data to the drop-site window.

Drag and Drop

Drag and Drop 437