GTK+ Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
The selection mechanism provides the basis for different types of IPC 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.
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 { 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 { GdkAtom target; guint flags; guint info; }; |
Internally used structure in the drag-and-drop and selection handling code.
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. |
void gtk_target_list_ref (GtkTargetList *list); |
Increase the reference count of a GtkTargetList by one.
list : | a GtkTargetList |
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 |
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 |
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 |
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 |
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 |
gboolean 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 |
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. |
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 |
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 |
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). |
void gtk_selection_data_set (GtkSelectionData *selection_data, GdkAtom type, gint format, const 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 |
gboolean gtk_selection_data_set_text (GtkSelectionData *selection_data, const guchar *str); |
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 |
Returns : | TRUE if the selection was succesfully set, otherwise FALSE. |
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(). |
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 |
GtkSelectionData* 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. |
void gtk_selection_data_free (GtkSelectionData *data); |
Free a GtkSelectionData structure returned from gtk_selection_data_copy().
data : | a pointer to a GtkSelectionData structure. |
gint gtk_selection_clear (GtkWidget *widget, GdkEventSelection *event); |
Internal function.
widget : | |
event : | |
Returns : |
gint gtk_selection_incr_event (GdkWindow *window, GdkEventProperty *event); |
Internal function.
window : | |
event : | |
Returns : |
gint gtk_selection_notify (GtkWidget *widget, GdkEventSelection *event); |
Internal function.
widget : | |
event : | |
Returns : |
gint gtk_selection_property_notify (GtkWidget *widget, GdkEventProperty *event); |
Internal function.
widget : | |
event : | |
Returns : |
gint gtk_selection_request (GtkWidget *widget, GdkEventSelection *event); |
Internal function.
widget : | |
event : | |
Returns : |