Next: , Previous: Key Values, Up: Top


21 Selections

Functions for transfering data via the X selection mechanism

21.1 Overview

The X selection mechanism provides a way to transfer arbitrary chunks of data between programs. A selection is a essentially a named clipboard, identified by a string interned as a <gdk-atom>. By claiming ownership of a selection, an application indicates that it will be responsible for supplying its contents. The most common selections are ‘PRIMARY’ and ‘CLIPBOARD’.

The contents of a selection can be represented in a number of formats, called targets. Each target is identified by an atom. A list of all possible targets supported by the selection owner can be retrieved by requesting the special target ‘TARGETS’. When a selection is retrieved, the data is accompanied by a type (an atom), and a format (an integer, representing the number of bits per item). See Properties and Atoms for more information.

The functions in this section only contain the lowlevel parts of the selection protocol. A considerably more complicated implementation is needed on top of this. GTK+ contains such an implementation in the functions in ‘gtkselection.h’ and programmers should use those functions instead of the ones presented here. If you plan to implement selection handling directly on top of the functions here, you should refer to the X Inter-client Communication Conventions Manual (ICCCM).

21.2 Usage

— Function: gdk-selection-owner-set (owner <gdk-window>) (selection <gdk-atom>) (time_ unsigned-int32) (send_event bool) ⇒  (ret bool)

Sets the owner of the given selection.

owner
a <gdk-window> or ‘#f’ to indicate that the the owner for the given should be unset.
selection
an atom identifying a selection.
time
timestamp to use when setting the selection. If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored.
send-event
if ‘#t’, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event.
ret
#t’ if the selection owner was successfully changed to owner, otherwise ‘#f’.
— Function: gdk-selection-owner-set-for-display (display <gdk-display>) (owner <gdk-window>) (selection <gdk-atom>) (time_ unsigned-int32) (send_event bool) ⇒  (ret bool)

Sets the <gdk-window>owner as the current owner of the selection selection.

display
the <gdk-display>.
owner
a <gdk-window> or ‘#f’ to indicate that the owner for the given should be unset.
selection
an atom identifying a selection.
time
timestamp to use when setting the selection. If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored.
send-event
if ‘#t’, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event.
ret
#t’ if the selection owner was successfully changed to owner, otherwise ‘#f’.

Since 2.2

— Function: gdk-selection-owner-get (selection <gdk-atom>) ⇒  (ret <gdk-window>)

Determines the owner of the given selection.

selection
an atom indentifying a selection.
ret
if there is a selection owner for this window, and it is a window known to the current process, the <gdk-window> that owns the selection, otherwise ‘#f’. Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call.
— Function: gdk-selection-owner-get-for-display (display <gdk-display>) (selection <gdk-atom>) ⇒  (ret <gdk-window>)

Determine the owner of the given selection.

Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call.

display
a <gdk-display>.
selection
an atom indentifying a selection.
ret
if there is a selection owner for this window, and it is a window known to the current process, the <gdk-window> that owns the selection, otherwise ‘#f’.

Since 2.2

— Function: gdk-selection-convert (requestor <gdk-window>) (selection <gdk-atom>) (target <gdk-atom>) (time_ unsigned-int32)

Retrieves the contents of a selection in a given form.

requestor
a <gdk-window>.
selection
an atom identifying the selection to get the contents of.
target
the form in which to retrieve the selection.
time
the timestamp to use when retrieving the selection. The selection owner may refuse the request if it did not own the selection at the time indicated by the timestamp.
— Function: gdk-selection-send-notify (requestor unsigned-int32) (selection <gdk-atom>) (target <gdk-atom>) (property <gdk-atom>) (time_ unsigned-int32)

Sends a response to SelectionRequest event.

requestor
window to which to deliver response.
selection
selection that was requested.
target
target that was selected.
property
property in which the selection owner stored the data, or ‘GDK_NONE’ to indicate that the request was rejected.
time
timestamp.