Récupérer la sélection est un processus asynchrone. Pour démarrer le processus, on appelle :

  result = widget.selection_convert(selection, target, time=0)

Ceci convertit la sélection selection au format indiqué par le paramètre cible target. La selection est un atome conforme au type de sélection; les sélections courantes sont les chaînes de caractères :

  PRIMARY

  SECONDARY

Si c'est possible, le champ temps time devrait être le moment où se produit l'événement qui a déclenché la sélection. Cela aide à s'assurer que les événements se produisent dans l'ordre dans lequel l'utilisateur les a demandés. Cependant, si ce n'est pas disponible (par exemple, si la conversion a été déclenchée par un signal "clicked"), on peut utiliser la valeur 0 qui indique l'utilisation du moment actuel. Le paramètre result vaut TRUE si la conversion réussit, FALSE dans le cas contraire.

Quand le propriétaire de la sélection répond à la requête, un signal "selection_received" est envoyé à votre application. Le gestionnaire de ce signal reçoit un objet gtk.SelectionData qui posséde les attributs suivants :

  selection
  target
  type
  format
  data

Les paramètres selection et target sont les valeurs que l'on a donné dans la méthode selection_convert().

Le paramètre type est un atome qui identifie le type de données renvoyées par le propriétaire de la sélection. Quelques unes des valeurs possibles sont "STRING", une chaîne de caractères en latin-1, "ATOM", une série d'atomes, "INTEGER", un nombre entier, "image/x-xpixmap", etc. la plupart des cibles ne peuvent renvoyer qu'un seul type.

Voici la liste des atomes standards dans X et GTK+ :

  PRIMARY
  SECONDARY
  ARC
  ATOM
  BITMAP
  CARDINAL
  COLORMAP
  CURSOR
  CUT_BUFFER0
  CUT_BUFFER1
  CUT_BUFFER2
  CUT_BUFFER3
  CUT_BUFFER4
  CUT_BUFFER5
  CUT_BUFFER6
  CUT_BUFFER7
  DRAWABLE
  FONT
  INTEGER
  PIXMAP
  POINT
  RECTANGLE
  RESOURCE_MANAGER
  RGB_COLOR_MAP
  RGB_BEST_MAP
  RGB_BLUE_MAP
  RGB_DEFAULT_MAP
  RGB_GRAY_MAP
  RGB_GREEN_MAP
  RGB_RED_MAP
  STRING
  VISUALID
  WINDOW
  WM_COMMAND
  WM_HINTS
  WM_CLIENT_MACHINE
  WM_ICON_NAME
  WM_ICON_SIZE
  WM_NAME
  WM_NORMAL_HINTS
  WM_SIZE_HINTS
  WM_ZOOM_HINTS
  MIN_SPACE
  NORM_SPACE
  MAX_SPACE  END_SPACE,
  SUPERSCRIPT_X
  SUPERSCRIPT_Y
  SUBSCRIPT_X
  SUBSCRIPT_Y
  UNDERLINE_POSITION
  UNDERLINE_THICKNESS
  STRIKEOUT_ASCENT
  STRIKEOUT_DESCENT
  ITALIC_ANGLE
  X_HEIGHT
  QUAD_WIDTH
  WEIGHT
  POINT_SIZE
  RESOLUTION
  COPYRIGHT
  NOTICE
  FONT_NAME
  FAMILY_NAME
  FULL_NAME
  CAP_HEIGHT
  WM_CLASS
  WM_TRANSIENT_FOR
  CLIPBOARD

Le paramètre format fournit la longueur des unités (par exemple, les caractères) en bits. En général, on ne s'en soucie pas lorsqu'on reçoit les données.

Le paramètre data représente les données renvoyées sous la forme d'une chaîne de caractères.

PyGTK organise toutes les données reçues dans une chaîne de caractères. Ceci rend facile la manipulation des cibles chaînes. Pour récupérer les autres types (par exemple ATOM ou INTEGER), le programme doir extraire l'information de la chaîne renvoyée. PyGTK fournit deux méthodes pour récupérer le texte et une liste de cibles à partir des données de la sélection.

  text = selection_data.get_text()

  targets = selection_data.get_targets()

... où le paramètre text est une chaîne de caractères qui contient le texte de la sélection et targets est une liste des cibles reconnues par la sélection.

Étant donnée une gtk.SelectionData contenant une liste de cibles, la méthode :

  has_text = selection_data.targets_include_text()

... doit renvoyer TRUE si une ou plusieurs cibles peuvent fournir un texte.

Le programme getselection.py illustre la récupération de cibles "STRING" ou "TARGETS" à partir de la sélection primaire et écrit les données correspondantes sur la console quand on clique sur le bouton associé. La Figure 21.1, « Exemple de récupération de sélection » montre un aperçu du programme  :

Figure 21.1. Exemple de récupération de sélection

Voici le code du programme getselection.py :

     1   #!/usr/bin/env python
     2   # -*- coding:utf-8 -*-
     3   # exemple getselection.py
     4   
     5   import pygtk
     6   pygtk.require('2.0')
     7   import gtk
     8   
     9   class GetSelectionExample:
    10       # Gestionnaire de signal invoqué quand l'utilisateur
    11       # clique sur le bouton "Contenu de la cible"
    12       def get_stringtarget(self, widget):
    13           # Et demande la cible "STRING" pour la sélection primaire
    14           ret = widget.selection_convert("PRIMARY", "STRING")
    15           return
    16   
    17       # Gestionnaire de signal invoqué quand l'utilisateur clique sur le bouton "Liste des cibles"
    18       def get_targets(self, widget):
    19           # Et demande la cible "TARGETS" pour la sélection primaire
    20           ret = widget.selection_convert("PRIMARY", "TARGETS")
    21           return
    22   
    23       # Gestionnaire de signal appelé quand le propriétaire de la sélection retourne les données
    24       def selection_received(self, widget, selection_data, data):
    25           # On s'assure que les données sont au bon format
    26           if str(selection_data.type) == "STRING":
    27               # On affiche la chaîne reçue
    28               print "STRING TARGET: %s" % selection_data.get_text()
    29   
    30           elif str(selection_data.type) == "ATOM":
    31               # On affiche la liste des cibles que l'on reçoit
    32               targets = selection_data.get_targets()
    33               for target in targets:
    34                   name = str(target)
    35                   if name != None:
    36                       print "%s" % name
    37                   else:
    38                       print "(mauvaise cible)"
    39           else:
    40               print "La sélection n'est pas un \"STRING\" ou un \"ATOM\" !"
    41   
    42           return False
    43     
    44   
    45       def __init__(self):
    46           # Création de la fenêtre de niveau supérieur
    47           window = gtk.Window(gtk.WINDOW_TOPLEVEL)
    48           window.set_title("Get Selection")
    49           window.set_border_width(10)
    50           window.connect("destroy", lambda w: gtk.main_quit())
    51   
    52           vbox = gtk.VBox(False, 0)
    53           window.add(vbox)
    54           vbox.show()
    55   
    56           # Création du bouton pour obtenir la contenu chaîne de la cible
    57           button = gtk.Button("Contenu de la cible")
    58           eventbox = gtk.EventBox()
    59           eventbox.add(button)
    60           button.connect_object("clicked", self.get_stringtarget, eventbox)
    61           eventbox.connect("selection_received", self.selection_received)
    62           vbox.pack_start(eventbox)
    63           eventbox.show()
    64           button.show()
    65   
    66           # Création du bouton pour obtenir les formats de cible acceptés
    67           button = gtk.Button("Liste des cibles")
    68           eventbox = gtk.EventBox()
    69           eventbox.add(button)
    70           button.connect_object("clicked", self.get_targets, eventbox)
    71           eventbox.connect("selection_received", self.selection_received)
    72           vbox.pack_start(eventbox)
    73           eventbox.show()
    74           button.show()
    75   
    76           window.show()
    77   
    78   def main():
    79       gtk.main()
    80       return 0
    81   
    82   if __name__ == "__main__":
    83       GetSelectionExample()
    84       main()

Les lignes 30-38 se chargent d'obtenir les données de sélection des "TARGETS" et impriment la liste des noms de cibles. Les boutons sont inclus dans leur propre boîtes à évènements car une sélection doit être associée à un gtk.gdkWindow alors que les boutons sont des widgets sans fenêtre dans GTK+2.0.