Une zone de saisie avec complètement (EntryCompletion) est un objet associé à un champ de saisie (Entry) pour fournir la fonction de complètement. Lorsque l'utilisateur entre des données dans le champ de saisie Entry, le EntryCompletion fait apparaître une fenêtre contextuelle montrant un ensemble de chaînes de caractères correspondant au texte du champ de saisie(Entry)

Un EntryCompletion est créé par le constructeur :

  completion = gtk.EntryCompletion()

On peut utiliser la méthode set_completion() du champ de saisie Entry pour associer le EntryCompletion au Entry :

  entry.set_completion(completion)

Les chaînes de caractères qu'utilise le EntryCompletion pour la correspondance sont récupérées depuis un TreeModel (généralement un ListStore) qui doit être défini par la méthode :

  completion.set_model(model)

Le EntryCompletion implémente l'interface CellLayout, à la manière du TreeViewColumn, pour gérer l'affichage des données du TreeModel. La méthode suivante définit un EntryCompletion sous la forme la plus courante - une liste de chaînes de caractères :

  completion.set_text_column(column)

Cette méthode est équivalente à  :

  cell = CellRendererText()
  completion.pack_start(cell)
  completion.add_attribute(cell, 'text', column)

Pour définir le nombre de caractères qui doivent être entrés avant que le EntryCompletion recherche une correspondance, on peut utiliser la méthode :

  completion.set_minimum_key_length(length)

Le programme d'exemple entrycompletion.py illustre l'utilisation du EntryCompletion. La Figure 16.10, « Saisie avec complètement » montre le programme en cours d'exécution.

Figure 16.10. Saisie avec complètement

Le programme d'exemple démarre avec un faible nombre de chaînes de complètement qui peut être augmenté en entrant des données dans le champ de saisie et en appuyant sur la touche Entrée. Si la chaîne est unique, elle est ajoutée à la liste des chaînes de complètement.

La fonction interne de concordance ne tient pas compte de la casse (minuscule/majuscule). Si on a besoin d'une fonction plus spécifique, il est possible d'utiliser la méthode suivante pour installer sa propre fonction de concordance :

  completion.set_match_func(func, user_data)

La fonction func est :

  def func(completion, key_string, iter, data):

... où le paramètre key_string contient le contenu courant du champ Entry, iter est un TreeIter pointant sur une ligne dans le TreeModel associé et data contient les données utilisateur user_data. Le paramètre func devrait renvoyer TRUE si la chaîne de complètement de la ligne devrait être affichée.

L'extrait de code suivant utilise une fonction de concordance pour afficher les possibles chaînes de complètement qui commencent par le contenu du champ de saisie et qui possèdent le suffixe indiqué (ici, un nom se terminant par .png pour un fichier PNG file.

  ...
  completion.set_match_func(end_match, (0, '.png'))
  ...
  def end_match(completion, entrystr, iter, data):
      column, suffix = data
      model = completion.get_model()
      modelstr = model[iter][column]
      return modelstr.startswith(entrystr) and modelstr.endswith(suffix)
  ...

Par exemple, si l'utilisateur tape 'mou' et que le modèle de complètement contient une chaîne comme 'moulin.png', 'farine.png', 'moule.png' et 'mou.tif', les choix 'moulin.png' et moule.png' seront proposés comme complètement.