Selections

Name

Selections -- functions for transfering data via the X selection mechanism.

Synopsis


#include <gdk/gdk.h>


typedef     GdkSelection;
typedef     GdkSelectionType;
typedef     GdkTarget;
#define     GDK_SELECTION_PRIMARY
#define     GDK_SELECTION_SECONDARY
#define     GDK_SELECTION_CLIPBOARD
#define     GDK_TARGET_BITMAP
#define     GDK_TARGET_COLORMAP
#define     GDK_TARGET_DRAWABLE
#define     GDK_TARGET_PIXMAP
#define     GDK_TARGET_STRING
#define     GDK_SELECTION_TYPE_ATOM
#define     GDK_SELECTION_TYPE_BITMAP
#define     GDK_SELECTION_TYPE_COLORMAP
#define     GDK_SELECTION_TYPE_DRAWABLE
#define     GDK_SELECTION_TYPE_INTEGER
#define     GDK_SELECTION_TYPE_PIXMAP
#define     GDK_SELECTION_TYPE_WINDOW
#define     GDK_SELECTION_TYPE_STRING
gboolean    gdk_selection_owner_set         (GdkWindow *owner,
                                             GdkAtom selection,
                                             guint32 time,
                                             gboolean send_event);
GdkWindow*  gdk_selection_owner_get         (GdkAtom selection);
void        gdk_selection_convert           (GdkWindow *requestor,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             guint32 time);
gboolean    gdk_selection_property_get      (GdkWindow *requestor,
                                             guchar **data,
                                             GdkAtom *prop_type,
                                             gint *prop_format);
void        gdk_selection_send_notify       (guint32 requestor,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             GdkAtom property,
                                             guint32 time);

Description

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 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).

Details

GdkSelection

typedef GdkAtom GdkSelection;

Warning

GdkSelection is deprecated and should not be used in newly-written code.

The GdkSelection enumeration contains predefined atom values for several common selections.


GdkSelectionType

typedef GdkAtom GdkSelectionType;

Warning

GdkSelectionType is deprecated and should not be used in newly-written code.

The GdkSelectionType enumeration contains predefined atom values used to represent the types of data transferred in response to a request for a target. See the ICCCM for details about what data should be transferred for each of these types. Other atoms can be used, and the recommended practice for GTK+ is to to use mime types for this purpose. However, supporting these types may be useful for compatibility with older programs.


GdkTarget

typedef GdkAtom GdkTarget;

Warning

GdkTarget is deprecated and should not be used in newly-written code.

The GdkTarget enumeration contains predefined atom values which are used to describe possible targets for a selection. Other atoms can be used, and the recommended practice for GTK+ is to to use mime types for this purpose. However, supporting these types may be useful for compatibility with older programs.


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.


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.


gdk_selection_owner_get ()

GdkWindow*  gdk_selection_owner_get         (GdkAtom selection);

Determines the owner of the given selection.


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 ()

gboolean    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().


gdk_selection_send_notify ()

void        gdk_selection_send_notify       (guint32 requestor,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             GdkAtom property,
                                             guint32 time);

Sends a response to SelectionRequest event.