AJOUTER A LISTE

version 2003 (Modifiée)

AJOUTER A LISTE (liste; texteElément; réfElément{; sous_Liste; déployée})

La commande AJOUTER A LISTE ajoute un nouvel élément à la liste hiérarchique dont vous avez passé le numéro de référence dans le paramètre liste.

Vous passez le libellé de l'élément dans le paramètre texteElément. Vous pouvez passer une expression de type Alpha ou Texte de 255 caractères maximum. Si vous passez un libellé plus long, il sera tronqué.

Vous passez le numéro de référence unique de l'élément dans le paramètre réfElément. Même si nous qualifions ce numéro de référence d'élément comme unique, vous pouvez en réalité passer la valeur que vous voulez. Reportez-vous ci-dessous au paragraphe "Exploiter les numéros de référence des éléments".

Si vous souhaitez également que l'élément comporte des sous-éléments, passez un numéro de référence de liste valide dans le paramètre sous_Liste. Dans ce cas, vous devez également passer le paramètre déployé. Passez Vrai ou Faux dans ce paramètre pour que cette sous-liste s'affiche respectivement déployée ou contractée.

La référence de la liste que vous passez dans sous_Liste doit être une liste existante. Elle peut comporter un seul niveau ou contenir elle-même des sous-listes. Si vous ne voulez pas rattacher de sous-liste au nouvel élément, omettez le paramètre ou passez 0. Si vous passez le paramètre sous_Liste et ne passez pas le paramètre déployée, la sous-liste apparaît par défaut contractée.

• Pour insérer un nouvel élément dans une liste, utilisez INSERER ELEMENT. Pour modifier le libellé d'un élément existant ou sa sous-liste, ainsi que son état déployé/contracté, utilisez CHANGER ELEMENT.

• Pour changer l'apparence de l'élément ajouté, utilisez CHANGER PROPRIETES ELEMENT.

Attention : Si vous ajoutez un élément à une liste affichée dans un formulaire ou à une liste rattachée à un élément (à travers un ou plusieurs niveaux) dont la liste est affichée dans un formulaire, vous devez appeler REDESSINER LISTE pour que 4D recalcule la liste et l'affiche en fonction de vos modifications. La règle est simple : quel que soit le niveau de la liste sur lequel vous agissez, appliquez REDESSINER LISTE à la liste principale, c'est-à-dire la liste reférencée par l'objet dans le formulaire.

Chaque élément d'une liste hiérarchique dispose d'un numéro de référence 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 Structure. 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 fourni plus bas. 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]. Reportez-vous à l'exemple de la présente commande.

(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 ELEMENT, 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 ELEMENT ou SUPPRIMER ELEMENT 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é.

Voici une vue partielle de la structure d'une base :

Les tables [Départements] et [Employés] contiennent les enregistrements suivants :

Vous voulez utiliser une liste hiérarchique, appelée hlList, qui affiche les départements, et pour chaque département, une sous-liste contenant les employés travaillant dans ce département. La méthode objet de hlList est la suivante:

      ` Méthode objet Liste hiérarchique hlList

   Au cas ou 

      : (Evenement formulaire=Sur chargement)
         C_ENTIER LONG(hlList;$hSousListe;$vlDépartement;$vlEmployé)
            ` Créer une nouvelle liste hiérarchique vide
         hlList:=Nouvelle liste
            ` Sélectionner tous les enregistrements de la table [Départements]
         TOUT SELECTIONNER([Départements])
            ` Pour chaque Département
         Boucle ($vlDepartement;1;Enregistrements trouves([Départements]))
               ` Sélectionner les employés de ce département
            LIEN RETOUR([Départements]Nom)
               ` Combien sont-ils?
            $vlNbEmployés:=Enregistrements trouves([Employés])
               ` Y a-t-il au moins un employé dans ce département?
            Si ($vlNbEmployés>0)
                  ` Créer une sous-liste pour l'élément Département
               $hSousListe:=Nouvelle liste
                  ` Pour chaque Employé
               Boucle ($vlEmployé;1;Enregistrements trouves([Employés]))
                     ` Ajouter l'élément Employé à la sous-liste 
                     ` Noter que le numéro de l'enregistrement [Employés]
                     ` est passé comme numéro de référence de l'élément
                  AJOUTER A LISTE($hSousListe;[Employés]Nom+", "+[Employés]Prénom;Numero enregistrement([Employés]))
                     ` Aller à l'enregistrement [Employés] suivant
                  ENREGISTREMENT SUIVANT([Employés])
               Fin de boucle
            Sinon 
                  ` Pas d'Employé, pas de sous-liste pour l'élément Département
               $hSousListe:=0
            Fin de si 

               ` Ajouter l'élément Département à la liste principale
               ` Notez que le numéro de l'enregistrement [Départements]
               ` est passé comme numéro de référence de l'élément. Le bit #31
               ` du numéro de référence de l'élément est forcé à 1. Ainsi nous pourrons faire
               ` la distinction entre les éléments Département et Employés (cf. note ci-dessous)
            AJOUTER A LISTE(hlList;[Départements]Nom;0x80000000 | Numero enregistrement([Départements]);$hSousListe;$hSousListe#0)
               ` Passer l'élément Département en gras pour renforcer la hiérarchie de la liste
            CHANGER PROPRIETES ELEMENT(hlList;0;Faux;Gras;0)
               ` Aller au département suivant
            ENREGISTREMENT SUIVANT([Départements])
         Fin de boucle 
            ` Trier toute la liste en ordre croissant    
         TRIER LISTE(hlList;>)
            ` Afficher la liste en style Windows et forcer la hauteur de ligne minimale à 14 Pts
         CHANGER PROPRIETES LISTE(hlList;A la Windows;Réf icône Windows;14)
    
      : (Evenement formulaire=Sur libération)
            ` La liste n'est plus utile. N'oubliez pas de l'effacer !
         SUPPRIMER LISTE(hlList;*)
    
      : (Evenement formulaire=Sur double clic)
            ` Il y a eu un double-clic
            ` Obtenir la position de l'élément sélectionné
         $vlÉlémentPos:=Elements selectionnes(hlList)
            ` A toutes fins utiles, vérifier la position
         Si ($vlÉlémentPos # 0)
               ` Obtenir l'information de l'élément de la liste     
            INFORMATION ELEMENT(hlList;$vlÉlémentPos;$vlÉlémentRef;$vsÉlémentText;$vlÉlémentSousListe;$vbÉlémentDéployé)
               ` Cet élément est-il l'élément d'un Département?
            Si ($vlÉlémentRef ?? 31)
                  ` Si oui, c'est un double-clic sur un élément Département
               ALERTE("Vous avez double-cliqué sur l'élément Département "+Caractere(34)+$vsÉlémentText+Caractere(34)+".")
            Sinon 
                  ` Sinon, c'est un double-clic sur un élément Employé. Avec le numéro de référence
                  ` de l'élément parent, trouver l'enregistrement [Départements]
               ALLER A ENREGISTREMENT([Départements];Element parent(hlList;$vlÉlémentRef)?-31)
                  ` Signaler où l'Employé travaille et de qui il dépend
               ALERTE("Vous avez double-cliqué sur l'élément Employé "+Caractere(34)+$vsÉlémentText+Caractere(34)+" qui travaille dans le Département "+Caractere(34)+[Départements]Nom+Caractere(34)+ " dont le responsable est "+Caractere(34)+[Départements]Responsable+Caractere(34)+".")
            Fin de si 
         Fin de si 
   
   Fin de cas 

      ` Note : 4D peut stocker jusqu'à 16 millions d'enregistrements par table
      ` (exactement 16 777 215). Cette valeur est 2^24 moins 1. Le numéro d'enregistrement
      ` tient sur 24 bits. Dans notre exemple, nous utilisons le bit #31 de l'octet supérieur inutilisé
      ` pour différencier les éléments des Employés des Départements.

Dans cet exemple, il y a une seule raison d'établir une distinction entre les éléments Départements et les éléments Employés :

1. Nous stockons les numéros d'enregistrements dans les numéros de référence des éléments. En conséquence, nous avons toutes les chances de rencontrer des éléments Départements dont les numéros de référence sont les mêmes que ceux des éléments Employés.

2. Nous utilisons la commande Element parent pour récupérer le parent de l'élément sélectionné. Si nous cliquons sur un élément Employés dont le numéro d'enregistrement associé est 10, et s'il existe aussi un élément Départements qui a le numéro 10, l'élément Départements sera trouvé en premier par Element parent quand cette fonction passera la liste en revue pour repérer l'élément avec le numéro de référence que nous passons. La commande retournera le parent de l'élément Départements et non celui de l'élément Employés.

C'est pourquoi nous avons choisi des numéros de référence d'éléments uniques, non pas pour des questions de principe, mais parce que nous devions différencier les éléments de Départements et d'Employés.

Dans les modes Utilisation et Menus créés, la liste apparaîtra ainsi :

Note : Cet exemple ci-dessus est utile dans le cadre de la gestion de l'interface utilisateur, si vous manipulez un nombre limité d'enregistrements. Souvenez-vous que les listes sont conservées en mémoire ; donc, ne construisez pas d'interfaces utilisateur exploitant des listes hiérarchiques comportant des milliers d'éléments.

CHANGER ELEMENT, CHANGER PROPRIETES ELEMENT, INSERER ELEMENT.