Selections: GTK+ 2 Reference Manual

## Selections 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

## 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;
    };

### struct GtkTargetList

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

### struct GtkTargetPair

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