Selections: GTK+ 2 Reference Manual

## Selections Selections — Functions for handling inter-process communication via selections |

## Functions

GtkTargetList * | gtk_target_list_new ()
GtkTargetList * | gtk_target_list_ref ()
void | gtk_target_list_unref ()
void | gtk_target_list_add ()
void | gtk_target_list_add_table ()
void | gtk_target_list_add_text_targets ()
void | gtk_target_list_add_image_targets ()
void | gtk_target_list_add_uri_targets ()
void | gtk_target_list_add_rich_text_targets ()
void | gtk_target_list_remove ()
gboolean | gtk_target_list_find ()
void | gtk_target_table_free ()
GtkTargetEntry * | gtk_target_table_new_from_list ()
gboolean | gtk_selection_owner_set ()
gboolean | gtk_selection_owner_set_for_display ()
void | gtk_selection_add_target ()
void | gtk_selection_add_targets ()
void | gtk_selection_clear_targets ()
gboolean | gtk_selection_convert ()
void | gtk_selection_data_set ()
gboolean | gtk_selection_data_set_text ()
guchar * | gtk_selection_data_get_text ()
gboolean | gtk_selection_data_set_pixbuf ()
GdkPixbuf * | gtk_selection_data_get_pixbuf ()
gboolean | gtk_selection_data_set_uris ()
gchar ** | gtk_selection_data_get_uris ()
gboolean | gtk_selection_data_get_targets ()
gboolean | gtk_selection_data_targets_include_image ()
gboolean | gtk_selection_data_targets_include_text ()
gboolean | gtk_selection_data_targets_include_uri ()
gboolean | gtk_selection_data_targets_include_rich_text ()
GdkAtom | gtk_selection_data_get_selection ()
const guchar * | gtk_selection_data_get_data ()
gint | gtk_selection_data_get_length ()
GdkAtom | gtk_selection_data_get_data_type ()
GdkDisplay * | gtk_selection_data_get_display ()
gint | gtk_selection_data_get_format ()
GdkAtom | gtk_selection_data_get_target ()
gboolean | gtk_targets_include_image ()
gboolean | gtk_targets_include_text ()
gboolean | gtk_targets_include_uri ()
gboolean | gtk_targets_include_rich_text ()
void | gtk_selection_remove_all ()
gboolean | gtk_selection_clear ()
GtkSelectionData * | gtk_selection_data_copy ()
void | gtk_selection_data_free ()

## Types and Values

struct | GtkTargetEntry
struct | GtkTargetList
struct | GtkTargetPair

## Object Hierarchy

        GBoxed
        ╰── GtkTargetList

## Includes

    #include <gtk/gtk.h>

## Description

The selection mechanism provides the basis for different types of communication between processes. In particular, drag and drop and GtkClipboard work via selections. You will very seldom or never need to use most of the functions in this section directly; GtkClipboard provides a nicer interface to the same functionality.

Some of the datatypes defined this section are used in the GtkClipboard and drag-and-drop API's as well. The GtkTargetEntry structure and GtkTargetList objects represent lists of data types that are supported when sending or receiving data. The GtkSelectionData object is used to store a chunk of data along with the data type and other associated information.

## Functions

### gtk_target_list_new ()

    GtkTargetList *
    gtk_target_list_new (const GtkTargetEntry *targets,
                         guint ntargets);

Creates a new GtkTargetList from an array of GtkTargetEntry.

#### Parameters

targets | Pointer to an array of GtkTargetEntry. | [array length=ntargets]
ntargets | number of entries in `targets` . |

#### Returns

the new GtkTargetList.

[transfer full]

### gtk_target_list_ref ()

    GtkTargetList *
    gtk_target_list_ref (GtkTargetList *list);

Increases the reference count of a GtkTargetList by one.

#### Parameters

list | a GtkTargetList |

#### Returns

the passed in GtkTargetList.

### gtk_target_list_unref ()

    void
    gtk_target_list_unref (GtkTargetList *list);

Decreases the reference count of a GtkTargetList by one. If the resulting reference count is zero, frees the list.

#### Parameters

list | a GtkTargetList |

### gtk_target_list_add ()

    void
    gtk_target_list_add (GtkTargetList *list,
                         GdkAtom target,
                         guint flags,
                         guint info);

Appends another target to a GtkTargetList.

#### Parameters

list | a GtkTargetList |
target | the interned atom representing the target |
flags | the flags for this target |
info | an ID that will be passed back to the application |

### gtk_target_list_add_table ()

    void
    gtk_target_list_add_table (GtkTargetList *list,
                               const GtkTargetEntry *targets,
                               guint ntargets);

Prepends a table of GtkTargetEntry to a target list.

#### Parameters

list | a GtkTargetList |
targets | the table of GtkTargetEntry. | [array length=ntargets]
ntargets | number of targets in the table |

### gtk_target_list_add_text_targets ()

    void
    gtk_target_list_add_text_targets (GtkTargetList *list,
                                      guint info);

Appends the text targets supported by GtkSelection to the target list. All targets are added with the same `info` .

#### Parameters

list | a GtkTargetList |
info | an ID that will be passed back to the application |

Since: 2.6

### gtk_target_list_add_image_targets ()

    void
    gtk_target_list_add_image_targets (GtkTargetList *list,
                                       guint info,
                                       gboolean writable);

Appends the image targets supported by GtkSelection to the target list. All targets are added with the same `info` .

#### Parameters

list | a GtkTargetList |
info | an ID that will be passed back to the application |
writable | whether to add only targets for which GTK+ knows how to convert a pixbuf into the format |

Since: 2.6

### gtk_target_list_add_uri_targets ()

    void
    gtk_target_list_add_uri_targets (GtkTargetList *list,
                                     guint info);

Appends the URI targets supported by GtkSelection to the target list. All targets are added with the same `info` .

#### Parameters

list | a GtkTargetList |
info | an ID that will be passed back to the application |

Since: 2.6

### gtk_target_list_add_rich_text_targets ()

    void
    gtk_target_list_add_rich_text_targets (GtkTargetList *list,
                                           guint info,
                                           gboolean deserializable,
                                           GtkTextBuffer *buffer);

Appends the rich text targets registered with `gtk_text_buffer_register_serialize_format()` or `gtk_text_buffer_register_deserialize_format()` to the target list. All targets are added with the same `info` .

#### Parameters

list | a GtkTargetList |
info | an ID that will be passed back to the application |
deserializable | if `TRUE`, then deserializable rich text formats will be added, serializable formats otherwise. |
buffer | a GtkTextBuffer. |

Since: 2.10

### gtk_target_list_remove ()

    void
    gtk_target_list_remove (GtkTargetList *list,
                            GdkAtom target);

Removes a target from a target list.

#### Parameters

list | a GtkTargetList |
target | the interned atom representing the target |

### gtk_target_list_find ()

    gboolean
    gtk_target_list_find (GtkTargetList *list,
                          GdkAtom target,
                          guint *info);

Looks up a given target in a GtkTargetList.

#### Parameters

list | a GtkTargetList |
target | an interned atom representing the target to search for |
info | a pointer to the location to store application info for target, or `NULL` |

#### Returns

`TRUE` if the target was found, otherwise `FALSE`

### gtk_target_table_free ()

    void
    gtk_target_table_free (GtkTargetEntry *targets,
                           gint n_targets);

This function frees a target table as returned by `gtk_target_table_new_from_list()`

#### Parameters

targets | a GtkTargetEntry array. | [array length=n_targets]
n_targets | the number of entries in the array |

Since: 2.10

### gtk_target_table_new_from_list ()

    GtkTargetEntry *
    gtk_target_table_new_from_list (GtkTargetList *list,
                                    gint *n_targets);

This function creates an GtkTargetEntry array that contains the same targets as the passed `list`. The returned table is newly allocated and should be freed using `gtk_target_table_free()` when no longer needed.

#### Parameters

list | a GtkTargetList |
n_targets | return location for the number ot targets in the table |

#### Returns

the new table.

[array length=n_targets][transfer full]

Since: 2.10

### gtk_selection_owner_set ()

    gboolean
    gtk_selection_owner_set (GtkWidget *widget,
                             GdkAtom selection,
                             guint32 time_);

Claims ownership of a given selection for a particular widget, or, if `widget` is `NULL`, release ownership of the selection.

#### Parameters

widget | a GtkWidget, or `NULL`. | [allow-none]
selection | an interned atom representing the selection to claim |
time_ | timestamp with which to claim the selection |

#### Returns

`TRUE` if the operation succeeded

### gtk_selection_owner_set_for_display ()

    gboolean
    gtk_selection_owner_set_for_display (GdkDisplay *display,
                                         GtkWidget *widget,
                                         GdkAtom selection,
                                         guint32 time_);

Claim ownership of a given selection for a particular widget, or, if `widget` is `NULL`, release ownership of the selection.

#### Parameters

display | the Gdkdisplay where the selection is set |
widget | new selection owner (a GdkWidget), or `NULL`. | [allow-none]
selection | an interned atom representing the selection to claim. |
time_ | timestamp with which to claim the selection |

#### Returns

TRUE if the operation succeeded

Since: 2.2

### gtk_selection_add_target ()

    void
    gtk_selection_add_target (GtkWidget *widget,
                              GdkAtom selection,
                              GdkAtom target,
                              guint info);

Appends a specified target to the list of supported targets for a given widget and selection.

#### Parameters

widget | a GtkTarget |
selection | the selection |
target | target to add. |
info | A unsigned integer which will be passed back to the application. |

### gtk_selection_add_targets ()

    void
    gtk_selection_add_targets (GtkWidget *widget,
                               GdkAtom selection,
                               const GtkTargetEntry *targets,
                               guint ntargets);

Prepends a table of targets to the list of supported targets for a given widget and selection.

#### Parameters

widget | a GtkWidget |
selection | the selection |
targets | a table of targets to add. | [array length=ntargets]
ntargets | number of entries in `targets` |

### gtk_selection_clear_targets ()

    void
    gtk_selection_clear_targets (GtkWidget *widget,
                                 GdkAtom selection);

Remove all targets registered for the given selection for the widget.

#### Parameters

widget | a GtkWidget |
selection | an atom representing a selection |

### gtk_selection_convert ()

    gboolean
    gtk_selection_convert (GtkWidget *widget,
                           GdkAtom selection,
                           GdkAtom target,
                           guint32 time_);

Requests the contents of a selection. When received, a "selection-received" signal will be generated.

#### Parameters

widget | The widget which acts as requestor |
selection | Which selection to get |
target | Form of information desired (e.g., STRING) |
time_ | Time of request (usually of triggering event) In emergency, you could use GDK_CURRENT_TIME |

#### Returns

`TRUE` if requested succeeded. `FALSE` if we could not process request. (e.g., there was already a request in process for this widget).

### gtk_selection_data_set ()

    void
    gtk_selection_data_set (GtkSelectionData *selection_data,
                            GdkAtom type,
                            gint format,
                            const guchar *data,
                            gint length);

Stores new data into a GtkSelectionData object. Should only be called from a selection handler callback. Zero-terminates the stored data.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |
type | the type of selection data |
format | format (number of bits in a unit) |
data | pointer to the data (will be copied). | [array length=length]
length | length of the data |

### gtk_selection_data_set_text ()

    gboolean
    gtk_selection_data_set_text (GtkSelectionData *selection_data,
                                 const gchar *str,
                                 gint len);

Sets the contents of the selection from a UTF-8 encoded string. The string is converted to the form determined by `selection_data->target` .

#### Parameters

selection_data | a GtkSelectionData |
str | a UTF-8 string |
len | the length of `str` , or -1 if `str` is nul-terminated. |

#### Returns

`TRUE` if the selection was successfully set, otherwise `FALSE`.

### gtk_selection_data_get_text ()

    guchar *
    gtk_selection_data_get_text (GtkSelectionData *selection_data);

Gets the contents of the selection data as a UTF-8 string.

#### Parameters

selection_data | a GtkSelectionData |

#### Returns

if the selection data contained a recognized text type and it could be converted to UTF-8, a newly allocated string containing the converted text, otherwise `NULL`. If the result is non-`NULL` it must be freed with `g_free()`.

### gtk_selection_data_set_pixbuf ()

    gboolean
    gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data,
                                   GdkPixbuf *pixbuf);

Sets the contents of the selection from a GdkPixbuf The pixbuf is converted to the form determined by `selection_data->target` .

#### Parameters

selection_data | a GtkSelectionData |
pixbuf | a GdkPixbuf |

#### Returns

`TRUE` if the selection was successfully set, otherwise `FALSE`.

Since: 2.6

### gtk_selection_data_get_pixbuf ()

    GdkPixbuf *
    gtk_selection_data_get_pixbuf (GtkSelectionData *selection_data);

Gets the contents of the selection data as a GdkPixbuf.

#### Parameters

selection_data | a GtkSelectionData |

#### Returns

if the selection data contained a recognized image type and it could be converted to a GdkPixbuf, a newly allocated pixbuf is returned, otherwise `NULL`. If the result is non-`NULL` it must be freed with `g_object_unref()`.

[transfer full]

Since: 2.6

### gtk_selection_data_set_uris ()

    gboolean
    gtk_selection_data_set_uris (GtkSelectionData *selection_data,
                                 gchar **uris);

Sets the contents of the selection from a list of URIs. The string is converted to the form determined by `selection_data->target` .

#### Parameters

selection_data | a GtkSelectionData |
uris | a `NULL`-terminated array of strings holding URIs. | [array zero-terminated=1]

#### Returns

`TRUE` if the selection was successfully set, otherwise `FALSE`.

Since: 2.6

### gtk_selection_data_get_uris ()

    gchar **
    gtk_selection_data_get_uris (GtkSelectionData *selection_data);

Gets the contents of the selection data as array of URIs.

#### Parameters

selection_data | a GtkSelectionData |

#### Returns

if the selection data contains a list of URIs, a newly allocated `NULL`-terminated string array containing the URIs, otherwise `NULL`. If the result is non-`NULL` it must be freed with `g_strfreev()`.

[array zero-terminated=1][element-type utf8][transfer full]

Since: 2.6

### gtk_selection_data_get_targets ()

    gboolean
    gtk_selection_data_get_targets (GtkSelectionData *selection_data,
                                    GdkAtom **targets,
                                    gint *n_atoms);

Gets the contents of `selection_data` as an array of targets. This can be used to interpret the results of getting the standard TARGETS target that is always supplied for any selection.

#### Parameters

selection_data | a GtkSelectionData object |
targets | location to store an array of targets. The result stored here must be freed with `g_free()`. | [out][array length=n_atoms][transfer container]
n_atoms | location to store number of items in `targets` . |

#### Returns

`TRUE` if `selection_data` contains a valid array of targets, otherwise `FALSE`.

### gtk_selection_data_targets_include_image ()

    gboolean
    gtk_selection_data_targets_include_image
                                   (GtkSelectionData *selection_data,
                                    gboolean writable);

Given a GtkSelectionData object holding a list of targets, determines if any of the targets in `targets` can be used to provide a GdkPixbuf.

#### Parameters

selection_data | a GtkSelectionData object |
writable | whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format |

#### Returns

`TRUE` if `selection_data` holds a list of targets, and a suitable target for images is included, otherwise `FALSE`.

Since: 2.6

### gtk_selection_data_targets_include_text ()

    gboolean
    gtk_selection_data_targets_include_text
                                   (GtkSelectionData *selection_data);

Given a GtkSelectionData object holding a list of targets, determines if any of the targets in `targets` can be used to provide text.

#### Parameters

selection_data | a GtkSelectionData object |

#### Returns

`TRUE` if `selection_data` holds a list of targets, and a suitable target for text is included, otherwise `FALSE`.

### gtk_selection_data_targets_include_uri ()

    gboolean
    gtk_selection_data_targets_include_uri
                                   (GtkSelectionData *selection_data);

Given a GtkSelectionData object holding a list of targets, determines if any of the targets in `targets` can be used to provide a list or URIs.

#### Parameters

selection_data | a GtkSelectionData object |

#### Returns

`TRUE` if `selection_data` holds a list of targets, and a suitable target for URI lists is included, otherwise `FALSE`.

Since: 2.10

### gtk_selection_data_targets_include_rich_text ()

    gboolean
    gtk_selection_data_targets_include_rich_text
                                   (GtkSelectionData *selection_data,
                                    GtkTextBuffer *buffer);

Given a GtkSelectionData object holding a list of targets, determines if any of the targets in `targets` can be used to provide rich text.

#### Parameters

selection_data | a GtkSelectionData object |
buffer | a GtkTextBuffer |

#### Returns

`TRUE` if `selection_data` holds a list of targets, and a suitable target for rich text is included, otherwise `FALSE`.

Since: 2.10

### gtk_selection_data_get_selection ()

    GdkAtom
    gtk_selection_data_get_selection (GtkSelectionData *selection_data);

Retrieves the selection GdkAtom of the selection data.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the selection GdkAtom of the selection data.

[transfer none]

Since: 2.16

### gtk_selection_data_get_data ()

    const guchar *
    gtk_selection_data_get_data (GtkSelectionData *selection_data);

Retrieves the raw data of the selection.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the raw data of the selection.

Since: 2.14

### gtk_selection_data_get_length ()

    gint
    gtk_selection_data_get_length (GtkSelectionData *selection_data);

Retrieves the length of the raw data of the selection.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the length of the data of the selection.

Since: 2.14

### gtk_selection_data_get_data_type ()

    GdkAtom
    gtk_selection_data_get_data_type (GtkSelectionData *selection_data);

Retrieves the data type of the selection.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the data type of the selection.

[transfer none]

Since: 2.14

### gtk_selection_data_get_display ()

    GdkDisplay *
    gtk_selection_data_get_display (GtkSelectionData *selection_data);

Retrieves the display of the selection.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the display of the selection.

[transfer none]

Since: 2.14

### gtk_selection_data_get_format ()

    gint
    gtk_selection_data_get_format (GtkSelectionData *selection_data);

Retrieves the format of the selection.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the format of the selection.

Since: 2.14

### gtk_selection_data_get_target ()

    GdkAtom
    gtk_selection_data_get_target (GtkSelectionData *selection_data);

Retrieves the target of the selection.

#### Parameters

selection_data | a pointer to a GtkSelectionData structure. |

#### Returns

the target of the selection.

[transfer none]

Since: 2.14

### gtk_targets_include_image ()

    gboolean
    gtk_targets_include_image (GdkAtom *targets,
                               gint n_targets,
                               gboolean writable);

Determines if any of the targets in `targets` can be used to provide a GdkPixbuf.

#### Parameters

targets | an array of GdkAtoms. | [array length=n_targets]
n_targets | the length of `targets` |
writable | whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format |

#### Returns

`TRUE` if `targets` include a suitable target for images, otherwise `FALSE`.

Since: 2.10

### gtk_targets_include_text ()

    gboolean
    gtk_targets_include_text (GdkAtom *targets,
                              gint n_targets);

Determines if any of the targets in `targets` can be used to provide text.

#### Parameters

targets | an array of GdkAtoms. | [array length=n_targets]
n_targets | the length of `targets` |

#### Returns

`TRUE` if `targets` include a suitable target for text, otherwise `FALSE`.

Since: 2.10

### gtk_targets_include_uri ()

    gboolean
    gtk_targets_include_uri (GdkAtom *targets,
                             gint n_targets);

Determines if any of the targets in `targets` can be used to provide an uri list.

#### Parameters

targets | an array of GdkAtoms. | [array length=n_targets]
n_targets | the length of `targets` |

#### Returns

`TRUE` if `targets` include a suitable target for uri lists, otherwise `FALSE`.

Since: 2.10

### gtk_targets_include_rich_text ()

    gboolean
    gtk_targets_include_rich_text (GdkAtom *targets,
                                   gint n_targets,
                                   GtkTextBuffer *buffer);

Determines if any of the targets in `targets` can be used to provide rich text.

#### Parameters

targets | an array of GdkAtoms. | [array length=n_targets]
n_targets | the length of `targets` |
buffer | a GtkTextBuffer |

#### Returns

`TRUE` if `targets` include a suitable target for rich text, otherwise `FALSE`.

Since: 2.10

### gtk_selection_remove_all ()

    void
    gtk_selection_remove_all (GtkWidget *widget);

Removes all handlers and unsets ownership of all selections for a widget. Called when widget is being destroyed. This function will not generally be called by applications.

#### Parameters

widget | a GtkWidget |

### gtk_selection_clear ()

    gboolean
    gtk_selection_clear (GtkWidget *widget,
                         GdkEventSelection *event);

`gtk_selection_clear` has been deprecated since version 2.4 and should not be used in newly-written code.

Instead of calling this function, chain up from your selection-clear-event handler. Calling this function from any other context is illegal.

The default handler for the “selection-clear-event” signal.

#### Parameters

widget | a GtkWidget |
event | the event |

#### Returns

`TRUE` if the event was handled, otherwise false

Since: 2.2

### gtk_selection_data_copy ()

    GtkSelectionData *
    gtk_selection_data_copy (GtkSelectionData *data);

Makes a copy of a GtkSelectionData structure and its data.

#### Parameters

data | a pointer to a GtkSelectionData structure. |

#### Returns

a pointer to a copy of `data` .

### gtk_selection_data_free ()

    void
    gtk_selection_data_free (GtkSelectionData *data);

Frees a GtkSelectionData structure returned from `gtk_selection_data_copy()`.

#### Parameters

data | a pointer to a GtkSelectionData structure. |

## Types and Values

### struct GtkTargetEntry

    struct GtkTargetEntry {
      gchar *target;
      guint  flags;
      guint  info;
    };

A GtkTargetEntry structure represents a single type of data than can be supplied for by a widget for a selection or for supplied or received during drag-and-drop. It contains a string representing the drag type, a flags field (used only for drag and drop - see GtkTargetFlags), and an application assigned integer ID. The integer ID will later be passed as a signal parameter for signals like "selection_get". It allows the application to identify the target type without extensive string compares.

### struct GtkTargetList

    struct GtkTargetList {
      GList *list;
      guint ref_count;
    };

A GtkTargetList structure is a reference counted list of GtkTargetPair. It is used to represent the same information as a table of GtkTargetEntry, but in an efficient form. This structure should be treated as opaque.

### struct GtkTargetPair

    struct GtkTargetPair {
      GdkAtom   target;
      guint     flags;
      guint     info;
    };

Internally used structure in the drag-and-drop and selection handling code.

## See Also

GtkWidget | Much of the operation of selections happens via signals for GtkWidget. In particular, if you are using the functions in this section, you may need to pay attention to ::selection_get, ::selection_received, and :selection_clear_event signals.