Description
GDK’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 GdkAtom. 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).
Note that although much of the selection API design is based on that of X,
it will work on other GDK backends too.
Functions
gdk_selection_owner_set ()
gboolean
gdk_selection_owner_set (GdkWindow *owner,
GdkAtom selection,
guint32 time_,
gboolean send_event);
Sets the owner of the given selection.
Returns
TRUE if the selection owner was successfully
changed to owner
, otherwise FALSE.
gdk_selection_owner_set_for_display ()
gboolean
gdk_selection_owner_set_for_display (GdkDisplay *display,
GdkWindow *owner,
GdkAtom selection,
guint32 time_,
gboolean send_event);
Sets the GdkWindow owner
as the current owner of the selection selection
.
Returns
TRUE if the selection owner was successfully changed to owner,
otherwise FALSE.
Since: 2.2
gdk_selection_owner_get ()
GdkWindow *
gdk_selection_owner_get (GdkAtom selection);
Determines the owner of the given selection.
Returns
if there is a selection owner
for this window, and it is a window known to the current process,
the GdkWindow 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]
gdk_selection_owner_get_for_display ()
GdkWindow *
gdk_selection_owner_get_for_display (GdkDisplay *display,
GdkAtom 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.
Returns
if there is a selection owner
for this window, and it is a window known to the current
process, the GdkWindow that owns the selection, otherwise
NULL.
[nullable][transfer none]
Since: 2.2
gdk_selection_convert ()
void
gdk_selection_convert (GdkWindow *requestor,
GdkAtom selection,
GdkAtom target,
guint32 time_);
Retrieves the contents of a selection in a given
form.
gdk_selection_property_get ()
gint
gdk_selection_property_get (GdkWindow *requestor,
guchar **data,
GdkAtom *prop_type,
gint *prop_format);
Retrieves selection data that was stored by the selection
data in response to a call to gdk_selection_convert(). This function
will not be used by applications, who should use the GtkClipboard
API instead.
[skip]
Returns
the length of the retrieved data.
gdk_selection_send_notify ()
void
gdk_selection_send_notify (GdkWindow *requestor,
GdkAtom selection,
GdkAtom target,
GdkAtom property,
guint32 time_);
Sends a response to SelectionRequest event.
gdk_selection_send_notify_for_display ()
void
gdk_selection_send_notify_for_display (GdkDisplay *display,
GdkWindow *requestor,
GdkAtom selection,
GdkAtom target,
GdkAtom property,
guint32 time_);
Send a response to SelectionRequest event.
Since: 2.2
Types and Values
GDK_SELECTION_PRIMARY
#define GDK_SELECTION_PRIMARY _GDK_MAKE_ATOM (1)
A GdkAtom representing the PRIMARY selection.
GDK_SELECTION_SECONDARY
#define GDK_SELECTION_SECONDARY _GDK_MAKE_ATOM (2)
A GdkAtom representing the SECONDARY selection.
GDK_SELECTION_CLIPBOARD
#define GDK_SELECTION_CLIPBOARD _GDK_MAKE_ATOM (69)
A GdkAtom representing the CLIPBOARD selection.
GDK_TARGET_BITMAP
#define GDK_TARGET_BITMAP _GDK_MAKE_ATOM (5)
A GdkAtom representing the BITMAP selection target.
GDK_TARGET_COLORMAP
#define GDK_TARGET_COLORMAP _GDK_MAKE_ATOM (7)
A GdkAtom representing the COLORMAP selection target.
GDK_TARGET_DRAWABLE
#define GDK_TARGET_DRAWABLE _GDK_MAKE_ATOM (17)
A GdkAtom representing the DRAWABLE selection target.
GDK_TARGET_PIXMAP
#define GDK_TARGET_PIXMAP _GDK_MAKE_ATOM (20)
A GdkAtom representing the PIXMAP selection target.
GDK_TARGET_STRING
#define GDK_TARGET_STRING _GDK_MAKE_ATOM (31)
A GdkAtom representing the STRING selection target.
GDK_SELECTION_TYPE_ATOM
#define GDK_SELECTION_TYPE_ATOM _GDK_MAKE_ATOM (4)
A GdkAtom representing the ATOM selection type.
GDK_SELECTION_TYPE_BITMAP
#define GDK_SELECTION_TYPE_BITMAP _GDK_MAKE_ATOM (5)
A GdkAtom representing the BITMAP selection type.
GDK_SELECTION_TYPE_COLORMAP
#define GDK_SELECTION_TYPE_COLORMAP _GDK_MAKE_ATOM (7)
A GdkAtom representing the COLORMAP selection type.
GDK_SELECTION_TYPE_DRAWABLE
#define GDK_SELECTION_TYPE_DRAWABLE _GDK_MAKE_ATOM (17)
A GdkAtom representing the DRAWABLE selection type.
GDK_SELECTION_TYPE_INTEGER
#define GDK_SELECTION_TYPE_INTEGER _GDK_MAKE_ATOM (19)
A GdkAtom representing the INTEGER selection type.
GDK_SELECTION_TYPE_PIXMAP
#define GDK_SELECTION_TYPE_PIXMAP _GDK_MAKE_ATOM (20)
A GdkAtom representing the PIXMAP selection type.
GDK_SELECTION_TYPE_WINDOW
#define GDK_SELECTION_TYPE_WINDOW _GDK_MAKE_ATOM (33)
A GdkAtom representing the WINDOW selection type.
GDK_SELECTION_TYPE_STRING
#define GDK_SELECTION_TYPE_STRING _GDK_MAKE_ATOM (31)
A GdkAtom representing the STRING selection type.