Toutes les sous-classes TreeModel implémentent l'interface TreeModel. Elle fournit des méthodes pour :

• récupérer les caractéristiques du modèle, telles que le nombre de colonnes et le type de données dans une colonne ;
• récupérer un TreeIter (une référence temporaire pointant sur une ligne du modèle) ;
• récupérer des informations sur un nœud (ou une ligne) comme une liste de ses nœuds enfants, leur nombre, le contenu de ses colonnes ou un pointeur sur son nœud parent ;
• obtenir des notifications de changement des données du TreeModel

Les classes de base de stockage des données, le ListStore et le TreeStore, permettent de définir et de manipuler les lignes et les colonnes de données dans le modèle. Dans les constructeurs de ces deux objets, les colonnes devront être déclarées comme étant de l'un des types suivants :

• un type Python, comme les types prédéfinis int, str, long, float et object ;
• un type PyGTK, comme les Button, VBox, gdk.Rectangle, gdk.Pixbuf ;

• un type GObject (les GTypes de GTK+), spécifié sous la forme soit d'une constante gobject.TYPE, soit d'une chaîne de caractères. La majorité des GTypes sont mappés sur un type Python :

  • gobject.TYPE_CHAR ou 'gchar',
  • gobject.TYPE_UCHAR ou 'guchar',
  • gobject.TYPE_BOOLEAN ou 'gboolean',
  • gobject.TYPE_INT ou 'gint',
  • gobject.TYPE_UINT ou 'guint',
  • gobject.TYPE_LONG ou 'glong',
  • gobject.TYPE_ULONG ou 'gulong',
  • gobject.TYPE_INT64 ou 'gint64',
  • gobject.TYPE_UINT64 ou 'guint64',
  • gobject.TYPE_FLOAT ou 'gfloat',
  • gobject.TYPE_DOUBLE ou 'gdouble',
  • gobject.TYPE_STRING ou 'gchararray',
  • gobject.TYPE_OBJECT ou 'Gobject.

Par exemple, la création d'un ListStore ou d'un TreeStore dont les lignes contiendraient un gdk.Pixbuf, un entier, une chaîne et un booléen, pourrait ressembler à ceci :

  liststore = ListStore(gtk.gdk.Pixbuf, int, str, 'gboolean')

  treestore = TreeStore(gtk.gdk.Pixbuf, int, str, 'gboolean')

Une fois un ListStore ou un TreeStore créé et ses colonnes définies, ils ne peuvent plus être modifiés. Il est également important de savoir qu'il n'y a pas de relation prédéfinie entre les colonnes d'un TreeView et celles de son TreeModel. Ainsi, la cinquième colonne de données d'un TreeModel peut être affichée dans la première colonne d'un TreeView et dans la troisième d'un autre. On n'a donc pas à se soucier de l'affichage des données lorsque l'on crée un modèle.

Si ces deux modèles ne conviennent pas à votre application, il est possible de définir votre propre modèle personnalisé en Python, pourvu qu'il implémente l'interface TreeModel. Nous verrons ceci plus en détail dans la Section 14.11, « Le TreeModel générique »Le TreeModel générique.

Avant de pouvoir manipuler des lignes de données dans un TreeStore ou un ListStore, il nous faut pouvoir désigner les lignes à traiter. PyGTK offre trois moyens de faire référence à des lignes de TreeModel : le chemin d'accès, le TreeIter et le TreeRowReference.

14-2-3-1. Le chemin d'accès▲

  chemin = modele.get_path(iter)

14-2-3-2. Les TreeIter▲

  treeiter = modele.get_iter(path)

  treeiter = modele.get_iter_first()

  treeiter = modele.iter_next(iter)

  treeiter = treestore.iter_children(parent)

  treeiter = treestore.iter_nth_child(parent, n)

  treeiter = treestore.iter_parent(child)

  chemin = modele.get_path(iter)

14-2-3-3. Les TreeRowReference▲

  treerowref = TreeRowReference(model, path)

14-2-4-1. Ajouter des lignes à un ListStore▲

  iter = append(row=None)
  iter = prepend(row=None)
  iter = insert(position, row=None)
  iter = insert_before(sibling, row=None)
  iter = insert_after(sibling, row=None)

  ...
  liststore = gtk.ListStore(int, str, gtk.gdk.Color)
  liststore.append([0,'red',colormap.alloc_color('red')])
  liststore.append([1,'green',colormap.alloc_color('green')])
  iter = liststore.insert(1, (2,'blue',colormap.alloc_color('blue')) )
  iter = liststore.insert_after(iter, [3,'yellow',colormap.alloc_color('blue')])
  ...

14-2-4-2. Ajouter des lignes à un TreeStore▲

  iter = append(parent, row=None)
  iter = prepend(parent, row=None)
  iter = insert(parent, position, row=None)
  iter = insert_before(parent, sibling, row=None)
  iter = insert_after(parent, sibling, row=None)

  ...
  pbdossier = gtk.gdk.pixbuf_from_file('dossier.xpm')
  pbfichier = gtk.gdk.pixbuf_from_file('fichier.xpm')
  treestore = gtk.TreeStore(int, str, gtk.gdk.Pixbuf)
  iter0 = treestore.append(None, [1,'(0,)',pbdossier] )
  treestore.insert(iter0, 0, [11,'(0,0)',pbfichier])
  treestore.append(iter0, [12,'(0,1)',pbfichier])
  iter1 = treestore.insert_after(None, iter0, [2,'(1,)',pbdossier])
  treestore.insert(iter1, 0, [22,'(1,1)',pbfichier])
  treestore.prepend(iter1, [21,'(1,0)',pbfichier])
  ...

14-2-4-3. Modèles de grande taille▲

14-2-5-1. Supprimer des lignes d'un ListStore▲

  treeiter = liststore.remove(iter)

  liststore.clear()

14-2-5-2. Supprimer des lignes d'un TreeStore▲

  result = treestore.remove(iter)
  treestore.clear()

14-2-6-1. Définir et récupérer des valeurs▲

  valeur = modele.get_value(iter, column)

  valeurs = modele.get(iter, column, ...)

  val0, val2 = modele.get(iter, 0, 2)

  modele.set_value(iter, column, value)

  modele.set(iter, ...)

  modele.set(iter, 0, 'Foo', 5, 'Bar', 1, 123)

14-2-6-2. Réordonner les lignes d'un ListStore▲

  liststore.swap(a, b)
  liststore.move_after(iter, position)
  liststore.move_before(iter, position)

  liststore.reorder(nouvel_ordre)

  nouvel_ordre[nouvelleposition] = ancienneposition

  'un'
  'deux'
  'trois'
  'quatre'

  liststore.reorder([2, 1, 3, 0])

  'trois'
  'deux'
  'quatre'
  'un'

14-2-6-3. Réordonner les lignes d'un TreeStore▲

  treestore.swap(a, b)
  treestore.move_after(iter, position)
  treestore.move_before(iter, position)

  treestore.reorder(parent, new_order)

  new_order[nouvelleposition] = ancienneposition

  'ligne parent'
      'un'
      'deux'
      'trois'
      'quatre'

  treestore.reorder(parent, [2, 1, 3, 0])

  'ligne parent'
      'trois'
      'deux'
      'quatre'
      'un'

14-2-6-4. Manipuler plusieurs lignes▲

  def deplace_enfants(treestore, parent_source, parent_destination):
    nb_colonnes = treestore.get_n_columns()
    iter = treestore.iter_children(parent_source)
    while iter:
      valeurs = treestore.get(iter, *range(nb_colonnes))
      treestore.remove(iter)
      treestore.append(parent_destination, valeurs)
      iter = treestore.iter_children(parent_source)
    return

  modele.foreach(fonction, donnees_utilisateur)

  def fonction(modele, chemin, iter, donnees_utilisateur):

  ...
  # On vérifie que la valeur de la première colonne >= la valeur transmise
  # données est un tuple contenant la valeur de comparaison ainsi qu'une liste
  # pour sauvegarder les chemins d'accès
  def rappel_compar_valeur(modele, chemin, iter, donnees):
    if modele.get_value(iter, 0) >= donnees[0]:
      donnees[1].append(chemin)
    return False     # foreach continue d'itérer

  listechemins = []
  treestore.foreach(rappel_compar_valeur, (10, listechemins))

  # foreach fonctionne en profondeur d'abord (depth-first)
  listechemins.reverse()
  for chemin in listechemins:
    treestore.remove(treestore.get_iter(chemin))
  ...

   treestore = TreeStore(str)
   ...
   def fonction_compar(modele, iter, donnees):
       colonne, critere = donnees # donnes est un tuple contenant un numéro de colonne et un critère
       valeur = modele.get_value(iter, colonne)
       return valeur == critere
   def recherche(modele, iter, fonction, donnees):
       while iter:
           if fonction(modele, iter, donnees):
               return iter
           resultat = recherche(modele, modele.iter_children(iter), fonction, donnees)
           if resultat: return resultat
           iter = modele.iter_next(iter)
       return None
   ...
   compar_iter = recherche(treestore, treestore.iter_children(None), 
                       fonction_compar, (0, 'bla'))

Les classes qui implémentent l'interface TreeModel (TreeStore, ListStore et, à partir de PyGTK 2.4 TreeModelSort et TreeModelFilter) supportent les protocoles Python de mappage et d'itération. Le protocole d'itération permet d'utiliser la fonction iter() de Python sur un Treemodel pour créer un itérateur qui servira à itérer sur ses lignes de premier niveau. Une possibilité plus utile est d'itérer en utilisant l'instruction for ou une création fonctionnelle de liste (list comprehension). Par exemple :

  ...
  liststore = gtk.ListStore(str, str)
  ...
  # on ajoute des lignes au ListStore
  ...
  # une boucle for
  for ligne in liststore:
      # traitement individuel des lignes
  ...
  # création fonctionnelle de liste renvoyant une liste des valeurs de la première colonne
  valeurs = [ l[0] for l in liststore ]
  ...

L'utilisation de del pour supprimer une ligne du modèle et l'extraction d'un TreeModelRow PyGTK de ce dernier à partir d'une valeur-clé qui est un chemin d'accès ou un TreeIter, sont d'autres parties supportées des protocoles de mappage. Par exemple, les instructions suivantes renvoient toutes la première ligne d'un TreeModel et la dernière instruction supprime le premier enfant de la première ligne :

  ligne = modele[0]
  ligne = modele['0']
  ligne = modele["0"]
  ligne = modele[(0,)]
  i = modele.get_iter(0)
  ligne = modele[i]
  del modele[(0,0)]

De plus, on peut fixer les valeurs d'une ligne existante comme ceci :

  ...
  liststore = gtk.ListStore(str, int, object)
  ...
  liststore[0] = ['Bouton', 23, gtk.Button('Etiquette')]

Les objets TreeModelRow de PyGTK supportent les protocoles de séquence et d'itération Python. On peut faire en sorte qu'un itérateur itère sur les valeurs des colonnes de la ligne, ou bien utiliser l'instruction for ou encore une création fonctionnelle de liste. Les TreeModelRow utilisent le numéro de colonne comme l'index à partir duquel extraire une valeur. Par exemple :

  ...
  liststore = gtk.ListStore(str, int)
  liststore.append(['Chaine de caracteres', 514])
  ...
  ligne = liststore[0]
  valeur1 = ligne[1]
  valeur0 = liststore['0'][0]
  for valeur in ligne:
      print valeur
  val0, val1 = ligne
  ...

On utilise l'exemple de la section précédente pour itérer sur un TreeStore afin de localiser une ligne contenant une valeur particulière, le code devient :

   treestore = TreeStore(str)
   ...
   def fonction_compar(ligne, donnees):
       colonne, critere = donnees # "donnees" est un tuple contenant un numéro de colonne et un critère
       return ligne[colonne] == critere
   ...
   def recherche(lignes, fonction, donnees):
       if not lignes: return None
       for ligne in lignes:
           if fonction(ligne, donnees):
               return ligne
           resultat = recherche(ligne.iterchildren(), fonction, donnees)
           if resultat: return resultat
       return None
   ...
   compar_ligne = recherche(treestore, fonction_compar, (0, 'bla'))

On peut également définir une valeur dans une colonne existante ainsi :

  treestore[(1,0,1)][1] = 'abc'

Les TreeModelRow supportent aussi l'instruction del et la conversion en listes ou tuples avec les fonctions list() et tuple() de Python. Comme illustré dans l'exemple suivant, le TreeModelRow dispose de la méthode iterchildren() qui renvoie un itérateur pour itérer sur les lignes enfants du TreeModelRow.

Votre application peut suivre les changements d'un TreeModel en se connectant aux signaux qu'il émet : "row-changed", "row-deleted", "row-inserted", "row-has-child-toggled" et "rows-reordered". Ces signaux sont utilisés par un TreeView pour suivre les changements dans son TreeModel.

Dans une application connectée à ces signaux, l'appel de certaines méthodes peut déclencher l'émission de plusieurs signaux. Par exemple, l'appel pour ajouter à une ligne sa première ligne enfant :

  treestore.append(parent, ['qwe', 'asd', 123])

déclenchera l'émission des signaux suivants :

• "row-inserted" (ligne-insérée), du fait de l'insertion de la ligne (vide) ;
• "row-has-child-toggled" (ligne-possède-enfant-modifié), puisque parent n'avait pas de ligne enfant auparavant ;
• "row-changed" (ligne-modifiée), car la valeur de la première colonne est fixée à 'qwe' ;
• "row-changed" (ligne-modifiée), car la valeur de la deuxième colonne est fixée à 'asd' ;
• "row-changed" (ligne-modifiée), car la valeur de la troisième colonne est fixée à 123.

Notez qu'il n'est pas possible de récupérer l'ordre des lignes dans la fonction de rappel du signal "rows-reordered", car le nouvel ordre des lignes est transmis sous la forme d'un pointeur opaque vers un tableau d'entiers.

On trouvera plus d'information sur les signaux des TreeModel dans le PyGTK Reference Manual.

14-2-9-1. L'interface TreeSortable▲

  treesortable.set_sort_func(id_class_colonne, fonction_classement, donnees_utilisateur=None)

  def fonction_classement(modele, iter1, iter2, donnees)
  def methode_classement(self, modele, iter1, iter2, donnees)

  treesortable.set_sort_column_id(sort_column_id, order)

  treesortable.set_default_sort_func(fonction_classement, donnees_utilisateur=None)

  resultat = treesortable.has_default_sort_func()

14-2-9-2. Classement dans les ListStore et les TreeStore▲

On crée un TreeView en faisant appel à son constructeur :

  treeview = gtk.TreeView(model=None)

où model est un objet implémentant l'interface TreeModel (en général un ListStore ou un TreeStore). Si model vaut None ou n'est pas spécifié, le TreeView ne sera associé à aucun modèle.

Le modèle fournissant les données au TreeView peut être récupéré avec la méthode get_model() :

  modele = treeview.get_model()

Un TreeModel peut être associé simultanément avec plusieurs TreeView qui actualiseront automatiquement leur affichage lorsque les données du TreeModel seront modifiées. Si un TreeView affiche obligatoirement toutes les lignes de son modèle, il peut en revanche n'afficher que certaines des colonnes de ce dernier. Deux TreeView associés au même TreeModel peuvent donc donner deux affichages différents des mêmes données.

Il est également important de savoir qu'il n'y a pas de relation prédéfinie entre les colonnes d'un TreeView et celles de son TreeModel. Ainsi, la cinquième colonne de données d'un TreeModel peut être affichée dans la première colonne d'un TreeView et dans la troisième d'un autre.

Un TreeView peut changer de modèle grâce à la méthode set_model() :

  treeview.set_model(model=None)

où model est un objet implémentant l'interface TreeModel (par exemple, un ListStore ou un TreeStore). Si model vaut None, le modèle courant est abandonné.

Le TreeView dispose de plusieurs propriétés ainsi que de méthodes pour traiter ces dernières :

Les méthodes correspondantes sont les suivantes :

  autorise_rechercher = treeview.get_enable_search()
  treeview.set_enable_search(enable_search)

  colonne = treeview.get_expander_column()
  treeview.set_expander_column(column)

  ajustement_horizontal = treeview.get_hadjustment()
  treeview.set_hadjustment(adjustment)

  treeview.set_headers_clickable(active)

  entetes_visibles = treeview.get_headers_visible()
  treeview.set_headers_visible(headers_visible)

  reordonner = treeview.get_reorderable()
  treeview.set_reorderable(reorderable)

  alterner_couleurs = treeview.get_rules_hint()
  treeview.set_rules_hint(setting)

  colonne = treeview.get_search_column()
  treeview.set_search_column(column)

  ajustement_vertical = treeview.get_vadjustment()
  treeview.set_vadjustment(adjustment)

Si la plupart se passent de description, signalons cependant que pour activer la propriété "enable-search" il est nécessaire d'indiquer un numéro de colonne valide à "search-column". Quand l'utilisateur pressera la combinaison de touches Control+f, une boîte de dialogue de recherche apparaîtra alors, dans laquelle il pourra saisir le texte à rechercher. La première ligne correspondante sera automatiquement sélectionnée pendant la saisie du texte.

La propriété "headers-clickable" ne fait en réalité qu'activer la propriété "clickable" des TreeViewColumn sous-jacents. Un TreeViewColumn ne pourra pas être réordonné si le modèle n'implémente pas l'interface TreeSortable et si la méthode de TreeViewColumn set_sort_column_id() n'a pas été appelée avec un numéro de colonne valide.

La propriété "reorderable" permet à l'utilisateur de réordonner le modèle du TreeView en glissant-déposant les lignes affichées du TreeView.

La propriété "rules-hint" ne devrait être activée que dans les cas où l'on aurait beaucoup de colonnes et où l'on penserait qu'alterner les couleurs pourrait aider l'utilisateur.

Les TreeViewColumn et les CellRenderer travaillent ensemble pour afficher une colonne de données dans un TreeView. Le TreeViewColumn fournit un en-tête de colonne ainsi qu'un espace vertical que les CellRenderer utiliseront pour afficher une partie des données stockées dans le modèle du TreeView. Un CellRenderer prend en charge l'affichage des données de chaque ligne et colonne dans l'espace offert par le TreeViewColumn. Un TreeViewColumn peut contenir plusieurs CellRenderer pour afficher les lignes comme des HBox. On combine par exemple assez fréquemment un CellRendererPixbuf et un CellRendererText dans la même colonne.

La Figure 14.2, « TreeViewColumn avec CellRenderer » montre un exemple de disposition pour deux TreeViewColumn : l'un contenant deux CellRenderer et l'autre un seul.

L'application de chaque CellRenderer est indiquée avec une couleur d'arrière-plan : jaune pour le CellRendererPixbuf, cyan pour le CellRendererText et rose pour l'autre CellRendererText. Notez que le CellRendererPixbuf et le premier CellRendererText sont dans la même colonne, dont l'en-tête est "Pixbuf and Text". La couleur d'arrière-plan du CellRendererText qui affiche "Imprime un fichier" est la couleur par défaut afin de montrer la zone d'application sur une seule ligne.

La Figure 14.2, « TreeViewColumn avec CellRenderer » a été générée par le programme treeviewcolumn.py.

Le type de CellRenderer dont on a besoin dépend du type d'affichage attendu pour les données du modèle ; PyGTK dispose de trois CellRenderer prédéfinis :

Les propriétés d'un CellRenderer déterminent la manière dont les données doivent être affichées :

Les propriétés ci-dessus sont disponibles pour toutes les sous-classes de CellRenderer. Chaque type de CellRenderer dispose en plus de ses propres propriétés.

Le CellRendererPixbuf a les propriétés suivantes :

Le CellRendererText possède un grand nombre de propriétés donnant pour la plupart des indications stylistiques :

La quasi totalité des propriétés du CellRendererText possède un équivalent booléen (avec le suffixe "-set") qui indique si la propriété doit être appliquée. Cela permet de définir une propriété globalement et d'activer ou non son application de manière sélective.

Le CellRendererToggle possède les propriétés suivantes :

Les propriétés peuvent être définies pour l'ensemble des lignes en utilisant la méthode gobject.set_property(), comme dans le programme treeviewcolumn.py, par exemple.

Les attributs associent une colonne de TreeModel à une propriété de CellRenderer ; le CellRenderer définit la propriété à partir de la valeur de colonne de la ligne avant d'afficher la cellule. Cela permet de personnaliser l'affichage des cellules en utilisant les données du modèle. On peut ajouter un attribut à l'ensemble courant de la manière suivante :

  treeviewcolumn.add_attribute(cell_renderer, attribute, column)

où la propriété spécifiée par attribute est définie pour le cell_renderer à partir de la colonne column. Par exemple :

  treeviewcolumn.add_attribute(cell, "cell-background", 1)

fixe la couleur d'arrière-plan du CellRenderer à la couleur spécifiée par la chaîne de caractères située dans la deuxième colonne du modèle.

Afin de supprimer tous les attributs et d'en fixer de nouveaux immédiatement, on utilisera :

  treeviewcolumn.set_attributes(cell_renderer, ...)

où les attributs de cell_renderer sont définis par des couples clé-valeur : propriété=colonne. Par exemple, pour un CellRendererText, la méthode :

  treeviewcolumn.set_attributes(cell, text=0, cell_background=1, xpad=3)

fixe, pour chaque ligne, le texte à partir de la première colonne, la couleur d'arrière-plan à partir de la deuxième et l'espacement à gauche et à droite de la cellule à partir de la quatrième. Le programme treeviewcolumn.py donne des exemples d'utilisation de ces méthodes.

Les attributs d'un CellRenderer peuvent être supprimés comme suit :

  treeviewcolumn.clear_attributes(cell_renderer)

Si définir des attributs ne suffit pas, il est possible de définir une fonction à appeler à chaque ligne pour fixer les propriétés du CellRenderer :

  treeviewcolumn.set_cell_data_func(cell_renderer, fonction_rendu, donnees=None)

où fonction_rendu est de la forme :

  def fonction_rendu(colonne, cell_renderer, tree_model, iter, donnees_utilisateur)

où colonne est le TreeViewColumn contenant le cell_renderer, tree_model est le modèle et iter est un TreeIter pointant vers une ligne du tree_model. donnees_utilisateur contient la valeur des donnees transmises par la méthode set_cell_data_func().

Dans fonction_rendu on peut définir toutes les propriétés voulues du cell_renderer. La portion de code suivante définit la propriété "text" pour afficher les objets PyGTK sous la forme d'une chaîne les identifiant.

  ...
  def chaine_objet(treeviewcolumn, cellrenderer, modele, iter):
     objetpygtk = modele.get_value(iter, 0)
     cell.set_property('text', str(objetpygtk))
     return
  ...
  treestore = gtk.TreeStore(object)
  fenetre = gtk.Window()
  treeview = gtk.TreeView(treestore)
  fenetre.add(treeview)
  cell = gtk.CellRendererText()
  tvcolumn = gtk.TreeViewColumn('Objet', cell)
  treeview.append_column(tvcolumn)
  iter = treestore.append(None, [fenetre])
  iter = treestore.append(iter, [treeview])
  iter = treestore.append(iter, [tvcolumn])
  iter = treestore.append(iter, [cell])
  iter = treestore.append(None, [treestore])
  ...

La Figure 14.3, « Fonction d'affichage des données cellulaires » montre le résultat :

Cette fonction permet aussi de contrôler l'affichage des données numériques en format texte (par exemple, d'un nombre réel). Un CellRendererText affiche et convertit automatiquement un réel en chaîne avec le format par défaut "%f".

Les fonctions d'affichage de données cellulaires permettent même de créer les données des colonnes à partir de données externes. Le programme listefichiers.py utilise un ListStore avec une seule colonne contenant une liste de fichiers. Le TreeView affiche des colonnes qui comprennent un pixbuf, le nom du fichier, sa taille, son mode et la date de dernière modification. Les données sont créées par la fonction suivante :

    def fichier_pixbuf(self, colonne, cell, modele, iter):
        nomfichier = os.path.join(self.nomrep, modele.get_value(iter, 0))
        statsfichier = os.stat(nomfichier)
        if stat.S_ISDIR(statsfichier.st_mode):
            pb = dossierpb
        else:
            pb = fichierpb
        cell.set_property('pixbuf', pb)
        return

    def nom_fichier(self, colonne, cell, modele, iter):
        cell.set_property('text', modele.get_value(iter, 0))
        return

    def taille_fichier(self, colonne, cell, modele, iter):
        nomfichier = os.path.join(self.nomrep, modele.get_value(iter, 0))
        statsfichier = os.stat(nomfichier)
        cell.set_property('text', statsfichier.st_size)
        return

    def mode_fichier(self, colonne, cell, modele, iter):
        nomfichier = os.path.join(self.nomrep, modele.get_value(iter, 0))
        statsfichier = os.stat(nomfichier)
        cell.set_property('text', oct(stat.S_IMODE(statsfichier.st_mode)))
        return


    def modif_fichier(self, colonne, cell, modele, iter):
        nomfichier = os.path.join(self.nomrep, modele.get_value(iter, 0))
        statsfichier = os.stat(nomfichier)
        cell.set_property('text', time.ctime(statsfichier.st_mtime))
        return

Ces fonctions d'affichage de données cellulaires récupèrent l'information sur chaque fichier par son nom, extraient les données nécessaires et fixent la propriété 'text' ou 'pixbuf' des cellules selon les données. La Figure 14.4, « Exemple de liste de fichiers utilisant les fonctions d'affichage de données cellulaires » illustre le résultat du programme.

Un CellRendererText peut présenter un texte enrichi avec des polices et des styles différents plutôt qu'une simple chaîne de caractères bruts grâce à l'utilisation du balisage Pango (en définissant la propriété "markup"). On trouvera davantage de renseignements sur le balisage Pango dans la section Pango Markup du PyGTK Reference Manual.

L'extrait de code ci-dessous montre l'utilisation de la propriété "markup" :

  ...
  liststore = gtk.ListStore(str)
  cell = gtk.CellRendererText()
  tvcolumn = gtk.TreeViewColumn('Pango Markup', cell, markup=0)
  ...
  liststore.append(['<span foreground="blue"><b>Pango</b></span> markup peut'
' modifier\n<i>le style</i> <big>la taille</big>, <u>souligner,'
 <s>barrer</s></u>,\n'
'et <span font_family="URW Chancery L"><big>changer la police '
'ex : URW Chancery L</big></span>\n<span foreground="red">avant-plan'
' rouge et <span background="cyan">arrière-plan cyan</span></span>'])
  ...

et donne un résultat semblable à la Figure 14.5, « CellRendererText et balisage »:

Lorsque l'on crée un balisage Pango à la volée, il faut faire attention à remplacer les caractères spécifiques au langage balisé : "<", ">", "&". La fonction cgi.escape() de la bibliothèque Python peut réaliser ces conversions élémentaires.

Les cellules CellRendererText peuvent devenir éditables pour permettre à un utilisateur de changer le contenu de la cellule sélectionnée en la cliquant ou en pressant une des touches Retour, Entrée, Espace ou Maj+Espace. On rend un CellRendererText éditable pour toutes les lignes en fixant sa propriété "editable" à TRUE de cette façon :

  cellrenderertext.set_property('editable', True)

Pour rendre éditable une seule cellule, il faut ajouter un attribut au TreeViewColumn et utiliser le CellRendererText ainsi :

  treeviewcolumn.add_attribute(cellrenderertext, "editable", 2)

qui fixe la propriété "editable" pour la valeur contenue dans la troisième colonne du treemodel.

Les modifications de la cellule terminées, l'application doit gérer le signal "edited" pour récupérer le nouveau texte et modifier la valeur du treemodel associé. Sinon, la cellule reprend sa valeur précédente. Le gestionnaire du signal "edited" a la signature suivante :

  def rappel_edited(celltext, chemin, nouveau_texte, donnees_utilisateur)

où celltext est le CellRendererText, chemin est le chemin d'accès (une chaîne) à la ligne contenant la cellule éditée, nouveau_texte est le texte modifié et donnees_utilisateur les données contextuelles. Le TreeModel étant indispensable pour définir le nouveau_texte dans le stock de données, il faudra peut-être transmettre le TreeModel comme donnees_utilisateur dans la méthode connect() :

  cellrenderertext.connect('edited', rappel_edited, modele)

S'il y a deux ou plusieurs cellules éditables dans une ligne, on peut passer le numéro de la colonne dans donnees_utilisateur, en même temps que le TreeModel :

  cellrenderertext.connect('edited', rappel_edited, (modele, num_col))

Ensuite, on peut définir le nouveau texte dans le gestionnaire "edited" comme le montre cet exemple avec un ListStore :

  def rappel_edited(celltext, chemin, nouveau_texte, donnees_utilisateur):
      liststore, colonne = donnees_utilisateur
      liststore[chemin][colonne] = nouveau_texte
      return

Les boutons CellRendererToggle peuvent être rendus activables en fixant leur propriété "activatable" à TRUE. De la même manière que pour les cellules éditables CellRendererText, la propriété "activatable" peut être fixée pour l'ensemble des cellules CellRendererToggle en utilisant la méthode set_property() ou pour des cellules individuelles en ajoutant un attribut au TreeViewColumn contenant le CellRendererToggle.

  cellrenderertoggle.set_property('activatable', True)

  treeviewcolumn.add_attribute(cellrenderertoggle, "activatable", 1)

La déclaration individuelle des boutons à bascule peut être obtenue à partir des valeurs d'une colonne du TreeModel en ajoutant un attribut, comme ceci :

  treeviewcolumn.add_attribute(cellrenderertoggle, "active", 2)

Une connexion au signal "toggled" est nécessaire si l'on veut savoir quand l'utilisateur a cliqué sur le bouton et pouvoir modifier la valeur dans le treemodel. Par exemple :

  cellrenderertoggle.connect("toggled", rappel_toggled, (modele, colonne))

La fonction de rappel aura la signature suivante :

  def rappel_toggled(cellrenderertoggle, chemin, donnees_utilisateur)

où chemin est le chemin d'accès (une chaîne), pointant sur la ligne contenant le bouton à bascule qui a été cliqué. On doit passer le TreeModel et éventuellement l'index de colonne dans le paramètre donnees_utilisateur pour fournir les éléments nécessaires à l'établissement des valeurs du treemodel. Par exemple, l'application peut modifier la valeur du treemodel de la façon suivante :

  def rappel_toggled(cellule, chemin, donnees_utilisateur):
      modele, colonne = donnees_utilisateur
      modele[chemin][colonne] = not modele[chemin][colonne]
      return

Si l'on veut afficher les boutons à bascule comme des boutons radio dont un seul serait sélectionné, l'application doit parcourir le treemodel pour désactiver le bouton radio actif et ensuite déclarer le bouton à activer. Par exemple, la fonction de rappel suivante :

  def rappel_toggled(cellule, chemin, donnees_utilisateur):
      modele, colonne = donnees_utilisateur
      for ligne in modele:
          ligne[colonne] = False
      modele[chemin][colonne] = True
      return

utilise la solution de facilité qui consiste à mettre toutes les valeurs du treemodel à FALSE avant de remettre à TRUE la valeur pour la ligne indiquée par le chemin.

Le programme cellrenderer.py illustre l'utilisation de CellRendererText éditables et de CellRendererToggle activables dans un TreeStore.

#!/usr/bin/env python
# vim: ts=4:sw=4:tw=78:nowrap
""" Exemple avec Cellrenderer éditables et activables """
import pygtk
pygtk.require("2.0")
import gtk, gobject

taches =  {
    "Faire les courses": "Acheter une baguette",
    "Programmer": "Mettre a jour le programme",
    "Cuisiner": "Allumer le four",
    "Regarder la TV": "Enregistrer \"Urgences\""
    } 

class GUI_Controleur:
    """ La classe GUI est le contrôleur de l'application """
    def __init__(self):
        # Création de la fenêtre principale
        self.fenetre = gtk.Window(type=gtk.WINDOW_TOPLEVEL)
        self.fenetre.set_title("Exemple de CellRenderer")
        self.fenetre.connect("destroy", self.evnmt_destroy)
        # On récupère le modèle et on le relie à la vue
        self.modele = Ranger.recup_modele()
        self.vue = Afficher.cree_vue( self.modele )
        # Ajouter la vue à la fenêtre principale
        self.fenetre.add(self.vue)
        self.fenetre.show_all()
        return
    def evnmt_destroy(self, *kw):
        """ Fonction de rappel pour fermer l'application """
        gtk.main_quit()
        return
    def lance(self):
        """ La fonction est appelée pour lancer la boucle principale GTK """
        gtk.main()
        return  

class InfoModele:
    """ La classe du modèle contient l'information que nous voulons afficher """
    def __init__(self):
        """ Création et remplissage du gtk.TreeStore """
        self.tree_store = gtk.TreeStore( gobject.TYPE_STRING,
                                         gobject.TYPE_BOOLEAN )
        # on place les données utilisateur globales dans une liste
        # on crée une arborescence simple.
        for item in taches.keys():
            lignemere = self.tree_store.append( None, (item, None) )
            self.tree_store.append( lignemere, (taches[item],None) )
        return
    def recup_modele(self):
        """ Renvoie le modèle """
        if self.tree_store:
            return self.tree_store 
        else:
            return None

class AfficheModele:
    """ Affiche le modèle InfoModele dans un treeview """
    def cree_vue( self, modele ):
        """ Crée une vue pour le Tree Model """
        self.vue = gtk.TreeView( modele )
        # Crée le CellRendererText et permet aux cellules
        # d'être éditées.
        self.renderer = gtk.CellRendererText()
        self.renderer.set_property( 'editable', True )
        self.renderer.connect( 'edited', self.rappel_edited_col0, modele )

        # Crée le CellRendererToggle et permet sa 
        # modification (toggled) par l'utilisateur.
        self.renderer1 = gtk.CellRendererToggle()
        self.renderer1.set_property('activatable', True)
        self.renderer1.connect( 'toggled', self.rappel_toggled_col1, modele )

        # On connecte la colonne 0 de l'affichage à la colonne 0 du modèle
        # Le cellrenderer va alors afficher tout ce qui est en colonne 0 de
        # notre modèle .
        self.colonne0 = gtk.TreeViewColumn("Nom", self.renderer, text=0)

        # L'état actif des colonnes est relié à la seconde colonne
        # du modèle. Ainsi, quand le modèle indique True, le bouton
        # apparaîtra comme actif.
        self.colonne1 = gtk.TreeViewColumn("Fait", self.renderer1 )
        self.colonne1.add_attribute( self.renderer1, "active", 1)
        self.vue.append_column( self.colonne0 )
        self.vue.append_column( self.colonne1 )
        return self.vue
    def rappel_edited_col0( self, cellrenderer, chemin, nouveau_texte, modele ):
        """
        Appelé quand un texte est modifie. Il inscrit le nouveau texte
        dans le modèle pour qu'il puisse être affiché correctement.
        """
        print "Change '%s' en '%s'" % (modele[chemin][0], nouveau_texte)
        modele[chemin][0] = nouveau_texte
        return
    def rappel_toggled_col1( self, cellrenderer, chemin, modele ):
        """
        Fixe l'état du bouton à bascule sur true ou false.
        """
        modele[chemin][1] = not modele[chemin][1]
        print "Valeur de '%s'  : %s" % (modele[chemin][0], modele[chemin][1],)
        return

if __name__ == '__main__':
    Ranger = InfoModele()    
    Afficher = AfficheModele()
    monGUI = GUI_Controleur()
    monGUI.lance()

Le programme propose des cellules éditables dans la première colonne et des cellules activables dans la deuxième. Les lignes 64-66 créent un CellRendererText éditable et connectent le signal "edited" à la fonction de rappel rappel_edited_col0() (lignes 87-94) qui modifie la valeur de colonne de la ligne adéquate dans le TreeStore. De même, les lignes 70-72 créent un CellRendererToggle activable et connectent le signal "toggled" à la fonction de rappel rappel_toggled_col0()() (lignes 95-101) qui modifie la valeur de la ligne adéquate. Lorsqu'une cellule éditable ou activable est modifiée, un message s'affiche, indiquant de quelle modification il s'agissait.

La Figure 14.6, « Cellules éditables et activables » montre le programme cellrenderer.py en action.

La fonction de création du TreeViewColumn est la suivante :

  treeviewcolumn = gtk.TreeViewColumn(titre=None, cell_renderer=None, ...)

où titre est la chaîne utilisée comme en-tête de colonne et cell_renderer est le premier CellRenderer placé dans la colonne. Les autres arguments pouvant être passés au constructeur sont des mots-clés (sous la forme attribute=colonne) qui donnent des attributs au cell_renderer. Par exemple :

  treeviewcolumn = gtk.TreeViewColumn('États', cellule, text=0, foreground=1)

crée un TreeViewColumn dont le CellRendererText récupère son texte dans la première colonne du TreeModel et la couleur du texte dans la seconde.

On peut ajouter un CellRenderer à un TreeViewColumn par l'une de ces méthodes :

  treeviewcolumn.pack_start(cell, expand)
  treeviewcolumn.pack_end(cell, expand)

Les méthodes pack_start() et pack_end() ajoutent une cellule respectivement au début ou à la fin du TreeViewColumn. Si le paramètre expand est réglé sur TRUE, la cellule s'étirera pour remplir tout l'espace donné par le TreeViewColumn.

La méthode get_cell_renderers() :

  liste_cell = treeviewcolumn.get_cell_renderers()

renvoie une liste de tous les CellRenderer de la colonne.

La méthode clear() enlève tous les attributs de CellRenderer du TreeViewColumn :

  treeviewcolumn.clear()

Il y a un grand nombre d'autres méthodes disponibles pour le TreeViewColumn - principalement pour fixer ou retrouver des propriétés. On trouvera davantage de renseignements sur les propriétés du TreeViewColumn dans le PyGTK Reference Manual. La possibilité de faire appel ou non à la fonction de tri intégré s'installe ainsi ;

  treeviewcolumn.set_sort_column_id(sort_column_id)

définit sort_column_id comme étant l'identifiant de classement de colonne du treemodel à utiliser lors du tri de l'affichage du TreeView. Cette méthode active aussi la propriété "clickable" de la colonne et permet ainsi à l'utilisateur de cliquer sur l'en-tête de colonne pour réaliser le classement. Quand l'utilisateur clique sur cet en-tête, l'identifiant de classement de colonne du TreeViewColumn est défini comme étant l'identifiant de classement de colonne du TreeModel et les lignes sont réordonnées selon la fonction associée de comparaison de classement. La fonction de classement automatique inverse également l'ordre de classement de la colonne et contrôle l'affichage de l'indicateur de classement. On trouvera plus de renseignements au sujet des identifiants de classement de colonne et des fonctions de comparaison de tri dans Section 14.2.9, « Ordonner les lignes d'un TreeModel »Ordonner les lignes d'un TreeModel. En règle générale, lorsqu'on utilise un ListStore ou un TreeStore, l'identifiant de classement de colonne par défaut (c'est-à-dire l'index de la colonne) de la colonne du TreeModel associée au TreeViewColumn est défini comme étant l'identifiant de classement de colonne du TreeViewColumn.

Si on se sert des en-têtes de colonne du TreeViewColumn pour le classement avec la méthode set_sort_column_id(), il n'est pas nécessaire d'utiliser la méthode de TreeSortable set_sort_column_id().

Il est possible de tracer les opérations de tri ou d'utiliser le clic sur l'en-tête à d'autres fins en le connectant au signal "clicked" de la colonne du TreeView. La fonction de rappel doit être de la forme :

  def callback(treeviewcolumn, donnees_utilisateur, ...)

On peut récupérer un TreeViewColumn dans un TreeView soit isolément, soit comme une liste :

  treeviewcolumn = treeview.get_column(n)
  columnlist = treeview.get_columns()

où n est l'index (à partir de zéro) de la colonne à récupérer. Une colonne peut être effacée par la méthode :

  treeview.remove_column(column)

où column est un TreeViewColumn du treeview.

Les lignes qui possèdent des lignes enfants sont affichées avec une flèche de développement (voir Figure 14.3, « Fonction d'affichage des données cellulaires ») sur laquelle l'utilisateur peut cliquer pour masquer ou afficher les lignes enfants. On peut choisir la colonne qui possède la flèche de développement par cette méthode :

  treeview.set_expander_column(column)

où column est un TreeViewColumn du treeview. Cette méthode est utile lorsqu'on ne souhaite pas que la première colonne soit indentée. Par exemple, Figure 14.7, « Flèche de développement dans la seconde colonne » montre la flèche de développement dans la seconde colonne :

Toutes les lignes enfants d'un TreeView peuvent être affichées ou masquées grâce aux méthodes suivantes :

  treeview.expand_all()
  treeview.collapse_all()

Ces méthodes sont pratiques pour initialiser l'affichage du TreeView dans un état donné. Chaque ligne peut avoir ses lignes enfants affichées ou masquées de manière indépendante par :

  treeview.expand_row(path, open_all)
  treeview.collapse_row(path)

où path est le chemin arborescent vers une ligne du treeview ; si open_all vaut TRUE, toute la descendance de la ligne est affichée, sinon, seuls ses enfants directs sont affichés.

On peut savoir si une ligne a ses enfants affichés par cette méthode :

  is_expanded = treeview.row_expanded(path)

Les TreeSelection sont des objets qui gèrent les sélections dans un TreeView. Quand on crée un TreeView, un TreeSelection est automatiquement créé en même temps. Le TreeSelection peut être obtenu à partir du TreeView par la méthode :

  treeselection = treeview.get_selection()

On peut retrouver le TreeView associé au TreeSelection par la méthode :

  treeview = treeselection.get_treeview()

Le TreeSelection dispose des modes de sélection suivants :

On peut récupérer le mode de sélection en cours par la méthode :

  mode = treeselection.get_mode()

Ce mode peut être fixé en utilisant :

  treeselection.set_mode(mode)

où mode est l'un des modes de sélection ci-dessus.

La méthode à utiliser pour retrouver la sélection est fonction du mode de sélection en cours. Si le mode de sélection est gtk.SELECTION_SINGLE ou gtk.SELECTION_BROWSE, il faut utiliser la méthode suivante :

  (modele, iter) = treeselection.get_selected()

qui renvoie un 2-tuple contenant modele, le TreeModel utilisé par le TreeView associé au treeselection et iter, un TreeIter pointant sur la ligne sélectionnée. S'il n'y a pas de ligne sélectionnée, alors iter vaut None. Si le mode de sélection est gtk.SELECTION_MULTIPLE, une exception TypeError est déclenchée.

Pour un TreeView utilisant le mode de sélection gtk.SELECTION_MULTIPLE, il faut utiliser la méthode :

  (modele, listechemins) = treeselection.get_selected_rows()

qui renvoie un 2-tuple contenant le modèle et une liste des chemins des lignes sélectionnées dans l'arborescence. Cette méthode n'est pas disponible en PyGTK 2.0 ; pour retrouver cette liste, il faut passer par une fonction intermédiaire en utilisant :

  treeselection.selected_foreach(fonct, donnees=None)

où fonct est une fonction appelée pour chaque ligne sélectionnée avec les données donnees. La fonction a la signature suivante :

  def fonct(modele, chemin, iter, donnees)

où modele est le TreeModel, chemin est le chemin de la ligne sélectionnée dans l'arborescence et iter est un TreeIter pointant sur la ligne sélectionnée.

Cette méthode peut être utilisée pour simuler la méthode get_selected_row() de la manière suivante :

  ...
  def rappel_chacune(modele, chemin, iter, listechemins) :
      liste.append(chemin)
  ...
  def ma_recup_selection(treeselection) :
      listechemins = []
      treeselection.selected_foreach(rappel_chacune, listechemins)
      modele = choix.get_treeview().get_model()
      return(modele, listechemins)
  ...

La méthode selected_foreach() ne peut servir à modifier le treemodel ou la sélection, mais peut permettre de modifier les données des lignes.

Si on souhaite avoir un contrôle total sur la sélection de ligne, on peut définir une fonction à appeler avant qu'une ligne soit sélectionnée ou déselectionnée grâce à la méthode :

  treeselection.set_select_function(fonct, donnees)

où fonct est une fonction de rappel et donnees sont les données utilisateur qui sont transmises à fonct quand celle-ci est appelée. La méthode fonct a pour signature :

  def fonct(selection, modele, chemin, est_choisi, donnees_utilisateur)

où selection est le TreeSelection, modele est le TreeModel utilisé avec le TreeView associé à la selection, chemin est le chemin dans l'arbre de la ligne sélectionnée, est_choisi vaut TRUE si la ligne est actuellement sélectionnée et donnees_utilisateur est données. fonct renvoie TRUE si l'état de sélection de la ligne peut être modifié.

Établir une fonction de sélection est utile si :

• on souhaite contrôler la sélection ou déselection d'une ligne en fonction d'une information complémentaire du contexte. On doit indiquer d'une façon ou d'une autre que le changement de sélection ne peut être réalisé et pourquoi. Par exemple, on peut différencier visuellement la ligne ou ouvrir un MessageDialog contextuel ;
• on doit maintenir soi-même la liste des lignes sélectionnées ou déselectionnées quoique cela puisse aussi être réalisé, mais de manière plus laborieuse, en se connectant au signal "changed" ;
• on veut faire un traitement complémentaire avant qu'une ligne soit sélectionnée ou non. Changer par exemple l'apparence de la ligne ou modifier les données de cette ligne.

Il est possible de modifier la sélection par programme en employant les méthodes suivantes :

  treeselection.select_path(path)
  treeselection.unselect_path(path)

  treeselection.select_iter(iter)
  treeselection.unselect_iter(iter)

Ces méthodes sélectionnent ou déselectionnent une ligne unique indiquée, soit par le path, un chemin de l'arbre, soit par iter, un TreeIter pointant sur la ligne. Les méthodes qui suivent sélectionnent ou déselectionnent plusieurs lignes à la fois :

  treeselection.select_all()
  treeselection.unselect_all()

  treeselection.select_range(start_path, end_path)
  treeselection.unselect_range(start_path, end_path)

Les méthodes select_all() et select_range() nécessitent que le mode de sélection soit gtk.SELECTION_MULTIPLE. Les méthodes unselect_all() et unselect_range() fonctionnent quel que soit le mode de sélection. À noter que la méthode unselect_all() n'est pas disponible en PyGTK 2.0.

On peut vérifier si une ligne est sélectionnée en utilisant l'une de ces méthodes :

  resultat = treeselection.path_is_selected(chemin)
  resultat = treeselection.iter_is_selected(iter)

qui renvoie TRUE si la ligne indiquée par chemin ou iter est actuellement sélectionnée. On peut connaître le nombre de lignes sélectionnées avec la méthode :

  compte = treeselection.count_selected_rows()

Cette méthode n'est pas disponible en PyGTK 2.0 ; il faut donc la simuler en utilisant la méthode selected_foreach() semblable à l'émulation de la méthode get_selected_rows() dans Section 21.2, « Retrieving the Selection »Récupérer la sélection (pas encore traduit). Par exemple :

  ...
  def rappel_chacune(modele, chemin, iter, compteur) :
      compteur[0] += 1
  ...
  def mon_compte_lignes_choisies(treeselection) :
      compteur = [0]
      treeselection.selected_foreach(rappel_chacune, compteur)
      return compteur[0]
  ...

Reclasser les lignes d'un TreeView (et les lignes sous-jacentes d'un treemodel) s'effectue par la méthode set_reorderable() mentionnée précédemment. La méthode set_reorderable() fixe la propriété "reorderable" à la valeur indiquée et autorise ou interdit le glisser- déposer interne aux lignes du TreeView. Lorsque la propriété "reorderable" vaut TRUE, l'utilisateur peut faire glisser des lignes et les relâcher à un nouvel endroit. Cette action provoque le reclassement en parallèle des lignes sous-jacentes du TreeModel. Reclasser avec un glisser-déposer n'est possible qu'avec des treeview non triés.

Si l'on souhaite contrôler ou gérer un glisser-déposer depuis une source extérieure, il faut permettre et contrôler le glisser-déposer avec les méthodes suivantes :

  treeview.enable_model_drag_source(start_button_mask, targets, actions)
  treeview.enable_model_drag_dest(targets, actions)

Ces méthodes permettent d'utiliser les lignes respectivement comme source du glisser et cible du déposer. Le paramètre start_button_mask est un masque modificateur (voir la référence à gtk.gtk Constants dans le PyGTK Reference Manual qui indique les boutons ou les touches qui doivent être utilisés pour débuter le glisser. Le paramètre targets est une liste de 3-tuples qui définit l'information de cible qui peut être envoyée ou reçue. Pour qu'un glisser-déposer réussisse, au moins une des cibles de la source doit correspondre à une des cibles de la destination (par exemple, la cible "STRING"). Chaque tuple de cible contient le type de la cible, des indicateurs (une combinaison de gtk.TARGET_SAME_APP et gtk.TARGET_SAME_WIDGET ou aucune) et un identifiant unique entier. Le paramètre actions définit le résultat attendu de l'opération :

Par exemple, pour créer la destination d'un glisser-déposer

  treeview.enable_model_drag_dest([('text/plain', 0, 0)],
                  gtk.gdk.ACTION_DEFAULT | gtk.gdk.ACTION_MOVE)

Ensuite, il faut gérer le signal "drag-data-received" du Widget pour accueillir ces données déposées - peut-être remplacer les données de la ligne où on les dépose. La fonction de rappel du signal "drag-data-received" a pour signature :

  def fonct_rappel(widget, drag_context, x, y, selection_data, info, timestamp)

où widget est le TreeView, drag_context est un DragContext contenant le contexte de la sélection, x et y représente la position où le "déposer" est fait, selection_data est le SelectionData contenant les données, info est l'identifiant entier du type, timestamp est le moment où le "déposer" est réalisé. La ligne peut être récupérée par cette méthode :

  info_depot = treeview.get_dest_row_at_pos(x, y)

où (x, y) représentent la position transmise à la fonction de rappel, info_depot est un 2-tuple contenant le chemin d'une ligne et une constante indiquant la position du "déposer" par rapport à cette ligne : gtk.TREE_VIEW_DROP_BEFORE, gtk.TREE_VIEW_DROP_AFTER, gtk.TREE_VIEW_DROP_INTO_OR_BEFORE ou gtk.TREE_VIEW_DROP_INTO_OR_AFTER (avant, après, dedans ou avant, dedans ou après). La fonction de rappel ressemble à ceci :

  treeview.enable_model_drag_dest([('text/plain', 0, 0)],
                  gtk.gdk.ACTION_DEFAULT | gtk.gdk.ACTION_MOVE)
  treeview.connect("drag-data-received", rappel_donnees_du__deposer)
  ...
  ...
  def rappel_donnees_du__deposer(treeview, contexte, x, y, selection, info, dateur):
      depot_info = treeview.get_dest_row_at_pos(x, y)
      if depot_info:
          modele = treeview.get_model()
          chemin, position = depot_info
          donnees = selection.data
          # faire quelque chose avec les données et le modèle
          ...
      return
  ...

Si une ligne est utilisée comme source du glisser, elle doit gérer le signal "drag-data-get" du Widget, lequel remplit une sélection avec les données devant être transmises à la destination du glisser-déposer par une fonction de rappel ayant comme signature :

  def fonct_rappel(widget, drag_context, selection_data, info, timestamp)

Les paramètres de cette fonction de rappel sont semblables à ceux de la fonction de rappel "drag-data-received". Comme la fonction de rappel ne transmet pas le chemin de l'arborescence ou tout autre moyen simple de récupérer l'information sur la ligne qui est glissée, nous présumons que la ligne glissée est celle qui est sélectionnée et que le mode de sélection est gtk.SELECTION_SINGLE ou gtk.SELECTION_BROWSE. De cette façon, il est possible de récupérer la ligne en obtenant le TreeSelection et de retrouver le modele et le TreeIter pointant sur cette ligne. Par exemple, un texte dans une ligne peut être transmis ainsi dans le glisser-déposer :

  ...
  treestore = gtk.TreeStore(str, str)
  ...
  treeview.enable_model_drag_source(gtk.gdk.BUTTON1_MASK,
                  [('text/plain', 0, 0)],
                  gtk.gdk.ACTION_DEFAULT | gtk.gdk.ACTION_MOVE)
  treeview.connect("drag-data-get", rappel_donnees_du_glisser)
  ...
  ...
  def rappel_donnees_du_glisser(treeview, contexte, selection, info, dateur):
      treeselection = treeview.get_selection()
      modele, iter = treeselection.get_selected()
      texte = modele.get_value(iter, 1)
      selection.set('text/plain', 8, texte)
      return
  ...

On peut désactiver l'utilisation du TreeView comme source ou destination du glisser-déposer par la méthode :

  treeview.unset_rows_drag_source()
  treeview.unset_rows_drag_dest()

Un exemple simple est nécessaire pour assembler les extraits de code présentés ci-dessus. Cet exemple (treeviewdnd.py) consiste en une liste dans laquelle des URL peuvent être glissées et déposées. Les URL peuvent aussi être reclassées en effectuant un glisser-déposer à l'intérieur du TreeView. Deux boutons permettent de vider la liste ou de supprimer un item sélectionné.

#!/usr/bin/env python

# exemple treeviewdnd.py

import pygtk
pygtk.require('2.0')
import gtk

class TreeViewDnDExemple:

    CIBLES = [
        ('MY_TREE_MODEL_ROW', gtk.TARGET_SAME_WIDGET, 0),
        ('text/plain', 0, 1),
        ('TEXT', 0, 2),
        ('STRING', 0, 3),
        ]
    # fermer la fenêtre et quitter
    def ferme_event(self, widget, event, donnees=None):
        gtk.main_quit()
        return False

    def efface_selection(self, bouton):
        selection = self.treeview.get_selection()
        modele, iter = selection.get_selected()
        if iter:
            modele.remove(iter)
        return

    def __init__(self):
        # Créer une nouvelle fenêtre
        self.fenetre = gtk.Window(gtk.WINDOW_TOPLEVEL)

        self.fenetre.set_title("Cache URL")

        self.fenetre.set_size_request(250, 200)

        self.fenetre.connect("delete_event", self.ferme_event)

        self.fen_deroule = gtk.ScrolledWindow()
        self.vboite = gtk.VBox()
        self.hboite = gtk.HButtonBox()
        self.vboite.pack_start(self.fen_deroule, True)
        self.vboite.pack_start(self.hboite, False)
        self.b0 = gtk.Button('Effacer tout')
        self.b1 = gtk.Button('Effacer selection')
        self.hboite.pack_start(self.b0)
        self.hboite.pack_start(self.b1)

        # pour modèle, créer une liste avec une colonne contenant une chaîne
        self.modeleliste = gtk.ListStore(str)

        # créer la vue arborescente utilisant le modeleliste
        self.treeview = gtk.TreeView(self.modeleliste)

        # créer un CellRenderer pour préparer les données
        self.cell = gtk.CellRendererText()

        # créer unTreeViewColumn pour afficher les données
        self.colonneTV = gtk.TreeViewColumn('URL', self.cell, text=0)

        # ajouter la colonne au treeview
        self.treeview.append_column(self.colonneTV)
        self.b0.connect_object('clicked', gtk.ListStore.clear, self.modeleliste)
        self.b1.connect('clicked', self.efface_selection)
        # autoriser la recherche dans le treeview
        self.treeview.set_search_column(0)

        # autoriser le tri pour la colonne
        self.colonneTV.set_sort_column_id(0)

        # Autoriser le glisser-deposer y compris interne à la colonne
        self.treeview.enable_model_drag_source( gtk.gdk.BUTTON1_MASK,
                                                self.CIBLES,
                                                gtk.gdk.ACTION_DEFAULT|
                                                gtk.gdk.ACTION_MOVE)
        self.treeview.enable_model_drag_dest(self.CIBLES,
                                             gtk.gdk.ACTION_DEFAULT)

        self.treeview.connect("drag_data_get", self.donnees_du_glisser)
        self.treeview.connect("drag_data_received",
                              self.donnees_du_deposer)

        self.fen_deroule.add(self.treeview)
        self.fenetre.add(self.vboite)
        self.fenetre.show_all()

    def donnees_du_glisser(self, treeview, context, selection, id_cible,
                           etime):
        treeselection = treeview.get_selection()
        modele, iter = treeselection.get_selected()
        donnees = modele.get_value(iter, 0)
        selection.set(selection.target, 8, donnees)

    def donnees_du_deposer(self, treeview, context, x, y, selection,
                                info, etime):
        modele = treeview.get_model()
        donnees = selection.data
        info_depot = treeview.get_dest_row_at_pos(x, y)
        if info_depot:
            chemin, position = info_depot
            iter = modele.get_iter(chemin)
            if (position == gtk.TREE_VIEW_DROP_BEFORE
                or position == gtk.TREE_VIEW_DROP_INTO_OR_BEFORE):
                modele.insert_before(iter, [donnees])
            else:
                modele.insert_after(iter, [donnees])
        else:
            modele.append([donnees])
        if context.action == gtk.gdk.ACTION_MOVE:
            context.finish(True, True, etime)
        return

def main():
    gtk.main()

if __name__ == "__main__":
    treeviewdndex = TreeViewDnDExemple()
    main()

Voici une copie d'écran Figure 14.8, « Exemple de glisser-déposer dans un TreeView » du programme exemple treeviewdnd.py en cours d'exécution :

L'essentiel pour permettre à la fois un glisser-déposer externe et un reclassement interne des lignes est l'organisation des cibles (l'attribut TARGETS - ligne 11). Une cible spécifique à l'application (MY_TREE_MODEL_ROW) est créée et utilisée pour signifier un glisser-déposer interne au treeview en fixant l'indicateur à gtk.TARGET_SAME_WIDGET. En indiquant celle-ci comme première cible, la destination tentera d'abord cette correspondance avec les cibles sources. Ensuite, les actions de glisser de la source doivent comprendre gtk.gdk.ACTION_MOVE et gtk.gdk.ACTION_DEFAULT (voir lignes 72-75). Quand la destination reçoit les données en provenance de la source, si l'action du DragContext est gtk.gdk.ACTION_MOVE, la source est informée qu'elle doit détruire les données (la ligne dans cet exemple) en appelant la méthode finish() du DragContext (lignes 109-110). Le TreeView fournit un certain nombre de fonctions internes que nous complétons pour glisser, déposer et effacer les données.

Le TreeModelSort maintient un modèle trié du modèle enfant indiqué dans son constructeur. L'usage principal du TreeModelSort est de fournir, pour un modèle, des vues multiples qui peuvent être classées diversement. Lorsque l'on a plusieurs vues d'un même modèle, toute opération de tri se répercute dans toutes les vues. Utiliser le TreeModelSort permet de laisser le modèle de départ dans son état originel pendant que les modèles de tri absorbent toutes les opérations de tri. Pour créer un TreeModelSort, il faut utiliser le constructeur :

  treemodelsort = gtk.TreeModelSort(child_model)

où child_model est un TreeModel. La plupart des méthodes du TreeModelSort portent sur la conversion des chemins de l'arborescence et des TreeIter du modèle enfant vers le modèle trié, et réciproquement :

  sorted_path = treemodelsort.convert_child_path_to_path(child_path)
  child_path = treemodelsort.convert_path_to_child_path(sorted_path)

Ces méthodes de conversion de chemin renvoient None si le chemin donné ne peut être converti en chemin dans le modèle trié ou dans le modèle enfant. Les méthodes de conversion du TreeIter sont :

  sorted_iter = treemodelsort.convert_child_iter_to_iter(sorted_iter, child_iter)
 child_iter = treemodelsort.convert_iter_to_child_iter(child_iter, sorted_iter)

Les méthodes de conversion du TreeIter dupliquent l'argument converti (la valeur de retour comme le premier argument) pour une préserver une compatibilité antérieure. Il faut donner la valeur None au premier argument et n'utiliser que la valeur de retour. Par exemple :

  sorted_iter = treemodelsort.convert_child_iter_to_iter(None, child_iter)
  child_iter = treemodelsort.convert_iter_to_child_iter(None, sorted_iter)

Comme les méthodes de conversion du chemin, ces méthodes renvoient None si le TreeIter indiqué ne peut être converti.

On peut retrouver le TreeModel enfant grâce à la méthode get_model().

treemodelsort.py est un exemple simple utilisant les objets du TreeModelSort. Les résultats obtenus avec six lignes sont illustrés par Figure 14.9, « Exemple de TreeModelSort ».

Chacune des colonnes d'une fenêtre peut être réordonnée avec un clic sur son titre indépendamment des autres fenêtres. Lorsque le bouton "Add a Row" est pressé, une nouvelle ligne est ajoutée dans le ListStore de base et cette nouvelle ligne est affichée dans chaque fenêtre comme étant la ligne sélectionnée.

Un objet TreeModelFilter fournit plusieurs façons de modifier la vue du TreeModel de base, y compris :

• afficher un sous-ensemble de lignes dans le modèle fils basé soit sur la valeur booléenne d'une "colonne visible", soit sur la valeur booléenne de retour d'une "fonction visible" ayant comme arguments un modèle fils, un TreeIter pointant sur une ligne du modèle fils et des données utilisateurs. Dans les deux cas, si la valeur booléenne vaut TRUE, la ligne est affichée sinon elle est cachée ;
• utiliser une racine virtuelle qui fournit une vue d'un sous-arbre des enfants d'une ligne dans un modèle fils. Ceci n'est réalisable que si les données sont dans un TreeStore ;
• combiner les colonnes et données d'un modèle relativement aux données du modèle fils. Par exemple, on peut afficher une colonne dans laquelle les données sont calculées à partir de données dans plusieurs colonnes du modèle fils.

Un objet TreeModelFilter est créé par la méthode TreeModel :

  treemodelfilter = treemodel.filter_new(root=None)

où root est un chemin dans l'arbre du treemodel précisant une racine virtuelle du modèle ou None si la racine du treemodel doit être utilisée.

Indiquer une "racine virtuelle" quand on crée le TreeModelFilter permet de limiter la vue aux enfants de cette ligne "racine" dans la hiérarchie du modèle fils. Ceci, bien sûr, n'est utile que si le modèle fils est basé sur un TreeStore. Par exemple, on peut vouloir fournir une vue de la liste des pièces qui composent un lecteur de CDROM, distincte de la liste complète des pièces de l'ordinateur.

Les modes de visibilité sont mutuellement exclusifs et ne peuvent être fixés qu'une seule fois ; Une fois la visibilité de la colonne ou de la fonction établie, on ne peut plus la modifier et l'autre mode ne peut plus être utilisé. Le mode de visibilité le plus simple extrait une valeur booléenne d'une colonne du modèle fils pour déterminer si la ligne doit être affichée. La visibilité colonne est fixée par :

  treemodelfilter.set_visible_column(column)

où column est le numéro de la colonne dans le TreeModel fils, de laquelle extraire les valeurs booléennes. Par exemple, le code suivant utilise les valeurs de la troisième colonne pour fixer la visibilité des lignes :

  ...
  treestore = gtk.TreeStore(str, str, "gboolean")
  ...
  modelfilter = treestore.filter_new()
  modelfilter.set_visible_column(2)
  ...

Ainsi, toutes les lignes du treestore qui possèdent la valeur TRUE dans la troisième colonne seront affichées.

Si on veut utiliser des critères de visibilité plus complexes, une fonction visibilité devrait fournir des capacités suffisantes :

  treemodelfilter.set_visible_func(func, data=None)

où func est la fonction appelée pour chaque ligne du modèle fils afin de décider si elle doit être affichée et data représente les données utilisateur transmises à la fonction func. La fonction func renvoie TRUE si la ligne doit être affichée. Cette fonction a pour signature :

  def func(modele, iter, donnees_utilisateur)

où modele est le TreeModel fils, iter est un TreeIter pointant sur une ligne du modele et donnees_utilisateur sont les data passées dans la fonction.

Si on modifie le critère de visibilité, il faut utiliser :

  treemodelfilter.refilter()

pour imposer un nouveau filtrage des lignes du modèle fils.

Par exemple, l'extrait de code ci-dessous illustre un TreeModelFilter qui affiche des lignes selon une comparaison entre la valeur de la troisième colonne et le contenu des données utilisateurs :

  ...
  def match_type(modele, iter, donnees_utilisateur):
      valeur = model.get_value(iter, 2)
      return valeur in donnees_utilisateur
  ...
  show_vals = ['OPEN', 'NEW', 'RESO']
  liststore = gtk.ListStore(str, str, str)
  ...
  modelfilter = liststore.filter_new()
  modelfilter.set_visible_func(match_type, show_vals)
  ...

Le programme treemodelfilter.py illustre l'utilisation de la méthode set_visible_func(). Figure 14.10, « Exemple de visibilité d'un TreeModelFilter » montre le résultat obtenu.

En agissant sur les boutons du bas, on modifie le contenu du TreeView pour afficher seulement les lignes qui correspondent à l'étiquette du bouton.

Une fonction modify permet un autre niveau de contrôle sur l'affichage du TreeView sur la manière dont on peut combiner une ou plusieurs (ou toutes) colonnes présentées par le TreeModelFilter. Il faut utiliser un modèle fils de base, un TreeStore ou un ListStore pour déterminer le nombre de lignes et la hiérarchie, mais les colonnes peuvent être tout ce qui est indiqué dans la méthode :

  treemodelfilter.set_modify_func(types, func, data=None)

où types est une suite (liste ou tuple) précisant le type des colonnes présentes, func est une fonction appelée pour renvoyer la valeur pour une rangée et une colonne et data est un argument passé à la fonction func. La fonction func a pour signature :

  def func(modele, iter, colonne, donnees_utilisateur)

où modele est le TreeModelFilter, iter le TreeIter qui pointe sur une ligne du modèle, colonne est le numéro de la colonne pour laquelle une valeur est nécessaire et donnees_utilisateur est le paramètre data. La fonction func doit renvoyer une valeur correspondant au type de colonne.

Une fonction de modification est utile quand on souhaite fournir une colonne de données qui doivent être générées à partir de données de colonnes du modèle fils. Par exemple, on dispose d'une colonne contenant des dates de naissance et on veut fournir une colonne affichant les âges ; une fonction de modification peut générer l'information sur l'âge à partir de la date de naissance et de la date actuelle. Un autre exemple serait de choisir l'image à afficher selon l'analyse des données (un nom de fichier) dans une colonne. Cette action peut aussi être réalisée par la méthode set_cell_data_func() du TreeViewColumn.

Généralement, avec la fonction modify, il faut convertir le TreeIter du TreeModelFilter en un TreeIter dans le modèle fils par :

  child_iter = treemodelfilter.convert_iter_to_child_iter(filter_iter)

Bien sûr, il faut aussi retrouver le modèle fils par :

  child_model = treemodelfilter.get_model()

Ceci donne accès à la ligne du modèle fils et à son contenu pour fournir la valeur de la ligne et colonne indiquées du TreeModelFilter. Il existe aussi une méthode pour convertir les chemins du modèle filtre de et vers les chemins de l'arborescence fille.

  filter_iter = treemodelfilter.convert_child_iter_to_iter(child_iter)

  child_path = treemodelfilter.convert_path_to_child_path(filter_path)
  filter_path = treemodelfilter.convert_child_path_to_path(child_path)

Bien sûr, il est possible de combiner les modes de visibilité et la fonction modify pour, à la fois, filtrer les lignes et produire les colonnes. Pour obtenir encore plus de contrôle sur la vue, il faudrait utiliser un TreeModel personnalisé.

Avec un GenericTreeModel, on construit et gère son modèle de données et on fournit un accès externe à travers l'interface du TreeModel standard en définissant un ensemble de méthodes de classe. PyGTK implémente l'interface du TreeModel et prend en charge les méthodes du TreeModel appelées pour fournir le modèle de données réel.

Les détails de l'implémentation de votre modèle devraient rester complètement cachés aux applications externes. Ce qui signifie que la manière dont votre modèle identifie, range et retrouve les données n'est pas connue de l'application. En général, la seule information qui est sauvegardée en-dehors du GenericTreeModel sont les références de ligne qui sont enveloppées par les TreeIter externes. Ces références ne sont pas visibles par l'application.

Voici un examen détaillé de l'interface GenericTreeModel qu'il faut fournir.

L'interface du GenericTreeModel comprend les méthodes suivantes qui doivent être implémentées dans le modèle personnalisé :

def on_get_flags(self)
def on_get_n_columns(self)
def on_get_column_type(self, index)
def on_get_iter(self, path)
def on_get_path(self, rowref)
def on_get_value(self, rowref, column)
def on_iter_next(self, rowref)
def on_iter_children(self, parent)
def on_iter_has_child(self, rowref)
def on_iter_n_children(self, rowref)
def on_iter_nth_child(self, parent, n)
def on_iter_parent(self, child)

Il faut remarquer que ces méthodes supportent entièrement l'interface du TreeModel, y compris :

def get_flags()
def get_n_columns()
def get_column_type(index)
def get_iter(path)
def get_iter_from_string(path_string)
def get_string_from_iter(iter)
def get_iter_root()
def get_iter_first()
def get_path(iter)
def get_value(iter, column)
def iter_next(iter)
def iter_children(parent)
def iter_has_child(iter)
def iter_n_children(iter)
def iter_nth_child(parent, n)
def iter_parent(child)
def get(iter, column, ...)
def foreach(func, user_data)

Pour illustrer l'utilisation du GenericTreeModel j'ai modifié le programme listefichiers.py et montré comment les méthodes d'interface sont réalisées. Le programme listefichiers-gtm.py affiche les fichiers d'un répertoire avec une icône indiquant si le fichier est ou non un répertoire, le nom du fichier, sa taille, son mode et sa date de dernière modification.

La méthode on_get_flags() doit retourner une valeur qui est une combinaison de  :

Si un modèle possède des références de lignes valides malgré les changements de lignes (réordonnancement, ajout, suppression), on utilise gtk.TREE_MODEL_ITERS_PERSIST. De la même façon, si un modèle est seulement une liste, on utilise gtk.TREE_MODEL_LIST_ONLY. Autrement, on renvoie 0 si le modèle ne possède pas de références de lignes persistantes et est une arborescence. Dans l'exemple, le modèle est une liste avec des TreeIter persistants.

    def on_get_flags(self):
        return gtk.TREE_MODEL_LIST_ONLY|gtk.TREE_MODEL_ITERS_PERSIST

La méthode on_get_n_columns() doit retourner le nombre de colonnes que le modèle exporte vers l'application. L'exemple garde une liste de types de colonnes, ainsi on peut renvoyer la longueur de la liste :

class Fichmodeleliste(gtk.GenericTreeModel):
    ...
    column_types = (gtk.gdk.Pixbuf, str, long, str, str)
    ...
    def on_get_n_columns(self):
        return len(self.types_colonnes)

La méthode on_get_column_type() doit renvoyer le type de la colonne pour l'index indiqué. Cette méthode est généralement appelée par un TreeView quand le modèle est établi. On peut soit créer une liste ou un tuple contenant l'information de type de colonne, soit le créer à la volée. Dans l'exemple :

    def on_get_column_type(self, n):
        return self.types_colonnes[n]

L'interface GenericTreeModel convertit le type Python en un GType, donc le code suivant :

  flm = Fichmodeleliste()
  print flm.on_get_column_type(1), flm.get_column_type(1)

imprimerait :

<type 'str'> <GType gchararray (64)>

Les méthodes suivantes utilisent les références de ligne qui sont conservées comme données privées dans un TreeIter. L'application ne peut lire la référence de ligne dans un TreeIter, donc on peut utiliser n'importe quel item unique voulu comme référence de ligne. Par exemple, dans un modèle comportant des lignes comme des tuples, il est possible d'utiliser l'index de tuple comme la référence de ligne. Un autre exemple serait d'utiliser un nom de fichier comme référence de ligne dans un modèle représentant des fichiers dans un répertoire. Dans ces deux cas, le référence de ligne n'est pas modifiée par les changements du modèle, aussi les TreeIter peuvent être déclarés persistants. L'interface de l'application PyGTK GenericTreeModel extraira vos références de ligne à partir des TreeIter et enveloppera vos références de ligne dans les TreeIter selon les besoins.

Dans les méthodes suivantes, refligne se réfère à une référence de ligne interne.

La méthode on_get_iter() devrait renvoyer un refligne pour le chemin de l'arborescence indiqué par le chemin. Le chemin de l'arborescence doit toujours être représenté par un tuple. L'exemple utilise le nom de fichier comme refligne. Les noms de fichier sont conservés dans une liste dans le modèle, ainsi on prend le premier index du chemin comme index du nom de fichier :

    def on_get_iter(self, chemin):
        return self.fichiers[chemin[0]]

Il faut être cohérent dans l'utilisation de la référence de ligne puisqu'on récupérera une référence de ligne dans les appels des méthodes GenericTreeModel qui prennent les arguments TreeIter : on_get_path(), on_get_value(), on_iter_next(), on_iter_children(), on_iter_has_child(), on_iter_n_children(), on_iter_nth_child() et on_iter_parent().

La méthode on_get_path() devrait retourner un chemin de l'arborescence donnant un refligne. Par exemple, poursuivant l'exemple précédent où le nom de fichier est utilisé comme refligne, on pourrait définir la méthode on_get_path() comme suit :

    def on_get_chemin(self, refligne):
        return self.fichiers.index(refligne)

Cette méthode trouve l'index de la liste contenant le nom de fichier dans refligne. Cet exemple montre clairement qu'un choix judicieux de référence de ligne rend l'exécution plus efficiente. Par exemple, on pourrait utiliser un dictionnaire Python pour relier refligne à un chemin.

La méthode on_get_value() devrait renvoyer les données rangées à la ligne et colonne indiquées par refligne et colonne. Dans l'exemple :

    def on_get_value(self, refligne, colonne):
        fname = os.path.join(self.nomrep, refligne)
        try:
            statutfich = os.stat(fname)
        except OSError:
            return None
        mode = statutfich.st_mode
        if colonne is 0:
            if stat.S_ISDIR(mode):
                return dossierpb
            else:
                return fichierpb
        elif colonne is 1:
            return refligne
        elif colonne is 2:
            return statutfich.st_size
        elif colonne is 3:
            return oct(stat.S_IMODE(mode))
        return time.ctime(statutfich.st_mtime)

on doit extraire l'information de fichier associée et renvoyer la valeur appropriée selon la colonne indiquée.

La méthode on_iter_next() devrait retourner une référence de ligne, à la ligne (de même niveau), après la ligne indiquée par refligne. Dans l'exemple :

    def on_iter_next(self, refligne):
        try:
            i = self.fichiers.index(refligne)+1
            return self.fichiers[i]
        except IndexError:
            return None

L'index du nom de fichier de refligne est établi et le nom de fichier suivant est renvoyé ou s'il n'existe pas, None est renvoyé.

La méthode on_iter_children() devrait retourner une référence de ligne vers la première ligne enfant de la ligne indiquée par refligne. Si refligne vaut None, une référence à la première ligne du niveau supérieur est retournée. S'il n'existe pas de ligne enfant, None est retourné. Dans l'exemple :

    def on_iter_children(self, refligne):
        if refligne:
            return None
        return self.fichiers[0]

Puisque le modèle est une liste, seul le niveau supérieur (refligne=None) peut posséder des lignes enfant. None est retourné si refligne contient un nom de fichier.

La méthode on_iter_has_child() doit renvoyer TRUE si la ligne indiquée par refligne possède des lignes enfant, FALSE sinon. Dans l'exemple, on renvoie FALSE puisque aucune ligne ne peut posséder d'enfant :

    def on_iter_has_child(self, refligne):
        return False

La méthode on_iter_n_children() renvoie le nombre de lignes enfant que possède la ligne indiquée par refligne. Si refligne vaut None, on renvoie le nombre de lignes du niveau supérieur. Dans l'exemple, on renvoie 0 si refligne ne vaut pas None :

    def on_iter_n_children(self, refligne):
        if refligne:
            return 0
        return len(self.fichiers)

La méthode on_iter_nth_child() renvoie une référence de ligne à la énième ligne enfant de la ligne indiquée par parent. Si parent vaut None, une référence à la énième ligne du niveau supérieur est retournée. Dans l'exemple, on retourne une référence à la énième ligne du niveau supérieur si parent vaut None, None sinon :

    def on_iter_nth_child(self, refligne, n):
        if refligne:
            return None
        try:
            return self.fichiers[n]
        except IndexError:
            return None

La méthode on_iter_parent() renvoie une référence de ligne à la ligne parent de la ligne indiquée par refligne. Si refligne pointe sur une ligne du niveau supérieur, on renvoie None. Dans l'exemple, None est toujours renvoyé en supposant que refligne doit pointer sur une ligne du niveau supérieur :

    def on_iter_parent(child):
        return None

Ces exemples sont assemblés dans le programme listefichiers-gtm.py. La Figure 14.11, « Exemple de TreeModel générique » montre le résultat.

Le programme listefichiers-gtm.py calcule la liste des noms de fichier lorsqu'il crée une instance de FileListModel. Si l'on souhaite vérifier régulièrement la création de nouveaux fichiers et ajouter ou retirer des fichiers du modèle, on peut soit créer un nouveau FileListModel pour le même répertoire, soit ajouter une méthode pour ajouter ou retirer des lignes dans le modèle. Selon le type de modèle créé, il peut être nécessaire d'ajouter une méthode semblable à celles des modèles de TreeStore et de ListStore :

• insert()
• insert_before()
• insert_after()
• prepend()
• append()
• remove()
• clear()

Il n'est, bien sûr, pas nécessaire d'utiliser toutes ou même une seule de ces méthodes. On peut créer ses propres méthodes plus adaptées à son modèle.

En utilisant le programme exemple précédent pour montrer l'ajout de méthodes pour supprimer ou ajouter des fichiers, voici comment on implémente ces méthodes :

def remove(iter)
def add(filename)

La méthode remove() retire le fichier indiqué par le paramètre iter. Outre retirer la ligne du modèle, la méthode efface aussi le fichier du répertoire. Évidemment, si l'utilisateur n'a pas les droits de suppression du ficher, la ligne n'est pas supprimée non plus. Par exemple :

    def remove(self, iter):
        path = self.get_path(iter)
        pathname = self.get_pathname(path)
        try:
            if os.path.exists(pathname):
                os.remove(pathname)
            del self.files[path[0]]
            self.row_deleted(path)
        except OSError:
            pass
        return

La méthode transmet un TreeIter qu'il faut transformer en un chemin à utiliser pour récupérer le chemin du fichier par la méthode get_pathname(). Il est possible que le fichier ait déjà été supprimé, il faut donc tester son existence avant de le supprimer. Si une exception OSError intervient pendant la suppression du fichier, c'est probablement parce que le fichier est dans un répertoire où l'utilisateur n'a pas suffisamment de droits. Finalement, le fichier est supprimé et le signal "row-deleted" est émis par la méthode rows_deleted(). Le signal "file-deleted" indique aux TreeView utilisant le modèle que celui-ci a changé, ainsi ils peuvent mettre à jour leur état interne et afficher le modèle modifié.

La méthode add() impose de créer un fichier dans le répertoire courant avec le nom donné. Si le fichier est créé, son nom est ajouté à la liste des fichiers du modèle. Par exemple :

    def add(self, filename):
        pathname = os.path.join(self.dirname, filename)
        if os.path.exists(pathname):
            return
        try:
            fd = file(pathname, 'w')
            fd.close()
            self.dir_ctime = os.stat(self.dirname).st_ctime
            files = self.files[1:] + [filename]
            files.sort()
            self.files = ['..'] + files
            path = (self.files.index(filename),)
            iter = self.get_iter(path)
            self.row_inserted(path, iter)
        except OSError:
            pass
        return

Cet exemple simple s'assure que le fichier n'existe pas déjà, puis tente d'ouvrir le fichier en écriture. Si cela réussit, le fichier est refermé et son nom inséré dans la liste de fichiers. Le chemin et le TreeIter de la ligne du fichier ajouté sont récupérés pour être utilisés dans la méthode row_inserted() qui émet le signal "row-inserted". Ce signal "row-inserted" sert à indiquer aux TreeView utilisant le modèle qu'ils doivent mettre à jour leur état et rafraîchir leur affichage.

Les autres méthodes mentionnées précédemment (par exemple, append et prepend) n'ont pas de signification pour cet exemple puisque le modèle a sa liste de fichiers triée.

D'autres méthodes peuvent être utiles dans un TreeModel découlant du GenericTreeModel :

• set_value()
• reorder()
• swap()
• move_after()
• move_before()

L'implémentation de ces méthodes est similaire à celle des méthodes précédentes. Il faut synchroniser le modèle et l'état externe, et ensuite indiquer aux TreeView que le modèle a changé. Les méthodes suivantes sont utilisées pour indiquer aux TreeView les changement du modèle en envoyant le signal approprié :

def row_changed(path, iter)
def row_inserted(path, iter)
def row_has_child_toggled(path, iter)
def row_deleted(path)
def rows_reordered(path, iter, new_order)

L'un des problèmes avec le GenericTreeModel est que le TreeIter contient une référence à un objet Python venant du modèle personnalisé. Puisque le TreeIter peut être crée et initialisé dans un module en C et être présent dans la pile, il n'est pas possible de connaître le moment où le TreeIter est détruit et la référence à l'objet Python n'est plus d'utilité. Donc l'objet Python référencé dans un TreeIter voit par défaut son compteur incrémenté, mais il n'est pas décrémenté lorsque le TreeIter est détruit. Ceci garantit que l'objet Python ne peut être détruit quand il est utilisé par un TreeIter et produire éventuellement une erreur de segmentation. Malheureusement les comptes de référence supplémentaires font que, au mieux, l'objet Python aura un compte de référence excessif et, au pire, il ne sera jamais libéré même lorsque il n'est pas utilisé. Le dernier cas cause des fuites de mémoire et le premier, des fuites de références.

Pour parer à la situation où le TreeModel personnalisé maintient une référence à l'objet Python jusqu'à ce qu'il ne soit plus disponible (le TreeIter est invalide, car le modèle a changé) et il n'y a pas besoin de relâcher les références, le GenericTreeModel possède une propriété "leak-references". Par défaut, "leak-references" vaut TRUE pour indiquer que le GenericTreeModel relâchera les références. Si "leak-references" vaut FALSE, le compteur de références de l'objet Python ne sera pas incrémenté quand il sera référencé dans un TreeIter. Ce qui signifie que le le TreeModel personnalisé doit conserver une référence à tous les objets Python utilisés dans un TreeIter jusqu'à la destruction du modèle. Malheureusement, même ceci ne protège pas d'un mauvais code qui tente d'utiliser un TreeIter sauvegardé dans un GenericTreeModel différent. Pour se protéger contre ce cas de figure, l'application doit conserver une référence à tous les objets Python référencés dans un TreeIter pour toutes les instances du GenericTreeModel. Naturellement, ceci a le même effet qu'une fuite de références.

Avec PyGTK 2.4 et ultérieurs, les méthodes invalidate_iters() et iter_is_valid() sont disponibles comme aide à la gestion des TreeIter et des références des objets Python :

  generictreemodel.invalidate_iters()

  result = generictreemodel.iter_is_valid(iter)

Ceci est particulièrement utile lorsque la propriété "leak-references" vaut FALSE. Les modèles d'arbre dérivés du GenericTreeModel sont protégés des problèmes de TreeIter périmés, car la validité des iters est automatiquement vérifiée avec le modèle arbre.

Si un modèle d'arbre personnalisé ne gère pas les iters persistants (par exemple, gtk.TREE_MODEL_ITERS_PERSIST n'est pas établi dans le retour de la méthode TreeModel.get_flags(), il est possible d'appeler la méthode invalidate_iters() pour annuler tous les TreeIter en cours quand le modèle est modifié (après insertion d'une nouvelle ligne, par exemple). Le modèle d'arbre peut aussi utiliser n'importe quel objet Python qui a été référencé par un TreeIter après l'appel à la méthode invalidate_iters().

Les applications peuvent utiliser la méthode iter_is_valid() pour déterminer si un TreeIter est encore valide pour le modèle d'arbre personnalisé.

Les modèles ListStore et TreeStore comprennent outre l'interface TreeModel, les interfaces TreeSortable, TreeDragSource et TreeDragDest. Le GenericTreeModel ne comprend que l'interface TreeModel. Je pense que c'est à cause de la référence directe au modèle dans le langage C par les modèles TreeView, TreeModelSort et TreeModelFilter. Créer et utiliser un TreeIter exige un code collant au C pour l'interface avec le modèle d'arbre personnalisé Python qui contient les données. Ce code collant est fourni par le GenericTreeModel et il semble qu'il n'y a pas d'alternative purement Python de réaliser ceci, car le TreeView et les autres modèles appellent les fonctions du GtkTreeModel en C en passant leur référence au modèle d'arbre personnalisé.

L'interface TreeSortable nécessite aussi un code collant au C pour agir sur le mécanisme de tri par défaut du TreeViewColumn ainsi qu'il est expliqué dans la Section 14.2.9, « Ordonner les lignes d'un TreeModel »Ordonner les lignes d'un TreeModel. Cependant un modèle personnalisé doit réaliser ses propres tris et une application doit gérer l'utilisation des critères de tri en prenant en compte les clics sur les en-têtes des TreeViewColumn et en appelant les méthodes de tri du modèle d'arbre personnalisé. Le modèle effectue la mise à jour du TreeView en émettant le signal "rows-reordered" grâce à la méthode rows_reordered() du TreeModel. Ainsi le GenericTreeModel ne nécessite probablement pas d'implémenter l'interface TreeSortable.

Pareillement, le GenericTreeModel n'a pas besoin d' implémenter les interfaces TreeDragSource et TreeDragDest puisque le modèle d'arbre personnalisé peut effectuer ses propres interfaces de glisser-déposer et l'application peut gérer les signaux TreeView appropriés et faire appel aux méthodes du modèle d'arbre personnalisé tant que nécessaire.

Je crois que le GenericTreeModel ne devrait être utilisé qu'en dernier ressort. Les objets standards du TreeView comprennent des mécanismes puissants qui devraient être suffisants pour la plupart des applications. Sans doute, il existe des applications qui peuvent avoir besoin du GenericTreeModel mais il faudrait d'abord essayer d'utiliser ce qui suit :

Si un GenericTreeModel doit être utilisé, il faut veiller à :

• l'interface complète du TreeModel doit être créée et être en mesure de fonctionner comme indiqué. I y a des finesses qui peuvent induire des erreurs. Par opposition, le TreeModel standard a été complètement testé ;
• gérer les références des objets Python utilisés par un TreeIter peut se révéler difficile, particulièrement pour des programmes longs avec beaucoup d'affichages variés ;
• il faut créer une interface pour ajouter, supprimer ou modifier le contenu des lignes. Le lien d'un TreeIter aux objets de Python et aux rangées modèles dans cette interface n'est pas très élégant ;
• le développement d'interfaces de glisser-déposer et de tri demande un effort important, l'application doit trés probablement participer à ce que ces interfaces soient entièrement fonctionnelles.