Selections

Selections — Functions for handling inter-process communication via selections

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── GtkSelectionData

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 GdkContentFormats object represents 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_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.

 

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

[type utf8][nullable][transfer full]


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

[nullable][transfer full]

Since: 2.6


gtk_selection_data_set_surface ()

gboolean
gtk_selection_data_set_surface (GtkSelectionData *selection_data,
                                cairo_surface_t *surface);

Sets the contents of the selection from a cairo image surface. The surface is converted to the form determined by selection_data->target .

Parameters

selection_data

a GtkSelectionData

 

surface

a cairo image surface

 

Returns

TRUE if the selection was successfully set, otherwise FALSE.

Since: 3.94


gtk_selection_data_get_surface ()

cairo_surface_t *
gtk_selection_data_get_surface (GtkSelectionData *selection_data);

Gets the contents of the selection data as a cairo surface.

Parameters

selection_data

a GtkSelectionData

 

Returns

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

[nullable][transfer full]

Since: 3.94


gtk_selection_data_set_texture ()

gboolean
gtk_selection_data_set_texture (GtkSelectionData *selection_data,
                                GdkTexture *texture);

Sets the contents of the selection from a GdkTexture. The surface is converted to the form determined by selection_data->target .

Parameters

selection_data

a GtkSelectionData

 

texture

a GdkTexture

 

Returns

TRUE if the selection was successfully set, otherwise FALSE.

Since: 3.94


gtk_selection_data_get_texture ()

GdkTexture *
gtk_selection_data_get_texture (const 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 GdkTexture, a newly allocated texture is returned, otherwise NULL. If the result is non-NULL it must be freed with g_object_unref().

[nullable][transfer full]

Since: 3.94


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

const guchar *
gtk_selection_data_get_data (const GtkSelectionData *selection_data);

Retrieves the raw data of the selection.

[skip]

Parameters

selection_data

a pointer to a GtkSelectionData.

 

Returns

the raw data of the selection.

[array][element-type guint8]

Since: 2.14


gtk_selection_data_get_length ()

gint
gtk_selection_data_get_length (const GtkSelectionData *selection_data);

Retrieves the length of the raw data of the selection.

Parameters

selection_data

a pointer to a GtkSelectionData.

 

Returns

the length of the data of the selection.

Since: 2.14


gtk_selection_data_get_data_with_length ()

const guchar *
gtk_selection_data_get_data_with_length
                               (const GtkSelectionData *selection_data,
                                gint *length);

Retrieves the raw data of the selection along with its length.

[rename-to gtk_selection_data_get_data]

Parameters

selection_data

a pointer to a GtkSelectionData.

 

length

return location for length of the data segment.

[out]

Returns

the raw data of the selection.

[array length=length]

Since: 3.0


gtk_selection_data_get_data_type ()

GdkAtom
gtk_selection_data_get_data_type (const GtkSelectionData *selection_data);

Retrieves the data type of the selection.

Parameters

selection_data

a pointer to a GtkSelectionData.

 

Returns

the data type of the selection.

[transfer none]

Since: 2.14


gtk_selection_data_get_display ()

GdkDisplay *
gtk_selection_data_get_display (const GtkSelectionData *selection_data);

Retrieves the display of the selection.

Parameters

selection_data

a pointer to a GtkSelectionData.

 

Returns

the display of the selection.

[transfer none]

Since: 2.14


gtk_selection_data_get_format ()

gint
gtk_selection_data_get_format (const GtkSelectionData *selection_data);

Retrieves the format of the selection.

Parameters

selection_data

a pointer to a GtkSelectionData.

 

Returns

the format of the selection.

Since: 2.14


gtk_selection_data_get_target ()

GdkAtom
gtk_selection_data_get_target (const GtkSelectionData *selection_data);

Retrieves the target of the selection.

Parameters

selection_data

a pointer to a GtkSelectionData.

 

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

GtkSelectionData *
gtk_selection_data_copy (const GtkSelectionData *data);

Makes a copy of a GtkSelectionData and its data.

Parameters

data

a pointer to a GtkSelectionData.

 

Returns

a pointer to a copy of data .


gtk_selection_data_free ()

void
gtk_selection_data_free (GtkSelectionData *data);

Frees a GtkSelectionData returned from gtk_selection_data_copy().

Parameters

data

a pointer to a GtkSelectionData.

 

Types and Values

GtkSelectionData

typedef struct {
} GtkSelectionData;

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