GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

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

<<< Previous Page | Home | Up | Next Page >>>
Keyboard Accelerators | Drag and Drop