Un control EntryCompletion es un objeto que se usa con un control de entrada Entry para proporcionar la funcionalidad de completado. Cuando la usuaria escribe en la entrada Entry, el EntryCompletion mostrará una ventana con un conjunto de cadenas que coinciden con el texto parcial del Entry.

Un EntryCompletion se crea con el constructor:

  completion = gtk.EntryCompletion()

Se puede usar el método Entry. set_completion() para asociar un EntryCompletion a una entrada Entry:

  entry.set_completion(completion)

Las cadenas usadas por el EntryCompletion para buscar coincidencias se obtienen desde un TreeModel (generalmente un almacén de lista ListStore), que debe ser asignado usando el método:

  completion.set_model(model)

El EntryCompletion implementa la interfaz CellLayout, al igual que la TreeViewColumn, para manejar la visulización de los datos del TreeModel. El siguiente método configura una EntryCompletion de la manera más habitual (una lista de cadenas):

  completion.set_text_column(column)

Este método es equivalente a:

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

Para establecer el número de caracteres que deben ser introducidos antes de que EntryCompletion comience a mostrar coincidencias se puede usar el método:

  completion.set_minimum_key_length(length)

El programa de ejemplo entrycompletion.py demuestra el uso de EntryCompletion. Figura 16.10, “Entrada con Completado (EntryCompletion)” ilustra el programa en ejecución.

Figura 16.10. Entrada con Completado (EntryCompletion)

El programa comienza con un pequeño número de cadenas para el completado que puede ser aumentado escribiendo en el campo de entrada y presionando la tecla Enter. Si la cadena es única entonce se agrega a la lista de cadenas de completado.

La función de coincidencias preconstruida no diferencia entre mayúsculas y minúsculas. Si se necesita una función más especializada, se puede usar el siguiente método para instalar una función propia:

  completion.set_match_func(func, user_data)

La signatura de func es:

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

donde key_string contiene el texto actual de la entrada Entry, iter es un iterador TreeIter que señala la fila del modelo TreeModel, y data son datos de usuario user_data. func debe devolver TRUE si la cadena de completado de la fila tiene que ser desplegada.

El fragmento de código mostrado a continuación usa una función de coincidencia para desplegar los nombres de completado que comienzan con el contenido de la entrada y tienen el sufijo dado, en este caso, un nombre terminado en .png para un archivo PNG.

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

Por ejemplo, si el usuario teclea 'foo' y el modelo de completado contiene cadenas como 'foobar.png', 'smiley.png', 'foot.png' y 'foo.tif', las cadenas 'foobar.png' y 'foot.png' deberían mostrarse como alternativas.