Gestion des listes hiérarchiques

Les listes hiérarchiques sont des objets de formulaire permettant d'afficher des données sous forme de listes comportant un ou plusieurs niveaux qu'il est possible de déployer ou de contracter.

Dans les formulaires, les listes hiérarchiques peuvent servir à l'affichage ou la saisie de données. Chaque élément de liste peut contenir jusqu'à de 2 milliards de caractères (taille maximale d’un champ texte) et être associé à une icône. Les listes hiérarchiques prennent généralement en charge les clics, double-clics, navigation au clavier ou encore le glisser-déposer. Il est possible d'effectuer une recherche parmi le contenu d'une liste (commande Find in list).

Les listes hiérarchiques peuvent être créées entièrement par programmation (via les commandes New list ou Copy list) ou à partir d'énumérations définies dans l'éditeur d'énumérations en mode Développement (commande Load list).

Le contenu et l'apparence des listes hiérarchiques sont gérés par programmation, à l'aide des commandes du thème "Liste hiérarchique". Certaines caractéristiques d'apparence spécifiques peuvent également être définies via les commandes génériques du thème Objets de formulaires (cf. ci-dessous).

Vous pouvez associer dynamiquement des références de listes hiérarchiques aux énumérations des objets de formulaires (sources, valeurs obligatoires et valeurs exclues) à l’aide des commandes OBJECT SET LIST BY REFERENCE ou OBJECT SET LIST BY NAME. Vous pouvez également associer des énumérations définies dans l'éditeur d'énumérations aux objets de formulaires via la Liste des propriétés. 

Une liste hiérarchique est à la fois un objet de langage existant en mémoire et un objet de formulaire.
L'objet de langage est référencé de manière unique par un identifiant interne, de type Entier long, désigné par RefListe dans ce manuel. Cet identifiant est retourné par les commandes permettant de créer des listes New list, Copy list, Load list, BLOB to list. Il n’existe qu’une seule instance en mémoire de l’objet de langage et toute modification effectuée sur cet objet est immédiatement répercutée dans tous les endroits où il est utilisé.
L'objet de formulaire n'est pas nécessairement unique : il peut exister plusieurs représentations d’une même liste hiérarchique dans un même formulaire ou dans des formulaires différents. Comme pour les autres objets de formulaire, vous désignez l'objet dans le langage via la syntaxe (*;"NomListe"...).

Vous connectez l'"objet de langage" liste hiérarchique avec l'"objet de formulaire" liste hiérarchique par l'intermédiaire de la variable contenant la valeur de l'identifiant unique RefListe. Par exemple, si vous écrivez :

... il suffit d'associer le nom de variable maliste à l'objet de formulaire Liste hiérarchique dans la liste des propriétés afin qu'il gère l'objet de langage dont la RefListe est stockée dans maListe.

Chaque représentation de liste dispose de caractéristiques propres et partage des caractéristiques communes avec l’ensemble des représentations. Les caractéristiques propres à chaque représentation de liste sont les suivantes :

• la sélection,
• l’état déployé/contracté des éléments,
• la position du curseur de défilement.
  Les autres caractéristiques (police, style, filtre de saisie, couleur, contenu de la liste, icônes, etc.) sont communes à toutes les représentations et ne peuvent pas être modifiées séparément.
  Par conséquent, lorsque vous utilisez des commandes se basant sur la configuration déployé/contracté ou l'élément courant, par exemple Count list items (lorsque le paramètre * final n’est pas passé), il importe de pouvoir désigner sans ambiguïté la représentation à utiliser.

Vous devez utiliser l'identifiant de type RefListe avec les commandes du langage lorsque vous souhaitez désigner la liste hiérarchique résidant en mémoire.
Si vous souhaitez désigner la représentation au niveau du formulaire d'un objet Liste hiérarchique, vous devez utiliser le nom de l'objet (type chaîne) dans la commande, via la syntaxe (*;"NomListe"...). Cette syntaxe est identique à celle en vigueur dans les commandes du thème "Propriétés des objets". Elle est acceptée par la plupart des commandes du thème "Liste hiérarchique" agissant sur les propriétés des listes (reportez-vous à la description des commandes du thème).

Attention, dans le cas des commandes définissant des propriétés, la syntaxe basée sur le nom d’objet ne signifie pas que seul l’objet de formulaire désigné sera modifié par la commande, mais que l’action de la commande sera basée sur l’état de cet objet. Les caractérisques communes des listes hiérarchiques sont toujours modifiées dans toutes les représentations.
Par exemple, si vous passez l’instruction SET LIST ITEM FONT(*;"maliste1";*;lapolice), vous indiquez que vous souhaitez modifier la police d’un élément de la liste hiérarchique associée à l’objet de formulaire maliste1. La commande tiendra compte de l’élément courant de l’objet maliste1 pour définir l’élément à modifier, mais cette modification sera reportée dans toutes les représentations de la liste dans tous les process.

Comme pour les autres commandes de gestion des propriété d’objets, il est possible d’utiliser le caractère “@” dans le paramètre NomListe. En principe, cette syntaxe permet de désigner un ensemble d’objets dans le formulaire. Toutefois, dans le contexte des commandes de liste hiérarchique, ce principe n’est pas applicable dans tous les cas. Cette syntaxe aura deux effets différents en fonction du type de commande :

• Pour les commandes fixant des propriétés, cette syntaxe désigne tous les objets dont le nom correspond (fonctionnement standard). Par exemple, le paramètre "LH@" désigne tous les objets de type liste hiérarchique dont le nom débute par “LH”. Ces commandes sont :
  DELETE FROM LIST,
  INSERT IN LIST
  SELECT LIST ITEMS BY POSITION
  SET LIST ITEM
  SET LIST ITEM FONT
  SET LIST ITEM ICON
  SET LIST ITEM PARAMETER
  SET LIST ITEM PROPERTIES
• Pour les commandes récupérant des propriétés, cette syntaxe désigne le premier objet dont le nom correspond. Ces commandes sont :
  Count list items
  Find in list
  GET LIST ITEM
  Get list item font
  GET LIST ITEM ICON
  GET LIST ITEM PARAMETER
  GET LIST ITEM PROPERTIES
  List item parent
  List item position
  Selected list items 

Il est possible de modifier l’apparence d’une liste hiérarchique dans un formulaire à l’aide de plusieurs commandes 4D génériques. Vous devez passer à ces commandes soit le nom d’objet de la liste hiérarchique (en utilisant le paramètre *), soit son nom de variable (syntaxe standard).

Note : Dans le cas des listes hiérarchiques, la variable de formulaire contient la valeur de RéfListe. Si vous exécutez une commande de modification d’attribut en lui passant la variable associée à la liste hiérarchique, il ne sera pas possible de définir la liste cible en cas de multi-représentation. Seul le nom d’objet permet donc de différencier individuellement chaque représentation.

Voici la liste des commandes utilisables avec les listes hiérarchiques :
OBJECT SET FONT
OBJECT SET FONT STYLE
OBJECT SET FONT SIZE
OBJECT SET COLOR
OBJECT SET FILTER
OBJECT SET ENTERABLE
OBJECT SET SCROLLBAR
OBJECT SET SCROLL POSITION
OBJECT SET RGB COLORS

Rappel : A l'exception de la commande OBJECT SET SCROLL POSITION, ces commandes modifient toutes les représentations d'une même liste, même si vous désignez une liste via son nom d'objet.

Certaines propriétés d’une liste hiérarchique (par exemple l’attribut saisissable ou la couleur) peuvent être définies de trois manières : via la Liste des propriétés en mode Développement, via une commande du thème “Propriétés des objets” ou via une commande du thème “Liste hiérarchique”.
Lorsque ces trois moyens sont utilisés pour définir les propriétés d’une liste, l’ordre de priorité suivant est appliqué :
1. Commandes du thème “Liste hiérarchique”
2. Commandes générique de propriété d'objet
3. Paramètres de la Liste des propriétés
Ce principe est appliqué quel que soit l’ordre d’appel des commandes. Si une propriété d’élément est modifiée individuellement via une commande de liste hiérarchique, la commande de propriété d’objet équivalente sera sans effet sur cet élément même si elle est appelée ultérieurement. Par exemple, si vous modifiez la couleur d’un élément via la commande SET LIST ITEM PROPERTIES, la commande OBJECT SET COLOR n’aura aucun effet sur cet élément.

Vous pouvez généralement travailler de deux manières avec le contenu des listes hiérarchiques : par position ou par référence.

• Lorsque vous travaillez par position, 4D se base sur la position relative des éléments dans la liste affichée à l'écran pour les identifier. Le résultat sera différent selon que certains éléments hiérarchiques sont déployés ou non. A noter qu'en cas de multi-représentation, chaque objet de formulaire comporte sa propre configuration d'éléments contractés/déployés.
• Lorsque vous travaillez par référence, 4D se base sur le numéro unique réfElément des éléments de la liste. Chaque élément peut être ainsi désigné, quelle que soit sa position ou son affichage dans la liste hiérarchique.

Chaque élément d'une liste hiérarchique dispose d'un numéro de référence (réfElément) de type Entier long. Cette valeur est destinée uniquement à votre propre usage : 4D ne fait que la maintenir.

Attention : Vous pouvez utiliser comme numéro de référence toute valeur de type entier long, sauf la valeur 0. En effet, pour la plupart des commandes de ce thème, la valeur 0 permet de désigner le dernier élément ajouté à la liste.

Voici quelques astuces quant à l'utilisation du numéro de référence unique :

(1) Vous n'avez pas besoin d'identifier chaque élément de façon unique (niveau débutant).

• Premier exemple : vous construisez par programmation un système d'onglets, par exemple, un carnet d'adresses. Comme le système vous retournera le numéro de l'onglet sélectionné, vous n'aurez probablement pas besoin de davantage d'informations. Dans ce cas, ne vous préoccupez pas des numéros de référence des éléments : passez n'importe quelle valeur (hormis 0) dans le paramètre réfElément. Notez que pour un système de carnet d'adresses, vous pouvez prédéfinir une liste A, B,..., Z en mode Développement. Vous pouvez également la créer par programmation afin d'éliminer les lettres pour lesquelles il n'y a pas d'enregistrement.
• Deuxième exemple : en travaillant avec une base, vous construisez progressivement une liste de mots-clés. Vous pouvez sauvegarder la liste à la fin de chaque session, en utilisant les commandes SAVE LIST ou LIST TO BLOB, et la recharger au début de chaque session, à l'aide des commandes Load list ou BLOB to list. Vous pouvez afficher cette liste dans une palette flottante ; lorsque l'utilisateur clique sur un mot-clé de la liste, l'élément choisi est inséré dans la zone saisissable sélectionnée du process de premier plan. Vous pouvez également utiliser le glisser-déposer. En tout état de cause, l'important est que vous ne traitez que l'élément sélectionné (par clic ou glisser-déposer), car les commandes Selected list items (en cas de clic) et DRAG AND DROP PROPERTIES vous retournent la position de l'élément que vous devez traiter. En utilisant cette valeur de position, vous obtenez le libellé de l'élément grâce à la commande GET LIST ITEM. Ici aussi, vous n'avez pas besoin d'identifier de façon unique chaque élément ; vous pouvez passer n'importe quelle valeur (hormis 0) dans le paramètre réfElément.

(2) Vous avez besoin d'identifier partiellement les éléments de la liste (niveau intermédiaire).
Vous utilisez le numéro de référence de l'élément pour stocker l'information nécessaire lorsque vous devez agir sur un élément ; ce point est détaillé dans l'exemple de la commande APPEND TO LIST. Dans cet exemple, nous utilisons les numéros de référence des éléments pour stocker des numéros d'enregistrements. Cependant, nous devons pouvoir établir une distinction entre les éléments qui correspondent aux enregistrements [Départements] et ceux qui correspondent aux enregistrements [Employés].

(3) Vous avez besoin d'identifier les éléments de la liste de façon unique (niveau avancé).
Vous programmez une gestion élaborée de listes hiérarchiques, dans laquelle vous devez absolument pouvoir identifier chaque élément de manière unique à tous les niveaux de la liste. Un moyen simple d'implémenter ce fonctionnement est de maintenir un compteur personnel. Supposons que vous créez une liste hlList à l'aide de la commande APPEND TO LIST. A ce stade, vous initialisez un compteur vlhCounter à 1. A chaque fois que vous appelez APPEND TO LIST ou INSERT IN LIST, vous incrémentez ce compteur (vlhCounter:=vlhCounter+1), et vous passez le compteur comme numéro de référence de l'élément. L'astuce consiste à ne pas décrémenter le compteur lorsque vous détruisez des éléments — le compteur ne peut qu'augmenter. En procédant ainsi, vous garantissez l'unicité des numéros de référence des éléments. Puisque ces numéros sont des valeurs de type Entier long, vous pouvez ajouter ou insérer plus de deux milliards d'éléments dans une liste qui a été réinitialisée... (si vous manipulez d'aussi grandes quantités d'éléments, cela signifie généralement que vous devriez utiliser une table plutôt qu'une liste.)

Note : Si vous exploitez les Opérateurs sur les bits, vous pouvez également utiliser les numéros de référence des éléments pour stocker des informations qui peuvent être logées dans un Entier long, c'est-à-dire 2 Entiers, des valeurs de 4 octets ou encore 32 Booléens.

Dans la plupart des cas, lorsque vous utilisez des listes hiérarchiques pour des besoins d'interface utilisateur, pour lesquels seul l'élément sélectionné (par un clic ou par glisser-déposer) est important, vous n'avez pas besoin d'utiliser les numéros de référence des éléments. Les commandes Selected list items et GET LIST ITEM vous fournissent toutes les informations nécessaires à la gestion de l'élément sélectionné. De plus, des commandes telles que INSERT IN LIST et DELETE FROM LIST vous permettent de manipuler la liste de manière "relative" à l'élément sélectionné.
En pratique, vous devez vous préoccuper des numéros de référence d'éléments lorsque vous voulez accéder directement par programmation à n'importe quel élément de la liste, et pas nécessairement à l'élément couramment sélectionné.