Gestion programmée des objets de type List box

Les commandes de ce thème sont dédiées à la gestion programmée des objets de formulaire de type List box.
Les list box peuvent être comparées aux Zones de défilement groupées. De fait, une list box propose toutes les fonctions d'un ensemble de zones de défilement groupées, notamment la possibilité de représenter des données sous forme de colonnes et de lignes sélectionnables. Les list box proposent en outre de nombreuses fonctions supplémentaires telles que la possibilité de saisir des valeurs, trier les colonnes, définir des couleurs alternées, etc.

Un objet de type List box est entièrement paramétrable dans l’éditeur de formulaires de 4D et peut également être contrôlé par programmation. Pour plus d’informations sur la création et le paramétrage des objets de type List box dans l'éditeur de formulaires ainsi que leur utilisation, reportez-vous au manuel Mode Développement de la documentation de 4D.
La programmation des objets de type List box s’effectue sur le même modèle que les autres objets de formulaire en liste de 4D. Elle doit cependant tenir compte de principes spécifiques, décrits dans cette section.

Un objet List box peut contenir une ou plusieurs colonnes et peut être associé soit à des tableaux 4D, soit à une sélection d'enregistrements. Dans le cas des list box de type sélection, les colonnes sont associées à des champs ou des expressions.
Il n’est pas possible de combiner dans une même list box ces deux types de sources de données (tableaux et sélections). La définition de la source de données s'effectue au moment de la création de l'objet List box dans l'éditeur de formulaires, via la Liste des propriétés. Il n'est pas possible de la modifier ensuite par programmation.

Dans ce type de list box, chaque colonne est associée à un tableau 4D à une dimension ; tous les types de tableaux peuvent être utilisés, à l’exception des tableaux de pointeurs. Le format d’affichage de chaque colonne peut être défini dans l’éditeur de formulaires ou via la commande OBJET FIXER FORMATAGE.

En mode programmé, les valeurs des colonnes (saisie et affichage) sont gérées à l’aide des commandes de haut niveau du thème List box (telles que LISTBOX INSERER LIGNE ou LISTBOX INSERER COLONNE) ainsi que des commandes de manipulation des tableaux.
Par exemple, pour initialiser le contenu d’une colonne de List box, vous pouvez utiliser l’instruction suivante :

Vous pouvez également utiliser une énumération :

Attention : Lorsqu’un objet List box contient plusieurs colonnes de tailles différentes, seul le nombre d’éléments correspondant au plus petit tableau est affiché. Il est donc conseillé de veiller à ce que chaque tableau ait le même nombre d’éléments que les autres. A noter également que si une colonne de la list box est “vide” (c'est le cas lorsque le tableau associé n'a pas été déclaré ou dimensionné via le langage), la list box n'affiche aucun contenu.

Dans ce type de list box, chaque colonne peut être associée à un champ ou à une expression. Le contenu de chaque ligne est alors évalué en fonction d'une sélection d'enregistrements : la sélection courante d'une table ou une sélection temporaire.
Dans le cas de la sélection courante, toute modification effectuée côté base de données est automatiquement reportée dans la list box et inversement. La sélection courante est donc toujours identique aux deux emplacements. A noter que les commandes LISTBOX INSERER LIGNE et LISTBOX SUPPRIMER LIGNE ne peuvent pas être utilisées avec les list box de type sélection.
Vous pouvez associer une colonne de list box à une expression. L’expression pourra être basée sur un ou plusieurs champs (par exemple [Employés]Nom+“ ”+[Employés]Prénom) ou être simplement une formule (par exemple Chaine(Millisecondes)). L’expression peut également être une méthode projet, une variable ou un élément de tableau.
La commande LISTBOX FIXER TABLE SOURCE permet de modifier par programmation la table associée à la list box.

Un objet List box est composé de trois types d’éléments distincts :

• l’objet dans son ensemble,
• les colonnes,
• les en-têtes des colonnes.

Dans l’éditeur de formulaires, ces éléments peuvent être sélectionnés séparément. Chacun d’eux dispose de son propre nom d’objet et nom de variable et peut donc être adressé séparément.

Par défaut, les colonnes sont nommées Colonne1 à n et les en-têtes Entête1 à n dans le formulaire, indépendamment des objets List box eux-mêmes. A noter que, par défaut, le même nom est utilisé pour les objets et leurs variables associées.
Chaque type d’élément dispose de caractéristiques propres et de caractéristiques partagées avec les autres éléments. Par exemple, la police de caractères peut être assignée globalement à l’objet List box ou séparément aux colonnes et aux en-têtes. A l’inverse, les propriétés de saisie ne sont définissables que pour les colonnes.
Ces principes s’appliquent aux commandes du thème “Propriétés des objets” pouvant être utilisées avec les list box : en fonction de sa nature, chaque commande sera utilisable avec la list box, les colonnes et/ou les en-têtes des colonnes. Pour désigner le type d’élément sur lequel vous souhaitez agir, il suffit de passer le nom ou la variable qui lui est associé(e).
Le tableau suivant précise la portée de chaque commande du thème “Propriétés des objets” utilisable avec les objets de type list box :

Notes :

• Toutes les commandes du thème “List Box” s’appliquent à l’objet List box seulement, à l’exception de LISTBOX FIXER LARGEUR COLONNE (objet, colonne et en-tête) et LISTBOX Lire largeur colonne (colonne ou en-tête uniquement).
• Avec les List box de type tableau, il est possible de définir séparément les propriétés de style, de couleur de police, de couleur de fond et de visibilité de chaque ligne. Cette gestion s'effectue via des tableaux associés à la list box dans la Liste des propriétés. Vous pouvez récupérer par programmation le nom de ces tableaux à l'aide de la commande LISTBOX LIRE TABLEAUX.

Il est possible d’associer une méthode à l’objet List box dans son ensemble et/ou à chaque colonne de la list box. Les méthodes objet sont appelées dans l’ordre suivant :

1. Méthode objet de la colonne

2. Méthode objet de la list box
La méthode objet de la colonne reçoit les événements se produisant dans son en-tête.

Lorsque la commande OBJET FIXER VISIBLE est utilisée avec un en-tête de list box, elle agit sur tous les en-têtes de l’objet List box, quel que soit l’en-tête spécifié par la commande. Par exemple, l’instruction OBJET FIXER VISIBLE(*;"entête3";Faux) masquera tous les en-têtes de l’objet List box auquel appartient l’en-tête 3 (et non uniquement cet en-tête).

La fonction Objet Lire pointeur utilisée avec la constante Objet avec focus ou  Objet courant (anciennement fonctions Objet focus et Self) peut être utilisée dans la méthode objet d’une list box ou d'une colonne de list box. Elle retourne un pointeur vers la list box, la colonne de list box (1) ou la variable d'en-tête en fonction du type d'événement formulaire. Le tableau suivant détaille ce fonctionnement :

(*) Lorsque le focus est modifié à l'intérieur d'une list box, un pointeur vers la colonne est retourné. Lorsque le focus est modifié au niveau global du formulaire, un pointeur vers la list box est retourné. Dans le contexte d'une méthode objet de colonne, un pointeur vers la colonne est retourné.
(**) Non exécuté dans le contexte d'une méthode objet de colonne.

(1) Lorsqu'un pointeur vers la colonne est retourné, l'objet pointé dépend du type de la list box. Dans le cadre d'une list box de type tableau, OBJET Lire pointeur retourne un pointeur vers le tableau. Le mécanisme des pointeurs de 4D permet alors de connaître le numéro de l’élément de tableau modifié. Par exemple, en supposant que l’utilisateur a modifié la 5e ligne de la colonne col2 :

Dans le cadre d'une list box de type sélection, OBJET Lire pointeur retourne :

• pour une colonne associée à un champ, un pointeur vers le champ associé,
• pour une colonne associée à une variable, un pointeur vers la variable,
• pour une colonne associée à une expression, un pointeur Nil.

Il est possible d’utiliser la commande OBJET FIXER DEFILEMENT (thème “Propriétés des objets”) avec un objet de type list box. Cette commande permet de faire défiler les lignes de la list box afin d’afficher la première ligne sélectionnée ou une ligne spécifique.

La commande EDITER ELEMENT (thème “Gestion de la saisie”) permet de passer en mode édition une cellule d’un objet list box.

Lorsqu'elle est appliquée à une list box en mode sélection, la commande REDESSINER (thème "Interface utilisateur") provoque la mise à jour des données affichées dans la list box.

La commande Numero de ligne affichee (thème “Sélections”) fonctionne dans le contexte de l'événement Sur affichage corps pour un objet list box.

Des événements formulaire spécifiques sont destinés à la gestion programmée des list box, concernant notamment le glisser-déposer et le tri. Pour plus d’informations, reportez-vous à la description de la commande Evenement formulaire.

La gestion du glisser-déposer de données dans les list box est prise en charge par les commandes Position deposer et PROPRIETES GLISSER DEPOSER. Ces commandes ont été spécialement adaptées pour les list box.
Attention de ne pas confondre le glisser-déposer avec le déplacement de lignes et de colonnes, pris en charge par les commandes LISTBOX NUMERO LIGNE DEPLACEE et LISTBOX NUMERO COLONNE DEPLACEE.

Par défaut, la list box gère automatiquement les tris standard des colonnes en cas de clic sur l’en-tête. Un tri standard est un tri alphanumérique des valeurs de la colonne, alternativement croissant / décroissant lors de clics multiples. Toutes les colonnes sont toujours automatiquement synchronisées.
Il est possible d’interdire le tri utilisateur standard en désélectionnant la propriété “Triable” pour la list box.

Le développeur peut mettre en place une gestion personnalisée des tris à l'aide de la commande LISTBOX TRIER COLONNES et/ou en combinant les événements formulaire Sur clic entête et Sur après tri (cf. commande Evénement formulaire) et les commandes 4D de gestion des tableaux.

Note : La propriété “Triable” concerne uniquement le tri utilisateur standard, la commande LISTBOX TRIER COLONNES ne tient pas compte de cette propriété.

En outre, la valeur de la variable associée à l’en-tête d’une colonne permet de gérer une information supplémentaire : le tri courant de la colonne (lecture) et l’affichage de la flèche de tri.

• si la variable vaut 0, la colonne n’est pas triée et la flèche de tri n’est pas affichée ;
  

• si la variable vaut 1, la colonne est triée par ordre croissant et la flèche de tri croissant est affichée ;
  

• si la variable vaut 2, la colonne est triée par ordre décroissant et la flèche de tri décroissant est affichée.
  

Il est possible de fixer la valeur de la variable (par exemple Header2:=2) afin de “forcer” l’affichage de la flèche de tri. Le tri de la colonne lui-même n’est dans ce cas pas modifié, il appartient au développeur de le gérer.

La gestion des sélections s'effectue différemment pour les list box de type tableau et de type sélection.

• List box de type sélection : les sélections sont gérées par l'intermédiaire d'un ensemble appelé "Ensemble surlignage". Cet ensemble est défini dans les propriétés de la list box. Il est maintenu automatiquement par 4D : si l'utilisateur sélectionne une ou plusieurs ligne(s) dans la list box, l'ensemble est immédiatement mis à jour). A l'inverse, il est possible d'utiliser les commandes du thème "Ensembles" afin de modifier par programmation la sélection dans la list box.

• List box de type tableau : la commande LISTBOX SELECTIONNER LIGNE permet de sélectionner par programmation une ou plusieurs lignes de list box.
  En outre, la variable associée à l’objet List box peut être utilisée pour lire, fixer ou stocker les sélections de lignes dans l’objet. Cette variable correspond à un tableau de booléens automatiquement créé et maintenu par 4D. La taille de ce tableau est déterminée par celle de la list box : il contient le même nombre d’éléments que le plus petit tableau associé aux colonnes.
  Chaque élément de ce tableau contient Vrai si la ligne correspondante est sélectionnée et Faux sinon. 4D met à jour le contenu de ce tableau en fonction des actions utilisateur. A l’inverse, vous pouvez modifier la valeur des éléments de ce tableau afin de modifier la sélection dans la list box.
  En revanche, vous ne pouvez ni insérer ni supprimer de ligne dans ce tableau ; il n’est pas possible non plus de le retyper.

Note : La commande Compter dans tableau est utile dans ce cas pour connaître le nombre de lignes sélectionnées.

Par exemple, cette méthode permet d’inverser la sélection de la première ligne de la list box (type tableau) :

Note : Les spécificités de la gestion des sélections dans les list box en mode hiérarchique sont détaillées dans la section .

Il est possible d’imprimer des list box à compter de 4D v12. Deux modes d’impression sont proposés : le mode prévisualisation, permettant d’imprimer une list box comme un objet de formulaire et le mode avancé, permettant de contrôler l’impression de l’objet list box lui-même au sein du formulaire. A noter que l'apparence "Impression" est proposée pour les list box dans l'éditeur de formulaires.

L’impression d’une list box en mode prévisualisation consiste à imprimer directement la list box avec le formulaire qui la contient via les commandes d’impression standard ou la commande de menu Imprimer. La list box est imprimée dans l’état où elle se trouve dans le formulaire. Ce mode ne permet pas de contrôler précisément l’impression de l’objet ; en particulier, il ne permet pas d’imprimer toutes les lignes d’une list box contenant plus de lignes qu’elle ne peut en afficher.

Dans ce mode, l’impression des list box s’effectue par programmation, via la commande Imprimer objet. Par conséquent, seules des list box présentes dans des formulaires projet peuvent être imprimées en mode avancé. La commande LISTBOX LIRE INFORMATION IMPRESSION permet de contrôler l’impression de l’objet.

Dans ce mode :

• la hauteur de l’objet list box est automatiquement réduite lorsque le nombre de lignes à imprimer est inférieur à la hauteur d’origine de l’objet (il n’y a pas de lignes "vides" imprimées). En revanche, la hauteur n’augmente pas automatiquement en fonction du contenu de l’objet. La taille de l’objet effectivement imprimé peut être obtenue via la commande LISTBOX LIRE INFORMATION IMPRESSION.
• l’objet list box est imprimé "tel quel", c’est-à-dire en tenant compte de ses paramètres d’affichage courants : visibilité des en-têtes et des grilles, lignes affichées et masquées, etc. Ces paramètres incluent également la première ligne à imprimer : si vous appelez la commande DEFILER LIGNES avant de lancer l’impression, la première ligne imprimée dans la list box sera celle désignée par la commande. 
• un mécanisme automatique facilite l’impression des list box contenant plus de lignes qu’il est possible d’en afficher : des appels successifs à Imprimer objet permettent d’imprimer à chaque fois un nouvel ensemble de lignes. La commandeLISTBOX LIRE INFORMATION IMPRESSION permet de contrôler le statut de l’impression durant l’impression.