NAMES

OlDnDAllocTransientAtom, OlDnDBeginSelectionTransaction, OlDnDChangeDropSitePreviewHints, OlDnDClearDragState OlDnDDeliverPreviewMessage, OlDnDDeliverTriggerMessage, OlDnDDestroyDropSite, OlDnDDisownSelection OlDnDDragAndDrop, OlDnDDragNDropDone, OlDnDEndSelectionTransaction, OlDnDErrorDuringSelectionTransaction, OlDnDFreeTransientAtom, OlDnDGetCurrentSelectionsForWidget, OlDnDGetDropSitesOfWidget, OlDnDGetDropSitesOfWindow, OlDnDGetWidgetOfDropSite, OlDnDGetWindowOfDropSite, OlDnDInitializeDragState, OlDnDOwnSelection, OlDnDOwnSelectionIncremental, OlDnDQueryDropSiteInfo, OlDnDRegisterWidgetDropSite, OlDnDRegisterWindowDropSite, OlDnDSetDropSiteInterest OlDnDSetInterestInWidgetHier OlDnDUpdateDropSiteGeometry, OlDnDWidgetConfiguredInHier − drag and drop functions

DESCRIPTION

Drag and Drop is a user-controlled data transfer operation with several steps:

The user chooses an object (representation of data) on the desktop, by pressing the SELECT mouse button over an eligible object,

drags it across the desktop, holding down the SELECT mouse button,

and drops it on some eligible recipient part of the desktop, by releasing the SELECT button. 

For example, picking up a file from a file manager and dropping it on a trash can icon to delete the file, is a Drag and Drop operation. 

TERMINOLOGY

Drop Rectangle

A drop rectangle is an area of the screen sensitive to drops, it is the unit from which drop sites are built.  Drop rectangles are not directly visible to the user without action on the part of the application defining them. 

Drop Site

A drop site is a list of drop rectangles.  Drop sites are registered with the toolkit in order for them to participate in the Drag and Drop “protocol”. 

Drop Target

A drop target is a visible receptacle for a drop.  It is marked by the glyph shown below. 

  Figure 1 Drop Target Glyph

Owner

The owner of a drop site is the window or the widget that registered it.  The owner of a drop site is notified when the user moves the cursor over one of its rectangles following a drag operation.  Drop sites die when their owner dies. 

Be careful not to confuse the widget owner of a drop site with the widget owner of a selection. 

Preview Callback

In the course of being registered, a destination drop site declares a set of preview hints and a preview callback. These are used when the user has begun a drag operation, and has moved the cursor over a drop site.  Potentially, this drop site will be the destination for the drop, to be indicated by the user releasing the SELECT button.

Before the drop occurs, the drop site is notified that a drop could be pending by calling its preview callback, subject to the conditions specified in its preview hints. 

Trigger Callback

When the user actually releases the SELECT button to indicate a drop, the drop site over which this occurs is notified of this by the toolkit calling its trigger callback.

OVERVIEW

The basic interaction between the source and destination of a Drag and Drop follows.  The source need not be a registered drop site, but the destination must be. 

Setup

Source The source must somehow have arranged to be notified when the SELECT button goes down.  How this is handled for the application varies widely, and is not discussed here.  The source can acquire an X selection Atom, at this point in preparation for performing the actual transfer.

Destination The OlDnDRegisterWidgetDropSite function is used to inform the toolkit that the widget is interested in being eligible to be a drop site.  With this call, the widget also notifies the toolkit of its preview preferences, that is when it wants to be notified that a drop may be occurring. 

Drag

The user moves the pointer away from the source, with the SELECT button still pressed, dragging the selected object over a suitable object belonging to the source. 

Source The source first grabs the mouse cursor (pointer) by calling OlGrabDragPointer. 
Then the source initializes the operation by callaing OlDnDDragAndDrop. 
This function grabs the keyboard and takes over event handling until the drop occurs.

Destination No action. 

Preview and Animate

Each time the user moves the cursor over a potential drop site, both source and destination may be notified, depending on whather they have registered suitable callbacks. 

Source The source is notified each time a potential site is entered by the activation of its Animate callback. 

Destination The drop site is notified through the pmnotify argument to the OlDnDRegisterWidgetDropSite function call it used to register itself as a drop site. 

Drop and Transfer

The actual drop occurs when the user releases the SELECT button over a drop site. 

Source The OlDnDDragAndDrop function returns and the source:

1) obtains ownership of a selection atom from the server with OlDnDOwnSelection or equivalent (if it has not done so previously).  Note that a transient Atom may be used, and that the OlDnDAllocTransientAtom may be used for this purpose. 
2) notifies the destination of its possession of the atom that will carry the data to the destination. OlDnDDeliverTriggerMessage does this, passing the selection ID of the Atom in its selection field.

Destination The destination is notified through its tm_notify callback and begins the data transfer with XGetSelection to obtain the contents of the selection. 

Closing Handshake

There is provision made for a final handshake between destination and source following ther actual data transfer. 

Source indicates interest in a closing handshake message by setting the send_done field to TRUE when it sends the Trigger message.  FALSE( indicates no interest).  This tells the destination to use OlDnDBeginSelectionTransaction and OlDnDEndSelectionTransaction functions to notify the source via its OlDnDTransactionStateCallback.  This callback function was registered as an argument to OlDnDOwnSelection or OlDnDOwnSelectionIncremental.

theDestinationbrackets with a OlDnDBeginSelectionTransaction and OlDnDEndSelectionTransaction pair of calls, which result in the source’s OlDnDTransactionStateCallback being called with the appropriate value in the reason field.  If something unpleasant happens during the transfer, the destination notifies the source with OlDnDErrorDuringSelectionTransaction.  This handshake sequence is not normally used by most applications.

Cleanup

Source releases the pointer with OlUngrabDragPointer and then releases the selection with OlDnDDisownSelection. 

Destination calls OlDnDDragandDropDone

ARGUMENTS

Since most of the arguments to the functions discussed in this manpage are repetitive, commonly used arguments are listed here for compactness.  When an argument to a specific function differs in interpretation from what is listed here, it will be noted for that individual function. 

closure user-defined data

dropsiteid ID of the dropsite over which the drop occurred

detail is an event type, either Enter, Motion, or Leave. 

num_sites is the number of drop rectangles defining the drop site

operation is either OlDnDTriggerCopyOp or OlDnDTriggerMoveOp. 

pmnotify pointer to a preview callback function, of type OlDnDPMNotifyProc.  The preview callback is registered by the destination when it is created.  It is called when the cursor passes over it follwoing the start of a drag, subject to the conditions given in the preview_hints.

preview_hints pointer to a structure of type OlDnDSitePreviewHints

root the base window of the application owning the drop site, NOT the root window of OpenWindows.

rootx the horizontal (x) coordinate at which the drop occurred, relative to the application’s root, or base window. The origin, (0,0) of this window is in the upper left hand corner. 

rooty the vertical (y) coordinate at which the drop occurred, relative to the application’s root, or base window. The origin, (0,0) of this window is in the upper left hand corner. 

selection the X selection atom actually used to transfer the data.

site_rects is the address of a variable of type which returns a pointer to an array that contains the current geometry of the drop site. This parameter may be NULL if no query on the site geometry is required.  Clients must use XtFree() to deallocate the memory used by the array when they no longer require it. 

sites is a list of OlDnDSiteRect which defines the drop rectangles, in the cordinate system of the widget that registers the drop site. 

time the current server time.  Often, this argument indicates the time of an event such as the cursor entering a drop site.  In these cases it will be explicitly noted.

tmnotify pointer to a trigger callback function, of type OlDnDTMNotifyProc

widget the widget associated with the owner of a dropsite.

window the window associated with the owner of a dropsite.

FUNCTION GROUPS

The current Drag and Drop API contains the following functions for manipulation of drop sites:

—register a widget based drop site -OlDnDRegisterWidgetDropSite()

—register a window based drop site -OlDnDRegisterWindowDropSite()

—update a drop site’s geometry -OlDnDUpdateDropSiteGeometry()

—update a drop site’s preview hints -OlDnDChangeDropSitePreviewHints()

—delete an existing drop site -OlDnDDestroyDropSite()

—query a drop site’s geometry -OlDnDQueryDropSiteInfo()

—get a window associated with a drop site -OlDnDGetWindowOfDropSite()

—get a widget associated with a drop site -OlDnDGetWidgetOfDropSite()

—get the drop sites for a widget -OlDnDGetDropSitesOfWidget()

—get the drop sites for a window -OlDnDGetDropSitesOfWindow()

And the following functions related to callbacks:

—OlDnDDeliverPreviewMessage

—OlDnDChangeDropSitePreviewHints

—OlDnDDeliverTriggerMessage

—OlDnDPreviewAndAnimate

And the following functions related to a closing handshake:

—OlDnDBeginSelectionTransaction

—OlDnDEndSelectionTransaction

—OlDnDErrorDuringSelectionTransaction

And the following functions related to obtaining selections:

—OlDnDAllocTransientAtom

—OlDnDDisownSelection

—OlDnDOwnSelection

—OlDnDOwnSelectionIncremental

—OlDnDGetCurrentSelectionsForWidget

The following functions recommended for general purpose use:

—OlDnDDragAndDrop

—OlDnDDragNDropDone

And the following special functions for subclassing:

—OlDnDWidgetConfiguredInHier

—OlDnDSetInterestInWidgetHier

DATA STRUCTURES

OlDnDDropSiteID

Synopsis:
typedef struct oldnd_drop_site ∗OlDnDDropSiteID

OlDnDDropSiteID is an opaque reference to a particular instance of a drop site. 

OlDnDSiteRect

Synopsis:
typedef XRectangle OlDnDSiteRect, ∗OlDnDSiteRectPtr;

The OlDnDSiteRect structure describes the drop site rectangle. Drop sites can include multiple rectangles. 

OlDnDSitePreviewHints

Synopsis:

typedef enum oldnd_site_preview_hints{
    OlDnDSitePreviewNone,
    OlDnDSitePreviewEnterLeave,
    OlDnDSitePreviewMotion,
    OlDnDSitePreviewBoth,
    OlDnDSitePreviewDefaultSite
    OlDnDSitePreviewForwarded,
    OlDnDSitePreviewInsensitive,
    } OlDnDSitePreviewHints;

The OlDnDSitePreviewHints structure specifies the conditions under which the drop site is interested in receiving notification through its preview callback. 

OlDnDSitePreviewNone specifies previewing. TRUE specifies no previewing. 

OlDnDSitePreviewEnterLeave specifies whether or not to preview Enter/Leave events.

OlDnDSitePreviewMotion specifies previewing of Motion events.

OlDnDSitePreviewBoth specifies previewing of Enter/Leave and Motion events.

OlDnDSitePreviewDefaultSite specifies that the drop site is the default site for drop site forwarding on this application shell.  Note that a default drop site is the site nominated to receive drops forwarded byt the window manager decorations or icons.

CALLBACK PROTOTYPES

OlDnDPreviewAnimateCallbackProc

Synopsis:

#include <Xol/OlDnDVCX.h>
 . . .
typedef void ∗(OlDnDPreviewAnimateCallbackProc)(

Widget widget,
int eventcode,
Time time,
Boolean sensitivity,
XtPointer closure);

eventcode event code, LeaveNotify, EnterNotify, MotionNotify. 

sensitivity TRUE means insensitive

This is the function prototype for the animate callback. 

OlDnDPMNotifyProc

Synopsis:

#include <Xol/OlDnDVCX.h>
 . . .
typedef void (∗OlDnDPMNotifyProc)(

Widget widget,
Window window,
Position root_x,
Position root_y,
Atom selection,
Time time,
OlDnDDropSiteID dropsiteid,
OlDnDTriggerOperation operation,
Boolean send_done,
Boolean forwarded,
XtPointer closure);

rootx is the root-relative x coordinate of preview "event"

rooty root relative-y coordinate of preview "event"

time is the time of "preview" event

dropsiteid is the id of the drop site on which the preview occurred

forwarded specifies whether the drop has been forwarded to this target from another dropsite

closure is user defined data The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDPMNotifyProc procedure is the function prototype for the drop site preview message notifier. This notifier is associated with a particular drop site at registration.  It is invoked when a drop operation in progess either enters, leaves, or moves across the drop site.  Which of these actions invokes the notifier depends on the current value of the drop site’s preview_hints. 

OlDnDPreviewAndAnimate

Synopsis:

#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDPreviewAnimateCallbackProc(

Widget widget,
Window window,
Position x,
Position y,
Time time,
OlDnDPreviewAnimateCbP animateproc,
XtPointer closure);

animateproc the animate procedure.

This function is called implicitly by OlDnDDragAndDrop and therefore is not ordinarily directly called by the OLIT programmer. 

OlDnDProtocolActionCallbackProc

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDProtocolActionCallbackProc(

Widget widget,
Atom selection,
OlDnDProtocolAction protocol_action,
Boolean flag,
XtPointer closure);

OlDnDTransactionStateCallback

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
typedef void OlDnDTransactionStateCallback(

Widget widget,
Atom selection,
OlDnDTransactionState state,
Time timestamp,
XtPointer closure);

widget is the selection holder.

selection is the selection atom

state is the protocol event that has occurred

timestamp when the event occurred.

The OlDnDTransactionState structure is defined as:

typedef enum oldnd_transaction_state {
    OlDnDTransactionBegins,
    OlDnDTransactionEnds,
    OlDnDTransactionDone,
    OlDnDTransactionRequestorError,
    OlDnDTransactionRequestorWindowDeath,
    OlDnDTransactionTimeout,
} OlDnDTransactionState;

The OlDnDOwnSelection and OlDnDOwnSelectionIncremental functions have a OlDnDTransactionStateCallback function pointer as their last parameter. This function is invoked as a result of drag and drop protocol events during the drag and drop selection transaction. 

The callback is invoked with the following OlDnDTransactionState values when the requestor of the selection (i.e the drop site) invokes the following functions:

—OlDnDBeginSelectionTransaction() - OlDnDTransactionBegins

—OlDnDEndSelectionTransaction() - OlDnDTransactionEnds

—OlDnDDragNDropDone() - OlDnDTransactionDone

A requestor may notify the selection holder of an error by calling the OlDnDErrorDuringSelectionTransaction() function.   This invokes the callback with a state value of OlDnDRequestorError. 

If the requesting client is lost during the selection transfer because its window dies, the state callback will be invoked with a state value of OlDnDTransactionRequestorWindowDeath. 

OlDnDTMNotifyProc

Synopsis:

#include <Xol/OlDnDVCX.h>
 . . .
typedef void (∗OlDnDTMNotifyProc)(

Widget widget,
Window window,
Position root_x,
Position root_y,
Atom selection,
Time time,
OlDnDDropSiteID dropsiteid,
OlDnDTriggerOperation operation,
Boolean send_done,
Boolean forwarded,
XtPointer closure);

rootx is the root-relative x coordinate at which the drop occurred

rooty is the root-relative y coordinate at which the drop occurred

time is the timestamp of the trigger message

dropsiteid is the ID of the drop site on which the drop occurred

send_done if TRUE the selection holder expects to be notified at the end of the selection transaction that it has been completed and that no further transactions associated with this drop will occur. This notification is achieved by calling .JL OlDnDDragNDropDone() when the selection transaction is completed successfully. 

forwarded if TRUE the site rectangle dropped upon is a forwarded site rectangle associated by a 3rd party (such as a window manager) with the default drop site of a top level window. 

closure is user defined data

The other arguments to this function at the beginning of this section; see Arguments.

OlDnDTMNotifyProc is the function prototype for the drop operation trigger message notifier. This notifier, associated with a particular drop site at registration, is invoked when a drop operation occurs on its associated drop site. 

FUNCTIONS

OlDnDAllocTransientAtom

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Atom OlDnDAllocTransientAtom(

Widget w);

widget is the id of the widget that will own the transient atom returned by this call.

The OlDnDAllocTransientAtom function allocates a reusable "transient" atom suitable for use in a drag and drop selection transaction for this widget. 

OlDnDBeginSelectionTransaction

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDBeginSelectionTransaction(

Widget widget,
Atom selection,
Time timestamp,
OlDnDProtocolActionCallbackProc proc,
XtPointer closure);

widget is the requesting widget or the drop site owner.

selection the selection atom passed in the trigger notify procedure.

timestamp is the server timestamp for the current time.

ack_action_cb is the callback to notify the requestor that the holder received the begin notification. The OlDnDTransactionState parameter takes the value OlDnDTransactionBegins. 

closure user data passed to ack_action_cb.

The OlDnDBeginSelectionTransaction function is used in conjuction with the OlDnDEndSelectionTransaction function to provide a positive handshake indicating a selection transaction. 

It invokes the selection holder’s transaction state callback (specified by the OlDnDOwnSelection and OlDnDOwnSelectionIncremental functions) with a state parameter of OlDnDTransactionBegins. 

OlDnDChangeDropSitePreviewHints

Synopsis:

#include <OpenLook.h>
 . . .
Boolean OlDnDChangeDropSitePreviewHints(

OlDnDDropSiteID dropsiteid;
OlDnDSitePreviewHints preview_hints);

The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDUpdateSitePreviewHints procedure updates a drop site’s preview hints.  During the lifetime of a drop site it may be necessary to alter the nature of its previewing interest.   Use OlDnDUpdateSitePreviewHints() to overwrite the existing preview hints for a drop site and update the drop site interest list appropriately. 

OlDnDClearDragState

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDClearDragState(

Widget widget);

widget is the widget ID of the selection holder

The OlDnDClearDragState function must be called upon completion of the previewing phase of a drag and drop gesture to clear internal state within the drag and drop system. 

OlDnDDeliverPreviewMessage

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDDeliverPreviewMessage(

Widget widget,
Window root,
Position rootx,
Position rooty,
Time timestamp);

widget is the  widget id of the selection owner.

The other arguments to this function at the beginning of this section; see Arguments.

OlDnDDeliverPreviewMessage attempts to deliver Enter, Leave and Motion events to any drop sites currently under the (rootx,rooty) position on the root window specified. To preview drop sites, the DSDM (DropSite Database Manager) client must be running in order to provide the source client with up-to-date drop site information.

The function returns TRUE if it finds a drop site to deliver an event to.  Otherwise it returns FALSE. 

OlDnDDeliverTriggerMessage

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDDeliverTriggerMessage(

Widget widget,
Window root,
Position rootx,
Position root_y,
Atom selection,
OlDnDTriggerOperation operation,
Time timestamp);

widget is the widget id of the selection holder

The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDDeliverTriggerMessage function is called by the dragging client to deliver a trigger message to a target drop site on the root window at the coordinates specified. 

The calling client is responsible for establishing a timeout period. If the drop target doesn’t send selection conversion requests during this period it should take appropriate action.  OlDnDDeliverTriggerMessage returns TRUE if it finds a drop site to dispatch a trigger message to at the root (x,y).  Otherwise it returns FALSE. 

OlDnDDestroyDropSite

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDDestroyDropSite(

OlDnDDropSiteID dropsiteid);

The OlDnDDestroyDropSite explictly destroys a drop site. Note that when a drop site’s widget or window is destroyed, all drop sites associated with that widget or window are automatically destroyed. 

dropsiteid is the id of the drop site

OlDnDDisownSelection

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDDisownSelection(

Widget widget,
Atom selection,
Time timestamp);

The OlDnDDisownSelection function is identical in semantics to the Xt function XtDisownSelection(). 

OlDnDDragAndDrop

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDDragAndDrop(

Widget widget,
Window ∗window,
Position ∗x,
Position ∗y,
OlDnDDragDropInfoPtr drop_info,
OlDnDPreviewAnimateCbP proc,
XtPointer closure);

widget is the widget ID of the selection holder

window returns the ID of the window containing the cursor (pointer).

x is the x coordinate of the cursor relative to the containing window

y is the y coordinate of the cursor relative to the containing window

drop_info is a pointer to a structure of type OlDnDDragNDropInfo containing information about location of drop,  root-relative. 

typedef struct_ol_dnd_root_info {
    Windowroot_window;
    Positionroot_x;
    Positionroot_y;
    Timedrop_timestamp;
    } OlDnDDragNDropInfo, ∗OlDnDDragNDropInfoPtr;

proc is the animate procedure which is called when the cursor enters a dropsite.

The OlDnDDragAndDrop function provides a simple interface for processing the mouse and keyboard events during a drop and drop operation. Before calling this function, you should call OlGrabDragCursor or XGrabPointer to effectively grab pointer events.  .LP OlDnDDragAndDrop issues an XGrabKeyboard to obtain keystrokes during the drag operation. It then inserts a raw event handler on the widget specified for the pointer and key events and initializes the drag and drop system with OlDnDInitializeDragState.  Then it proceeds to process the event stream, delivering preview messages where appropriate via OlDnDDeliverPreviewMessage until the drag completes or is aborted. The function returns the x, y location and the window that the pointer was in when the operation completed.  It also returns the necessary root information. 

OlDnDDragNDropDone

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDDragNDropDone(

Widget widget,
Atom selection,
Time timestamp,
OlDnDProtocolActionCallbackProc proc,
XtPointer closure);

OlDnDEndSelectionTransaction

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDEndSelectionTransaction(

Widget widget,
Atom selection,
Time timestamp,
OlDnDProtocolActionCbP proc,
XtPointer closure);

ack_action_cb is the callback to inform the requestor that the holder has successfully received the end notification. When it is invoked, the OlDnDTransactionState parameter takes the value OlDnDTransactionEnds. 

closure is user data passed to the

proc the protocol action callback.

The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDEndSelectionTransaction function provides a positive handshake between the selection requestor and holder. 

It invokes the selection holders transaction state callback (registered with the OlDnDOwnSelection and OlDnDOwnSelectionIncremental functions) with a state parameter of OIDnDSelectionTransactionEnds. 

OlDnDErrorDuringSelectionTransaction

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDErrorDuringSelectionTransaction(

Widget widget,
Atom selection,
Time timestamp,
OlDnDProtocolActionCallbackProc proc,
XtPointer closure);

ack_action_cb is the callback to inform the requestor that the selection holder has successfully received the error notification. When it is invoked the OlDnDTransactionState paramater takes the value OlDnDTransactionError. 

closure is user data passed to ack_action_cb.

The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDErrorDuringSelectionTransaction function can be called at any time during the selection transfer by the requestor to inform the selection holder that there is an error. The subsequent behaviour of the holder is undefined by this protocol.  OlDnDErrorDuringSelectionTransaction invokes the selection holder’s protocol state callback (registered with OlDnDOwnSelection or OlDnDOwnSelectionIncremental) with a protocol state parameter value of OlDnDSelectionTransactionError. 

OlDnDFreeTransientAtom

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDFreeTransientAtom(

Widget widget,
Atom transient);

widget is the widget with which the transient atom was associated.

transient is the selection atom.

The OlDnDFreeTransientAtom function frees the transient atom specified for use by other X entities. 

OlDnDGetCurrentSelectionsForWidget

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDGetCurrentSelectionsForWidget(

Widget widget,
Atom ∗∗atoms_return,
Cardinal ∗num_sites_return);

widget is the ID of the widget ID being investigated. atoms_return points to an array of atoms currently held as selections by the widget.

num_sites_return points to the number of atoms returned.

The OlDnDGetCurrentSelectionsForWidget function returns a list of atoms currently held as drag and drop selections for the specified widget. If OlDnDGetCurrentSelectionsForWidget finds any, it returns TRUE.  Otherwise it returns FALSE. 

The caller must call XtFree() on the pointer returned in the atom’s parameter to free the store allocated when no longer required. 

OlDnDGetDropSitesOfWidget

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
OlDnDDropSiteID ∗OlDnDGetDropSitesOfWidget(

Widget widget,
Cardinal ∗num_sites_return);

The arguments to this function at the beginning of this section; see Arguments.

The OlDnDGetDropSitesOfWidget obtains the currently registered list of drop sites for a particular widget instance. The function returns a pointer to an OlDnDDropSiteID array that is an enumeration of the drop sites currently registered for the widget. Clients should use XtFree() on this return value  to deallocate the array when it is no longer needed.  If there are no drop sites registered or the function fails, OlDnDGetDropSitesOfWidget returns NULL. 

OlDnDGetDropSitesOfWindow

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
OlDnDDropSiteID ∗OlDnDGetDropSitesOfWindow(

Display dpy,
Window window,
Cardinal ∗num_sites_return);

dpy the display The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDGetDropSitesOfWindow function obtains the currently registered list of drop sites for a particular window. The function returns a pointer to an array that is an enumeration of the drop sites currently registered for the window. Clients should use XtFree() on this return value  to deallocate the array when it is no longer needed.  If there are no drop sites registered or the function fails, OlDnDGetDropSitesOfWindow returns NULL. 

OlDnDGetWidgetOfDropSite

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Widget OlDnDGetWidgetOfDropSite(

OlDnDDropSiteID dropsiteid);

The argument to this function is described earlier; see Arguments.

The OlDnDGetWidgetOfDropSite function returns the ID of the widget associated with a drop site. If the drop site was registered with returns the ID of the widget that is the most immediate ancestor of the associated window. 

OlDnDGetWindowOfDropSite

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Window OlDnDGetWindowOfDropSite(

OlDnDDropSiteID dropsiteid);

The argument to this function is described earlier; see Arguments.

The OlDnDGetWindowOfDropSite function returns the window ID that the drop site was associated with. If the drop site was registered with a gadget then OlDnDGetWindowOfDropSite returns the window ID of the gadget’s windowed parent. 

OlDnDInitializeDragState

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDInitializeDragState(

Widget widget);

widget is the widget id of the selection holder

The OlDnDInitializeDragState function is called prior to commencing delivery of preview messages to cause the drag and drop system to download drop site previewing information from the DSDM. It returns TRUE if the download was successful.  Otherwise it returns FALSE. 

OlDnDOwnSelection

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDOwnSelection(

Widget widget,
Atom selection,
Time timestamp,
XtConvertSelectionProc convert_proc,
XtLoseSelectionProc lose_proc,
XtSelectionDoneProc done_proc,
OlDnDTransactionStateCallback state_cb,
XtPointer closure);

The OlDnDOwnSelection procedure is identical in semantics to the Xt function XtOwnSelection() except for the additional parameter state_cb (see OlDnDTransactionStateCallback below). 

OlDnDOwnSelectionIncremental

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDOwnSelectionIncremental(

Widget widget,
Atom selection,
Time timestamp,
XtConvertSelectionIncrProc convert_incr_proc,
XtLoseSelectionIncrProc lose_incr_proc,
XtSelectionDoneIncrProc done_incr_proc,
XtCancelConvertSelectionProc cancel_proc,
XtPointer client_data,
OlDnDTransactionStateCallback state_cb);

The OlDnDOwnSelectionIncremental function is identical in semantics to the Xt function XtOwnSelectionIncremental() except for the additional parameter state_cb (see OlDnDTransactionStateCallback below). 

OlDnDQueryDropSiteInfo

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDQueryDropSiteInfo(

OlDnDDropSiteID dropsiteid,
Widget ∗widget,
Window ∗window,
OlDnDSitePreviewHints ∗preview_hints,
OlDnDSiteRectPtr ∗site_rects,
unsigned int ∗num_rects,
Boolean ∗on_interest);

window is the address of a variable of type Window which returns the id of the window that owns the drop site.  Set this parameter to NULL if no query on the window id is required. For gadgets, this is the window id of its windowed ancestor. 

hints is the address of a variable of type OlDnDSitePreviewHints which returns the current hints for the drop site.  Set this parameter to NULL if no query on the preview hints is required. 

site_rects is the address of a variable of type which returns a pointer to an array that contains the current geometry of the drop site. This parameter may be set to NULL if no query on the site geometry is required.  Clients must use XtFree() to deallocate the memory used by the array when they no longer require it. 

num_rects is the address of an  unsigned int variable that returns the number of OlSiteRect structures specified for the drop site.  Set this parameter to noNULLif non-NULL if the site_rects parameter is non-NULL. 

The OlDnDQueryDropSiteInfo function retrieves information about a particular drop site. The function returns TRUE if the query was successful.  Otherwise it returns FALSE. 

OlDnDRegisterWidgetDropSite

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
OlDnDDropSiteID OlDnDRegisterWidgetDropSite(

Widget widget,
OlDnDSitePreviewHints preview_hints,
OlDnDSiteRectPtr site_rects,
unsigned int num_sites,
OlDnDTMNotifyProc tmnotify,
OlDnDPMNotifyProc pmnotify,
Boolean on_interest,
XtPointer closure);

closure is a user defined parameter which is passed to the tmnotify and pmnotify functions when they are called.

The other arguments to this function at the beginning of this section; see Arguments.

The OlDnDRegisterWidgetDropSite function creates a drop site associated with a particular widget.  A widget must be realized, that is it must have a window associated with it, before you can create a drop site for it.  Gadgets can support drop sites and use their windowed ancestor’s window in association with the registered drop site.  Drop sites are automatically destroyed when their owning widgets die. 

OlDnDRegisterWindowDropSite

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
OlDnDDropSiteID OlDnDRegisterWindowDropSite(

Display ∗dpy,
Window window,
OlDnDSitePreviewHints preview_hints,
OlDnDSiteRectPtr site_rects,
unsigned int num_sites,
OlDnDTMNotifyProc tmnotify,
OlDnDPMNotifyProc pmnotify,
Boolean on_interest,
XtPointer closure);

dpy is the display

closure is a user-defined parameter that is passed to the tmnotifyand pmnotify functions when they are called.

The other arguments to this function at the beginning of this section; see Arguments

The OlDnDRegisterWindowDropSite procedure registers a window-based drop site. It creates a drop site associated with a particular X Window and is useful for toolkit applications that mix ‘raw’ X windows with widgets. Drop sites are automatically destroyed when their owning windows die. The window must be an inferior of a widgets window. 

OlDnDSetDropSiteInterest

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDSetDropSiteInterest(

OlDnDDropSiteID dropsite,
Boolean flag);

flag TRUE means the drop sites are made active. 

FALSE means the drop sites are made inactive

This function activates or inactivates a drop site by exporting its existence.  Active drop sites respond to drops.  Inactive drop sites do not respond to drops. 

OlDnDSetInterestInWidgetHier

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDSetInterestInWidgetHier(

Widget w);

flag TRUE means the drop sites are made active. 

FALSE means the drop sites are made inactive

This function activates or inactivates all drop sites belonging to this widget and it’s children. 

OlDnDUpdateDropSiteGeometry

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
Boolean OlDnDUpdateDropSiteGeometry(

OlDnDDropSiteID dropsiteid,
OlDnDSiteRectPtr site_rects,
unsigned int num_sites);

The OlDnDUpdateDropSiteGeometry function alters the geometry of a drop site. Changes in the geometry of a drop site are caused by changes in the geometry of the widget or window that owns the drop site. To reduce client-server traffic, the Drag and Drop implementation does not automatically track changes in the window that owns a drop site.  The creator of a drop site is responsible for maintaining the geometry of the site to reflect any changes in the widget or window that owns the site. 

dropsiteid is the id of the drop site to be updated

site_rects is the new list of site rectangles for the drop site

num_sites is the number of rectangles in the new rectangle list.

OlDnDWidgetConfiguredInHier

Synopsis:

#include <Xol/OpenLook.h>
#include <Xol/OlDnDVCX.h>
 . . .
void OlDnDWidgetConfiguredInHier(

Widget widget);

This function is primarily for use by developers of Composite widgets. 

Since drop sites are separate from the servers window hierarchy, drop site owners must attempt to maintain their drop sites clipped to their visible region(s) as defined by the server window hierarchy associated with the widget hierarchy that contains the drop sites. 

In order to achieve this clipping, widgets and their subclasses must inform the Drag and Drop system that they have configured some widgets in their subtree, as a result of a call to that Composite widgets ChangeManaged() or GeometryManager() methods, hence potentially changing the visble region(s) of drop sites in that subtree. Calling this function will cause the Drag and Drop system to recalcuate the clipping region(s) of any drop sites under the configuring widget in the widget hierarchy. 

In order to eliminate multiple recalculations of drop site clipping region(s) due to configures propagating down a widget hierachy a mechanism exists to suppress such multiple calculations, developers should take advantage of this in order to optimise for performance. 

Below is an example of the usage of this function in a simple geometry_manager:

staticXtGeometryResult
GeometryManager()
Widgetrequestor;
XtWidgetGeometry∗request,
XtWidgetGeometry∗reply);
  {
  CompositeWidgetcomp =
                            requestor->core.parent;
  Widgetvendor = comp;
  Argargs[2];
  Booleanconfigured_others = False;
XtSetArg(args[0], XtNconfiguringWidget, (XtPointer)requestor);
XtSetArg(args[1], XtNdisableDSClipping, True);
while (!XtIsVendorShell(w)) vendor = vendor->core.parent;
XtSetValues(vendor, args, XtNumber(args);
/∗ disable clipping in my subtree while I configure ∗/
/∗
∗ consider the geometry request recieved and then maybe
∗ configure one or more of the managed set and/or perhaps
∗ request that my parent reconfigure me as a result of the
∗ request being made by the requestor widget.
∗
∗ set configured_others True if the Composite made a successful
∗ geometry request to its parent, or if it moved siblings of
∗ the requestor ......
∗
∗/
if ((request->request_mode & CWX) == CWX)
    requestor->core.x = request->x;
if ((request->request_mode & CWY) == CWY)
    requestor->core.y = request->y;
if ((request->request_mode & CWWidth) == CWWidth)
    requestor->core.width = request->width;
if ((request->request_mode & CWHeight) == CWHeight)
    requestor->core.height = request->height;
    XtSetArg(args[1], XtNdisableDSClipping, False);
    XtSetValues(vendor, args, XtNumber(args));
/∗ enable clipping again .... ∗/
/∗
∗ inform the drag and drop system to clip any drop sites in
∗ the widget hierarchy under the configuring widget.
∗/
if (configured_others)
    OlDnDWidgetConfiguredInHier((Widget)comp);
else
    OlDnDWidgetConfiguredInHier(requestor);
return XtGeometryYes;
}

Version 3.0.1  —  Last change: June 92