Selections

Selections — Functions for handling inter-process communication via selections

Functions

GtkTargetEntry * gtk_target_entry_new ()
GtkTargetEntry * gtk_target_entry_copy ()
void gtk_target_entry_free ()
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 ()
const guchar * gtk_selection_data_get_data_with_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 ()
GtkSelectionData * gtk_selection_data_copy ()
void gtk_selection_data_free ()

Types and Values

Object Hierarchy

    GBoxed
    ├── GtkSelectionData
    ╰── 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.

If an application is expected to exchange image data and work on Windows, it is highly advised to support at least "image/bmp" target for the widest possible compatibility with third-party applications. GtkClipboard already does that by using gtk_target_list_add_image_targets() and gtk_selection_data_set_pixbuf() or gtk_selection_data_get_pixbuf(), which is one of the reasons why it is advised to use GtkClipboard.

Some of the datatypes defined this section are used in the GtkClipboard and drag-and-drop API’s as well. The GtkTargetEntry 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_entry_new ()

GtkTargetEntry *
gtk_target_entry_new (const gchar *target,
                      guint flags,
                      guint info);

Makes a new GtkTargetEntry.

Parameters

target

String identifier for target

 

flags

Set of flags, see GtkTargetFlags

 

info

an ID that will be passed back to the application

 

Returns

a pointer to a new GtkTargetEntry. Free with gtk_target_entry_free()


gtk_target_entry_copy ()

GtkTargetEntry *
gtk_target_entry_copy (GtkTargetEntry *data);

Makes a copy of a GtkTargetEntry and its data.

Parameters

data

a pointer to a GtkTargetEntry

 

Returns

a pointer to a copy of data . Free with gtk_target_entry_free()


gtk_target_entry_free ()

void
gtk_target_entry_free (GtkTargetEntry *data);

Frees a GtkTargetEntry returned from gtk_target_entry_new() or gtk_target_entry_copy().

Parameters

data

a pointer to a GtkTargetEntry.

 

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][allow-none]

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 GtkSelectionData 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 GtkSelectionData 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 GtkSelectionData to the target list. All targets are added with the same info .

Since 3.24.37, this includes the application/vnd.portal.files target when possible, to allow sending files between sandboxed apps via the FileTransfer portal.

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.

[out][allow-none]

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.

[out]

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

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 GtkWidget

 

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.

 

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

Since 3.24.37, this may involve using the FileTransfer portal to send files between sandboxed apps.

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.

Since 3.24.37, this may involve using the FileTransfer portal to send files between sandboxed apps.

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

gboolean
gtk_selection_data_targets_include_rich_text
                               (const 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 (const GtkSelectionData *selection_data);

Retrieves the selection GdkAtom of the selection data.

Parameters

selection_data

a pointer to a GtkSelectionData.

 

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 (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_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_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 GtkSelectionData;

struct GtkTargetEntry

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

A GtkTargetEntry 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.

Members

gchar *target;

a string representation of the target type

 

guint flags;

GtkTargetFlags for DND

 

guint info;

an application-assigned integer ID which will get passed as a parameter to e.g the “selection-get” signal. It allows the application to identify the target type without extensive string compares.

 

GtkTargetList

typedef struct _GtkTargetList GtkTargetList;

A GtkTargetList is a reference counted list of GtkTargetPair and should be treated as opaque.


struct GtkTargetPair

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

A GtkTargetPair is used to represent the same information as a table of GtkTargetEntry, but in an efficient form.

Members

GdkAtom target;

GdkAtom representation of the target type

 

guint flags;

GtkTargetFlags for DND

 

guint info;

an application-assigned integer ID which will get passed as a parameter to e.g the “selection-get” signal. It allows the application to identify the target type without extensive string compares.

 

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