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 Chercher dans liste).

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

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 OBJET FIXER LISTE PAR REFERENCE ou OBJET FIXER LISTE PAR NOM. 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 Nouvelle liste, Copier liste, Charger liste, BLOB vers liste. 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 Nombre elements (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 FIXER POLICE ELEMENT(*;"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 :
  SUPPRIMER DANS LISTE,
  INSERER DANS LISTE
  SELECTIONNER ELEMENTS PAR POSITION
  CHANGER ELEMENT
  FIXER POLICE ELEMENT
  FIXER ICONE ELEMENT
  FIXER PARAMETRE ELEMENT
  CHANGER PROPRIETES ELEMENT
• Pour les commandes récupérant des propriétés, cette syntaxe désigne le premier objet dont le nom correspond. Ces commandes sont :
  Nombre elements
  Chercher dans liste
  INFORMATION ELEMENT
  Lire police element
  LIRE ICONE ELEMENT
  LIRE PARAMETRE ELEMENT
  LIRE PROPRIETES ELEMENT
  Element parent
  Position element liste
  Elements selectionnes 

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 :
OBJET FIXER POLICE
OBJET FIXER STYLE POLICE
OBJET FIXER TAILLE POLICE
OBJET FIXER COULEUR
OBJET FIXER FILTRE SAISIE
OBJET FIXER SAISISSABLE
OBJET FIXER BARRES DEFILEMENT
OBJET FIXER DEFILEMENT
OBJET FIXER COULEURS RVB

Rappel : A l'exception de la commande OBJET FIXER DEFILEMENT, 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 CHANGER PROPRIETES ELEMENT, la commande OBJET FIXER COULEUR 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 STOCKER LISTE ou LISTE VERS BLOB, et la recharger au début de chaque session, à l'aide des commandes Charger liste ou BLOB vers liste. 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 Elements selectionnes (en cas de clic) et PROPRIETES GLISSER DEPOSER 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 INFORMATION ELEMENT. 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 AJOUTER A LISTE. 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 Nouvelle liste. A ce stade, vous initialisez un compteur vlhCounter à 1. A chaque fois que vous appelez AJOUTER A LISTE ou INSERER DANS LISTE, 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 Elements selectionnes et INFORMATION ELEMENT vous fournissent toutes les informations nécessaires à la gestion de l'élément sélectionné. De plus, des commandes telles que INSERER DANS LISTE ou SUPPRIMER DANS LISTE 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é.