Selections

Selections — Functions for handling inter-process communication via selections

Synopsis

#include <gtk/gtk.h>

                    GtkTargetEntry;
                    GtkTargetList;
                    GtkTargetPair;
GtkTargetList *     gtk_target_list_new                 (const GtkTargetEntry *targets,
                                                         guint ntargets);
GtkTargetList *     gtk_target_list_ref                 (GtkTargetList *list);
void                gtk_target_list_unref               (GtkTargetList *list);
void                gtk_target_list_add                 (GtkTargetList *list,
                                                         GdkAtom target,
                                                         guint flags,
                                                         guint info);
void                gtk_target_list_add_table           (GtkTargetList *list,
                                                         const GtkTargetEntry *targets,
                                                         guint ntargets);
void                gtk_target_list_add_text_targets    (GtkTargetList *list,
                                                         guint info);
void                gtk_target_list_add_image_targets   (GtkTargetList *list,
                                                         guint info,
                                                         gboolean writable);
void                gtk_target_list_add_uri_targets     (GtkTargetList *list,
                                                         guint info);
void                gtk_target_list_add_rich_text_targets
                                                        (GtkTargetList *list,
                                                         guint info,
                                                         gboolean deserializable,
                                                         GtkTextBuffer *buffer);
void                gtk_target_list_remove              (GtkTargetList *list,
                                                         GdkAtom target);
gboolean            gtk_target_list_find                (GtkTargetList *list,
                                                         GdkAtom target,
                                                         guint *info);
void                gtk_target_table_free               (GtkTargetEntry *targets,
                                                         gint n_targets);
GtkTargetEntry *    gtk_target_table_new_from_list      (GtkTargetList *list,
                                                         gint *n_targets);
gboolean            gtk_selection_owner_set             (GtkWidget *widget,
                                                         GdkAtom selection,
                                                         guint32 time_);
gboolean            gtk_selection_owner_set_for_display (GdkDisplay *display,
                                                         GtkWidget *widget,
                                                         GdkAtom selection,
                                                         guint32 time_);
void                gtk_selection_add_target            (GtkWidget *widget,
                                                         GdkAtom selection,
                                                         GdkAtom target,
                                                         guint info);
void                gtk_selection_add_targets           (GtkWidget *widget,
                                                         GdkAtom selection,
                                                         const GtkTargetEntry *targets,
                                                         guint ntargets);
void                gtk_selection_clear_targets         (GtkWidget *widget,
                                                         GdkAtom selection);
gboolean            gtk_selection_convert               (GtkWidget *widget,
                                                         GdkAtom selection,
                                                         GdkAtom target,
                                                         guint32 time_);
void                gtk_selection_data_set              (GtkSelectionData *selection_data,
                                                         GdkAtom type,
                                                         gint format,
                                                         const guchar *data,
                                                         gint length);
gboolean            gtk_selection_data_set_text         (GtkSelectionData *selection_data,
                                                         const gchar *str,
                                                         gint len);
guchar *            gtk_selection_data_get_text         (GtkSelectionData *selection_data);
gboolean            gtk_selection_data_set_pixbuf       (GtkSelectionData *selection_data,
                                                         GdkPixbuf *pixbuf);
GdkPixbuf *         gtk_selection_data_get_pixbuf       (GtkSelectionData *selection_data);
gboolean            gtk_selection_data_set_uris         (GtkSelectionData *selection_data,
                                                         gchar **uris);
gchar **            gtk_selection_data_get_uris         (GtkSelectionData *selection_data);
gboolean            gtk_selection_data_get_targets      (GtkSelectionData *selection_data,
                                                         GdkAtom **targets,
                                                         gint *n_atoms);
gboolean            gtk_selection_data_targets_include_image
                                                        (GtkSelectionData *selection_data,
                                                         gboolean writable);
gboolean            gtk_selection_data_targets_include_text
                                                        (GtkSelectionData *selection_data);
gboolean            gtk_selection_data_targets_include_uri
                                                        (GtkSelectionData *selection_data);
gboolean            gtk_selection_data_targets_include_rich_text
                                                        (GtkSelectionData *selection_data,
                                                         GtkTextBuffer *buffer);
GdkAtom             gtk_selection_data_get_selection    (GtkSelectionData *selection_data);
const guchar *      gtk_selection_data_get_data         (GtkSelectionData *selection_data);
gint                gtk_selection_data_get_length       (GtkSelectionData *selection_data);
GdkAtom             gtk_selection_data_get_data_type    (GtkSelectionData *selection_data);
GdkDisplay *        gtk_selection_data_get_display      (GtkSelectionData *selection_data);
gint                gtk_selection_data_get_format       (GtkSelectionData *selection_data);
GdkAtom             gtk_selection_data_get_target       (GtkSelectionData *selection_data);
gboolean            gtk_targets_include_image           (GdkAtom *targets,
                                                         gint n_targets,
                                                         gboolean writable);
gboolean            gtk_targets_include_text            (GdkAtom *targets,
                                                         gint n_targets);
gboolean            gtk_targets_include_uri             (GdkAtom *targets,
                                                         gint n_targets);
gboolean            gtk_targets_include_rich_text       (GdkAtom *targets,
                                                         gint n_targets,
                                                         GtkTextBuffer *buffer);
void                gtk_selection_remove_all            (GtkWidget *widget);
gboolean            gtk_selection_clear                 (GtkWidget *widget,
                                                         GdkEventSelection *event);
GtkSelectionData *  gtk_selection_data_copy             (GtkSelectionData *data);
void                gtk_selection_data_free             (GtkSelectionData *data);

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.

Details

GtkTargetEntry

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

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.

GtkTargetList

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

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.

GtkTargetPair

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

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

gtk_target_list_new ()

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

Creates a new GtkTargetList from an array of GtkTargetEntry.

targets :

 Pointer to an array of GtkTargetEntry

ntargets :

 number of entries in targets.

Returns :

 the new GtkTargetList.

gtk_target_list_ref ()

GtkTargetList *     gtk_target_list_ref                 (GtkTargetList *list);

Increases the reference count of a GtkTargetList by one.

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.

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.

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.

list :

 a GtkTargetList

targets :

 the table of GtkTargetEntry

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.

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.

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.

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.

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.

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.

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

targets :

 a GtkTargetEntry array

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.

list :

 a GtkTargetList

n_targets :

 return location for the number ot targets in the table

Returns :

 the new table.

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.

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.

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.

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.

widget :

 a GtkWidget

selection :

 the selection

targets :

 a table of targets to add

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.

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.

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.

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)

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.

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.

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.

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.

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

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.

selection_data :

 a GtkSelectionData

uris :

 a NULL-terminated array of strings holding URIs

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.

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

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.

selection_data :

 a GtkSelectionData object

targets :

 location to store an array of targets. The result stored here must be freed with g_free().

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.

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.

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.

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.

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.

selection_data :

 a pointer to a GtkSelectionData structure.

Returns :

 the selection GdkAtom of the selection data.

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.

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.

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.

selection_data :

 a pointer to a GtkSelectionData structure.

Returns :

 the data type of the selection.

Since 2.14

gtk_selection_data_get_display ()

GdkDisplay *        gtk_selection_data_get_display      (GtkSelectionData *selection_data);

Retrieves the display of the selection.

selection_data :

 a pointer to a GtkSelectionData structure.

Returns :

 the display of the selection.

Since 2.14

gtk_selection_data_get_format ()

gint                gtk_selection_data_get_format       (GtkSelectionData *selection_data);

Retrieves the format of the selection.

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.

selection_data :

 a pointer to a GtkSelectionData structure.

Returns :

 the target of the selection.

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.

targets :

 an array of GdkAtoms

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.

targets :

 an array of GdkAtoms

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.

targets :

 an array of GdkAtoms

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.

targets :

 an array of GdkAtoms

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.

widget :

 a GtkWidget

gtk_selection_clear ()

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

Warning

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.

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.

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

data :

 a pointer to a GtkSelectionData structure.

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.

Generated by GTK-Doc V1.14