Selections

Name

Selections -- Functions for handling inter-process communication via selections.

Synopsis


#include <gtk/gtk.h>


struct      GtkTargetEntry;
struct      GtkTargetList;
struct      GtkTargetPair;
GtkTargetList* gtk_target_list_new          (const GtkTargetEntry *targets,
                                             guint ntargets);
void        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_remove          (GtkTargetList *list,
                                             GdkAtom target);
gboolean    gtk_target_list_find            (GtkTargetList *list,
                                             GdkAtom target,
                                             guint *info);
gboolean    gtk_selection_owner_set         (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_get_targets  (GtkSelectionData *selection_data,
                                             GdkAtom **targets,
                                             gint *n_atoms);
gboolean    gtk_selection_data_targets_include_text
                                            (GtkSelectionData *selection_data);
void        gtk_selection_remove_all        (GtkWidget *widget);
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

struct GtkTargetEntry

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

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.


struct GtkTargetList

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

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.


struct GtkTargetPair

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

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.


gtk_target_list_ref ()

void        gtk_target_list_ref             (GtkTargetList *list);

Increases the reference count of a GtkTargetList by one.


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.


gtk_target_list_add ()

void        gtk_target_list_add             (GtkTargetList *list,
                                             GdkAtom target,
                                             guint flags,
                                             guint info);

Adds another target to a GtkTargetList.


gtk_target_list_add_table ()

void        gtk_target_list_add_table       (GtkTargetList *list,
                                             const GtkTargetEntry *targets,
                                             guint ntargets);

Adds a table of GtkTargetEntry into a target list.


gtk_target_list_remove ()

void        gtk_target_list_remove          (GtkTargetList *list,
                                             GdkAtom target);

Removes a target from a target list.


gtk_target_list_find ()

gboolean    gtk_target_list_find            (GtkTargetList *list,
                                             GdkAtom target,
                                             guint *info);

Looks up a given target in a GtkTargetList.


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.


gtk_selection_add_target ()

void        gtk_selection_add_target        (GtkWidget *widget,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             guint info);

Adds specified target to the list of supported targets for a given widget and selection.


gtk_selection_add_targets ()

void        gtk_selection_add_targets       (GtkWidget *widget,
                                             GdkAtom selection,
                                             const GtkTargetEntry *targets,
                                             guint ntargets);

Adds a table of targets to the list of supported targets for a given widget and selection.


gtk_selection_clear_targets ()

void        gtk_selection_clear_targets     (GtkWidget *widget,
                                             GdkAtom selection);

Remove all targets registered for the given selection for the widget.


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.


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.


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.


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.


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.


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.


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.


gtk_selection_data_copy ()

GtkSelectionData* gtk_selection_data_copy   (GtkSelectionData *data);

Makes a copy of a GtkSelectionData structure and its data.


gtk_selection_data_free ()

void        gtk_selection_data_free         (GtkSelectionData *data);

Frees a GtkSelectionData structure returned from gtk_selection_data_copy().

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.