Richlist

I - INTRODUCTION


UNE LISTE D'ITEMS ENRICHIS : DEMONSTRATION


résultat de la démo :
 
 
   Asia
       China     Beijing
       India     New Delhi
       Japan     Tokyo
   Europe
       England   London
       France    Paris
       Germany   Berlin
       Russia    Moscow
   North America
       Canada    Ottawa
       Mexico    Mexico City
       USA       Washington
   South America
       Brazil    Brasilia
 


source de la démo :
 
 
   # create the rich list
   richlist create countries -country "" -continent "" -capital ""
   # fill the rich list
   set list \ 
   {
     {-country Brazil  -continent "South America"  -capital Brasilia}
     {-country Canada  -continent "North America"  -capital Ottawa}
     {-country China   -continent Asia             -capital Beijing}
     {-country England -continent Europe           -capital London}
     {-country France  -continent Europe           -capital Paris}
     {-country Germany -continent Europe           -capital Berlin}
     {-country India   -continent Asia             -capital "New Delhi"}
     {-country Japan   -continent Asia             -capital Tokyo}
     {-country Mexico  -continent "North America"  -capital "Mexico City"}
     {-country Russia  -continent Asia             -capital Moscow}
     {-country USA     -continent "North America"  -capital Washington}
   }
   foreach item $list { countries add [eval countries create $item] }
   # update an item
   [countries ref (-country|Russia)] config -continent Europe
   # display the countries by continent
     # create an index
   countries index create -continent
     # go thru all continents
   foreach continent [countries values -continent] \ 
   {
     # get continent subset
     set sublist($continent) [countries selection -continent $continent]
     # display continent name
     puts $continent
     # sort continent sublist by countries & capitals names
     $sublist($continent) sort {-country -capital} -dictionary
     # display continent countries & capitals names
     puts [$($continent) foreach item { $item cget -country -capital } \ 
           \n {\t\t%-10s%s}]
   }
 


Commentaires de la démo :
 
La démo crée une Richlist dont les items auront comme options :
-country (de valeur par défaut ""),

-continent (de valeur par défaut ""),

-capital (de valeur par défaut "").

 
 
   richlist create countries -country "" -continent "" -capital ""
 


Ensuite 11 items sont créés avec des options de différentes valeurs, et ajoutés à la liste.
 
 
   foreach item $list { countries add [eval countries create $item] }
 


La valeur de l'option -continent de l'item d'indice (-country|Russia) est modifié.
 
 
   [countries ref (-country|Russia)] config -continent Europe
 


Un index est ajouté sur l'option -continent. Il permettra de partitionner les pays en créant une sous-liste par continent.
 
 
   countries index create -continent
 


Ensuite la démo boucle sur tous les continents.
 
 
   foreach continent [countries values -continent] \ 
   { ... }
 


Pour chaque continent est créée une sous-liste en sélectionnant tous les items dont l'option -continent a la bonne valeur. Cette sélection est réalisée grâce à l'index -continent précédement créé.
 
 
     set sublist($continent) [countries selection -continent $continent]
 


Les items de la sous-liste sont ensuite triés suivant les valeurs des options -country et -capital.
 
 
     $sublist($continent) sort {-country -capital} -dictionary
 


Et pour chaque item, on imprime les valeurs de ces options.
 
 
     puts [$($continent) foreach item { $item cget -country -capital } \ 
           \n {\t\t%-10s%s}]
 


CE QUE C'EST

C'est un package en pur Tcl.

II - DESCRIPTION


CE QU'IL FAIT

a(Rich)List est un package écrit en Tcl, puissant et facile à utiliser, qui gère des listes d'items enrichis.
Ces items, comme les widgets, ont des options qui peuvent prendre des valeurs et, comme les widgets, peuvent exécuter des actions.

Une Richlist peut, selon le besoin, être considérée comme une classe d'objets du pauvre, une table de base de données (chaque item étant une rangée et chaque option étant une colonne) ou comme un description de structure (chaque item étant une occurence de structure et chaque option un élément de structure).

Les items peuvent être regroupés dans des sous-listes qui sont comme des vues sur la table.
La première sous-liste est créée avec la Richlist et les autres sous-listes peuvent être construites à partir d'une simple liste d'items, d'un index sur une sous-liste ou d'opérations ensemblistes sur les sous-listes (union, intersection, différence).
Un index sur une sous-liste est comme un index de table et permet d'accéder aux items par les valeurs d'une option (il accepte des patterns de recherche).
Il est ainsi possible de créer des sous-listes qui partitionnent l'ensemble des items de la Richlist suivant les valeurs d'une option.
Des opérations puissantes permettent de retrouver, modifier, mettre en forme les valeurs de tout ou partie des items d'une sous-liste.

Chaque sous-liste et chaque item est accessible à travers sa référence.
La référence d'une sous-liste est une commande qui permet d'accéder aux opérations de la sous-liste.
La référence d'un item est une commande qui permet d'accéder aux options et aux actions de l'item.

Des callbacks associés à la Richlist permettent de définir des actions à des moments-clefs.
Les actions init et dispose sont appelées à l'initialisation et à la destruction des items.
L'action unknown permet d'intercepter les actions inconnues des items.

COMMENT IL FAIT

A chaque Richlist, sous-liste ou item est associé un identifiant unique.
Un tableau associatif du namespace ::richlist contient toutes les informations associées aux Richlists.
Chaque information est retrouvées grâce aux identifiants uniques. Par exemple la valeur de l'option option de l'item item de la richlist richlist est contenue dans la variable ::richlist::(richlistID:#itemID:option).
La référence de la sous-liste sublist ou de l'item item est générée par la Richlist sous la forme ::richlist::richlistID:@sublistID ou ::richlist::richlistID:#itemID.
Enfin, des liens croisés de la forme ::richlist::(reference:IDtype) et ::richlist::(richlistID:IDtype:ID) permettent de passer d'une référence à un identifiant unique et réciproquement.
Tout cela permet d'utiliser les références au niveau de l'utilisateur alors que le package utilise les ID qui sont beaucoup plus compacts.

III - INSTALLATION


Pour installer le package Richlist :
- téléchargez le fichier Richlist.zip,
- décompressez le fichier dans un répertoire,
- transférez ce répertoire dans le répertoire lib de Tcl.
 
Pour Windows, l'arborescence obtenue doit être :
.../Tcl
.../Tcl/bin
.../Tcl/doc
.../Tcl/lib
.../Tcl/lib/Richlist

IV - UTILISATION


La Richlist s'utilise à travers ses sous-listes et ses items.
Une sous-liste contient une liste des références de ses items.
 
Une Richlist est créée avec l'opération richlist create ref et détruite avec l'opération richlist destroy ref.
Le nom fourni à la création d'une Richlist devient le nom de la référence de la première sous-liste.
Ainsi on peut utiliser une Richlist sans créer d'autre sous-liste.
 
Les opérations sur une Richlist sont :
 
 richlist create  création d'une Richlist
 richlist destroy  destruction d'une Richlist

Pour une description des opérations sur une Richlist, voir la section Les opérations sur une Richlist.
 
Avec la référence d'une sous-liste on peut agir sur la Richlist et :
- créer les items de la Richlist,
- créer, modifier, supprimer les options de la Richlist,
- créer, modifier, supprimer les actions de la Richlist,
- définir les actions callback (init, dispose, unknown) de la Richlist.
 
Avec la référence d'une sous-liste on peut agir sur la sous-liste et :
- ajouter, insérer, supprimer des items dans la sous-liste,
- trier la sous-liste,
- créer d'autres sous-listes,
- exécuter un script pour tous les items de la sous-liste,
- récupérer la liste des références de tout ou partie des items de la sous-liste,
- récupérer la liste des valeurs (suivant un pattern) d'une option pour tous les items de la sous-liste,
- créer un index des valeurs d'une option pour tous les items de la sous-liste,
- retrouver l'identifiant ou la référence d'items de la sous-liste.
 
Avec la référence d'une sous-liste on peut agir sur ses items et :
- récupérer une liste de valeurs des options d'items de la sous-liste,
- modifier les valeurs des options d'items de la sous-liste.
 
Les opérations d'une sous-liste sont :
 
 sref action  gérer une action de la Richlist
 sref add  ajouter un item à la fin de la sous-liste
 sref cget  récupérer les résultats d'opérations cget pour une liste d'items de la sous-liste
 sref configure  récupérer les résultats d'opérations configure pour une liste d'items de la sous-liste
 sref create  créer un item de la Richlist
 sref default  récupérer les valeurs par défaut des options de la Richlist
 sref delete  supprimer un rang d'items dans la sous-liste
 sref destroy  détruire une sous-liste
 sref difference  créer une sous-liste par différence ensembliste
 sref dispose  modifier le callback dispose
 sref foreach  exécuter un script pour tous les items de la sous-liste
 sref id  récupérer les identifiants uniques d'une liste d'items de la sous-liste
 sref index  créer un index pour la sous-liste
 sref info  récupérer des infos sur la sous-liste ou la Richlist
 sref init  modifier le callback init
 sref insert  insérer des items dans la sous-liste
 sref intersection  créer une sous-liste par intersection ensembliste
 sref itemcget  récupérer les valeurs d'une liste d'options pour un item de la sous-liste
 sref itemconfigure  modifier les valeurs d'une liste d'options pour un item de la sous-liste
 sref option  gérer une option de la Richlist
 sref ref  récupérer les références d'une liste d'items de la sous-liste
 sref richlist  retourner la référence de la Richlist
 sref sort  trier la sous-liste
 sref selection  créer une sous-liste à partir d'un index
 sref sublist  créer une sous-liste à partir d'une liste d'items
 sref union  créer une sous-liste par union ensembliste
 sref unknown  modifier le callback unknown
 sref values  récupérer une liste de valeurs suivant un pattern d'une option pour les items de la sous-liste

Pour une description des opérations d'une sous-liste, voir la section Les opérations d'une sous-liste.
 
Avec la référence d'un item on peut :
- récupérer une liste de valeurs des options de l'item,
- modifier les valeurs des options de l'item,
- exécuter une action sur l'item,
- détruire l'item.
 
Les opérations d'un item sont :
 
 iref action  exécuter une action
 iref cget  récupérer une liste de valeurs des options d'un item
 iref configure  modifier les valeurs des options d'un item
 iref destroy  détruire un item
 iref richlist  récupérer la référence de la Richlist

Pour une description des opérations d'un item, voir la section Les opérations d'un item.

IV.1 - Les opérations sur une Richlist

Les opérations sur une Richlist sont :
 
 richlist create  création d'une Richlist
 richlist destroy  destruction d'une Richlist

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

richlist create ref ?option default?...
Cette opération crée une nouvelle Richlist et sa première sous-liste.
ref est le nom de la référence de la Richlist à créer.
Le couple option default crée une option de nom option et de valeur par défaut default.
 
La référence ref est aussi la référence de la première sous-liste de la Richlist. La première sous-liste ne peut pas être supprimée.
 
 
   package require Richlist
   namespace import ::richlist::richlist
   richlist create countries -country "" -continent "" -capital ""
 


richlist destroy ref
Cette opération détruit une Richlist et libère toutes ses ressources.
ref est le nom de la référence de la Richlist à détruire.
 
 
   richlist destroy countries
 


IV.2 - Les opérations d'une sous-liste

Les opérations d'une sous-liste se répartissent en :
- 2.1 - Les opérations sur les actions de la Richlist,
- 2.2 - Les opérations sur les callbacks de la Richlist,
- 2.3 - Les opérations sur les items de la Richlist,
- 2.4 - Les opérations sur les options de la Richlist,
- 2.5 - Les opérations sur la sous-liste,
- 2.6 - Les opérations sur un item de la sous-liste,
- 2.7 - Les opérations sur un index de la sous-liste,
- 2.8 - Les opérations sur d'autres sous-listes.
 
Les opérations d'une sous-liste sont :
 
 sref action  gérer une action de la Richlist
 sref add  ajouter un item à la fin de la sous-liste
 sref cget  récupérer les résultats d'opérations cget pour une liste d'items de la sous-liste
 sref configure  récupérer les résultats d'opérations configure pour une liste d'items de la sous-liste
 sref create  créer un item de la Richlist
 sref default  récupérer les valeurs par défaut des options de la Richlist
 sref delete  supprimer un rang d'items dans la sous-liste
 sref destroy  détruire une sous-liste
 sref difference  créer une sous-liste par différence ensembliste
 sref dispose  modifier le callback dispose
 sref foreach  exécuter un script pour tous les items de la sous-liste
 sref id  récupérer les identifiants uniques d'une liste d'items de la sous-liste
 sref index  créer un index pour la sous-liste
 sref info  récupérer des infos sur la sous-liste ou la Richlist
 sref init  modifier le callback init
 sref insert  insérer des items dans la sous-liste
 sref intersection  créer une sous-liste par intersection ensembliste
 sref itemcget  récupérer les valeurs d'une liste d'options pour un item de la sous-liste
 sref itemconfigure  modifier les valeurs d'une liste d'options pour un item de la sous-liste
 sref option  gérer une option de la Richlist
 sref ref  récupérer les références d'une liste d'items de la sous-liste
 sref richlist  retourner la référence de la Richlist
 sref sort  trier la sous-liste
 sref selection  créer une sous-liste à partir d'un index
 sref sublist  créer une sous-liste à partir d'une liste d'items
 sref union  créer une sous-liste par union ensembliste
 sref unknown  modifier le callback unknown
 sref values  récupérer une liste de valeurs suivant un pattern d'une option pour les items de la sous-liste

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

IV.2.1 - Les opérations sur les actions de la Richlist

Les opérations sur les actions de la Richlist sont :
 
 sref action create  créer une action de la Richlist
 sref action destroy  supprimer une action de la Richlist
 sref action modify  modifier une action de la Richlist

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref action create name parms script
Cette opération crée une action de la Richlist.
sref est le nom de la référence d'une sous-liste.
name est le nom de l'action de la Richlist à créer.
parms est une liste de paramètres pour l'action dans le format attendu par la commande proc.
script est le script de l'action. Ce script peut référencer tous les paramètres de l'action. Il peut aussi référencer les variables me et richlist.
 
Pour une description de l'exécution d'une action, voir la section Exécution d'une action.
 
 
   # create a dump action
   $sref action create dump {} \ 
   {
     set res {}
     foreach {option value} [$me configure] \ 
     { lappend res "$option: $value" }
     return $res
   }
   $sref foreach iref { puts "$iref:\n[join [$iref dump] \n]" }
 


sref action destroy name
Cette opération détruit une action de la Richlist.
sref est le nom de la référence d'une sous-liste.
name est le nom de l'action de la Richlist à supprimer.
 
 
   # destroy the old action
   $sref action destroy $action
 


sref action modify name parms script
Cette opération modifie une action de la Richlist.
sref est le nom de la référence d'une sous-liste.
name est le nom de l'action de la Richlist à modifier.
parms est une liste de paramètres pour l'action dans le format attendu par la commande proc.
script est le script de l'action. Ce script peut référencer tous les paramètres de l'action. Il peut aussi référencer les variables me et richlist.
 
Pour une description de l'exécution d'une action, voir la section Exécution d'une action.
 
 
   # add a title to the dump
   $sref action modify dump {{title ""}} \ 
   {
     set res {}
     set prefix ""
     if {$title != ""} \ 
     { 
       set prefix "\t"
       lappend res "$title:" 
     }
     foreach {option value} [$me configure] \ 
     { lappend res "$prefix$option: $value" }
     return $res
   }
   $sref foreach iref { puts [join [$iref dump $iref] \n] }
 


IV.2.2 - Les opérations sur les callbacks de la Richlist

Les opérations sur les callbacks de la Richlist sont :
 
 sref dispose  modifier le callback dispose
 sref init  modifier le callback init
 sref unknown  modifier le callback unknown

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref dispose script
Cette opération modifie le script du callback dispose.
Ce callback est exécuté avant la destruction d'un item. Il peut servir à libérer les ressources utilisées par l'item.
sref est la référence d'une sous-liste.
script est le script du callback. Ce script peut référencer les variables me et richlist qui sont initialisées en début de script.
Pour une description de l'exécution d'une action, voir la section Exécution d'une action.
 
Par défaut, le script de ce callback est vide.
 
 
   # free the local info
   $sref dispose { array unset ::$me }
 


sref init script
Cette opération modifie le script du callback init.
Ce callback est exécuté après la création d'un item. Il peut servir à allouer et initialiser les ressources utilisées par l'item.
sref est la référence d'une sous-liste.
script est le script du callback. Ce script peut référencer les variables me et richlist qui sont initialisées en début de script.
Pour une description de l'exécution d'une action, voir la section Exécution d'une action.
 
Par défaut, le script de ce callback est vide.
 
 
   $sref init \ 
   { 
     # init the local info 
     array set $me [list time [clock second] \ 
                         pid  [pid] \ 
                         file $::currfile]
   }
 


sref unknown script
Cette opération modifie le script du callback unknown.
Ce callback est exécuté lorsqu'un item tente d'exécuter une action inconnue. Il peut servir à implémenter des actions qui varient en fonction du contexte.
sref est la référence d'une sous-liste.
script est le script du callback. Ce script peut référencer les variables me, richlist et args qui sont initialisées en début de script.
me a comme valeur la référence de l'item qui a tenter d'exécuter l'action inconnue.
richlist a comme valeur la référence de la Richlist (qui permet d'accéder à la première sous-liste).
args a comme valeur une liste contenant la commande exécutée.
Pour une description de cette liste, voir la page de la commande unknown dans le manuel de Tcl.
Pour une description de l'exécution d'une action, voir la section Exécution d'une action.
 
Par défaut, le script de ce callback tente d'appeler les opération cget ou configure si le nom de l'action inconnue est le nom d'une option, et renvoie une erreur sinon.
 
 
   # define the standard unknown callback
   $sref unknown \ 
   {
     # search the options list
     set options [$richlist info options]
     set l [llength $args]
     foreach {name value} $args break
     if {$l < 3 && [set n [lsearch -glob $options $name*]] != -1} \ 
     {
       # the 1st arg is an option
       set option [lindex $options $n]
       if {$l == 1} { $me cget $option } \ 
       else { $me config $option $value }
     } \ 
     else \ 
     { error "unknown action \"$name\"" }
   }
 


IV.2.3 - Les opérations sur les items de la Richlist

Les opération sur les items de la Richlist sont :
 
 sref create  créer un item de la Richlist
 sref info refs  retourner une liste des références de tous les items de la Richlist

Le mot-clef peut être abrégé jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref create ?option value?...
Cette opération crée un nouvel item de la Richlist.
Elle retourne la référence de l'item.
sref est la référence d'une sous-liste.
Le couple option value donne la valeur value à l'option option de l'item.
 
Le callback init est appelé après la création de l'item.
Voir la section Callback d'initialisation d'un item.
 
 
   # create the Brazil country
   countries create \ 
     -country Brazil \ 
     -continent "South America" \ 
     -capital Brasilia
 


sref info refs
Cette opération, avec le nom d'info refs, retourne la liste des références de tous les items de la Richlist.
Pour la description de l'opération info, voir la section Les informations de la Richlist ou de la sous-liste.
 
 
   # get all the items
   set items [$sref info refs]
 


IV.2.4 - Les opérations sur les options de la Richlist

Les opérations sur les options de la Richlist sont :
 
 sref option create  créer une option de la Richlist
 sref default  récupérer les valeurs par défaut des options de la Richlist
 sref option destroy  supprimer une option de la Richlist
 sref option modify  modifier une option de la Richlist

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref option create ?option default?...
Cette opération crée une option de la Richlist.
sref est le nom de la référence d'une sous-liste.
option est le nom de l'option de la Richlist à créer.
default est la valeur par défaut de cette option.
 
 
   # create the -country, -continent & -capital options
   countries option create -country "" -continent "" -capital ""
 


sref default ?option?...
Cette opération retourne les valeurs par défaut d'une liste d'options de la Richlist.
sref est le nom de la référence d'une sous-liste.
option est le nom d'une option de la Richlist dont la valeur par défaut est à ajouter à la liste retournée.
Si aucune option n'est indiquée, l'opération retourne la liste des valeurs par défaut de toutes les options de la Richlist.
 
 
   # get the default values
   set defaults [$sref default -created -tempfile]
 


sref option destroy option
Cette opération détruit une option de la Richlist.
Elle supprime la valeur de l'option pour tous les items et les index basés sur cette option pour toutes les sous-listes.
sref est le nom de la référence d'une sous-liste.
option est le nom de l'option de la Richlist à supprimer.
 
 
   # destroy the old option
   $sref option destroy $option
 


sref action modify ?option default?...
Cette opération modifie une option de la Richlist.
sref est le nom de la référence d'une sous-liste.
option est le nom de l'option de la Richlist à modifier.
default est la nouvelle valeur par défaut de cette option.
 
 
   set date [clock format [clock seconds] -format %Y-%m-%d]
   $sref option modify -createddate $date
 


IV.2.5 - Les opérations sur la sous-liste

Les opérations sur la sous-liste sont :
 
 sref add  ajouter un item à la fin de la sous-liste
 sref cget  récupérer les résultats d'opérations cget pour une liste d'items de la sous-liste
 sref configure  récupérer les résultats d'opérations configure pour une liste d'items de la sous-liste
 sref delete  supprimer un rang d'items dans la sous-liste
 sref destroy  détruire une sous-liste
 sref foreach  exécuter un script pour tous les items de la sous-liste
 sref id  récupérer les identifiants uniques d'une liste d'items de la sous-liste
 sref info  récupérer des infos sur la sous-liste ou la Richlist
 sref insert  insérer des items dans la sous-liste
 sref ref  récupérer les références d'une liste d'items de la sous-liste
 sref richlist  retourner la référence de la Richlist
 sref sort  trier la sous-liste
 sref values  récupérer une liste de valeurs d'une option pour les items de la sous-liste

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref add indice
Cette opération ajoute un item de la Richlist à la fin de la sous-liste.
sref est la référence d'une sous-liste.
indice est l'indice d'un item de la Richlist qui doit être ajouté à la fin de la sous-liste.
Un indice est un moyen de désigner un item dans la Richlist. Ce peut être la référence de l'item, son identifiant unique, son rang dans une sous-liste ou la valeur d'une de ses options telle qu'enregistrée dans un index.
Pour la description d'un rang, voir la section Indices pour un item.
 
 
   # append the last item of the buffer to the stack
   $stack add [$buffer id end]
 


sref cget ?indices-list ?option?...?
Cette opération retourne une liste de résultats de l'opération cget (pour un item) pour une liste d'items.
sref est la référence d'une sous-liste.
indices-list est une liste d'indices d'items de la Richlist pour lesquels l'opération cget (pour un item) doit être exécutée et le résultat ajouté à la liste.
Si aucun liste n'est indiquée, ou si la liste est vide, l'opération a lieu pour tous les items de la sous-liste.
Pour la description d'un indice, voir la section Indices pour un item.
option est le nom d'une option de la Richlist.
Si aucune option n'est indiquée, l'opération porte sur toutes les options de la Richlist.
 
Chaque résultat de l'opération cget (pour un item) est une liste des valeurs des options pour un item.
Le résultat retourné par l'opération est la liste de ces résultats.
 
 
   # get the values of all the options
   set table [$sref cget]
 


sref configure ?indices-list ?option value?...?
Cette opération retourne une liste de résultats de l'opération configure (pour un item) pour une liste d'items.
sref est la référence d'une sous-liste.
indices-list est une liste d'indices d'items de la Richlist pour lesquels l'opération configure (pour un item) doit être exécutée et le résultat ajouté à la liste.
Si aucun indice n'est indiqué, l'opération a lieu pour tous les items de la sous-liste.
Pour la description d'un indice, voir la section Indices pour un item.
option est le nom d'une option de la Richlist qui doit prendre la valeur value.
 
Si aucun couple option value n'est indiqué, l'opération porte sur toutes les options de la Richlist.
Et chaque résultat de l'opération configure est une liste des options, chacune suivie de sa valeur, pour un item.
Le résultat de l'opération est alors la liste de ces résultats.
Si au moins un couple option value est indiqué, l'option option est mise à jour avec la valeur value pour chacun des items.
Le résultat de l'opération configure (pour un item) est une liste vide pour chacun des items.
Et le résultat retourné par l'opération est une liste de ces listes vides.
 
 
   # get the named values of all the options of the last item
   set pairs [$sref configure end]
 


sref delete first ?last?
Cette opération supprime un interval d'items de la sous-liste.
Les items ne sont pas détruits. Pour détruire un item, voir la section Suppression d'un item.
sref est la référence d'une sous-liste.
first est le rang du premier item à supprimer de la sous-liste.
last est le rang du dernier item à supprimer de la sous-liste.
Si last est absent, sa valeur est prise égale à celle de first.
Pour la description d'un rang, voir la section L'identifiant unique d'un item.
 
 
   # delete the items of the sublist but the last
   $sref delete 0 end-1
 


sref destroy
Cette opération détruit une sous-liste et libère toutes ses ressources.
sref est la référence d'une sous-liste.
 
Remarque : La première sous-liste (qui a comme référence la référence de la Richlist) ne peut pas être supprimée.
Pour supprimer la Richlist, voir la section Suppression d'une Richlist.
 
 
   # destroy the sublist
   $sref destroy
 


sref foreach var-name script ?separ ?format??
Cette opération retourne une liste de résultats d'exécution d'un script pour tous les items de la sous-liste.
sref est la référence d'une sous-liste.
var-name est le nom d'une variable définie dans l'environnement du script.
script est un script qui est exécuté une fois pour chacun des items. Ce script peut référencer la variable de nom var-name dont la valeur est la référence de l'item courant.
A chaque exécution le résultat est ajouté à la liste qui est retournée comme résultat de l'opération.
separ est une chaîne de séparation servant à construire une chaîne à partir de la liste résultante et de la commande join.
Si cet argument est absent, la liste est retournée.
format est une chaîne de formattage servant à formatter chaque item de la liste résultante avec la commande format.
Avant d'être formatté, l'item est transformé en chaîne de caractères au moyen de la commande concat.
Si cet argument est absent, les items sont laissés tels qu'ils sont.
 
 
   # display the options -opt1 & -opt2 of all the items of the sublist
   puts [$sref foreach iref { $iref cget -opt1 -opt2 } \n {%-20s%-20s}]
 


sref id ?indice?...
Cette opération retourne une liste d'identifiants uniques d'items de la sous-liste.
sref est la référence d'une sous-liste.
indice est l'indice d'un item de la Richlist dont l'identificateur doit être ajouté à la liste retournée.
Si aucun indice n'est indiqué, l'opération retourne la liste des identifieurs uniques de tous les items de la sous-liste.
Pour la description d'un indice, voir la section Indices pour un item.
 
 
   # sublist of the two last items
   set slist [$sref id end-1 end]
 


sref info name
Cette opération retourne une information de la Richlist ou de la sous-liste.
sref est la référence d'une sous-liste.
name est le nom de l'information à retourner.
  Les noms des informations sont :
 
 actions  la liste des actions de la Richlist
 count  le nombre d'items de la Richlist
 indexes  la liste des index de la sous-liste
 options  la liste des options de la Richlist
 refs  la liste des références de tous les items de la Richlist

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.
 
 
   # get all the options
   set options [$sref info options]
 


sref insert rank ?indice?...
Cette opération insère des items de la Richlist à un certain rang de la sous-liste.
sref est la référence d'une sous-liste.
rank est le rang de l'item de la sous-liste devant lequel seront insérés les nouveaux items.
indice est l'indice d'un item de la Richlist qui doit être inséré dans la sous-liste.
Pour la description d'un indice ou d'un rang, voir la section Indices pour un item.
 
 
   # insert a new item at the head of the sublist
   $sref insert 0 [eval $sref create $optvals]
 


sref ref ?indice?...
Cette opération retourne une liste de références d'items de la sous-liste.
sref est la référence d'une sous-liste.
indice est l'indice d'un item de la Richlist dont la référence doit être ajoutée à la liste retournée.
Si aucun indice n'est indiqué, l'opération retourne la liste des références de tous les items de la sous-liste.
Pour la description d'un indice, voir la section Indices pour un item.
 
 
   # check the items of the two first items
   foreach iref [$sref ref 0 1] { check $iref }
 


sref richlist
Cette opération retourne la référence de la Richlist.
sref est la référence d'une sous-liste.
Pour une description des opérations sur une Richlist, voir la section Les opérations sur une Richlist.
 
 
   # destroy the richlist
   [$sref richlist] destroy
 


sref sort options-list ?sort-option?...
Cette opération trie la sous-liste.
sref est la référence d'une sous-liste.
options-list est une liste d'options selon lesquelles sera triée la sous-liste.
sort-option est une option de tri.
Pour une description des options de tri, voir la page de la commande lsort dans le manuel de Tcl.
 
 
   # sort by country & capital
   $sref sort {-country -capital} -dictionary
 


sref values option ?pattern?
Cette opération retourne une liste des valeurs d'une option dans la sous-liste.
sref est la référence d'une sous-liste.
option est une option de la Richlist.
pattern est un pattern de sélection des valeurs à retourner dans la liste.
Pour une description des patterns de sélection, voir la page de la commande string match dans le manuel de Tcl.
 
 
   # get all the continents of the countries
   countries values -continent
 


IV.2.6 - Les opérations sur un item de la sous-liste

Les opérations sur un item de la sous-liste sont :
 
 sref itemcget  récupérer les valeurs d'une liste d'options pour un item de la sous-liste
 sref itemconfigure  modifier les valeurs d'une liste d'options pour un item de la sous-liste

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref itemcget indice ?option?...
Cette opération retourne une liste de valeurs d'options pour un item de la sous-liste.
sref est la référence d'une sous-liste.
indice est l'indice d'un item de la Richlist.
Pour la description d'un indice, voir la section Indices pour un item.
option est le nom d'une option dont la valeur pour cet item doit être ajoutée à la liste retournée.
En l'absence d'option, l'opération retourne la valeur pour cet item de toutes les options.
 
 
   # display the country & the capital names
   #   of the first country of the continent
   puts [$continent itemcget 0 -country -capital]
 


sref itemconfigure indice ?option value?...
Cette opération modifie les valeurs d'options pour un item de la sous-liste, ou retourne une liste des options et de leur valeur pour l'item.
sref est la référence d'une sous-liste.
indice est l'indice d'un item de la Richlist.
Pour la description d'un indice, voir la section Indices pour un item.
option est le nom d'une option qui doit prendre la nouvelle valeur valeur.
En l'absence de paires option valeur, l'opération retourne une liste composée, pour toutes les options, du nom de l'option suivi de la valeur pour cet item.
 
 
   # set the continent of the Russia
   countries itemconfigure (-country|Russia) -continent Europe
 


IV.2.7 - Les opérations sur un index de la sous-liste

Les opérations sur un index de la sous-liste sont :
 
 sref index create  créer des index pour la sous-liste
 sref index destroy  supprimer des index de la sous-liste

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.
sref index create ?option?...
Cette opération crée des index pour la sous-liste.
sref est la référence d'une sous-liste.
option est une option de la Richlist.
Un index permet de rechercher rapidement des items suivant la valeur de l'option.
Pour les usages d'un index, voir les sections L'identifiant unique d'un item et Création d'une sous-liste à partir d'un index.
 
 
   # access the countries following the continent
   countries index create -continent
   foreach continent [countries values -continent] \ 
   {
     # get continent sublist
     set sublist($continent) [countries selection -continent $continent]
     ...
   }
 


sref index destroy ?option?...
Cette opération supprime des index de la sous-liste.
sref est la référence d'une sous-liste.
option est une option de la Richlist.
 
 
   # delete the continents index
   countries index destroy -continent
 


IV.2.8 - Les opérations sur d'autres sous-listes

Les opérations sur d'autres sous-listes sont :
 
 sref difference  créer une sous-liste par différence ensembliste
 sref intersection  créer une sous-liste par intersection ensembliste
 sref selection  créer une sous-liste à partir d'un index
 sref sublist  créer une sous-liste à partir d'une liste d'items
 sref union  créer une sous-liste par union ensembliste

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

sref difference sref2
Cette opération crée une sous-liste contenant tous les items de sref qui ne sont pas dans sref2.
sref est la référence d'une sous-liste.
sref2 est une sous-liste de la Richlist.
 
 
   # get a sublist of the blue elements that are not big
   set blue_not_big [$blue_elements difference $big_elements]
 


sref intersection sref2
Cette opération crée une sous-liste contenant tous les items qui sont dans sref et dans sref2.
sref est la référence d'une sous-liste.
sref2 est une sous-liste de la Richlist.
 
 
   # get a sublist of the big blue elements
   set blue_and_big [$blue_elements intersection $big_elements]
 


sref selection index pattern
Cette opération crée une sous-liste contenant tous les items dont la valeur de l'option index correspond à pattern.
sref est la référence d'une sous-liste.
index est un index de la sous-liste.
pattern est un pattern de sélection des valeurs à sélectionner.
Pour une description des patterns de sélection, voir la page de la commande string match dans le manuel de Tcl.
 
Les sélections permettent de partitionner une Richlist suivant les valeurs d'une option (correspondant à un index).
 
 
   # get the countries of Asia
   set Asia [$countries selection -continent Asia]
 


sref sublist ?indices-list?...
Cette opération crée une sous-liste contenant les items dont les indices sont dans indices-list.
sref est la référence d'une sous-liste.
indices-list est une liste d'indices d'items de la Richlist.
Si indices-list est absente, la sous-liste créée comprends tous les items de la sous-liste originale.
Pour la description d'un indice, voir la section Indices pour un item.
 
 
   # get an empty list
   set empty [$sref sublist {}]
 


sref union sref2
Cette opération crée une sous-liste contenant tous les items de sref et tous les items de sref2 comptés une seul fois.
sref est la référence d'une sous-liste.
sref2 est une sous-liste de la Richlist.
 
 
   # get a sublist of the blue elements and the big elements
   set blue_or_big [$blue_elements union $big_elements]
 


IV.3 - Les opérations d'un item

Les opérations d'un item sont :
 
 iref action  exécuter une action
 iref cget  récupérer une liste de valeurs des options d'un item
 iref configure  modifier les valeurs des options d'un item
 iref destroy  détruire un item
 iref id  récupérer l'identifiant unique d'un item
 iref richlist  récupérer la référence de la Richlist

Les mots-clefs peuvent être abrégés jusqu'à trois caractères s'il n'y a pas d'ambiguïté.

iref action args
Cette opération exécute une action pour un item.
iref est la référence d'un item.
action est une action de la Richlist.
args sont les arguments passés au script de l'action et tels que décrits par les paramètres de l'action.
 
Pour une description d'une action ou de son exécution pour un item, voir les sections Création d'une action et Exécution d'une action.
 
Le callback unknown est appelé si l'action est inconnue.
Voir la section Callback d'action inconnue.
 
 
   # display the info of the item
   puts [$item dump $title]
 


iref cget ?option?...
Cette opération retourne une liste de valeurs d'options pour l'item.
iref est la référence d'une item.
option est le nom d'une option dont la valeur pour cet item doit être ajoutée à la liste retournée.
En l'absence d'option, l'opération retourne la valeur pour cet item de toutes les options.
 
 
   # display the capital & the continent of the Brazil
   puts [$Brazil cget -capital -continent]
 


iref configure ?option value?...
Cette opération modifie les valeurs d'options pour l'item, ou retourne une liste des options et de leur valeur pour l'item.
iref est la référence d'un item.
option est le nom d'une option qui doit prendre la nouvelle valeur valeur.
En l'absence de paires option valeur, l'opération retourne une liste composée, pour toutes les options, du nom de l'option suivi de la valeur pour cet item.
 
 
   # set the continent of the Russia
   $Russia configure -continent Europe
 


iref destroy
Cette opération supprime l'item et libère toutes ses ressources.
iref est la référence d'un item.
 
Le callback dispose est appelé avant la destruction de l'item.
Voir la section Callback de suppression d'un item.
 
 
   # destroy the old item
   $iref destroy
 


iref id
Cette opération retourne l'identifiant unique de l'item.
iref est la référence d'un item.
 
 
   # get the item id
   set item_id [$iref id]
 


iref richlist
Cette opération retourne la référence de la Richlist.
iref est la référence d'un item.
Pour une description des opérations sur une Richlist, voir la section Les opérations sur une Richlist.
 
 
   # destroy the richlist
   [$iref richlist] destroy
 


IV.4 - Indice pour un item

Un indice est un moyen de désigner un item dans la Richlist.
Ce peut être la référence de l'item, son identifiant unique, son rang dans une sous-liste ou la valeur d'une de ses options telle qu'enregistrée dans un index.
 
Les différents types d'indice sont :
 
 (index|pattern)  un couple index/pattern désignant l'item dont l'option index a la valeur correspondant à pattern
 (option|pattern)  un couple option/pattern désignant l'item dont l'option option a la valeur correspondant à pattern
 id  l'identifiant unique d'un item de la Richlist
 ref  la référence d'un item de la Richlist
 rank  le rang d'un item dans la sous-liste

L'accès à un item par (index|pattern) (qui recherche dans l'index) est plus efficace que l'accès par (option|pattern) (qui demande une recherche à travers la sous-liste).
Un rang est un moyen de désigner un item dans une sous-liste. Ce peut être l'indice dans la liste, le mot-clef end ou end-<entier><entier> représente un nombre entier.
 
 
   # the first & the last item
   set slist [$sref id 0 end]
 


IV.5 - Exécution d'une action

Une action peut être exécutée :
- quand un item exécute une action,
- quand un évènement associé à une action callback survient.
 
Un item exécute une action par la commande iref action args. Où iref est la référence de l'item, action le nom de l'action et args les arguments attendus pour les paramètres.
Voir la section Exécution d'une action par un item.
Voir aussi la section Création d'une action.
Le script de l'action peut référencer tous les paramètres et les deux variables me et richlist.
En début d'exécution ces deux variables sont initialisées.
me reçoit comme valeur la référence de l'item (iref).
richlist reçoit comme valeur la référence de la Richlist (qui permet d'accéder à la première sous-liste).
 
La Richlist exécute une action callback lorsqu'un des évènement suivant survient :
- un item vient d'être créé (le callback init est appelé),
- un item va être détruit (le callback dispose est appelé),
- un item tente d'exécuter une action inconnue (le callback unknown est appelé).
Le script d'une action callback peut référencer les deux variables me et richlist.
Voir ci-dessus pour leur initialisation.
De plus le callback unknown peut référencer la variable args qui contient l'appel de l'action inconnue.
Pour une description des actions callbacks, voir les sections L'action callback dispose, L'action callback init et L'action callback unknown.
 
 
   # create a dump action
   $sref action create dump {} \ 
   {
     set res {}
     foreach {option value} [$me configure] \ 
     { lappend res "$option: $value" }
     return $res
   }
   $sref foreach iref { puts "$iref:\n[join [$iref dump] \n]" }
 


V - TELECHARGEMENT


Richlist.zip
L'URL sur le Web est là.

VI - DISTRIBUTION


VERSION

La présente version est la version 0.9 du 19/10/2003.
Elle a été testée sous Windows 2000 avec Tcl/Tk 8.4.
Elle est conçue pour être portable sur toutes les plate-formes supportées par Tcl/Tk.

LICENCE

Cette version est distribuée sous la licence NOL (No Obligation Licence).
(C) 2003, ulis

REMERCIEMENTS

Ce travail n'aurait pas pu être accompli sans la conception originale de Tcl et Tk par John Ousterhout, le travail du Core Team et le support de tous les Tclers.
Un grand MERCI à tous !

BUGS

Prière d'envoyer les rapports de bug et les demandes d'amélioration à ulis.

VII - BUGS


CORRECTIONS & MODIFICATIONS


 
 Description  Détection  Correction
 version béta     v 0.9 - 19/10/2003