Hugelist - Description

Hugelist

### Le code Tcl de ulis

#### english

### INDEX

INTRODUCTION
DESCRIPTION
INSTALLATION
UTILISATION
TELECHARGEMENT
DISTRIBUTION
BUGS

### INTRODUCTION

#### Une extension de la listbox de Tk qui accepte plus d'un million d'items, affiche des images, des hiérarchies, varie la police...

#### Ce que c'est

C'est un script Tcl implémentant un mégawidget.

### DESCRIPTION

#### Ce qu'il fait

a(Huge)ListBox est un mégawidget écrit en Tcl qui peut remplacer la listbox de Tk 8.4.

##### Ses avantages :

Il apporte des possibilités supplémentaires. Principalement :
- Les lignes paires peuvent avoir une couleur alternative,
- chaque item peut avoir un décalage, une image et/ou une police particulière.
Il est donc possible d'afficher des listes avec des boutons radio ou des cases à cocher, des hiérarchies, des arborescences de répertoires, la liste des polices dans leur propre corp...
Mais son grand intérêt est d'accepter une énorme quantité d'items sans pénalité de temps ou de mémoire
(avec 1 000 000 d'items il est 1000 fois plus rapide à charger, à scroller ou à redimensionner que la listbox).
Et comme c'est un script Tcl il est hautement adaptable.

##### Ses désavantages :

Pour les petites listes, il est 10 fois plus lent que la listbox
(mais le temps de chargement est imperceptible).

##### Erreurs connues :

La fonctionnalité des options -selectmode et -setgrid n'est pas implémentée,
il existe de petites différences par rapport à la listbox (apparence des items actif et sélectionnés,...).

#### Comment il fait

Les items sont virtuels et n'occupent pratiquement pas de place en mémoire et ne demandent aucun délai de création.
Un canvas est utilisé pour afficher la partie visible des items. Toute la cinématique des items est simulée.
Un nombre limité d'items text du canvas permet d'afficher les items lorsqu'ils passent dans la zone d'affichage.
Tous les items qui ont la même configuration partagent la même description.
Une liste d'intervalles d'items permet de retrouver la configuration associée à un item.
Le widget Hugelist répond aux bindings de la classe Listbox.
Une bonne partie du design est décrit à http://mini.net/tcl/mass-widget.

### INSTALLATION

Pour installer le package Hugelist :
- téléchargez le fichier Hugelist.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/Hugelist

### UTILISATION

Le widget Hugelist s'utilise comme le widget listbox, à la déclaration du package près.
(pour les incompatibilités, voir la section Incompatibilités)

`package require Hugelist`
`namespace import hugelist::hugelist`
`set ::listvar {one two three four}`
`hugelist .hl -listvar ::listvar`

#### Les opérations sur la classe

La commande hugelist, avec la syntaxe habituelle [hugelist pathName args], permet de créer des Huglist.
Elle permet aussi deux autres opérations sur la classe :

hugelist option | permet de récupérer ou modifier la valeur par défaut ou la description des options du widget
hugelist version | permet de récupérer le numéro de version de Hugelist

`hugelist option`
Cette opération s'applique aux options du widget et accepte deux options, get et set :

hugelist option get | retourne la liste des options avec les valeurs par défaut
hugelist option get key | retourne la valeur par défaut de l'option key
hugelist option set key | retourne la description de l'option key
hugelist option set key value... | donne la valeur par défaut value à l'option key

Les valeurs par défaut des options sont prises en compte lors de la création d'une Hugelist.
Les valeurs par défaut de la listbox sont utilisées pour initialiser la classe, mais ne sont plus utilisées après.
(pour la liste des nouvelles options du widget, voir la section Les options supplémentaires du widget)

`set descriptions [hugelist option get]`
`set default [hugelist option get -alternate]`
`hugelist option set -bg beige -alt linen`

`hugelist version`
Cette opération retourne le numéro de version de Hugelist.

`set version [hugelist version]`

#### L'opération modifiée

`itemconfigure`
Pour optimiser la gestion des grandes listes, cette opération accepte une syntaxe étendue avec un ou deux index.
Le premier index indique le premier item concerné.
Le deuxième index indique le dernier item concerné.
Si le deuxième index est absent, un seul item est concerné et correspond à l'unique index.
`path itemconfigure first ?last? ?option-paire?...`

`.hl itemconfigure 0 end -left 10`

#### La nouvelle opération

`info`
Cette opération permet d'obtenir les valeurs calculées par le widget :

charheight | hauteur de la police effective
charwidth | largeur du caractère 0 (zéro) de la police effective
colwidth | valeur de la largeur de la colonne utilisée pour le scrolling
count | nombre d'items
font | police effective du widget
rowheight | valeur de la hauteur de la ligne utilisée pour le scrolling

Pour la façon dont le widget calcule ces valeurs, voir la description des options -colwidth, -font, -ipadx, ipady et -rowheight.

`set rowheight [.hl info rowheight]`

#### Les options supplémentaires du widget

`-alternatecolor`
Cette option permet de définir la couleur des lignes paires.

`.hl configure -alternatecolor gray95`

`-colwidth`
Cette option permet de définir la largeur d'une colonne dans une des formes acceptées par Tk_GetPixels.
La valeur de cette option est utilisée pour calculer les déplacements dans la liste (scrollings).
Lorsque la valeur de cette option est vide ou nulle les déplacements sont calculés à partir de la largeur du caractère zéro augmentée de la valeur de l'option -ipadx.

`.hl configure -colwidth ""`

`-font`
Cette option standard permet de spécifier la valeur par défaut de l'option -font de tous les items.
Lorsque la valeur de cette option est vide, la police utilisée est la police standard de la listbox.
Cette valeur est aussi prise en compte lorsque la valeur de l'option -rowheight est vide ou nulle.
Dans ce cas, la hauteur d'une ligne est calculée à partir de la hauteur de la police augmentée de la valeur du paramètre -ipady.
Cette valeur est aussi prise en compte lorsque la valeur de l'option -colwidth est vide ou nulle.
Dans ce cas, la largeur d'une colonne est calculée à partir de la largeur du caractère 0 (zéro) augmentée de la valeur du paramètre -ipadx.

`.hl configure -font {-family Times -size -16}`

`-image (ou -img)`
Cette option permet de spécifier la valeur par défaut de l'option -image de tous les items.
Cette valeur est prise en compte lorsque la valeur de l'option -image d'un item est vide.
(voir la section Les options supplémentaires des items)

`.hl configure -image img_first`

`-ipadx`
Cette option permet de spécifier la valeur à ajouter à la largeur du caractère 0 (zéro) pour calculer la largeur d'une colonne.
Cette valeur est prise en compte lorsque la valeur de l'option -colwidth est vide ou nulle.
Dans ce cas, la largeur d'une colonne est calculée à partir de la largeur du caractère 0 (zéro) augmentée de la valeur du paramètre -ipadx.

`.hl configure -ipadx 0`

`-ipady`
Cette option permet de spécifier la valeur à ajouter à la hauteur de la police pour calculer la hauteur d'une ligne.
Cette valeur est prise en compte lorsque la valeur de l'option -rowheight est vide ou nulle.
Dans ce cas, la hauteur d'une ligne est calculée à partir de la hauteur de la police augmentée de la valeur du paramètre -ipady.

`.hl configure -ipadx 0`

`-left`
Cette option permet de spécifier la valeur par défaut de l'option -left de tous les items.
Cette valeur est prise en compte lorsque la valeur de l'option -left d'un item n'est pas définie.
(voir la section Les options supplémentaires des items)

`.hl configure -left 10`

`-rowheight`
Cette option permet de définir la hauteur d'une ligne dans une des formes acceptées par Tk_GetPixels.
La valeur de cette option est utilisée pour calculer les déplacements dans la liste (scrollings).
Lorsque la valeur de cette option est vide ou nulle les déplacements sont calculés à partir de la hauteur de la police augmentée de la valeur de l'option -ipady.

`.hl configure -rowheight 20`

`-text`
Cette option permet de spécifier la valeur par défaut du texte de tous les items.
Cette valeur est prise en compte lorsque le texte d'un item est vide.
(voir la section Les options supplémentaires des items)

`hugelist .hl -list ::list`
`.hl configure -text "(empty)"`
`set ::list [list $a $b $c $d]`

`-user`
Cette option est au seul usage de l'utilisateur.

`.hl configure -user {hugelist 4}`

`-values`
Cette option permet de spécifier la liste des textes des items.

`.hl configure -values {one two three four}`

`-xscrollcommand`
Cette option permet de spécifier le préfixe de la commande à exécuter lors de l'appel à l'opération xset.
La commande est construite en ajoutant au préfixe deux arguments :
- la fraction (entre 0 et 1) définissant le début horizontal de la zone visible,
- la fraction (entre 0 et 1) définissant la fin horizontale de la zone visible.
En général, cette commande correspond à l'opération set d'un widget scrollbar horizontal.
Cette commande n'est appelée que lorsqu'elle est définie, aussi il n'y a pas d'erreur si le widget scrollbar n'est pas encore défini.

`.hl configure -xscrollcommand {.hs set}`

`-yscrollcommand`
Cette option permet de spécifier le préfixe de la commande à exécuter lors de l'appel à l'opération yset.
La commande est construite en ajoutant au préfixe deux arguments :
- la fraction (entre 0 et 1) définissant le début vertical de la zone visible,
- la fraction (entre 0 et 1) définissant la fin verticale de la zone visible.
En général, cette commande correspond à l'opération set d'un widget scrollbar vertical.
Cette commande n'est appelée que lorsqu'elle est définie, aussi il n'y a pas d'erreur si le widget scrollbar n'est pas encore défini.

`.hl configure -yscrollcommand {.vs set}`

#### Les options supplémentaires des items

`-font`
Cette option permet de spécifier une police pour l'item.

`.hl itemconfigure 0 -font {-family Times -size -16}`

`-image (ou -img)`
Cette option permet de spécifier une image pour l'item.

`.hl itemconfigure 0 -image img_first`

`-left`
Cette option permet de spécifier une marge à la gauche de l'item.

`.hl itemconfigure end-1 -left 10`

`-text`
Cette option permet de spécifier le texte d'un item.

`.hl itemconfigure end -text "[.hl temcget end -text] (last)"`

### TELECHARGEMENT

Hugelist.zip

### DISTRIBUTION

#### Version

La présente version est la version 1.3 du 20/04/2003.
Elle a été testée sous Windows 2000 avec Tcl/Tk 8.4.
Elle passe 90% des tests du widget listbox (voir la section Incompatibilités pour les incompatibilités).
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 Tcler's.
Un grand MERCI à tous !
Un remerciement spécial à Bernd Platzdasch qui a testé la version béta de Hugelist

#### Bugs

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

### BUGS CONNUS

#### Incompatibilités

La Hugelist passe 300 des tests du widget listbox et échoue à 30 tests.
Voici un résumé du résultat :

Type d'incompatibilité | Nombre | Cause
gestion des items | 6 | configuration de masse
scrolling | 6 | scrolling de masse
messages d'erreur | 6 | optimisation de masse
gestion du recouvrement partiel de la liste box | 5 | bizzarerie à éviter
options supplémentaires | 2 | options supplémentaires
opération itemconfigure | 1 | syntaxe étendue
gestion de l'index anchor | 1 | il ne dépasse plus le dernier enregistrement
gestion de la sélection X | 1 | la sélection n'est pas supprimée sur perte de focus
protection de la variable | 1 | sais pas comment faire :-(
option activestyle | 1 | partiellement implémenté
classe de binding | 1 | pas le même nom de classe

La Hugelist n'utilise pas directement la base des options de Tk.
En fait, la classe Hugelist est initialisée à partir des valeurs par défaut des options de la classe Listbox.
Ensuite, il faut utiliser la commandes [hugelist option] pour modifier les valeurs par défaut.
(voir la section Les opérations sur la classe)

#### Corrections et modifications

Description | Détection | Correction
publication officielle |  | v 1.0 - 08/12/2002
nouvelle option -left pour les items |  | v 1.1 - 09/02/2003
nouvelle option -rowheight pour le widget |  | v 1.1 - 09/02/2003
redimensionnement dynamique | Scott Gamon - 27/02/2003 | v 1.2 - 09/03/2003
gestion des valeurs par défaut |  | v 1.2 - 09/03/2003
nouvelle option -user pour le widget |  | v 1.2 - 13/03/2003
nouvelle option -image pour le widget |  | v 1.2 - 23/03/2003
nouvelle option -left pour le widget |  | v 1.2 - 23/03/2003
nouvelle option -text pour le widget |  | v 1.2 - 23/03/2003
bug: traitement de l'option -listvar | ulis - 29/03/2003 | v 1.2.1 - 29/03/2003
bug: traitement de insert & delete | ulis - 30/03/2003 | v 1.2.2 - 30/03/2003
compatibilité: bbox & scan | ulis - 31/03/2003 | v 1.2.3 - 01/04/2003
nouvelle option -ipadx pour le widget |  | v 1.3 - 20/04/2003
nouvelle option -ipady pour le widget |  | v 1.3 - 20/04/2003
nouvelle option -charwidth pour le widget |  | v 1.3 - 20/04/2003
nouvelle option -font pour les items | Scott Gamon | v 1.3 - 20/04/2003
nouvelle opération info |  | v 1.3 - 20/04/2003