Liste hiérarchique

Vue d’ensemble

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.

Le cas échéant, l'icône déployer/contractée est automatiquement affichée à gauche de l'élément. Les listes hiérarchiques prennent en charge un nombre illimité de sous-niveaux.

Sources de données de liste hiérarchique

Le contenu d'un objet formulaire liste hiérarchique peut être initialisé de l'une des manières suivantes :

• Associer une énumération à l'objet. L'énumération doit avoir été définie dans l'éditeur de listes en mode Développement.
• Assignez directement une référence de liste hiérarchique à la variable ou à l'expression associée à l'objet formulaire.

Dans les deux cas, vous gérez une liste hiérarchique lors de l'exécution via sa référence ListRef, à l'aide des commandes de liste hiérarchique du langage 4D.

RefListe et nom d'objet

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", etc.).

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 avez associé la variable $mylist à l'objet de formulaire, vous écrivez :

$mylist:=New list

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. Par ailleurs, 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"...).

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(*;"mylist1";*;thefont)

... vous indiquez que vous souhaitez modifier la police d’un élément de la liste hiérarchique associée à l’objet de formulaire mylist1. La commande tiendra compte de l’élément courant de l’objet mylist1 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.

Prise en compte du @

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”

  • 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

Commandes génériques utilisables avec les listes hiérarchiques

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 (contenant la valeur RefListe) :

• 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.

Priorité des commandes de propriété

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. Propriété formulaire

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.

Gestion des éléments par position ou par référence

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.

Exploiter les numéros de référence des éléments (réfElément)

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. 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 la commande Selected list itemsvous retourne 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. Identifiez les éléments de la liste (niveau intermédiaire).
   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. Identifiez tous les éléments de la liste individuellement (niveau avancé).
   Programmez une gestion élaborée des listes hiérarchiques dans lesquelles vous devez absolument pouvoir identifier chaque élément individuellement à 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 nombres sont du 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 ... (cependant si vous travaillez avec un si grand nombre d'éléments, cela signifie généralement que vous devriez utiliser un tableau plutôt qu'une liste.)

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.

Quand avez-vous besoin de numéros de référence uniques ?

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 ITEMvous 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é.

Élément modifiable

Vous pouvez choisir si les éléments de la liste hiérarchique peuvent être modifiés par l'utilisateur à l'aide du raccourci Alt + clic (Windows)/ Option + clic (macOS), ou en effectuant un clic long sur le texte de l'élément.

• Quelle que soit la source de données de la liste hiérarchique, vous pouvez contrôler l'ensemble de l'objet avec la propriété Saisissable.

• En outre, si vous remplissez la liste hiérarchique à l'aide d'une liste créée dans l'éditeur de listes, vous contrôlez si un élément d'une liste hiérarchique est modifiable à l'aide de l'option Élément modifiable dans l'éditeur de listes. Pour plus d'informations, consultez Définir les propriétés des énumérations .

Propriétés prises en charge

Bold - Border Line Style - Bottom - Choice List - Class - Draggable - Droppable - Enterable - Entry Filter - Fill Color - Focusable - Font - Font Color - Font Size - Height - Hide focus rectangle - Horizontal Scroll Bar - Horizontal Sizing - Italic - Left - Multi-selectable - Object Name - Right - Top - Type - Underline - Vertical Scroll Bar - Vertical Sizing - Variable or Expression - Visibility - Width