Selections

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

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.

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

Increases the reference count of a GtkTargetList by one.

list : a 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);

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

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

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

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`.
`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`.
`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_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.

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

Adds 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` :
`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_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_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_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 ()

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.