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 donnees. fonct renvoie TRUE si l'état de sélection de la ligne peut être modifié.

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

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. A 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 » (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]
  ...