Sélections

Sélections — Fonctions pour manipuler des interprocessus de communication via des sélections.

Synopsis

#include <gtk/gtk.h>


GtkTargetEntry;
GtkTargetList;
GtkTargetPair;
GtkTargetList* gtk_target_list_new (const GtkTargetEntry *targets,
guint ntargets);
GtkTargetList* 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_add_rich_text_targets
(GtkTargetList *list,
guint info,
gboolean deserializable,
GtkTextBuffer *buffer);
void gtk_target_list_remove (GtkTargetList *list,
GdkAtom target);
gboolean gtk_target_list_find (GtkTargetList *list,
GdkAtom target,
guint *info);
void gtk_target_table_free (GtkTargetEntry *targets,
gint n_targets);
GtkTargetEntry* gtk_target_table_new_from_list (GtkTargetList *list,
gint *n_targets);
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);
gboolean gtk_selection_data_targets_include_uri
(GtkSelectionData *selection_data);
gboolean gtk_selection_data_targets_include_rich_text
(GtkSelectionData *selection_data,
GtkTextBuffer *buffer);
gboolean gtk_targets_include_image (GdkAtom *targets,
gint n_targets,
gboolean writable);
gboolean gtk_targets_include_text (GdkAtom *targets,
gint n_targets);
gboolean gtk_targets_include_uri (GdkAtom *targets,
gint n_targets);
gboolean gtk_targets_include_rich_text (GdkAtom *targets,
gint n_targets,
GtkTextBuffer *buffer);
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);

Description

Le mécanisme de la sélection fournit les bases pour différents types de communication entre processus.  En particulier, le glisser-déposer et GtkClipboard fonctionnent via des selections. Vous aurez  très rarement, voir jamais besoin d'utiliser la plupart des fonctions de cette section directement;  GtkClipboard fournit un  interface plus agréable pour la même fonctionnalité.

Certains types de données décrits dans cette section sont utilisés dans le GtkClipboard et l'API du glisser-déposer également.La structure GtkTargetEntry et les objets GtkTargetList représentent les listes de types de données supportées  pendant l'envoie ou la réception de données. L'objet GtkSelectionData est utilisé pour stocker un paquet de données avec le type de données et d'autres informations associées.

Details

GtkTargetEntry


typedef struct {
gchar *target;
guint flags;
guint info;
} GtkTargetEntry;

Une structure  GtkTargetEntry représente un seule type de données qui peuvent être fournies par un widget pour une sélection ou pour   un envoie ou une réception pendant un glisser-déposer. Elle contient une chaîne représentant le type de "glisser", un champ de flags (utilisé seulement pour le glisser-déposer - voir GtkTargetFlags), et un ID entier assigné à l'application. L'ID entier sera passé plus tard comme un paramètre du signal pour des signaux tel que  "selection_get". Cela permet à l'application d'identifier le type de cible  sans comparer la chaîne étendue.

GtkTargetList


typedef struct {
GList *list;
guint ref_count;
} GtkTargetList;

Une structure GtkTargetList  est une liste comptée par référence de  GtkTargetPair. Elle est utilisée pour répréenter les mêmes informations qu'une table de GtkTargetEntry, mais sous une forme  efficiente. Cette structure doit être traitée comme "opaque"(?).

GtkTargetPair


typedef struct {
GdkAtom target;
guint flags;
guint info;
} GtkTargetPair;

Structure utilisée en interne dans le glisser-déposer et le code de manipulation de sélection.

gtk_target_list_new ()


GtkTargetList*      gtk_target_list_new                 (const GtkTargetEntry *targets,
guint ntargets);

Créé un nouveau  GtkTargetList à partir d'un tableau de GtkTargetEntry.

targets : Pointeur sur un tableau de  GtkTargetEntry
ntargets : nombre d'entrées dans targets.
Retourne : le nouveau  GtkTargetList.

gtk_target_list_ref ()


GtkTargetList*      gtk_target_list_ref                 (GtkTargetList *list);

Augmente  de 1 le compteur de référence d'un  GtkTargetList .

list : un GtkTargetList
Retourne : ce qui est passé dans  (the passed in) GtkTargetList.

gtk_target_list_unref ()


void                gtk_target_list_unref               (GtkTargetList *list);

Diminue de 1 le compteur de référence de  GtkTargetList . Si le résultat du compteur de référence est zéro, la liste est libérée.

list : un  GtkTargetList

gtk_target_list_add ()


void                gtk_target_list_add                 (GtkTargetList *list,
GdkAtom target,
guint flags,
guint info);

Ajoute une autre cible à un  GtkTargetList.
list : un GtkTargetList
target : atome interne représentant la cible
flags : flags pour la cible
info : un ID qui sera passé après à l'application

gtk_target_list_add_table ()


void                gtk_target_list_add_table           (GtkTargetList *list,
const GtkTargetEntry *targets,
guint ntargets);

Ajoute une table de GtkTargetEntry à une liste de cibles.
list : un GtkTargetList
targets : la table de GtkTargetEntry
ntargets : nombre de cibles dans la table

gtk_target_list_add_text_targets ()


void                gtk_target_list_add_text_targets    (GtkTargetList *list,
guint info);

Ajoute les cibles texte supportés par GtkSelection à la liste de cibles. Tous les cibles sont ajoutées avec la même info.
list : un GtkTargetList
info : un  ID qui sera passé après à l'application

Depuis 2.6


gtk_target_list_add_image_targets ()


void                gtk_target_list_add_image_targets   (GtkTargetList *list,
guint info,
gboolean writable);

Ajoute les cibles images supportées par GtkSelection à la liste des cibles. Toutes les cibles sont ajoutées avec la même info.
list : un GtkTargetList
info : un ID qui sera passé après à l'application
writable : pour ajouter seulement les cibles pour lesquelles GTK+ sait comment convertir un pixbuf dans le format

Depuis 2.6


gtk_target_list_add_uri_targets ()


void                gtk_target_list_add_uri_targets     (GtkTargetList *list,
guint info);

Ajoute les cibles URI supportées par GtkSelection à la liste des cibles.rget list.  Toutes les cibles sont ajoutées avec la même info.

list : un GtkTargetList
info : un  ID qui sera passé après à l'application

Depuis 2.6


gtk_target_list_add_rich_text_targets ()


void                gtk_target_list_add_rich_text_targets
(GtkTargetList *list,
guint info,
gboolean deserializable,
GtkTextBuffer *buffer);

Ajoute les cibles rich texte enregistrées avec gtk_text_buffer_register_serialize_format() ou gtk_text_buffer_register_deserialize_format() à la liste des cibles.  Toutes les cibles sont ajoutées avec la même info.
list : un GtkTargetList
info : un  ID qui sera passé après à l'application
deserializable : si TRUE, alors des formats rich texte deserializable seront ajoutés, des formats serializable autrement.
buffer : un GtkTextBuffer.

Depuis 2.10


gtk_target_list_remove ()


void                gtk_target_list_remove              (GtkTargetList *list,
GdkAtom target);

Supprime une cible d'une liste de cibles.

list : un GtkTargetList
target : atome interne représentant la cible

gtk_target_list_find ()


gboolean            gtk_target_list_find                (GtkTargetList *list,
GdkAtom target,
guint *info);

Recherche une cible données dans un  GtkTargetList.

list : un GtkTargetList
target : un atome interne représentant la cible recherchée.
info : un pointeur sur l'endroit où stocker les information de l'application pour la cible.
Retourne : TRUE si la cible a été trouvée, autrement FALSE

gtk_target_table_free ()


void                gtk_target_table_free               (GtkTargetEntry *targets,
gint n_targets);

Cette fonction lébère une table de cibles comme celle retournée par  gtk_target_table_new_from_list()

targets : un tableau GtkTargetEntry 
n_targets : le nombre d'entrées dans le tableau

Depuis 2.10


gtk_target_table_new_from_list ()


GtkTargetEntry*     gtk_target_table_new_from_list      (GtkTargetList *list,
gint *n_targets);

Cette fonction créé un tableau  GtkTargetEntry qui contient les mêmes cibles que celles qui sont passée à  list.La table retournée est nouvellement allouée et doit être libérée en utilisant  gtk_target_table_free() quand elle n'est plus nécessaire.

list : un GtkTargetList
n_targets : retourne l'endroit pour ne nombre de cibles dans la table
Retourne : la nouvelle table

Depuis 2.10


gtk_selection_owner_set ()


gboolean            gtk_selection_owner_set             (GtkWidget *widget,
GdkAtom selection,
guint32 time_);

Réclame la propriété d'une sélection donnée pour un widget particulier, ou, si  widget est NULL, libére la propriété de la sélection.

widget : un GtkWidget, ou NULL.
selection : un atome interne représentant la sélection réclamée
time_ : timestamp avec lequel la sélection est réclamée
Retourne : TRUE si l'opération a réussi

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

Since 2.2


gtk_selection_add_target ()


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.

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

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

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_set_pixbuf ()


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


gtk_selection_data_get_pixbuf ()


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


gtk_selection_data_set_uris ()


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


gtk_selection_data_get_uris ()


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


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_image ()


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


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_data_targets_include_uri ()


gboolean gtk_selection_data_targets_include_uri
(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 a list or URIs.

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.

Since 2.10


gtk_selection_data_targets_include_rich_text ()


gboolean gtk_selection_data_targets_include_rich_text
(GtkSelectionData *selection_data,
GtkTextBuffer *buffer);

Given a GtkSelectionData object holding a list of targets, determines if any of the targets in targets can be used to provide rich text.

selection_data : a GtkSelectionData object
buffer : a GtkTextBuffer
Returns : TRUE if selection_data holds a list of targets, and a suitable target for rich text is included, otherwise FALSE.

Since 2.10


gtk_targets_include_image ()


gboolean gtk_targets_include_image (GdkAtom *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 GdkAtoms
n_targets : the length of targets
writable : whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format
Returns : TRUE if targets include a suitable target for images, otherwise FALSE.

Since 2.10


gtk_targets_include_text ()


gboolean gtk_targets_include_text (GdkAtom *targets,
gint n_targets);

Determines if any of the targets in targets can be used to provide text.

targets : an array of GdkAtoms
n_targets : the length of targets
Returns : TRUE if targets include a suitable target for text, otherwise FALSE.

Since 2.10


gtk_targets_include_uri ()


gboolean gtk_targets_include_uri (GdkAtom *targets,
gint n_targets);

Determines if any of the targets in targets can be used to provide an uri list.

targets : an array of GdkAtoms
n_targets : the length of targets
Returns : TRUE if targets include a suitable target for uri lists, otherwise FALSE.

Since 2.10


gtk_targets_include_rich_text ()


gboolean gtk_targets_include_rich_text (GdkAtom *targets,
gint n_targets,
GtkTextBuffer *buffer);

Determines if any of the targets in targets can be used to provide rich text.

targets : an array of GdkAtoms
n_targets : the length of targets
buffer : a GtkTextBuffer
Returns : TRUE if targets include a suitable target for rich text, otherwise FALSE.

Since 2.10


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_clear ()


gboolean gtk_selection_clear (GtkWidget *widget,
GdkEventSelection *event);

Warning

gtk_selection_clear has been deprecated since version 2.4 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


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.

Voir Aussi

GtkWidget

Much of the operation of selections happens via signals for GtkWidget. 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.