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.

Figure 14.2. TreeViewColumn avec CellRenderer

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

Figure 14.3. Fonction d'affichage des données cellulaires

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

Figure 14.4. Exemple de liste de fichiers utilisant les fonctions d'affichage de données cellulaires

Un CellRendererText peut présenter un texte enrichi avec des polices et des styles différents plutôt qu'une simple chaine 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 »:

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 chaine) à 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 dens 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é "activable" 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 chaine), 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.

    1   #!/usr/bin/env python
    2   # vim: ts=4:sw=4:tw=78:nowrap
    3   """ Exemple avec Cellrenderer éditables et activables """
    4   import pygtk
    5   pygtk.require("2.0")
    6   import gtk, gobject
    7   
    8   taches =  {
    9       "Faire les courses": "Acheter une baguette",
   10       "Programmer": "Mettre a jour le programme",
   11       "Cuisiner": "Allumer le four",
   12       "Regarder la TV": "Enregistrer \"Urgences\""
   13       } 
   14   
   15   class GUI_Controleur:
   16       """ La classe GUI est le controleur de l'application """
   17       def __init__(self):
   18           # Creation de la fenetre principale
   19           self.fenetre = gtk.Window(type=gtk.WINDOW_TOPLEVEL)
   20           self.fenetre.set_title("Exemple de CellRenderer")
   21           self.fenetre.connect("destroy", self.evnmt_destroy)
   22           # On recupere le modele et on le relie a la vue
   23           self.modele = Ranger.recup_modele()
   24           self.vue = Afficher.cree_vue( self.modele )
   25           # Ajouter la vue a la fenetre principale
   26           self.fenetre.add(self.vue)
   27           self.fenetre.show_all()
   28           return
   29       def evnmt_destroy(self, *kw):
   30           """ Fonction de rappel pour fermer l'application """
   31           gtk.main_quit()
   32           return
   33       def lance(self):
   34           """ La fonction est appelee pour lancer la boucle principale GTK """
   35           gtk.main()
   36           return  
   37   
   38   class InfoModele:
   39       """ La classe du modele contient l'information que nous voulons afficher """
   40       def __init__(self):
   41           """ Creation et remplissage du gtk.TreeStore """
   42           self.tree_store = gtk.TreeStore( gobject.TYPE_STRING,
   43                                            gobject.TYPE_BOOLEAN )
   44           # on place les donnees utilisateur globales dans une liste
   45           # on cree une arborescence simple.
   46           for item in taches.keys():
   47               lignemere = self.tree_store.append( None, (item, None) )
   48               self.tree_store.append( lignemere, (taches[item],None) )
   49           return
   50       def recup_modele(self):
   51           """ Renvoie le modele """
   52           if self.tree_store:
   53               return self.tree_store 
   54           else:
   55               return None
   56   
   57   class AfficheModele:
   58       """ Affiche le modele InfoModele dans un treeview """
   59       def cree_vue( self, modele ):
   60           """ Cree une vue pour le Tree Model """
   61           self.vue = gtk.TreeView( modele )
   62           # Cree le CellRendererText et permet aux cellules
   63           # d'etre editees.
   64           self.renderer = gtk.CellRendererText()
   65           self.renderer.set_property( 'editable', True )
   66           self.renderer.connect( 'edited', self.rappel_edited_col0, modele )
   67   
   68           # Cree le CellRendererToggle et permet sa 
   69           # modification (toggled) par l'utilisateur.
   70           self.renderer1 = gtk.CellRendererToggle()
   71           self.renderer1.set_property('activatable', True)
   72           self.renderer1.connect( 'toggled', self.rappel_toggled_col1, modele )
   73   
   74           # On connecte la colonne 0 de l'affichage a la colonne 0 du modele
   75           # Le cellrenderer va alors afficher tout ce qui est en colonne 0 de
   76           # notre modele .
   77           self.colonne0 = gtk.TreeViewColumn("Nom", self.renderer, text=0)
   78   
   79           # L'etat actif des colonnes est relie a la seconde colonne
   80           # du modele. Ainsi, quand le modele indique True, le bouton
   81           # apparaitra comme actif.
   82           self.colonne1 = gtk.TreeViewColumn("Fait", self.renderer1 )
   83           self.colonne1.add_attribute( self.renderer1, "active", 1)
   84           self.vue.append_column( self.colonne0 )
   85           self.vue.append_column( self.colonne1 )
   86           return self.vue
   87       def rappel_edited_col0( self, cellrenderer, chemin, nouveau_texte, modele ):
   88           """
   89           Appele quand un texte est modifie. Il inscrit le nouveau texte
   90           dans le modele pour qu'il puisse etre affiche correctement.
   91           """
   92           print "Change '%s' en '%s'" % (modele[chemin][0], nouveau_texte)
   93           modele[chemin][0] = nouveau_texte
   94           return
   95       def rappel_toggled_col1( self, cellrenderer, chemin, modele ):
   96           """
   97           Fixe l'etat du bouton a bascule sur true ou false.
   98           """
   99           modele[chemin][1] = not modele[chemin][1]
  100           print "Valeur de '%s'  : %s" % (modele[chemin][0], modele[chemin][1],)
  101           return
  102   
  103   if __name__ == '__main__':
  104       Ranger = InfoModele()	
  105       Afficher = AfficheModele()
  106       monGUI = GUI_Controleur()
  107       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.

Figure 14.6. Cellules éditables et activables