|  |  |  | GDK Reference Manual |  | 
|---|
| SelectionsSelections — Functions for transfering data via the X selection mechanism | 
#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); gboolean gdk_selection_owner_set_for_display (GdkDisplay *display, GdkWindow *owner, GdkAtom selection, guint32 time_, gboolean send_event); GdkWindow* gdk_selection_owner_get (GdkAtom selection); GdkWindow* gdk_selection_owner_get_for_display (GdkDisplay *display, 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_); void gdk_selection_send_notify_for_display (GdkDisplay *display, guint32 requestor, GdkAtom selection, GdkAtom target, GdkAtom property, guint32 time_);
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).
typedef GdkAtom GdkSelection;
GdkSelection is deprecated and should not be used in newly-written code.
The GdkSelection enumeration contains predefined atom values for several common selections.
typedef GdkAtom GdkSelectionType;
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.
typedef GdkAtom GdkTarget;
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.
#define GDK_SELECTION_PRIMARY _GDK_MAKE_ATOM (1)
A GdkAtom representing the PRIMARY selection.
#define GDK_SELECTION_SECONDARY _GDK_MAKE_ATOM (2)
A GdkAtom representing the SECONDARY selection.
#define GDK_SELECTION_CLIPBOARD _GDK_MAKE_ATOM (69)
A GdkAtom representing the CLIPBOARD selection.
#define GDK_TARGET_BITMAP _GDK_MAKE_ATOM (5)
A GdkAtom representing the BITMAP selection target.
#define GDK_TARGET_COLORMAP _GDK_MAKE_ATOM (7)
A GdkAtom representing the COLORMAP selection target.
#define GDK_TARGET_DRAWABLE _GDK_MAKE_ATOM (17)
A GdkAtom representing the DRAWABLE selection target.
#define GDK_TARGET_PIXMAP _GDK_MAKE_ATOM (20)
A GdkAtom representing the PIXMAP selection target.
#define GDK_TARGET_STRING _GDK_MAKE_ATOM (31)
A GdkAtom representing the STRING selection target.
#define GDK_SELECTION_TYPE_ATOM _GDK_MAKE_ATOM (4)
A GdkAtom representing the ATOM selection type.
#define GDK_SELECTION_TYPE_BITMAP _GDK_MAKE_ATOM (5)
A GdkAtom representing the BITMAP selection type.
#define GDK_SELECTION_TYPE_COLORMAP _GDK_MAKE_ATOM (7)
A GdkAtom representing the COLORMAP selection type.
#define GDK_SELECTION_TYPE_DRAWABLE _GDK_MAKE_ATOM (17)
A GdkAtom representing the DRAWABLE selection type.
#define GDK_SELECTION_TYPE_INTEGER _GDK_MAKE_ATOM (19)
A GdkAtom representing the INTEGER selection type.
#define GDK_SELECTION_TYPE_PIXMAP _GDK_MAKE_ATOM (20)
A GdkAtom representing the PIXMAP selection type.
#define GDK_SELECTION_TYPE_WINDOW _GDK_MAKE_ATOM (33)
A GdkAtom representing the WINDOW selection type.
#define GDK_SELECTION_TYPE_STRING _GDK_MAKE_ATOM (31)
A GdkAtom representing the STRING selection type.
gboolean gdk_selection_owner_set (GdkWindow *owner, GdkAtom selection, guint32 time_, gboolean send_event);
Sets the owner of the given selection.
| owner: | a GdkWindow or NULLto 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 TRUE, and the new owner is different
             from the current owner, the current owner
             will be sent a SelectionClear event. | 
| Returns : | TRUEif the selection owner was successfully
          changed toowner, otherwiseFALSE. | 
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.
| display: | the GdkDisplay. | 
| owner: | a GdkWindow or NULLto 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 TRUE, and the new owner is different from the current
             owner, the current owner will be sent a SelectionClear event. | 
| Returns : | TRUEif the selection owner was successfully changed to owner,
    otherwiseFALSE. | 
Since 2.2
GdkWindow* gdk_selection_owner_get (GdkAtom selection);
Determines the owner of the given selection.
| 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 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. | 
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.
| display: | a GdkDisplay. | 
| 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 GdkWindow that owns the 
   selection, otherwise NULL. | 
Since 2.2
void gdk_selection_convert (GdkWindow *requestor, GdkAtom selection, GdkAtom target, guint32 time_);
Retrieves the contents of a selection in a given form.
| requestor: | a GdkWindow. | 
| 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. | 
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(). This function
will not be used by applications, who should use the GtkClipboard
API instead.
| requestor: | the window on which the data is stored | 
| data: | location to store a pointer to the retrieved data.
       If the retrieval failed, NULLwe be stored here, otherwise, it
       will be non-NULLand the returned data should be freed withg_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. | 
void gdk_selection_send_notify (guint32 requestor, GdkAtom selection, GdkAtom target, GdkAtom property, guint32 time_);
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_NONEto indicate that the request
           was rejected. | 
| time_: | timestamp. | 
void        gdk_selection_send_notify_for_display
                                            (GdkDisplay *display,
                                             guint32 requestor,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             GdkAtom property,
                                             guint32 time_);
Send a response to SelectionRequest event.
| display: | the GdkDisplay where requestoris 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 GDK_NONEto indicate that the request was rejected. | 
| time_: | timestamp. | 
Since 2.2
| << Key Values | Drag and Drop >> |