Les listes et arbres en GTK+

• Convertir un itérateur en chemin :

GtkTreePath* gtk_tree_model_get_path(GtkTreeModel *tree_model, GtkTreeIter *iter);

La mémoire allouée pour le chemin doit ensuite être libérée par :

void gtk_tree_path_free(GtkTreePath *path);

Et voici une autre fonction qui fait, presque, la même chose :

gchar *gtk_tree_model_get_string_from_iter(GtkTreeModel *tree_model, GtkTreeIter *iter);

• Convertir un chemin en référence :

GtkTreeRowReference* gtk_tree_row_reference_new(GtkTreeModel *model, GtkTreePath *path);

• Convertir une référence en chemin :

GtkTreePath* gtk_tree_row_reference_get_path(GtkTreeRowReference *reference);

renvoie NULL si la référence n'est pas valide.

• Convertir un chemin en itérateur :

gboolean gtk_tree_model_get_iter(GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreePath *path);

et, en partant du texte du chemin, on utilise :

gboolean gtk_tree_model_get_iter_from_string(GtkTreeModel *tree_model, GtkTreeIter *iter, const gchar *path_string);

• Connaître l'enregistrement suivant dans le niveau courant :

gboolean gtk_tree_model_iter_next(GtkTreeModel *tree_model, GtkTreeIter *iter);

Modifie l'itérateur courant pour passer au suivant, la fonction retourne FALSE s'il n'y a pas de suivant.

• Savoir si un enregistrement a des fils :

gboolean gtk_tree_model_iter_has_child(GtkTreeModel *tree_model, GtkTreeIter *iter);

• Savoir combien un enregistrement a de fils :

gint gtk_tree_model_iter_n_children(GtkTreeModel *tree_model, GtkTreeIter *iter);

• Accéder au premier fils d'un enregistrement :

gboolean gtk_tree_model_iter_children(GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *parent);

• Accéder au nième fils d'un enregistrement :

gboolean gtk_tree_model_iter_nth_child(GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *parent, gint n);

(le premier enregistrement porte le numéro 0)

• Accéder au père d'un enregistrement :

gboolean gtk_tree_model_iter_parent(GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *child);

• Créer un nouvel objet chemin :

GtkTreePath *gtk_tree_path_new(void);

• Convertir une chaîne de caractères (« 2:3:0:1 ») en chemin :

GtkTreePath *gtk_tree_path_new_from_string(const gchar *path);

• Créer un chemin à partir d'une liste d'entiers :

GtkTreePath *gtk_tree_path_new_from_indices(gint first_index, ..., -1);

• Convertir un chemin en chaîne de caractères :

gchar *gtk_tree_path_to_string(GtkTreePath *path);

• Accéder au chemin du premier enregistrement (« 0 ») :

GtkTreePath *gtk_tree_path_new_first(void);

• Ajouter un index (le numéro d'un fils) à un chemin :

void gtk_tree_path_append_index(GtkTreePath *path, gint index);

• Ajouter un index (numéro de parent de plus au niveau) au début d'un chemin :

void gtk_tree_path_prepend_index(GtkTreePath *path, gint index);

• Calculer le niveau d'imbrication d'un chemin :

gint gtk_tree_path_get_depth(GtkTreePath *path);

• Convertir un chemin en tableau d'entiers :

gint *gtk_tree_path_get_indices(GtkTreePath *path);

• Libérer la mémoire allouée pour un chemin :

void gtk_tree_path_free(GtkTreePath *path);

• Copier la valeur d'un chemin :

GtkTreePath *gtk_tree_path_copy(const GtkTreePath *path);

• Comparer deux chemins :

gint gtk_tree_path_compare(const GtkTreePath *a, const GtkTreePath *b);

renvoie 0 s'ils sont égaux, -1 si a est avant b, 1 si a est après b.

• Déplacer le chemin vers l'enregistrement suivant, au même niveau :

void gtk_tree_path_next(GtkTreePath *path);

• Déplacer le chemin vers l'enregistrement précédent, au même niveau :

gboolean gtk_tree_path_prev(GtkTreePath *path);

renvoie FALSE s’il n'y a plus d'enregistrement précédent à ce niveau.

• Faire pointer le chemin vers le père de l'enregistrement :

gboolean gtk_tree_path_up(GtkTreePath *path);

renvoie FALSE si l'enregistrement n'a pas de père.

• Faire pointer l'enregistrement vers le premier fils de l'enregistrement :

void gtk_tree_path_down(GtkTreePath *path);

• Vérifier la descendance entre deux chemins :

gboolean gtk_tree_path_is_ancestor(GtkTreePath *path, GtkTreePath *descendant);
gboolean gtk_tree_path_is_descendant(GtkTreePath *path, GtkTreePath *ancestor);

• Vérifie si une référence est non NULL et valide (les données correspondantes peuvent avoir été supprimées) :

gboolean gtk_tree_row_reference_valid(GtkTreeRowReference *reference);

• Libère la mémoire allouée pour une référence :

void gtk_tree_row_reference_free(GtkTreeRowReference *reference);

• Copie la valeur d'une référence :

GtkTreeRowReference* gtk_tree_row_reference_copy(GtkTreeRowReference *reference);

La base des méthodes pour obtenir une présentation triée des lignes est indépendante du type de modèle (liste simple ou arbre).

La première étape consiste à obtenir une copie « triable » du magasin par les instructions :

GtkTreeSortable *sortable;
sortable = GTK_TREE_SORTABLE(store);

ensuite, il faut écrire une fonction de comparaison dont le prototype est le suivant :

gint* GtkTreeIterCompareFunc(GtkTreeModel *model,

GtkTreeIter *a, GtkTreeIter *b, gpointer user_data);

• le premier paramètre donne bien sûr le modèle concerné, mais attention, il est de type GtkTreeModel donc il faudra généralement le transtyper en GtkListStore ou GtkTreeStore pour l'utiliser ;
• les deux paramètres suivants sont des itérateurs sur les lignes à comparer ;
• tandis que le dernier paramètre est un pointeur sur les données passées lors de l'attachement en tant que fonction de rappel (il est habituel de passer ici le numéro correspondant au type de tri) ;
• la valeur de retour doit être 0 si les deux lignes sont équivalentes, -1 si la ligne pointée par « a » est supérieure à la ligne pointée par « b », et 1 sinon.

Il est possible d'écrire une fonction qui fait un traitement différent en fonction du numéro de type de tri ; il est aussi possible d'écrire autant de fonctions que de types de tri.

Au départ, il était prévu de définir un type de tri par colonne, mais en fait, rien n'oblige à utiliser les valeurs de cette colonne comme critère pour réaliser les tests, et donc le « numéro de colonne » correspond désormais à un type de test ; une des conséquences de cela est que le numéro du critère de tri n'est pas limité au nombre de colonnes du magasin.

Il faut maintenant lier la fonction de tri au magasin en lui associant un numéro de critère (« column_id », voir l'explication ci-dessus). on utilise pour cela la fonction :

void gtk_tree_sortable_set_sort_func (GtkTreeSortable *sortable,
gint sort_column_id, GtkTreeIterCompareFunc sort_func,
gpointer user_data, GtkDestroyNotify destroy);

• Classiquement, le premier paramètre (sortable) est le magasin concerné, dans sa version « triable » ;
• le deuxième paramètre est le numéro (sort_column_id) du critère de tri ;
• le troisième paramètre (sort_func) est la fonction de comparaison définie précédemment ;
• le quatrième paramètre (user_data) est un pointeur vers les données à passer là la fonction de comparaison, on l'utilise souvent pour indiquer le critère de tri lorsqu'on ne développe qu'une seule fonction de comparaison ;
• le dernier paramètre (destroy) est une fonction de rappel qui est appelée en cas de destruction des données utilisateurs (user_data), la plupart du temps on passe la valeur NULL pour ce paramètre.

Il est possible de définir un tri par défaut pour le magasin en utilisant la fonction :

void gtk_tree_sortable_set_default_sort_func (GtkTreeSortable *sortable,
GtkTreeIterCompareFunc sort_func, gpointer user_data,
GtkDestroyNotify destroy);

• Le premier paramètre (sortable) est le magasin concerné, dans sa version « triable » ;
• le deuxième paramètre (sort_func) est la fonction de comparaison définie précédemment ;
• le troisième paramètre (user_data) est un pointeur vers les données à passer là la fonction de comparaison, on l'utilise souvent pour indiquer le critère de tri lorsqu'on ne développe qu'une seule fonction de comparaison ;
• le dernier paramètre (destroy) est une fonction de rappel qui est appelée en cas de destruction des données utilisateurs (user_data), la plupart du temps on passe la valeur NULL pour ce paramètre.

Si le troisième paramètre (user_data) a la valeur NULL, alors, par défaut le magasin n'est pas trié.

Il est possible de trier le magasin en définissant un critère de tri grâce à la fonction :

void gtk_tree_sortable_set_sort_column_id(GtkTreeSortable *sortable, gint sort_column_id, GtkSortType order);

Rappel : le critère de tri est défini sous le nom de « sort_column_id » dans le nom de la fonction aussi bien que dans le nom du paramètre en raison de la sémantique initiale de la fonctionnalité de tri.

Le dernier paramètre indique l'ordre de tri en utilisant les constantes : GTK_SORT_ASCENDING et GTK_SORT_DESCENDING.

Si la valeur du critère de tri est GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, alors, c'est le critère de tri par défaut qui est utilisé. Si la fonction de tri par défaut est NULL alors, le magasin redevient non trié ce qui permet d'utiliser d'autres formes de tri(3).

Une autre méthode de tri consiste à faire en sorte que le tri se déclenche en cliquant sur les titres de colonne. Cette méthode est simple à mettre en œuvre et naturelle pour l'utilisateur.

Il suffit d'associer un critère de tri à chacune des colonnes qui doivent permettre le tri lors de la création de l'afficheur. on utilise pour cela la fonction :

void gtk_tree_view_column_set_sort_column_id(GtkTreeViewColumn *tree_column, gint sort_column_id);

Le premier clic trie dans l'ordre ascendant, le second dans l'ordre descendant.

Il se peut que vous ne souhaitiez pas trier directement les données dans le magasin ; par exemple parce que vous utilisez plusieurs afficheurs différents sur le même magasin.

III-C-4-a. La technique▲

GtkTreeModel* gtk_tree_model_sort_new_with_model(GtkTreeModel *child_model);

/* Exemple de magasin intermédiaire pour le tri */
GtkListStore *store; /* Le magasin principal */
GtkTreeModel *sortstore; /* Le magasin intermédiaire */
GtkTreeSortable *sortable; /* Le magasin triable */

store = gtk_list_store_new(5, G_TYPE_STRING, /* [...] */ );

/* Remplissage du magasin avec les données */
/* Création du magasin intermédiaire */
sortstore = gtk_tree_model_sort_new_with_model(store);

/* Application des fonctions de tri */
gtk_tree_sortable_set_sort_func(sortable, 25, sort_iter_compare_func, NULL, NULL);

/* Éventuellement, appel de gtk_tree_sortable_set_sort_column_id() */
/* Création de l'afficheur */
GtkWidget *tree;
GtkCellRenderer *renderer;
GtkTreeViewColumn *column;

tree = gtk_tree_view_new_with_model(GTK_TREE_MODEL(sortstore));
renderer = gtk_cell_renderer_text_new();
column = gtk_tree_view_column_new_with_attributes("Auteur", renderer, "text", 0, NULL);
gtk_tree_view_append_column(GTK_TREE_VIEW(tree), column);

/* Éventuellement appel de (gtk_tree_view_column_set_sort_column_id) */
gtk_tree_view_column_set_sort_column_id(column, 25);

III-C-4-b. Remarque sur les itérateurs et les chemins▲

GtkTreePath* gtk_tree_model_sort_convert_path_to_child_path(GtkTreeModelSort *tree_model_sort, GtkTreePath *sorted_path);
void gtk_tree_model_sort_convert_iter_to_child_iter(GtkTreeModelSort *tree_model_sort,GtkTreeIter *child_iter, GtkTreeIter *sorted_iter);

GtkTreePath* gtk_tree_model_sort_convert_child_path_to_path(GtkTreeModelSort *tree_model_sort, GtkTreePath *child_path);
void gtk_tree_model_sort_convert_child_iter_to_iter(GtkTreeModelSort *tree_model_sort,GtkTreeIter *sort_iter, GtkTreeIter *child_iter);

GtkTreeModel *gtk_tree_model_sort_get_model(GtkTreeModelSort *tree_model);

/* Suppression de la ligne sélectionnée */
/* En début de programme on a créé une sélection unique */
GtkWidget *tree;
GtkTreeSelection *select;

select = gtk_tree_view_get_selection(GTK_TREE_VIEW(tree));
gtk_tree_selection_set_mode(select, GTK_SELECTION_SINGLE);

/* Voici maintenant le contenu de la fonction de suppression */
GtkTreeIter sortiter, iter;
GtkTreeModelSort *sortstore;
GtkListStore *store;

if (gtk_tree_selection_get_selected(select, &sortstore, &sortiter)) {
    store = GTK_LIST_STORE(gtk_tree_model_sort_get_model(sortstore));
    gtk_tree_model_sort_convert_iter_to_child_iter(sortstore, &iter, &sortiter);
    gtk_list_store_remove(store, &iter);
}

Cette méthode fait partie de GtkTreeModel, elle est donc applicable indifféremment aux listes et aux arbres, mais elle nécessite un transtypage de votre magasin en magasin générique avec la macro GTK_TREE_MODEL().

Cette méthode se passe en deux temps :

• premièrement, il faut écrire la fonction à exécuter pour chaque enregistrement de données, comme elle va être utilisée en fonction de rappel, elle doit avoir un prototype imposé qui est le suivant :

gboolean user_func(GtkTreeModel *model, GtkTreePath *path, GtkTreeIter *iter, gpointer data);

Cette fonction vous permet donc d'accéder aux données par un chemin ou un itérateur et disposez d'un accès aux données passées lors de la connexion de cette fonction.

Si la fonction renvoie la valeur TRUE, le parcours du magasin s'arrête.

Pour récupérer les données, la technique la plus simple est certainement l'utilisation de la fonction :

void gtk_tree_model_get(GtkTreeModel *model, GtkTreeIter *iter, ..., -1);

Les deux premiers paramètres sont évidemment ceux que vous avez reçus en paramètres d'entrée de votre fonction, tandis qu'en suite vous avez une liste, terminée par -1, de couples numéro de colonne/pointeur sur la valeur. Il s'agit de pointeurs sur la valeur puisque c'est la fonction qui va modifier ces valeurs.

• ensuite, il faut demander l'exécution de cette fonction sur toutes les données du magasin en appelant :

void gtk_tree_model_foreach(GtkTreeModel *model, GtkTreeModelForeachFunc func, gpointer user_data);

Rien de très original, mais comme un exemple(4) vaut mieux qu'un long discours :

/* Exemple de dump d'un arbre */
gboolean foreach_func(GtkTreeModel *model,
    GtkTreePath *path, GtkTreeIter *iter, gpointer user_data)
{
    gchar *name;
    gdouble prix;
    gint depth;

    gtk_tree_model_get(model, iter, 0, &name, 2, &prix, -1);
    depth = gtk_tree_store_iter_depth(GTK_TREE_STORE(model), iter);
    if(depth)
        g_fprintf(user_data, "+%s:%0.2f\n", name, prix);
    else
        g_fprintf(user_data, "%s\n", name);

    g_free(name); /* Libérer la mémoire pour les chaînes de caractères */
    return FALSE; /* Continuer à parcourir l'arbre */
}

gboolean xx_save_in_file(const gchar *filename)
{
    FILE *fp;
    /* Sauvegarder le magasin dans un fichier */
    fp = fopen(filename,"w");
    if(fp == NULL) return FALSE;

    gtk_tree_model_foreach(GTK_TREE_MODEL(store), foreach_func, fp);
    fclose(fp);
    return TRUE;
}

Cette technique reste simple dans le cas d'une liste, c'est un peu plus compliqué pour un arbre (à cause de la gestion du niveau d'imbrication).

Bon, commençons par le début, donc récupérons l'itérateur du premier élément par la fonction :

gboolean gtk_tree_model_get_iter_first(GtkTreeModel *tree_model, GtkTreeIter *iter);

Ensuite, il faut récupérer un itérateur sur la donnée suivante :

gboolean gtk_tree_model_iter_next(GtkTreeModel *tree_model, GtkTreeIter *iter);

Dans le cas d'une liste, tout va bien ; on appelle cette fonction jusqu'à ce que la valeur de retour soit FALSE. Par contre, dans le cas d'un arbre, c'est plus compliqué, car cette fonction permet d'accéder à la donnée suivante de même niveau. Donc avant, de passer à la suite, il faut vérifier si la donnée n'a pas de fils par :

gboolean gtk_tree_model_iter_has_child(GtkTreeModel *tree_model, GtkTreeIter *iter);

Si c'est le cas, il faut récupérer le premier fils par :

gboolean gtk_tree_model_iter_children(GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *parent);

Il ne reste plus qu'à parcourir les fils comme vu plus haut, en n'oubliant pas de s'occuper de leurs enfants s'ils en ont.

Eh bien oui, un parcours d'arbre ça finit presque toujours par une fonction récursive. Alors, la voici :

/* Exemple de parcours d'arbre */
gboolean browse_tree(GtkTreeModel *model, GtkTreeIter *parent, gint level)
{
    gboolean ret;
    GtkTreeIter iter;

    if(parent == NULL)
        ret = gtk_tree_model_get_iter_first(model, &iter);
    else
        ret = gtk_tree_model_iter_children(model, &iter, parent);
    
    /* Au cas où le (sous-)arbre à explorer serait vide */
    if(!ret) return FALSE;
    
    do {
        gtk_tree_model_get(model, &iter, /* Données à récupérer, */ -1);
        /** TRAITEMENT des données de l'enregistrement **/

        if(gtk_tree_model_iter_has_child(model, &iter))
            browse_tree(model, &iter, level+1);
    } until (!gtk_tree_model_iter_next(model, &iter));
    return TRUE;
}

/* Le premier appel se fait par : */
browse_tree(model, NULL, 0);

Il est possible de créer un afficheur sans liaison avec un magasin par la fonction :

GtkWidget *gtk_tree_view_new(void);

On peut ensuite l'associer à un modèle avec la fonction :

void gtk_tree_view_set_model(GtkTreeView *tree_view, GtkTreeModel *model);

si l'afficheur était déjà lié à un magasin, ce lien est supprimé avant d'en créer un autre avec le magasin passé en paramètre.

Il peut aussi être intéressant de connaître le magasin qui contient les données affichées, pour cela, on utilise la fonction :

GtkTreeModel *gtk_tree_view_get_model(GtkTreeView *tree_view);

IV-A-2-a. Masquer les titres de colonnes▲

void gtk_tree_view_set_headers_visible(GtkTreeView *tree_view, gboolean headers_visible);

gboolean gtk_tree_view_get_headers_visible(GtkTreeView *tree_view);

IV-A-2-b. Autoriser le clic sur les titres de colonne▲

void gtk_tree_view_set_headers_clickable(GtkTreeView *tree_view, gboolean setting);

IV-A-2-c. Gestion des marques de suivi des lignes▲

void gtk_tree_view_set_rules_hint (GtkTreeView *tree_view, gboolean setting);

gboolean gtk_tree_view_get_rules_hint (GtkTreeView *tree_view);

IV-A-2-d. Gestion des regroupements de lignes▲

void gtk_tree_view_expand_all(GtkTreeView *tree_view);

void gtk_tree_view_collapse_all(GtkTreeView *tree_view);

void gtk_tree_view_expand_to_path(GtkTreeView *tree_view, GtkTreePath *path);

gboolean gtk_tree_view_expand_row(GtkTreeView *tree_view, GtkTreePath *path, gboolean open_all);

gboolean gtk_tree_view_collapse_row(GtkTreeView *tree_view, GtkTreePath *path);

gboolean gtk_tree_view_row_expanded(GtkTreeView *tree_view, GtkTreePath *path);

void gtk_tree_view_set_expander_column(GtkTreeView *tree_view, GtkTreeViewColumn *column);

void gtk_tree_view_map_expanded_rows(GtkTreeView *tree_view, GtkTreeViewMappingFunc func, gpointer data);

void func(GtkTreeView *tree_view, GtkTreePath *path, gpointer user_data);

Les fonctions qui permettent de gérer les colonnes, même si elles font partie de l'objet GtkTreeView, sont présentées plus loin avec la présentation détaillée des colonnes pour plus de clarté dans l'exposé.

Le principe ressemble fort à la gestion des tris.

• D'abord, il faut écrire une fonction de comparaison qui a le prototype suivant :

gboolean equal_func(GtkTreeModel *model, gint column, const gchar *key, GtkTreeIter *iter, gpointer search_data);

• ensuite, il faut dire que l'on souhaite utiliser cette fonction pour la recherche interactive :

void gtk_tree_view_set_search_equal_func(GtkTreeView *tree_view, 
    GtkTreeViewSearchEqualFunc search_equal_func,
    gpointer search_user_data, GtkDestroyNotify search_destroy);

• ensuite, il faut choisir la colonne du magasin où est appliquée la recherche :

void gtk_tree_view_set_search_column (GtkTreeView *tree_view, gint column);

ceci active en même temps la recherche.

Il est aussi possible d'activer ou désactiver la recherche par :

void gtk_tree_view_set_enable_search(GtkTreeView *tree_view, gboolean enable_search);

Enfin, il est possible de connaître le paramétrage courant de la recherche par les fonctions :

gboolean gtk_tree_view_get_enable_search (GtkTreeView *tree_view);
gint gtk_tree_view_get_search_column (GtkTreeView *tree_view);
GtkTreeViewSearchEqualFunc gtk_tree_view_get_search_equal_func(GtkTreeView *tree_view);

On voudra souvent accompagner l'afficheur de barres de défilement, horizontales et/ou verticales. L'objet GtkTreeView fait partie des quelques widgets (avec GtkTextView et GtkLayout) qui ont été conçus en prévoyant cet ajout ; il est donc très simple.

Il faut créer une fenêtre avec barres de défilement par la fonction :

GtkWidget* gtk_scrolled_window_new(GtkAdjustment *hadjustment, GtkAdjustment *vadjustment);

Les paramètres permettent de définir très précisément les caractéristiques des barres de défilement, comme le pas de celles-ci. En général, on laissera faire GTK+ en passant la valeur NULL.

Ensuite, il faut préciser la gestion des barres de défilement avec la fonction :

void gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window, GtkPolicyType hscroll_policy, GtkPolicyType vscroll_policy);

Pour les deux derniers paramètres, on utilise les constantes GTK_POLICY_ALWAYS, GTK_POLICY_AUTOMATIC, GTK_POLICY_NEVER.

Maintenant, il ne reste plus qu'à insérer l'afficheur dans cette fenêtre avec gtk_container_add().

Comme un exemple vaut mieux qu'un long discours :

/* Exemple d'afficheur d'arbre avec ascenseurs */
GtkTreeStore *store;
GtkWidget *tree, *pScrollbar;

tree = gtk_tree_view_new_with_model(GTK_TREE_MODEL(store));
pScrollbar = gtk_scrolled_window_new(NULL, NULL);

gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(pScrollbar), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC);
gtk_container_add(GTK_CONTAINER(pScrollbar), tree);

Nous avons vu plus haut qu'il est possible facilement de créer une colonne avec un afficheur élémentaire grâce à gtk_tree_view_column_new_with_attributes().

En fait, il est possible de décomposer toutes les opérations. GTK+ autorise même de mettre plusieurs afficheurs élémentaires dans une même colonne.

Pour mettre plusieurs afficheurs élémentaires dans une même cellule, le principe ressemble beaucoup à la Hbox ; on utilise les fonctions :

void gtk_tree_view_column_pack_start(GtkTreeViewColumn *tree_column, GtkCellRenderer *cell, gboolean expand);

et

void gtk_tree_view_column_pack_end(GtkTreeViewColumn *tree_column, GtkCellRenderer *cell, gboolean expand);

le paramètre expand à FALSE indique qu'aucun espace supplémentaire ne doit être utilisé par l'afficheur élémentaire ; cet espace est reparti entre les afficheurs pour lesquels il est à TRUE.

Il est possible de récupérer la liste des afficheurs contenus dans une colonne par la fonction :

Glist *gtk_tree_view_column_get_cell_renderers(GtkTreeViewColumn *tree_column);

Cette liste est doublement chaînée, elle n'est pas dans un ordre particulier. Après usage, il faut penser à libérer la mémoire avec g_list_free().

Il est possible de supprimer tous les afficheurs élémentaires contenus dans une colonne par la fonction :

void gtk_tree_view_column_clear(GtkTreeViewColumn *tree_column);

Cependant, dans ce cas, il faut ajouter les attributs(5) aux afficheurs élémentaires ensuite grâce aux fonctions :

void gtk_tree_view_column_set_attributes(GtkTreeViewColumn *tree_column, GtkCellRenderer *cell_renderer, ..., NULL);

et

void gtk_tree_view_column_add_attribute(GtkTreeViewColumn *tree_column, GtkCellRenderer *cell_renderer, const gchar *attribute, gint column);

ainsi que :

void gtk_tree_view_column_clear_attributes(GtkTreeViewColumn *tree_column, GtkCellRenderer *cell_renderer);

La première fonction permet de fixer une liste de couples attribut/valeur pour l'afficheur élémentaire selon une syntaxe proche de celle de gtk_tree_view_column_new_with_attributes(). Attention, cette fonction efface toutes les affectations préexistantes.

La deuxième fonction affecte la valeur d'un attribut en complément des affectations existantes.

La dernière fonction permet bien évidemment d'effacer toutes les affectations existantes de valeur aux attributs.

En complément, il est possible de gérer un espacement entre les afficheurs élémentaires grâce aux fonctions :

void gtk_tree_view_column_set_spacing(GtkTreeViewColumn *tree_column, gint spacing);

et

gint gtk_tree_view_column_get_spacing(GtkTreeViewColumn *tree_column);

la valeur de l'espacement est mesurée en pixels.

Parmi les paramètres de présentation que l'on peut gérer au niveau d'une colonne, on trouve la visibilité et le redimensionnement de la largeur.

IV-B-2-a. Visibilité d'une colonne▲

void gtk_tree_view_column_set_visible(GtkTreeViewColumn *tree_column, gboolean visible);

gboolean gtk_tree_view_column_get_visible (GtkTreeViewColumn *tree_column);

IV-B-2-b. Redimensionnement de la largeur d'une colonne▲

void gtk_tree_view_column_set_sizing(GtkTreeViewColumn *tree_column, GtkTreeViewColumnSizing type);

GtkTreeViewColumnSizing gtk_tree_view_column_get_sizing(GtkTreeViewColumn *tree_column);

gint gtk_tree_view_column_get_width(GtkTreeViewColumn *tree_column);

gint gtk_tree_view_column_get_fixed_width(GtkTreeViewColumn *tree_column);

void gtk_tree_view_column_set_fixed_width(GtkTreeViewColumn *tree_column, gint fixed_width);

void gtk_tree_view_column_set_min_width(GtkTreeViewColumn *tree_column, gint min_width);

gint gtk_tree_view_column_get_min_width(GtkTreeViewColumn *tree_column);

void gtk_tree_view_column_set_max_width(GtkTreeViewColumn *tree_column, gint max_width);

gint gtk_tree_view_column_get_max_width(GtkTreeViewColumn *tree_column);

void gtk_tree_view_column_set_expand(GtkTreeViewColumn *treecolumn, gboolean expand);

gboolean gtk_tree_view_column_get_expand (GtkTreeViewColumn *tree_column);

void gtk_tree_view_column_set_resizable(GtkTreeViewColumn *tree_column, gboolean resizable);

gboolean gtk_tree_view_column_get_resizable(GtkTreeViewColumn *tree_column);

En fait, il ne reste plus qu'une seule caractéristique : le titre.

IV-B-3-a. Gestion du titre de la colonne▲

void gtk_tree_view_column_set_title(GtkTreeViewColumn *tree_column, const gchar *title);

G_CONST_RETURN gchar *gtk_tree_view_column_get_title(GtkTreeViewColumn *tree_column);

void gtk_tree_view_column_set_widget(GtkTreeViewColumn *tree_column, GtkWidget *widget);

GtkWidget* gtk_tree_view_column_get_widget(GtkTreeViewColumn *tree_column);

IV-C-1-a. La notion d'attribut▲

IV-C-1-b. Les attributs variables▲

IV-C-1-c. Les attributs constants▲

void g_object_set(gpointer object, ..., NULL);

GTK+ fournit trois afficheurs élémentaires(6) : un pour l'affichage de texte (même si c'est une valeur numérique ou booléenne), un pour l'affichage d'icônes, un pour l'affichage de case à cocher.

IV-C-2-a. Afficheur de texte▲

GtkCellRenderer* gtk_cell_renderer_text_new (void);

IV-C-2-b. Afficheur d'icône▲

GtkCellRenderer* gtk_cell_renderer_pixbuf_new(void);

IV-C-2-c. Afficheur binaire▲

GtkCellRenderer* gtk_cell_renderer_toggle_new(void);

void gtk_cell_renderer_toggle_set_radio(GtkCellRendererToggle *toggle, gboolean radio);

Parfois, on a envie d'avoir un formatage plus précis que celui qui est autorisé par les attributs de l'afficheur élémentaire. C'est par exemple le cas pour les valeurs flottantes lorsque l'on veut choisir le nombre de chiffres après la virgule.

GTK+ nous offre une méthode(7) pour préparer l'affichage avant le passage de l'afficheur élémentaire. Il suffit d'utiliser la fonction :

void gtk_tree_view_column_set_cell_data_func(GtkTreeViewColumn *tree_column, 
    GtkCellRenderer *renderer, GtkTreeCellDataFunc func, 
    gpointer func_data, GtkDestroyNotify destroy);

La fonction de rappel doit avoir le prototype suivant :

void user_func(GtkTreeViewColumn *tree_column, GtkCellRenderer *cell,

GtkTreeModel *tree_model, GtkTreeIter *iter, gpointer data);

Dans cette fonction de rappel, il devient possible de positionner les attributs de l'afficheur élémentaire avec plus de souplesse. Attention cependant, si un attribut doit être forcé dans certains cas et pas d'autres, il faut lui en supprimer la valeur quand c'est inutile.

Un bon exemple vaut mieux qu'un long discours :

/* Exemple data_cell_function */
void double_display_function(GtkTreeViewColumn *col,
    GtkCellRenderer *renderer, GtkTreeModel *model,
    GtkTreeIter *iter, gpointer user_data)
{
    gdouble montant;
    guint colnum = GPOINTER_TO_UINT(user_data);
    gchar buf[20];

    gtk_tree_model_get(model, iter, colnum, &montant, -1);
    if(montant > 0.0) {
        g_snprintf(buf, sizeof(buf), "%.2f", montant);
        g_object_set(renderer, "text", buf, "visible", TRUE, NULL);
    } else {
        g_object_set(renderer, "visible", FALSE, NULL);
    }
}

/* [...] */
renderer = gtk_cell_renderer_text_new();
column = gtk_tree_view_column_new_with_attributes ("Montant",renderer,NULL);
gtk_tree_view_column_set_cell_data_func(column, renderer,
    double_display_function, GUINT_TO_POINTER(4), NULL);

gtk_tree_view_append_column(GTK_TREE_VIEW(tree), column);

Il est possible de modifier la valeur valeur d'une cellule texte en saisissant une nouvelle valeur dans la case.

Pour l'utilisateur, lorsque cette fonction est activée, il suffit de cliquer dans une case d'une ligne sélectionnée (par un clic précédent), de saisir la nouvelle valeur puis de valider par la touche « Entrée » ou en cliquant en dehors de la cellule en cours de saisie ; l'utilisateur peut renoncer à changer la valeur de la cellule en utilisant la touche « Escape(8) ».

Sur le plan de la programmation, il faut autoriser la saisie dans la cellule en donnant la valeur TRUE à l'attribut « editable » de l'afficheur élémentaire. Si toute la colonne doit être éditable, alors on utilise un attribut constant dont on fixe la valeur par :

g_object_set(renderer, "editable", TRUE, NULL);

(rien n'empêche de grouper cet attribut avec d'autres attributs constants.) mais il est aussi possible de lier cet attribut à une colonne dont les valeurs sont booléennes (cf. Les attributs variablesLes attributs variables).

Ensuite, il faut encore aller modifier le contenu du magasin lorsque l'utilisateur a saisi une nouvelle valeur dans la cellule. Pour cela, il faut récupérer le signal « edited » de l'afficheur élémentaire par la fonction g_signal_connect().

Pour ce signal, il faut définir une fonction de rappel dont le prototype est le suivant :

void user_function(GtkCellRendererText *renderer, gchar *path_string, gchar *new_text, gpointer user_data);

Le deuxième paramètre donne le chemin, sous forme de chaîne de caractères, de la ligne concernée par la saisie. Le troisième paramètre fournit le texte (en chaîne de caractères même pour une valeur numérique) qui a été saisi. Le dernier paramètre renvoie classiquement les données qui ont été fournies lors de l'attachement du signal.

Comme il est délicat de remonter au numéro de colonne du magasin en partant de l'afficheur élémentaire (cf. Remonter de la colonne d'un afficheur à la colonne d'un magasinRemonter de la colonne d'un afficheur à la colonne d'un magasin), il est fortement recommandé de mettre ce numéro de colonne comme donnée utilisateur lors de l'attachement du signal (ou au moins parmi les données). L'autre solution consiste à attacher le numéro de colonne à l'afficheur comme décrit iciAssocier le numéro de colonne.

Aucune possibilité d'édition en ligne n'est prévue.

Selon un principe analogue à l'afficheur texte, il faut rendre la cellule modifiable en positionnant à TRUE l'attribut « activatable ». Si toute la colonne doit être éditable, alors on utilise un attribut constant dont on fixe la valeur par :

g_object_set(renderer, "activatable", TRUE, NULL);

(rien n'empêche de grouper cet attribut avec d'autres attributs constants.) mais il est aussi possible de lier cet attribut à une colonne dont les valeurs sont booléennes (cf. Les attributs variablesLes attributs variables).

Ensuite, il faut encore aller modifier le contenu du magasin lorsque l'utilisateur a saisi une nouvelle valeur dans la cellule. Pour cela, il faut récupérer le signal « toggled » de l'afficheur élémentaire par la fonction g_signal_connect().

Pour ce signal, il faut définir une fonction de rappel dont le prototype est le suivant :

void user_function(GtkCellRendererToggle *renderer, gchar *path_string, gpointer user_data);

Le deuxième paramètre donne le chemin, sous forme de chaîne de caractères, de la ligne concernée par la saisie. Le dernier paramètre renvoie classiquement les données qui ont été fournies lors de l'attachement du signal.

Lorsque l'utilisateur clique sur la case, ni l'apparence de la case à cocher ni la valeur dans le magasin ne sont modifiées, pour que l'apparence change, il faut que le programme aille modifier la valeur dans le magasin (il faut d'abord lire l'ancienne valeur dans le magasin pour pouvoir forcer la valeur opposée).

Il est possible de récupérer facilement l'information du double clic dans une colonne en récupérant le signal « row-activated ».

Il faut connecter le signal au niveau de l'afficheur. La fonction de rappel doit avoir le prototype suivant :

void user_function(GtkTreeView *treeview, GtkTreePath *arg1, GtkTreeViewColumn *arg2, gpointer user_data);

En fait, lorsqu'on regarde les informations disponibles, on s'aperçoit que l'on dispose de la colonne, mais aussi de la ligne (chemin). Cependant, il ne faut pas en déduire qu'il est simple de remonter à la colonne correspondante du magasin (cf. Remonter de la colonne d'un afficheur à la colonne d'un magasinRemonter de la colonne d'un afficheur à la colonne d'un magasin).

La gestion d'un menu contextuel se fait généralement par un clic sur le bouton droit de la souris.

Comme tous les widgets de GTK+, l'afficheur de listes et d'arbres gère ce clic, il suffit de connecter le signal « button-press-event ». Dans la fonction de traitement, il faut s'assurer que c'est bien le bouton droit de la souris qui a été utilisé.

Habituellement, le menu contextuel doit aussi pouvoir être accessible sur l'appui de la touche Shift-F10 sans utilisation de la souris. Pour cela, il faut connecter le signal « popup-menu » à l'afficheur.

La gestion d'un menu pop-up sort du cadre de ce document.

Dans le cas d'une sélection simple (GTK_SELECTION_SINGLE ou GTK_SELECTION_BROWSE), il est facile de récupérer un itérateur qui pointe sur la donnée sélectionnée.

Comme vu plus haut, il est possible de récupérer le magasin et l'itérateur de la donnée par la fonction :

gboolean gtk_tree_selection_get_selected(GtkTreeSelection *selection, GtkTreeModel **model, GtkTreeIter *iter);

La fonction retourne une valeur vraie lorsqu'un élément est effectivement sélectionné.

Quelques précisions complémentaires :

• Cette fonction ne doit pas être utilisée si le mode est GTK_SELECTION_MULTIPLE ;
• Si l'appel de la fonction a seulement pour objet de savoir s’il y a une ligne sélectionnée ou non, il est possible de mettre NULL pour le paramètre « iter ».

V-A-2-a. Fonction de récupération d'une sélection▲

Glist *gtk_tree_selection_get_selected_rows(GtkTreeSelection *selection, GtkTreeModel **model);

V-A-2-b. Transformation des chemins en références▲

V-A-2-c. Parcours de la liste▲

void g_list_foreach(GList *list, GFunc func, gpointer user_data);

void func(gpointer data, gpointer user_data);

gint gtk_tree_selection_count_selected_rows(GtkTreeSelection *selection);

Glist *element; chemin = element->data;

Glist *g_list_first(GList *list);

Glist *g_list_last(GList *list);

Glist *g_list_next(GList *list);

Glist *g_list_previous(GList *list);

Glist *g_list_nth(GList *list, guint n);

gpointer g_list_nth_data(GList *list, guint n);

V-A-2-d. Libération de la mémoire▲

g_list_foreach (list, gtk_tree_path_free, NULL);

g_list_free (list);

Il est aussi possible de parcourir directement (au niveau gtk) les éléments sélectionnés grâce à la fonction :

void gtk_tree_selection_selected_foreach(GtkTreeSelection *selection,

    GtkTreeSelectionForeachFunc func, gpointer data);

la fonction de rappel doit avoir le prototype suivant :

gboolean func(GtkTreeModel *model,

    GtkTreePath *path, GtkTreeIter *iter, gpointer data);

Le premier paramètre est le magasin, le deuxième le chemin, le troisième l'itérateur, et le dernier les données fournies lors de l'appel à gtk_tree_selection_selected_foreach().

Si la fonction renvoie la valeur TRUE, le parcours de la sélection s'arrête.

Si l'utilisateur peut gérer la sélection en utilisant le souris et/ou le clavier, il est aussi possible de la modifier par programme. Pour cela, GTK+ met à notre disposition les fonctions suivantes :

void gtk_tree_selection_select_iter(GtkTreeSelection *selection, GtkTreeIter *iter);

void gtk_tree_selection_unselect_iter(GtkTreeSelection *selection, GtkTreeIter *iter);

void gtk_tree_selection_select_path(GtkTreeSelection *selection, GtkTreePath *path);

void gtk_tree_selection_unselect_path(GtkTreeSelection *selection, GtkTreePath *path);

void gtk_tree_selection_select_all(GtkTreeSelection *selection);

void gtk_tree_selection_unselect_all(GtkTreeSelection *selection);

void gtk_tree_selection_select_range(GtkTreeSelection *selection,

    GtkTreePath *start_path, GtkTreePath *end_path);

void gtk_tree_selection_unselect_range(GtkTreeSelection *selection,

    GtkTreePath *start_path, GtkTreePath *end_path);

La majorité de ces fonctions ont bien évidemment un comportement qui dépend du mode de sélection en cours (GTK_SELECTION_SINGLE, GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE). Si le mode est SINGLE ou BROWSE, la fonction gtk_tree_selection_select_iter() désélectionnera la ligne précédemment sélectionnée avant d'en sélectionner une nouvelle ; tandis que gtk_tree_selection_select_all() n'aura pas d'effet.

Il est possible d'être au courant que la sélection a changé en récupérant le signal « changed » avec une fonction de rappel dont le prototype est le suivant :

void user_function(GtkTreeSelection *treeselection, gpointer user_data);

Mais on peut faire mieux, c'est-à-dire être prévenu chaque fois que l'utilisateur souhaite sélectionner ou désélectionner une ligne pour donner notre accord (par programme). pour cela, on utilise la fonction :

void gtk_tree_selection_set_select_function(GtkTreeSelection *selection,

    GtkTreeSelectionFunc func, gpointer data, GtkDestroyNotify destroy);

Cette fonction utilise une fonction de rappel ayant le prototype :

gboolean user_func(GtkTreeSelection *selection, GtkTreeModel *model,

    GtkTreePath *path, gboolean currently_selected, gpointer data);

Le paramètre path permet de connaître la ligne concernée par le changement de sélection, tandis que currently_selected donne l'état actuel de la sélection (avant l'action utilisateur).

Si la fonction retourne TRUE, alors le changement de sélection est effectué, sinon, il n'est pas pris en compte.

Lorsque l'on connaît une colonne de l'afficheur et que l'on veut remonter à la colonne correspondante du magasin, la technique n'est pas simple. En fait, c'est tout bonnement impossible sauf à faire certaines hypothèses, parce qu'une colonne d'afficheur peut être liée à plusieurs colonnes du magasin :

• parce la colonne d'affichage contient plusieurs afficheurs élémentaires ;
• parce que l'afficheur élémentaire a plusieurs attributs liés à des colonnes différentes du magasin.

Nous supposerons donc dans la suite qu'il n'y a qu'un seul afficheur dans la colonne concernée, et que nous recherchons la colonne du magasin associée à l'attribut principal de l'afficheur élémentaire (« text » pour un afficheur de texte, « pixbuf » pour un afficheur d'icônes et « active » pour un afficheur booléen.

Donc, procédons par étape :

• depuis la colonne de l'afficheur, remontons à l'afficheur élémentaire par :

Glist *gtk_tree_view_column_get_cell_renderers(GtkTreeViewColumn *tree_column);

• puis :

renderer = CellList->data;

• ensuite, il faudrait savoir à quel type d'afficheur élémentaire on a affaire, mais on va simplement rechercher les attributs qui nous intéressent :

… et là, on est coincé : pas moyen de remonter à la colonne, l'objet GtkTreeViewColumn ne fournit pas de fonction gtk_tree_view_column_get_attribute(), la fonction g_objetc_get() sur l'afficheur élémentaire ne nous rendrait elle qu'un attribut constant, ce qui n'est pas ce que l'on recherche.

Puisqu'il n'est pas possible de remonter de l'afficheur élémentaire à la colonne du magasin avec les fonctions du noyau de GTK, la solution consiste à ajouter cette information dans la colonne ou à l'afficheur élémentaire lors de la constitution de la vue.

VI-A-2-a. Choisir entre colonne et afficheur élémentaire▲

VI-A-2-b. Associer le numéro de colonne▲

void g_object_set_data(GObject *object, const gchar *key, gpointer data);

gpointer g_object_get_data(GObject *object, const gchar *key);

/* Exemple 1 de passage de la colonne afficheur au magasin */
GtkTreeView *view,;
GtkTreeViewColumn *column;
guint ncol;

column = gtk_tree_view_column_new();
g_object_set_data
    (G_OBJECT(column), "columnnum", GUINT_TO_POINTER(COL_XXX));

/* [...] */
ncol = GPOINTER_TO_UINT(g_object_get_data(G_OBJECT(column), "columnnum");

/* Exemple 2 de passage de la colonne afficheur au magasin */
GtkTreeView *view,;
GtkTreeViewColumn *column;
GtkCellRenderer *renderer;
guint ncol;

renderer = gtk_cell_renderer_text_new();
g_object_set_data
    (G_OBJECT(renderer), "columnnum", GUINT_TO_POINTER(COL_XXX));

column = gtk_tree_view_column_new_with_attributes
    ("Titre XXX", renderer, "text", COL_XXX, NULL);

/* [...] */
ncol = GPOINTER_TO_UINT(g_object_get_data(G_OBJECT(renderer), "columnnum");

Glib https://developer.gnome.org/glib/

Gobject https://developer.gnome.org/gobject/stable/

Pango https://developer.gnome.org/pango/stable/

ATK https://developer.gnome.org/atk/stable/

GdkPixbuf https://developer.gnome.org/gdk-pixbuf/stable/

GDK https://developer.gnome.org/gdk3/stable/

GTK https://developer.gnome.org/gtk3/index.html

par Tim-Philipp Müller http://scentric.net/tutorial en anglais

par gtk-fr.org http://www.gtk-fr.org/index.php?page=cours&id=23 en français