X11SelectionRequestor.mesa
Copyright Ó 1990, 1991 by Xerox Corporation. All rights reserved.
Christian Jacobi, November 12, 1990 5:42 pm PST
Christian Jacobi, March 20, 1991 11:24 am PST
DIRECTORY Xl;
X11SelectionRequestor: CEDAR DEFINITIONS ~ BEGIN
Package to get the value of a selection. Uses all gorry details of ICCCM.
As a difference to the C language standards and the capabilities of the protocol this package does not allow the client to specify the actual windows and the properties to be used for communications.
To most clients this is a welcome simplification. Should a client need access to this data, it can use the SelectionSetup callback to get told the actual values used.
The reason these parameters are not available to clients is to increase robustness. By providing this information internally the package has the option of cleaning up and replacing windows and properties after any kind of failures. This prevents orphaned selection owners to do damage to future requests.
If a selection owner answers a request properly and to the very finish, this package assumes the owner will keep behaving properly and won't damage future requests. In this case internal windows and properties will be reused.
Result: TYPE = {ok, none, timeout};
Describes success of a request.
ok: selection owner answered; look at answer to find out real success.
none: E.g. no selection owner or no anwser.
timeout: Timed out. It is however possible that a request is partly executed.
Note that it is possible for different targets of a multiple request to return different Result's.
SelectionReceivedProc: TYPE = PROC [selection: Xl.XAtom, target: Xl.XAtom, result: Result, value: LIST OF REF ANY, type: Xl.XAtom, format: BYTE, clientData: REF];
Called to transfer results back to caller of GetSelection. Called on tq or directly.
clientData, selection, target: as requested; allows identification.
result: success state of operation.
type: returned type.
value: returned values.
format: size of unit of returned values.
SelectionSetupProc: TYPE = PROC [selection: Xl.XAtom, target: Xl.XAtom, window: Xl.Window, property: Xl.XAtom, clientData: REF, connection: Xl.Connection];
Gives the selection requestor a chance to set up properties first.
Called before doing actual work. Allways called directly.
clientData, selection, target, connection: as requested; allows identification.
window, property: the data told to the callee.
Request: TYPE = RECORD [target: Xl.XAtom, callback: SelectionReceivedProc ¬ NIL, clientData: REF ¬ NIL, setUp: SelectionSetupProc ¬ NIL];
Describes (part of) a selection request.
RequestList: TYPE = LIST OF Request;
Describes a multiple selection request.
GetSelection: PROC [c: Xl.Connection, selection: Xl.XAtom ¬ [1], timeStamp: Xl.TimeStamp, request: Request, tq: Xl.TQ ¬ NIL, timeout: INT ¬ 0];
c: ...
selection: name of requested selection.
timeStamp: Timestamp of event which initiated asking for the selection. Do NOT use Xl.currentTime.
request:
target: type desired by requestor.
callback: Procedure called/enqueued to return received results to caller.
setUp: Procedure eventually called while setting up the request.
clientData: data passed to callback and setUp.
tq: ThreadQueue used to enqueue callback. (callback's are called directly if tq=NIL).
timeout: In seconds; 0 defaults to some reasonable small value.
GetSelectionMultiple: PROC [c: Xl.Connection, selection: Xl.XAtom ¬ [1], timeStamp: Xl.TimeStamp, requests: RequestList, tq: Xl.TQ ¬ NIL, timeout: INT ¬ 0];
Like multiple GetSelection but guaranteed using the same owner.
END.