| Top | |
|
|
|
The selection mechanism provides the basis for different types of communication between processes. In particular, drag and drop and CtkClipboard work via selections. You will very seldom or never need to use most of the functions in this section directly; CtkClipboard provides a nicer interface to the same functionality.
If an application is expected to exchange image data and work
on Windows, it is highly advised to support at least "image/bmp" target
for the widest possible compatibility with third-party applications.
CtkClipboard already does that by using ctk_target_list_add_image_targets()
and ctk_selection_data_set_pixbuf() or ctk_selection_data_get_pixbuf(),
which is one of the reasons why it is advised to use CtkClipboard.
Some of the datatypes defined this section are used in the CtkClipboard and drag-and-drop API’s as well. The CtkTargetEntry and CtkTargetList objects represent lists of data types that are supported when sending or receiving data. The CtkSelectionData object is used to store a chunk of data along with the data type and other associated information.
CtkTargetEntry * ctk_target_entry_new (const gchar *target,guint flags,guint info);
Makes a new CtkTargetEntry.
target |
String identifier for target |
|
flags |
Set of flags, see CtkTargetFlags |
|
info |
an ID that will be passed back to the application |
CtkTargetEntry *
ctk_target_entry_copy (CtkTargetEntry *data);
Makes a copy of a CtkTargetEntry and its data.
void
ctk_target_entry_free (CtkTargetEntry *data);
Frees a CtkTargetEntry returned from
ctk_target_entry_new() or ctk_target_entry_copy().
CtkTargetList * ctk_target_list_new (const CtkTargetEntry *targets,guint ntargets);
Creates a new CtkTargetList from an array of CtkTargetEntry.
targets |
Pointer to an array of CtkTargetEntry. |
[array length=ntargets][allow-none] |
ntargets |
number of entries in |
CtkTargetList *
ctk_target_list_ref (CtkTargetList *list);
Increases the reference count of a CtkTargetList by one.
void
ctk_target_list_unref (CtkTargetList *list);
Decreases the reference count of a CtkTargetList by one. If the resulting reference count is zero, frees the list.
void ctk_target_list_add (CtkTargetList *list,CdkAtom target,guint flags,guint info);
Appends another target to a CtkTargetList.
void ctk_target_list_add_table (CtkTargetList *list,const CtkTargetEntry *targets,guint ntargets);
Prepends a table of CtkTargetEntry to a target list.
list |
||
targets |
the table of CtkTargetEntry. |
[array length=ntargets] |
ntargets |
number of targets in the table |
void ctk_target_list_add_text_targets (CtkTargetList *list,guint info);
Appends the text targets supported by CtkSelectionData to
the target list. All targets are added with the same info
.
Since: 2.6
void ctk_target_list_add_image_targets (CtkTargetList *list,guint info,gboolean writable);
Appends the image targets supported by CtkSelectionData to
the target list. All targets are added with the same info
.
list |
||
info |
an ID that will be passed back to the application |
|
writable |
whether to add only targets for which CTK+ knows how to convert a pixbuf into the format |
Since: 2.6
void ctk_target_list_add_uri_targets (CtkTargetList *list,guint info);
Appends the URI targets supported by CtkSelectionData to
the target list. All targets are added with the same info
.
Since: 2.6
void ctk_target_list_add_rich_text_targets (CtkTargetList *list,guint info,gboolean deserializable,CtkTextBuffer *buffer);
Appends the rich text targets registered with
ctk_text_buffer_register_serialize_format() or
ctk_text_buffer_register_deserialize_format() to the target list. All
targets are added with the same info
.
list |
||
info |
an ID that will be passed back to the application |
|
deserializable |
if |
|
buffer |
Since: 2.10
void ctk_target_list_remove (CtkTargetList *list,CdkAtom target);
Removes a target from a target list.
gboolean ctk_target_list_find (CtkTargetList *list,CdkAtom target,guint *info);
Looks up a given target in a CtkTargetList.
void ctk_target_table_free (CtkTargetEntry *targets,gint n_targets);
This function frees a target table as returned by
ctk_target_table_new_from_list()
targets |
a CtkTargetEntry array. |
[array length=n_targets] |
n_targets |
the number of entries in the array |
Since: 2.10
CtkTargetEntry * ctk_target_table_new_from_list (CtkTargetList *list,gint *n_targets);
This function creates an CtkTargetEntry array that contains the
same targets as the passed list. The returned table is newly
allocated and should be freed using ctk_target_table_free() when no
longer needed.
Since: 2.10
gboolean ctk_selection_owner_set (CtkWidget *widget,CdkAtom 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 CtkWidget, or |
[allow-none] |
selection |
an interned atom representing the selection to claim |
|
time_ |
timestamp with which to claim the selection |
gboolean ctk_selection_owner_set_for_display (CdkDisplay *display,CtkWidget *widget,CdkAtom 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 CdkDisplay where the selection is set |
|
widget |
new selection owner (a CtkWidget), or |
[allow-none] |
selection |
an interned atom representing the selection to claim. |
|
time_ |
timestamp with which to claim the selection |
Since: 2.2
void ctk_selection_add_target (CtkWidget *widget,CdkAtom selection,CdkAtom target,guint info);
Appends a specified target to the list of supported targets for a given widget and selection.
void ctk_selection_add_targets (CtkWidget *widget,CdkAtom selection,const CtkTargetEntry *targets,guint ntargets);
Prepends a table of targets to the list of supported targets for a given widget and selection.
void ctk_selection_clear_targets (CtkWidget *widget,CdkAtom selection);
Remove all targets registered for the given selection for the widget.
gboolean ctk_selection_convert (CtkWidget *widget,CdkAtom selection,CdkAtom 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 CDK_CURRENT_TIME |
void ctk_selection_data_set (CtkSelectionData *selection_data,CdkAtom type,gint format,const guchar *data,gint length);
Stores new data into a CtkSelectionData object. Should only be called from a selection handler callback. Zero-terminates the stored data.
selection_data |
a pointer to a CtkSelectionData. |
|
type |
the type of selection data |
|
format |
format (number of bits in a unit) |
|
data |
pointer to the data (will be copied). |
[array length=length] |
length |
length of the data |
gboolean ctk_selection_data_set_text (CtkSelectionData *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
.
guchar *
ctk_selection_data_get_text (const CtkSelectionData *selection_data);
Gets the contents of the selection data as a UTF-8 string.
gboolean ctk_selection_data_set_pixbuf (CtkSelectionData *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
.
Since: 2.6
GdkPixbuf *
ctk_selection_data_get_pixbuf (const CtkSelectionData *selection_data);
Gets the contents of the selection data as a GdkPixbuf.
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().
[nullable][transfer full]
Since: 2.6
gboolean ctk_selection_data_set_uris (CtkSelectionData *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 |
||
uris |
a |
[array zero-terminated=1] |
Since: 2.6
gchar **
ctk_selection_data_get_uris (const CtkSelectionData *selection_data);
Gets the contents of the selection data as array of URIs.
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().
[array zero-terminated=1][element-type utf8][transfer full]
Since: 2.6
gboolean ctk_selection_data_get_targets (const CtkSelectionData *selection_data,CdkAtom **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 CtkSelectionData object |
|
targets |
location to store an array of targets. The result stored
here must be freed with |
[out][array length=n_atoms][transfer container] |
n_atoms |
location to store number of items in |
gboolean ctk_selection_data_targets_include_image (const CtkSelectionData *selection_data,gboolean writable);
Given a CtkSelectionData object holding a list of targets,
determines if any of the targets in targets
can be used to
provide a GdkPixbuf.
selection_data |
a CtkSelectionData object |
|
writable |
whether to accept only targets for which CTK+ knows how to convert a pixbuf into the format |
TRUE if selection_data
holds a list of targets,
and a suitable target for images is included, otherwise FALSE.
Since: 2.6
gboolean
ctk_selection_data_targets_include_text
(const CtkSelectionData *selection_data);
Given a CtkSelectionData object holding a list of targets,
determines if any of the targets in targets
can be used to
provide text.
gboolean
ctk_selection_data_targets_include_uri
(const CtkSelectionData *selection_data);
Given a CtkSelectionData object holding a list of targets,
determines if any of the targets in targets
can be used to
provide a list or URIs.
TRUE if selection_data
holds a list of targets,
and a suitable target for URI lists is included, otherwise FALSE.
Since: 2.10
gboolean ctk_selection_data_targets_include_rich_text (const CtkSelectionData *selection_data,CtkTextBuffer *buffer);
Given a CtkSelectionData object holding a list of targets,
determines if any of the targets in targets
can be used to
provide rich text.
TRUE if selection_data
holds a list of targets,
and a suitable target for rich text is included,
otherwise FALSE.
Since: 2.10
CdkAtom
ctk_selection_data_get_selection (const CtkSelectionData *selection_data);
Retrieves the selection CdkAtom of the selection data.
Since: 2.16
const guchar *
ctk_selection_data_get_data (const CtkSelectionData *selection_data);
Retrieves the raw data of the selection.
[skip]
Since: 2.14
gint
ctk_selection_data_get_length (const CtkSelectionData *selection_data);
Retrieves the length of the raw data of the selection.
Since: 2.14
const guchar * ctk_selection_data_get_data_with_length (const CtkSelectionData *selection_data,gint *length);
Retrieves the raw data of the selection along with its length.
[rename-to ctk_selection_data_get_data]
selection_data |
a pointer to a CtkSelectionData. |
|
length |
return location for length of the data segment. |
[out] |
Since: 3.0
CdkAtom
ctk_selection_data_get_data_type (const CtkSelectionData *selection_data);
Retrieves the data type of the selection.
Since: 2.14
CdkDisplay *
ctk_selection_data_get_display (const CtkSelectionData *selection_data);
Retrieves the display of the selection.
Since: 2.14
gint
ctk_selection_data_get_format (const CtkSelectionData *selection_data);
Retrieves the format of the selection.
Since: 2.14
CdkAtom
ctk_selection_data_get_target (const CtkSelectionData *selection_data);
Retrieves the target of the selection.
Since: 2.14
gboolean ctk_targets_include_image (CdkAtom *targets,gint n_targets,gboolean writable);
Determines if any of the targets in targets
can be used to
provide a GdkPixbuf.
targets |
an array of CdkAtoms. |
[array length=n_targets] |
n_targets |
the length of |
|
writable |
whether to accept only targets for which CTK+ knows how to convert a pixbuf into the format |
Since: 2.10
gboolean ctk_targets_include_text (CdkAtom *targets,gint n_targets);
Determines if any of the targets in targets
can be used to
provide text.
Since: 2.10
gboolean ctk_targets_include_uri (CdkAtom *targets,gint n_targets);
Determines if any of the targets in targets
can be used to
provide an uri list.
Since: 2.10
gboolean ctk_targets_include_rich_text (CdkAtom *targets,gint n_targets,CtkTextBuffer *buffer);
Determines if any of the targets in targets
can be used to
provide rich text.
targets |
an array of CdkAtoms. |
[array length=n_targets] |
n_targets |
the length of |
|
buffer |
Since: 2.10
void
ctk_selection_remove_all (CtkWidget *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.
CtkSelectionData *
ctk_selection_data_copy (const CtkSelectionData *data);
Makes a copy of a CtkSelectionData and its data.
void
ctk_selection_data_free (CtkSelectionData *data);
Frees a CtkSelectionData returned from
ctk_selection_data_copy().
struct CtkTargetEntry {
gchar *target;
guint flags;
guint info;
};
A CtkTargetEntry 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.
a string representation of the target type |
||
CtkTargetFlags for DND |
||
an application-assigned integer ID which will get passed as a parameter to e.g the “selection-get” signal. It allows the application to identify the target type without extensive string compares. |
typedef struct _CtkTargetList CtkTargetList;
A CtkTargetList is a reference counted list of CtkTargetPair and should be treated as opaque.
struct CtkTargetPair {
CdkAtom target;
guint flags;
guint info;
};
A CtkTargetPair is used to represent the same information as a table of CtkTargetEntry, but in an efficient form.
CdkAtom |
CdkAtom representation of the target type |
|
CtkTargetFlags for DND |
||
an application-assigned integer ID which will get passed as a parameter to e.g the “selection-get” signal. It allows the application to identify the target type without extensive string compares. |
CtkWidget - Much of the operation of selections happens via signals for CtkWidget. In particular, if you are using the functions in this section, you may need to pay attention to “selection-get”, “selection-received” and “selection-clear-event” signals