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

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