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);
gint        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);
gint        gtk_selection_convert           (GtkWidget *widget,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             guint32 time);
void        gtk_selection_data_set          (GtkSelectionData *selection_data,
                                             GdkAtom type,
                                             gint format,
                                             guchar *data,
                                             gint length);
void        gtk_selection_remove_all        (GtkWidget *widget);
GtkSelectioData* gtk_selection_data_copy    (GtkSelectionData *data);
void        gtk_selection_data_free         (GtkSelectionData *data);

gint        gtk_selection_clear             (GtkWidget *widget,
                                             GdkEventSelection *event);
gint        gtk_selection_incr_event        (GdkWindow *window,
                                             GdkEventProperty *event);
gint        gtk_selection_notify            (GtkWidget *widget,
                                             GdkEventSelection *event);
gint        gtk_selection_property_notify   (GtkWidget *widget,
                                             GdkEventProperty *event);
gint        gtk_selection_request           (GtkWidget *widget,
                                             GdkEventSelection *event);

Description

See the documentation for GtkWidget for descriptions of the "selection_get" and "selection_received" signals.

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

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

void        gtk_target_list_ref             (GtkTargetList *list);

Increase the reference count of a GtkTargetList by one.

list :a GtkTargetList


gtk_target_list_unref ()

void        gtk_target_list_unref           (GtkTargetList *list);

Decrease the reference count of a GtkTargetList by one. If the resulting reference count is zero, free the list.

list :a GtkTargetList


gtk_target_list_add ()

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

Add 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);

Add a table of GtkTargetEntry into a target list

list :a GtkTargetList
targets :the table of GtkTargetEntry
ntargets :number of targets in the table


gtk_target_list_remove ()

void        gtk_target_list_remove          (GtkTargetList *list,
                                             GdkAtom target);

Remove 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);

Look 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
Returns :TRUE if the target was found, otherwise FALSE


gtk_selection_owner_set ()

gint        gtk_selection_owner_set         (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.

widget :a GtkWidget, or NULL.
selection :an interned atom representing the selection to claim
time :the time stamp for claiming the selection
Returns :TRUE if the operation succeeded


gtk_selection_add_target ()

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

Add 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);

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

gint        gtk_selection_convert           (GtkWidget *widget,
                                             GdkAtom selection,
                                             GdkAtom target,
                                             guint32 time);

Request 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,
                                             guchar *data,
                                             gint length);

Store new data into a GtkSelectionData object. Should _only_ by called from a selection handler callback. Null terminates the stored data.

selection_data : 
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_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_data_copy ()

GtkSelectioData* gtk_selection_data_copy    (GtkSelectionData *data);

Make a copy of a GtkSelection data 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);

Free a GtkSelectionData structure returned from gtk_selection_data_copy().

data :a pointer to a GtkSelectionData structure.


gtk_selection_clear ()

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

Internal function.

widget : 
event : 
Returns : 


gtk_selection_incr_event ()

gint        gtk_selection_incr_event        (GdkWindow *window,
                                             GdkEventProperty *event);

Internal function.

window : 
event : 
Returns : 


gtk_selection_notify ()

gint        gtk_selection_notify            (GtkWidget *widget,
                                             GdkEventSelection *event);

Internal function.

widget : 
event : 
Returns : 


gtk_selection_property_notify ()

gint        gtk_selection_property_notify   (GtkWidget *widget,
                                             GdkEventProperty *event);

Internal function.

widget : 
event : 
Returns : 


gtk_selection_request ()

gint        gtk_selection_request           (GtkWidget *widget,
                                             GdkEventSelection *event);

Internal function.

widget : 
event : 
Returns :