iBet uBet web content aggregator. Adding the entire web to your favor.

Link to original content: http://tronche.com/gui/x/icccm/sec-2.html

2. Peer-to-Peer Communication by Means of Selections

Selections communicate between an owner and a requestor. The owner has the data representing the value of its selection, and the requestor receives it. A requestor wishing to obtain the value of a selection provides the following:

• The name of the selection
• The name of a property
• A window
• The atom representing the data type required
• Optionally, some parameters for the request

• Convert the contents of the selection to the requested data type
• Place this data in the named property on the named window
• Send the requestor an event to let it know the property is available

Note that all data transferred between an owner and a requestor must usually go by means of the server in an X Version 11 environment. A client cannot assume that another client can open the same files or even communicate directly. The other client may be talking to the server by means of a completely different networking mechanism (for example, one client might be DECnet and the other TCP/IP). Thus, passing indirect references to data (such as file names, host names and port numbers, and so on) is permitted only if both clients specifically agree.

2.1. Acquiring Selection Ownership

SetSelectionOwner

selection :	ATOM
owner :	WINDOW or None
time :	TIMESTAMP or CurrentTime

The client should set the specified selection to the atom that represents the selection, set the specified owner to some window that the client created, and set the specified time to some time between the current last-change time of the selection concerned and the current server time. This time value usually will be obtained from the timestamp of the event that triggers the acquisition of the selection. Clients should not set the time value to CurrentTime , because if they do so, they have no way of finding when they gained ownership of the selection. Clients must use a window they created so that requestors can route events to the owner of the selection.²

Convention

Clients attempting to acquire a selection must set the time value of the SetSelectionOwner request to the timestamp of the event triggering the acquisition attempt, not to CurrentTime . A zero-length append to a property is a way to obtain a timestamp for this purpose; the timestamp is in the corresponding PropertyNotify event.

If the time in the SetSelectionOwner request is in the future relative to the server's current time or is in the past relative to the last time the specified selection changed hands, the SetSelectionOwner request appears to the client to succeed, but ownership is not actually transferred.

Because clients cannot name other clients directly, the specified owner window is used to refer to the owning client in the replies to GetSelectionOwner , in SelectionRequest and SelectionClear events, and possibly as a place to put properties describing the selection in question. To discover the owner of a particular selection, a client should invoke GetSelectionOwner , which is defined as follows:

GetSelectionOwner

selection :	ATOM
->
owner :	WINDOW or None

Convention

Clients are expected to provide some visible confirmation of selection ownership. To make this feedback reliable, a client must perform a sequence like the following:

SetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp)
owner = GetSelectionOwner(selection=PRIMARY)
if (owner != Window) Failure

If the SetSelectionOwner request succeeds (not merely appears to succeed), the client that issues it is recorded by the server as being the owner of the selection for the time period starting at the specified time.

2.2. Responsibilities of the Selection Owner

SelectionRequest

owner :	WINDOW
selection :	ATOM
target :	ATOM
property :	ATOM or None
requestor :	WINDOW
time :	TIMESTAMP or CurrentTime

The specified owner and selection will be the values that were specified in the SetSelectionOwner request. The owner should compare the timestamp with the period it has owned the selection and, if the time is outside, refuse the SelectionRequest by sending the requestor window a SelectionNotify event with the property set to None (by means of a SendEvent request with an empty event mask).

More advanced selection owners are free to maintain a history of the value of the selection and to respond to requests for the value of the selection during periods they owned it even though they do not own it now.

If the specified property is None , the requestor is an obsolete client. Owners are encouraged to support these clients by using the specified target atom as the property name to be used for the reply.

Otherwise, the owner should use the target to decide the form into which the selection should be converted. Some targets may be defined such that requestors can pass parameters along with the request. The owner will find these parameters in the property named in the selection request. The type, format, and contents of this property are dependent upon the definition of the target. If the target is not defined to have parameters, the owner should ignore the property if it is present. If the selection cannot be converted into a form based on the target (and parameters, if any), the owner should refuse the SelectionRequest as previously described.

If the specified property is not None , the owner should place the data resulting from converting the selection into the specified property on the requestor window and should set the property's type to some appropriate value, which need not be the same as the specified target.

Convention

All properties used to reply to SelectionRequest events must be placed on the requestor window.

In either case, if the data comprising the selection cannot be stored on the requestor window (for example, because the server cannot provide sufficient memory), the owner must refuse the SelectionRequest , as previously described. See also section 2.5.

If the property is successfully stored, the owner should acknowledge the successful conversion by sending the requestor window a SelectionNotify event (by means of a SendEvent request with an empty mask). SelectionNotify is defined as follows:

SelectionNotify

requestor :	WINDOW
selection, target :	ATOM
property :	ATOM or None
time :	TIMESTAMP or CurrentTime

The owner should set the specified selection, target, time, and property arguments to the values received in the SelectionRequest event. (Note that setting the property argument to None indicates that the conversion requested could not be made.)

Convention

The selection, target, time, and property arguments in the SelectionNotify event should be set to the values received in the SelectionRequest event.

If the owner receives more than one SelectionRequest event with the same requestor, selection, target, and timestamp, it must respond to them in the same order in which they were received.

Rationale

It is possible for a requestor to have multiple outstanding requests that use the same requestor window, selection, target, and timestamp, and that differ only in the property. If this occurs, and one of the conversion requests fails, the resulting SelectionNotify event will have its property argument set to None . This may make it impossible for the requestor to determine which conversion request had failed, unless the requests are responded to in order.

The data stored in the property must eventually be deleted. A convention is needed to assign the responsibility for doing so.

Convention

Selection requestors are responsible for deleting properties whose names they receive in SelectionNotify events (see section 2.4) or in properties with type MULTIPLE.

A selection owner will often need confirmation that the data comprising the selection has actually been transferred. (For example, if the operation has side effects on the owner's internal data structures, these should not take place until the requestor has indicated that it has successfully received the data.) Owners should express interest in PropertyNotify events for the specified requestor window and wait until the property in the SelectionNotify event has been deleted before assuming that the selection data has been transferred. For the MULTIPLE request, if the different conversions require separate confirmation, the selection owner can also watch for the deletion of the individual properties named in the property in the SelectionNotify event.

When some other client acquires a selection, the previous owner receives a SelectionClear event, which is defined as follows:

SelectionClear

owner :	WINDOW
selection :	ATOM
time :	TIMESTAMP

The timestamp argument is the time at which the ownership changed hands, and the owner argument is the window the previous owner specified in its SetSelectionOwner request.

If an owner loses ownership while it has a transfer in progress (that is, before it receives notification that the requestor has received all the data), it must continue to service the ongoing transfer until it is complete.

If the selection value completely changes, but the owner happens to be the same client (for example, selecting a totally different piece of text in the same xterm as before), then the client should reacquire the selection ownership as if it were not the owner, providing a new timestamp. If the selection value is modified, but can still reasonably be viewed as the same selected object,³ the owner should take no action.

2.3. Giving Up Selection Ownership

2.3.1. Voluntarily Giving Up Selection Ownership

Alternatively, the client may destroy the window used as the owner value of the SetSelectionOwner request, or the client may terminate. In both cases, the ownership of the selection involved will revert to None .

2.3.2. Forcibly Giving Up Selection Ownership

The timestamp is the time the selection changed hands. The specified owner is the window that was specified by the current owner in its SetSelectionOwner request.

2.4. Requesting a Selection

ConvertSelection

selection, target :	ATOM
property :	ATOM or None
requestor :	WINDOW
time :	TIMESTAMP or CurrentTime

The selection argument specifies the particular selection involved, and the target argument specifies the required form of the information. For information about the choice of suitable atoms to use, see section 2.6. The requestor should set the requestor argument to a window that it created; the owner will place the reply property there. The requestor should set the time argument to the timestamp on the event that triggered the request for the selection value. Note that clients should not specify CurrentTime .

Convention

Clients should not use CurrentTime for the time argument of a ConvertSelection request. Instead, they should use the timestamp of the event that caused the request to be made.

The requestor should set the property argument to the name of a property that the owner can use to report the value of the selection. Requestors should ensure that the named property does not exist on the window before issuing the ConvertSelection request.⁴ The exception to this rule is when the requestor intends to pass parameters with the request; see below.

Rationale

It is necessary for requestors to delete the property before issuing the request so that the target can later be extended to take parameters without introducing an incompatibility. Also note that the requestor of a selection need not know the client that owns the selection nor the window on which the selection was acquired.

Some targets may be defined such that requestors can pass parameters along with the request. If the requestor wishes to provide parameters to a request, they should be placed in the specified property on the requestor window before the requestor issues the ConvertSelection request, and this property should be named in the request.

Some targets may be defined so that parameters are optional. If no parameters are to be supplied with the request of such a target, the requestor must ensure that the property does not exist before issuing the ConvertSelection request.

The protocol allows the property field to be set to None , in which case the owner is supposed to choose a property name. However, it is difficult for the owner to make this choice safely.

Conventions

1. Requestors should not use None for the property argument of a ConvertSelection request.
2. Owners receiving ConvertSelection requests with a property argument of None are talking to an obsolete client. They should choose the target atom as the property name to be used for the reply.

The result of the ConvertSelection request is that a SelectionNotify event will be received. For the definition of a SelectionNotify event, see section 2.2.

The requestor, selection, time, and target arguments will be the same as those on the ConvertSelection request.

If the property argument is None , the conversion has been refused. This can mean either that there is no owner for the selection, that the owner does not support the conversion implied by the target, or that the server did not have sufficient space to accommodate the data.

If the property argument is not None , then that property will exist on the requestor window. The value of the selection can be retrieved from this property by using the GetProperty request, which is defined as follows:

GetProperty

window :	WINDOW
property :	ATOM
type :	ATOM or AnyPropertyType
long-offset, long-length :	CARD32
delete :	BOOL
->
type :	ATOM or None
format :	{0, 8, 16, 32}
bytes-after :	CARD32
value :	LISTofINT8 or LISTofINT16 or LISTofINT32

When using GetProperty to retrieve the value of a selection, the property argument should be set to the corresponding value in the SelectionNotify event. Because the requestor has no way of knowing beforehand what type the selection owner will use, the type argument should be set to AnyPropertyType . Several GetProperty requests may be needed to retrieve all the data in the selection; each should set the long-offset argument to the amount of data received so far, and the size argument to some reasonable buffer size (see section 2.5). If the returned value of bytes-after is zero, the whole property has been transferred.

Once all the data in the selection has been retrieved (which may require getting the values of several properties &emdash; see section 2.7), the requestor should delete the property in the SelectionNotify request by using a GetProperty request with the delete argument set to True . As previously discussed, the owner has no way of knowing when the data has been transferred to the requestor unless the property is removed.

Convention

The requestor must delete the property named in the SelectionNotify once all the data has been retrieved. The requestor should invoke either DeleteProperty or GetProperty (delete==True) after it has successfully retrieved all the data in the selection. For further information, see section 2.5.

2.5. Large Data Transfers

• Transferring large amounts of data to the server is expensive.
• All servers will have limits on the amount of data that can be stored in properties. Exceeding this limit will result in an Alloc error on the ChangeProperty request that the selection owner uses to store the data.

Conventions

1. Selection owners should transfer the data describing a large selection (relative to the maximum-request-size they received in the connection handshake) using the INCR property mechanism (see section 2.7.2).
2. Any client using SetSelectionOwner to acquire selection ownership should arrange to process Alloc errors in property change requests. For clients using Xlib, this involves using the XSetErrorHandler() function to override the default handler.
3. A selection owner must confirm that no Alloc error occurred while storing the properties for a selection before replying with a confirming SelectionNotify event.
4. When storing large amounts of data (relative to maximum-request-size), clients should use a sequence of ChangeProperty (mode==Append) requests for reasonable quantities of data. This avoids locking servers up and limits the waste of data an Alloc error would cause.
5. If an Alloc error occurs during the storing of the selection data, all properties stored for this selection should be deleted and the ConvertSelection request should be refused (see section 2.2).
6. To avoid locking servers up for inordinate lengths of time, requestors retrieving large quantities of data from a property should perform a series of GetProperty requests, each asking for a reasonable amount of data.

Advice to Implementors

Single-threaded servers should take care to avoid locking up during large data transfers.

2.6. Use of Selection Atoms

2.6.1. Selection Atoms

• PRIMARY
• SECONDARY
• CLIPBOARD

2.6.1.1. The PRIMARY Selection

2.6.1.2. The SECONDARY Selection

• As the second argument to commands taking two arguments (for example, "exchange primary and secondary selections")
• As a means of obtaining data when there is a primary selection and the user does not want to disturb it

2.6.1.3. The CLIPBOARD Selection

• It should assert ownership of the CLIPBOARD.
• If it succeeds in acquiring ownership, it should be prepared to respond to a request for the contents of the CLIPBOARD in the usual way (retaining the data to be able to return it). The request may be generated by the clipboard client described below.
• If it fails to acquire ownership, a cutting client should not actually perform the cut or provide feedback that would suggest that it has actually transferred data to the clipboard.

Clients wanting to paste data from the clipboard should request the contents of the CLIPBOARD selection in the usual way.

Except while a client is actually deleting or copying data, the owner of the CLIPBOARD selection may be a single, special client implemented for the purpose. This client maintains the content of the clipboard up-to-date and responds to requests for data from the clipboard as follows:

• It should assert ownership of the CLIPBOARD selection and reassert it any time the clipboard data changes.
• If it loses the selection (because another client has some new data for the clipboard), it should:
  • Obtain the contents of the selection from the new owner by using the timestamp in the SelectionClear event.
  • Attempt to reassert ownership of the CLIPBOARD selection by using the same timestamp.
  • Restart the process using a newly acquired timestamp if this attempt fails. This timestamp should be obtained by asking the current owner of the CLIPBOARD selection to convert it to a TIMESTAMP. If this conversion is refused or if the same timestamp is received twice, the clipboard client should acquire a fresh timestamp in the usual way (for example by a zero-length append to a property).
• It should respond to requests for the CLIPBOARD contents in the usual way.

• Stability - If the cutting client were to crash or terminate, the clipboard value would still be available.
• Feedback - The clipboard client can display the contents of the clipboard.
• Simplicity - A client deleting data does not have to retain it for so long, thus reducing the chance of race conditions causing problems.

• Performance - Data is only transferred if it is actually required (that is, when some client actually wants the data).
• Flexibility - The clipboard data may be available as more than one target.

2.6.2. Target Atoms

References:

1

Adobe Systems, Incorporated. Portable Document Format Reference Manual. Addison-Wesley, ISBN 0-201-62628-4.

2

Apple Computer, Incorporated. Inside Macintosh, Volume V. Chapter 4, "Color QuickDraw," Color Picture Format. ISBN 0-201-17719-6.

3

Adobe Systems, Incorporated. PostScript Language Reference Manual. Addison-Wesley, ISBN 0-201-18127-4.

Selection owners are required to support the following targets. All other targets are optional.

• TARGETS - The owner should return a list of atoms that represent the targets for which an attempt to convert the current selection will succeed (barring unforseeable problems such as Alloc errors). This list should include all the required atoms.
• MULTIPLE - The MULTIPLE target atom is valid only when a property is specified on the ConvertSelection request. If the property argument in the SelectionRequest event is None and the target is MULTIPLE, it should be refused.

  When a selection owner receives a SelectionRequest (target==MULTIPLE) request, the contents of the property named in the request will be a list of atom pairs: the first atom naming a target and the second naming a property ( None is not valid here). The effect should be as if the owner had received a sequence of SelectionRequest events (one for each atom pair) except that:

  • The owner should reply with a SelectionNotify only when all the requested conversions have been performed.
  • If the owner fails to convert the target named by an atom in the MULTIPLE property, it should replace that atom in the property with None .

Convention

The entries in a MULTIPLE property must be processed in the order they appear in the property. For further information, see section 2.6.3.

The requestor should delete each individual property when it has copied the data from that conversion, and the property specified in the MULTIPLE request when it has copied all the data.

The requests are otherwise to be processed independently, and they should succeed or fail independently. The MULTIPLE target is an optimization that reduces the amount of protocol traffic between the owner and the requestor; it is not a transaction mechanism. For example, a client may issue a MULTIPLE request with two targets: a data target and the DELETE target. The DELETE target will still be processed even if the conversion of the data target fails.

• TIMESTAMP - To avoid some race conditions, it is important that requestors be able to discover the timestamp the owner used to acquire ownership. Until and unless the protocol is changed so that a GetSelectionOwner request returns the timestamp used to acquire ownership, selection owners must support conversion to TIMESTAMP, returning the timestamp they used to obtain the selection.

2.6.3. Selection Targets with Side Effects

In general, targets with side effects will return no information, that is, they will return a zero-length property of type NULL. (Type NULL means the result of InternAtom on the string "NULL", not the value zero.) In all cases, the requested side effect must be performed before the conversion is accepted. If the requested side effect cannot be performed, the corresponding conversion request must be refused.

Conventions

1. Targets with side effects should return no information (that is, they should have a zero-length property of type NULL).
2. The side effect of a target must be performed before the conversion is accepted.
3. If the side effect of a target cannot be performed, the corresponding conversion request must be refused.

Problem

The need to delay responding to the ConvertSelection request until a further conversion has succeeded poses problems for the Intrinsics interface that need to be addressed.

These side effect targets are used to implement operations such as "exchange PRIMARY and SECONDARY selections."

2.6.3.1. DELETE

2.6.3.2. INSERT_SELECTION

2.6.3.3. INSERT_PROPERTY

2.7. Use of Selection Properties

The selection owner always chooses the type of the property in the selection data transfer. Some types have special semantics assigned by convention, and these are reviewed in the following sections.

In all cases, a request for conversion to a target should return either a property of one of the types listed in the previous table for that target or a property of type INCR and then a property of one of the listed types.

Certain selection properties may contain resource IDs. The selection owner should ensure that the resource is not destroyed and that its contents are not changed until after the selection transfer is complete. Requestors that rely on the existence or on the proper contents of a resource must operate on the resource (for example, by copying the contents of a pixmap) before deleting the selection property.

The selection owner will return a list of zero or more items of the type indicated by the property type. In general, the number of items in the list will correspond to the number of disjoint parts of the selection. Some targets (for example, side-effect targets) will be of length zero irrespective of the number of disjoint selection parts. In the case of fixed-size items, the requestor may determine the number of items by the property size. Selection property types are listed in the table below. For variable-length items such as text, the separators are also listed.

Type Atom	Format	Separator
APPLE_PICT	8	Self-sizing
ATOM	32	Fixed-size
ATOM_PAIR	32	Fixed-size
BITMAP	32	Fixed-size
C_STRING	8	Zero
COLORMAP	32	Fixed-size
COMPOUND_TEXT	8	Zero
DRAWABLE	32	Fixed-size
INCR	32	Fixed-size
INTEGER	32	Fixed-size
PIXEL	32	Fixed-size
PIXMAP	32	Fixed-size
SPAN	32	Fixed-size
STRING	8	Zero
WINDOW	32	Fixed-size

It is expected that this table will grow over time.

2.7.1. TEXT Properties

The atom TEXT is a polymorphic target. Requesting conversion into TEXT will convert into whatever encoding is convenient for the owner. The encoding chosen will be indicated by the type of the property returned. TEXT is not defined as a type; it will never be the returned type from a selection conversion request.

If the requestor wants the owner to return the contents of the selection in a specific encoding, it should request conversion into the name of that encoding.

In the table in section 2.6.2, the word TEXT (in the Type column) is used to indicate one of the registered encoding names. The type would not actually be TEXT; it would be STRING or some other ATOM naming the encoding chosen by the owner.

STRING as a type or a target specifies the ISO Latin-1 character set plus the control characters TAB (octal 11) and NEWLINE (octal 12). The spacing interpretation of TAB is context dependent. Other ASCII control characters are explicitly not included in STRING at the present time.

COMPOUND_TEXT as a type or a target specifies the Compound Text interchange format; see the Compound Text Encoding.

There are some text objects where the source or intended user, as the case may be, does not have a specific character set for the text, but instead merely requires a zero-terminated sequence of bytes with no other restriction; no element of the selection mechanism may assume that any byte value is forbidden or that any two differing sequences are equivalent.⁸ For these objects, the type C_STRING should be used.

Rationale

An example of the need for C_STRING is to transmit the names of files; many operating systems do not interpret filenames as having a character set. For example, the same character string uses a different sequence of bytes in ASCII and EBCDIC, and so most operating systems see these as different filenames, and offer no way to treat them as the same. Thus no character-set based property type is suitable.

Type STRING, COMPOUND_TEXT, and C_STRING properties will consist of a list of elements separated by null characters; other encodings will need to specify an appropriate list format.

2.7.2. INCR Properties

The selection requestor starts the transfer process by deleting the (type==INCR) property forming the reply to the selection.

The selection owner then:

• Appends the data in suitable-size chunks to the same property on the same window as the selection reply with a type corresponding to the actual type of the converted selection. The size should be less than the maximum-request-size in the connection handshake.
• Waits between each append for a PropertyNotify (state==Deleted) event that shows that the requestor has read the data. The reason for doing this is to limit the consumption of space in the server.
• Waits (after the entire data has been transferred to the server) until a PropertyNotify (state==Deleted) event that shows that the data has been read by the requestor and then writes zero-length data to the property.

• Waits for the SelectionNotify event.
• Loops:
  • Retrieving data using GetProperty with the delete argument True .
  • Waiting for a PropertyNotify with the state argument NewValue .
• Waits until the property named by the PropertyNotify event is zero-length.
• Deletes the zero-length property.

2.7.3. DRAWABLE Properties

• Foreground pixel
• Background pixel
• Colormap ID

• FOREGROUND returns a PIXEL value.
• BACKGROUND returns a PIXEL value.
• COLORMAP returns a colormap ID.

2.7.4. SPAN Properties

2.8. Manager Selections

The manager may support conversion of various targets for that selection. Managers are encouraged to use this technique as the primary means by which clients interact with the managed resource. Note that the conventions for interacting with the window manager predate this section; as a result many interactions with the window manager use other techniques.

Before a manager takes ownership of a manager selection, it should use the GetSelectionOwner request to check whether the selection is already owned by another client, and where appropriate, it should ask the user if the new manager should replace the old one. If so, it may then take ownership of the selection. Managers should acquire the selection using a window created expressly for this purpose. Managers must conform to the rules for selection owners described in sections 2.1 and 2.2, and they must also support the required targets listed in section 2.6.2.

If a manager loses ownership of a manager selection, this means that a new manager is taking over its responsibilities. The old manager must release all resources it has managed, and must then destroy the window that owned the selection. For example, a window manager losing ownership of WM_S2 must deselect from SubstructureRedirect on the root window of screen 2 before destroying the window that owned WM_S2.

When the new manager notices that the window owning the selection has been destroyed, it knows that it can successfully proceed to control the resource it is planning to manage. If the old manager does not destroy the window within a reasonable time, the new manager should check with the user before destroying the window itself or killing the old manager.

If a manager wants to give up, on its own, management of a shared resource controlled by a selection, it must do so by releasing the resources it is managing, and then by destroying the window that owns the selection. It should not first disown the selection, since this introduces a race condition.

Clients who are interesting in knowing when the owner of a manager selection is no longer managing the corresponding shared resource should select for StructureNotify on the window owning the selection so they can be notified when the window is destroyed. Clients are warned that after doing a GetSelectionOwner and selecting for StructureNotify , they should do a GetSelectionOwner again to ensure that the owner did not change after initially getting the selection owner and before selecting for StructureNotify .

Immediately after a manager successfully acquires ownership of a manager selection, it should announce its arrival by sending a ClientMessage event. This event should be sent using the SendEvent protocol request with the following arguments:

Argument	Value
destination:	the root window of screen 0, or the root manager is managing a screen-specific resource
propagate:	False
event-mask:	StructureNotify
event:	ClientMessage
type:	MANAGER
format:	32
data[0]:10	timestamp
data[1]:	manager selection atom
data[2]:	the window owning the selection
data[3]:	manager-selection-specific data
data[4]:	manager-selection-specific data

Clients that wish to know when a specific manager has started should select for StructureNotify on the appropriate root window, and should watch for the appropriate MANAGER ClientMessage .