| | | GTK+ Reference Manual | |
|---|
SelectionsSelections — Functions for handling inter-process communication via selections |
#include <gtk/gtk.h>
GtkTargetEntry;
GtkTargetList;
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_add_text_targets
(GtkTargetList *list,
guint info);
void gtk_target_list_add_image_targets
(GtkTargetList *list,
guint info,
gboolean writable);
void gtk_target_list_add_uri_targets (GtkTargetList *list,
guint info);
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_);
gboolean gtk_selection_owner_set_for_display
(GdkDisplay *display,
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_set_pixbuf (GtkSelectionData *selection_data,
GdkPixbuf *pixbuf);
GdkPixbuf* gtk_selection_data_get_pixbuf (GtkSelectionData *selection_data);
gboolean gtk_selection_data_set_uris (GtkSelectionData *selection_data,
gchar **uris);
gchar** gtk_selection_data_get_uris (GtkSelectionData *selection_data);
gboolean gtk_selection_data_get_targets (GtkSelectionData *selection_data,
GdkAtom **targets,
gint *n_atoms);
gboolean gtk_selection_data_targets_include_image
(GtkSelectionData *selection_data,
gboolean writable);
gboolean gtk_selection_data_targets_include_text
(GtkSelectionData *selection_data);
void gtk_selection_remove_all (GtkWidget *widget);
gboolean gtk_selection_clear (GtkWidget *widget,
GdkEventSelection *event);
GtkSelectionData* gtk_selection_data_copy (GtkSelectionData *data);
void gtk_selection_data_free (GtkSelectionData *data);
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.
typedef struct {
gchar *target;
guint flags;
guint info;
} GtkTargetEntry;
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.
typedef struct {
GList *list;
guint ref_count;
} GtkTargetList;
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.
typedef struct {
GdkAtom target;
guint flags;
guint info;
} GtkTargetPair;
Internally used structure in the drag-and-drop and selection handling code.
GtkTargetList* gtk_target_list_new (const GtkTargetEntry *targets, guint ntargets);
Creates a new GtkTargetList from an array of GtkTargetEntry.
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. |
void gtk_target_list_ref (GtkTargetList *list);
Increases the reference count of a GtkTargetList by one.
Increases the reference count of a GtkTargetList by one.
list : | a GtkTargetList |
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.
Decreases the reference count of a GtkTargetList by one. If the resulting reference count is zero, frees the list.
list : | a GtkTargetList |
void gtk_target_list_add (GtkTargetList *list, GdkAtom target, guint flags, guint info);
Appends another target to a GtkTargetList.
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 |
void gtk_target_list_add_table (GtkTargetList *list, const GtkTargetEntry *targets, guint ntargets);
Prepends a table of GtkTargetEntry to a target list.
Adds 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_add_text_targets
(GtkTargetList *list,
guint info);
Appends the text targets supported by GtkSelection to
the target list. All targets are added with the same info.
list : | a GtkTargetList |
info : | an ID that will be passed back to the application |
Since 2.6
void gtk_target_list_add_image_targets
(GtkTargetList *list,
guint info,
gboolean writable);
Appends the image targets supported by GtkSelection to
the target list. All targets are added with the same info.
list : | a GtkTargetList |
info : | an ID that will be passed back to the application |
writable : | whether to add only targets for which GTK+ knows how to convert a pixbuf into the format |
Since 2.6
void gtk_target_list_add_uri_targets (GtkTargetList *list, guint info);
Appends the URI targets supported by GtkSelection to
the target list. All targets are added with the same info.
list : | a GtkTargetList |
info : | an ID that will be passed back to the application |
Since 2.6
void gtk_target_list_remove (GtkTargetList *list, GdkAtom target);
Removes a target from a target list.
Removes 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);
Looks up a given target in a GtkTargetList.
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
|
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
|
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 |
Since 2.2
void gtk_selection_add_target (GtkWidget *widget, GdkAtom selection, GdkAtom target, guint info);
Appends a specified target to the list of supported targets for a given widget and selection.
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. |
void gtk_selection_add_targets (GtkWidget *widget, GdkAtom selection, const GtkTargetEntry *targets, guint ntargets);
Prepends a table of targets to the list of supported targets for a given widget and selection.
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
|
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 |
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.
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).
|
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.
Stores new data into a GtkSelectionData object. Should only be called from a selection handler callback. Zero-terminates the stored data.
selection_data : | a pointer to a GtkSelectionData structure. |
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 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.
|
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().
|
gboolean gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data, GdkPixbuf *pixbuf);
Sets the contents of the selection from a GdkPixbuf
The pixbuf is converted to the form determined by
selection_data->target.
selection_data : | a GtkSelectionData |
pixbuf : | a GdkPixbuf |
| Returns : | TRUE if the selection was successfully set,
otherwise FALSE.
|
Since 2.6
GdkPixbuf* gtk_selection_data_get_pixbuf (GtkSelectionData *selection_data);
Gets the contents of the selection data as a GdkPixbuf.
selection_data : | a GtkSelectionData |
| Returns : | if the selection data contained a recognized
image type and it could be converted to a GdkPixbuf, a
newly allocated pixbuf is returned, otherwise NULL.
If the result is non-NULL it must be freed with g_object_unref().
|
Since 2.6
gboolean gtk_selection_data_set_uris (GtkSelectionData *selection_data, gchar **uris);
Sets the contents of the selection from a list of URIs.
The string is converted to the form determined by
selection_data->target.
selection_data : | a GtkSelectionData |
uris : | a NULL-terminated array of strings hilding URIs
|
| Returns : | TRUE if the selection was successfully set,
otherwise FALSE.
|
Since 2.6
gchar** gtk_selection_data_get_uris (GtkSelectionData *selection_data);
Gets the contents of the selection data as array of URIs.
selection_data : | a GtkSelectionData |
| Returns : | if the selection data contains a list of
URIs, a newly allocated NULL-terminated string array
containing the URIs, otherwise NULL. If the result is
non-NULL it must be freed with g_strfreev().
|
Since 2.6
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.
|
gboolean gtk_selection_data_targets_include_image (GtkSelectionData *selection_data, gboolean writable);
Given a GtkSelectionData object holding a list of targets,
determines if any of the targets in targets can be used to
provide a GdkPixbuf.
selection_data : | a GtkSelectionData object |
writable : | whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format |
| Returns : | TRUE if selection_data holds a list of targets,
and a suitable target for images is included, otherwise FALSE.
|
Since 2.6
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.
|
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.
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 |
gboolean gtk_selection_clear (GtkWidget *widget, GdkEventSelection *event);
gtk_selection_clear is deprecated and should not be used in newly-written code. Instead of calling this function, chain up from
your selection_clear_event handler. Calling this function
from any other context is illegal.
The default handler for the GtkWidget::selection_clear_event signal.
widget : | a GtkWidget |
event : | the event |
| Returns : | TRUE if the event was handled, otherwise false
|
Since 2.2
GtkSelectionData* gtk_selection_data_copy (GtkSelectionData *data);
Makes a copy of a GtkSelectionData structure and its 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.
|
void gtk_selection_data_free (GtkSelectionData *data);
Frees a GtkSelectionData structure returned from
gtk_selection_data_copy().
Frees a GtkSelectionData structure returned from
gtk_selection_data_copy().
data : | a pointer to a GtkSelectionData structure. |
| << Styles | Version Information >> |