Selections: CDK 3 Reference Manual

Selections

Selections — Functions for transferring data between programs

Functions

gboolean	cdk_selection_owner_set ()
gboolean	cdk_selection_owner_set_for_display ()
CdkWindow *	cdk_selection_owner_get ()
CdkWindow *	cdk_selection_owner_get_for_display ()
void	cdk_selection_convert ()
gint	cdk_selection_property_get ()
void	cdk_selection_send_notify ()
void	cdk_selection_send_notify_for_display ()

Types and Values

#define	CDK_SELECTION_PRIMARY
#define	CDK_SELECTION_SECONDARY
#define	CDK_SELECTION_CLIPBOARD
#define	CDK_TARGET_BITMAP
#define	CDK_TARGET_COLORMAP
#define	CDK_TARGET_DRAWABLE
#define	CDK_TARGET_PIXMAP
#define	CDK_TARGET_STRING
#define	CDK_SELECTION_TYPE_ATOM
#define	CDK_SELECTION_TYPE_BITMAP
#define	CDK_SELECTION_TYPE_COLORMAP
#define	CDK_SELECTION_TYPE_DRAWABLE
#define	CDK_SELECTION_TYPE_INTEGER
#define	CDK_SELECTION_TYPE_PIXMAP
#define	CDK_SELECTION_TYPE_WINDOW
#define	CDK_SELECTION_TYPE_STRING

Includes

#include <cdk/cdk.h>

Description

CDK’s selection functions, based on the X selection mechanism, provide 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 CdkAtom. 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. CTK+ contains such an implementation in the functions in ctkselection.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).

Note that although much of the selection API design is based on that of X, it will work on other CDK backends too.

Functions

cdk_selection_owner_set ()

gboolean
cdk_selection_owner_set (CdkWindow *owner,
                         CdkAtom selection,
                         guint32 time_,
                         gboolean send_event);

Sets the owner of the given selection.

Parameters

owner	a CdkWindow or `NULL` to indicate that the the owner for the given should be unset.	[allow-none]
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 `TRUE`, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event.

Returns

TRUE if the selection owner was successfully changed to owner , otherwise FALSE.

cdk_selection_owner_set_for_display ()

gboolean
cdk_selection_owner_set_for_display (CdkDisplay *display,
                                     CdkWindow *owner,
                                     CdkAtom selection,
                                     guint32 time_,
                                     gboolean send_event);

Sets the CdkWindow owner as the current owner of the selection selection .

Parameters

display	the CdkDisplay
owner	a CdkWindow or `NULL` to indicate that the owner for the given should be unset.	[nullable]
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 `TRUE`, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event

Returns

TRUE if the selection owner was successfully changed to owner, otherwise FALSE.

Since: 2.2

cdk_selection_owner_get ()

CdkWindow *
cdk_selection_owner_get (CdkAtom selection);

Determines the owner of the given selection.

Parameters

selection

an atom indentifying a selection.

Returns

if there is a selection owner for this window, and it is a window known to the current process, the CdkWindow that owns the selection, otherwise NULL. 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.

[nullable][transfer none]

cdk_selection_owner_get_for_display ()

CdkWindow *
cdk_selection_owner_get_for_display (CdkDisplay *display,
                                     CdkAtom selection);

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.

Parameters

display	a CdkDisplay
selection	an atom indentifying a selection

Returns

if there is a selection owner for this window, and it is a window known to the current process, the CdkWindow that owns the selection, otherwise NULL.

[nullable][transfer none]

Since: 2.2

cdk_selection_convert ()

void
cdk_selection_convert (CdkWindow *requestor,
                       CdkAtom selection,
                       CdkAtom target,
                       guint32 time_);

Retrieves the contents of a selection in a given form.

Parameters

requestor	a CdkWindow.
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.

cdk_selection_property_get ()

gint
cdk_selection_property_get (CdkWindow *requestor,
                            guchar **data,
                            CdkAtom *prop_type,
                            gint *prop_format);

Retrieves selection data that was stored by the selection data in response to a call to cdk_selection_convert(). This function will not be used by applications, who should use the CtkClipboard API instead.

[skip]

Parameters

requestor	the window on which the data is stored
data	location to store a pointer to the retrieved data. If the retrieval failed, `NULL` we be stored here, otherwise, it will be non-`NULL` and the returned data should be freed with `g_free()` when you are finished using it. The length of the allocated memory is one more than the length of the returned data, and the final byte will always be zero, to ensure nul-termination of strings
prop_type	location to store the type of the property
prop_format	location to store the format of the property

Returns

the length of the retrieved data.

cdk_selection_send_notify ()

void
cdk_selection_send_notify (CdkWindow *requestor,
                           CdkAtom selection,
                           CdkAtom target,
                           CdkAtom property,
                           guint32 time_);

Sends a response to SelectionRequest event.

Parameters

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 `CDK_NONE` to indicate that the request was rejected.
time_	timestamp.

cdk_selection_send_notify_for_display ()

void
cdk_selection_send_notify_for_display (CdkDisplay *display,
                                       CdkWindow *requestor,
                                       CdkAtom selection,
                                       CdkAtom target,
                                       CdkAtom property,
                                       guint32 time_);

Send a response to SelectionRequest event.

Parameters

display	the CdkDisplay where `requestor` is realized
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 `CDK_NONE` to indicate that the request was rejected
time_	timestamp

Since: 2.2

Types and Values

CDK_SELECTION_PRIMARY

#define CDK_SELECTION_PRIMARY 		_CDK_MAKE_ATOM (1)

A CdkAtom representing the PRIMARY selection.

CDK_SELECTION_SECONDARY

#define CDK_SELECTION_SECONDARY 	_CDK_MAKE_ATOM (2)

A CdkAtom representing the SECONDARY selection.

CDK_SELECTION_CLIPBOARD

#define CDK_SELECTION_CLIPBOARD 	_CDK_MAKE_ATOM (69)

A CdkAtom representing the CLIPBOARD selection.

CDK_TARGET_BITMAP

#define CDK_TARGET_BITMAP 		_CDK_MAKE_ATOM (5)

A CdkAtom representing the BITMAP selection target.

CDK_TARGET_COLORMAP

#define CDK_TARGET_COLORMAP 		_CDK_MAKE_ATOM (7)

A CdkAtom representing the COLORMAP selection target.

CDK_TARGET_DRAWABLE

#define CDK_TARGET_DRAWABLE 		_CDK_MAKE_ATOM (17)

A CdkAtom representing the DRAWABLE selection target.

CDK_TARGET_PIXMAP

#define CDK_TARGET_PIXMAP 		_CDK_MAKE_ATOM (20)

A CdkAtom representing the PIXMAP selection target.

CDK_TARGET_STRING

#define CDK_TARGET_STRING 		_CDK_MAKE_ATOM (31)

A CdkAtom representing the STRING selection target.

CDK_SELECTION_TYPE_ATOM

#define CDK_SELECTION_TYPE_ATOM 	_CDK_MAKE_ATOM (4)

A CdkAtom representing the ATOM selection type.

CDK_SELECTION_TYPE_BITMAP

#define CDK_SELECTION_TYPE_BITMAP 	_CDK_MAKE_ATOM (5)

A CdkAtom representing the BITMAP selection type.

CDK_SELECTION_TYPE_COLORMAP

#define CDK_SELECTION_TYPE_COLORMAP 	_CDK_MAKE_ATOM (7)

A CdkAtom representing the COLORMAP selection type.

CDK_SELECTION_TYPE_DRAWABLE

#define CDK_SELECTION_TYPE_DRAWABLE 	_CDK_MAKE_ATOM (17)

A CdkAtom representing the DRAWABLE selection type.

CDK_SELECTION_TYPE_INTEGER

#define CDK_SELECTION_TYPE_INTEGER 	_CDK_MAKE_ATOM (19)

A CdkAtom representing the INTEGER selection type.

CDK_SELECTION_TYPE_PIXMAP

#define CDK_SELECTION_TYPE_PIXMAP 	_CDK_MAKE_ATOM (20)

A CdkAtom representing the PIXMAP selection type.

CDK_SELECTION_TYPE_WINDOW

#define CDK_SELECTION_TYPE_WINDOW 	_CDK_MAKE_ATOM (33)

A CdkAtom representing the WINDOW selection type.

CDK_SELECTION_TYPE_STRING

#define CDK_SELECTION_TYPE_STRING 	_CDK_MAKE_ATOM (31)

A CdkAtom representing the STRING selection type.