Name

XtSelectionCallbackProc — prototype procedure called when requested selection data arrives. 

Synopsis

typedef void (∗XtSelectionCallbackProc)(Widget, XtPointer, Atom ∗, Atom ∗, XtPointer, unsigned long ∗, int ∗);

    Widget w;
    XtPointer client_data;
    Atom ∗selection;
    Atom ∗type;
    XtPointer value;
    unsigned long ∗length;
    int ∗format;

Arguments

wSpecifies the widget that requested the selection value. 

client_data
Specifies a value passed in by the widget when it requested the selection.

selectionSpecifies the type of selection that was requested. 

typeSpecifies the representation type of the selection value (for example, XA_STRING).  Note that it is not the target that was requested but the type that is used to represent the target.  The special X Toolkit atom XT_CONVERT_FAIL is used to indicate that the selection conversion failed because the selection owner did not respond within the Intrinsics’ selection timeout interval. 

valueSpecifies a pointer to the selection value.  The requesting client owns this storage and is responsible for freeing it by calling XtFree when it is done with it. 

lengthSpecifies the number of elements in value. 

formatSpecifies the size in bits of the data elements of value. 

Description

This procedure is registered by the requestor with XtGetSelectionValue or XtGetSelectionValues, and is then called by the Intrinsics selection mechanism to deliver the requested selection to the requestor.  Data transfer proceeds as follows: data is requested from the owner of the selection with XtGetSelectionValue or XtGetSelectionValues; when the data finally arrives, the SelectionCallbackProc is invoked with the actual data. 

If the SelectionNotify event returns a property of None, this means the conversion has been refused, either because there is no owner for the specified selection or because the owner cannot convert the selection to the requested target for any reason.  In either case, the XtSelectionCallbackProc procedure is called with a value of NULL and a length of 0. 

This procedure does not need to worry about responding to the MULTIPLE or the TIMESTAMP target values.  A selection request with the MULTIPLE target type will be transparently transformed into a series of calls to this procedure, one for each target type, and a selection request with the TIMESTAMP target value will be answered automatically by the Intrinsics using the time specified in the call to XtOwnSelection or XtOwnSelectionIncremental. 

Data delivery is done by callback, since the Intrinsics may have to perform multiple server requests to get data, and other events may require processing ahead of the data transfer.  Therefore, actual data delivery must occur asynchronously with respect to XtGetSelectionValue or XtGetSelectionValues. 

Chapter 10, Interclient Communications, in Volume Four, X Toolkit Intrinsics Programming Manual, presents a complete example widget that both sends and receives data using selections. 

See Also

XtDisownSelection(1), XtGetSelectionValue(1), XtGetSelectionValueIncremental(1), XtGetSelectionValues(1), XtOwnSelection(1), XtOwnSelectionIncremental(1).