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 permettent de représenter des données sous forme de colonnes et de lignes sélectionnables et proposent de nombreuses fonctions d'interface telles que la possibilité de saisir des valeurs, trier les colonnes, afficher une hiérarchie, 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 LIGNES 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 quatre types d’éléments distincts :

• l’objet dans son ensemble,
• les colonnes,
• les en-têtes des colonnes (peuvent être affichés ou masqués, sont affichés par défaut),
• les pieds des colonnes (peuvent être affichés ou masqués, sont masqués par défaut).

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, les en-têtes Entête1 à n et les pieds Pied1 à 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, à l'exception des pieds (par défaut les variables sont vides pour les pieds, 4D utilise des variables dynamiques).
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, aux en-têtes et/ou aux pieds. 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, les en-têtes et/ou les pieds des colonnes. Pour désigner le type d’élément sur lequel vous souhaitez agir, il suffit de passer le nom d'objet 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 :

Note : 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 et dans son pied.

Lorsque la commande OBJET FIXER VISIBLE est utilisée avec un en-tête ou un pied de list box, elle agit sur tous les en-têtes ou tous les pieds de l’objet List box, quel que soit l’élément individuel 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).
A noter que, pour que vous puissiez gérer la visibilité de ces objets à l'aide de la commande OBJET FIXER VISIBLE, ils doivent avoir été affichés dans la list box au niveau de l'éditeur de formulaires (l'option Afficher en-têtes et/ou Afficher pieds doit être cochée pour l'objet).

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.

Pour qu’une cellule de list box soit saisissable, quel que soit son type (tableau et sélection), il est nécessaire que les deux conditions suivantes soient réunies :

• la colonne de la cellule a été définie comme Saisissable (dans le cas contraire, les cellules de la colonne ne seront jamais saisissables).
• dans l’événement formulaire Sur avant saisie, $0 ne retourne pas -1.
  Lorsque le curseur arrive dans la cellule, l’événement Sur avant saisie est généré dans la méthode de la colonne. Si, dans le contexte de cet événement, $0 prend la valeur -1, la cellule est considérée comme non saisissable. Si l’événement a été généré suite à un appui sur Tabulation ou Maj+Tabulation, le focus est donné à la cellule respectivement suivante ou précédente. Si $0 ne vaut pas -1 (par défaut $0 vaut 0), la cellule est saisissable et passe bien en édition.

Imaginons par exemple une list box contenant deux tableaux, de type date et texte. Le tableau date n’est pas saisissable. Le tableau texte est saisissable si la date n’est pas déjà passée. 

Voici la méthode de la colonne tText :

Note : A compter de 4D v13, l’événement Sur avant saisie est retourné avant Sur gain focus.

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 Gestion des List box hiérarchiques.

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.

Il est possible de placer directement le résultat d’une requête SQL dans une list box de type tableau. Cette fonction offre un moyen rapide de visualiser le résultat des requêtes SQL. Seules les requêtes de type SELECT peuvent être utilisées. Ce mécanisme n’est pas utilisable avec une base SQL externe. 

Les principes de mise en oeuvre sont les suivants :

• Vous créez la list box devant recevoir le résultat de la requête. La source de données de la list box doit être Tableaux.
• Vous exécutez la requête SQL de type SELECT et assignez le résultat à la variable associée la list box. Vous pouvez utiliser les mots-clés Debut SQL/Fin SQL (cf. manuel Langage de 4D).
• Les colonnes de la list box sont triables et modifiables par l’utilisateur.
• Chaque nouvelle exécution d’une requête SELECT avec la list box provoque la réinitialisation des colonnes (il n’est pas possible de remplir progressivement une même list box à l’aide de plusieurs requêtes SELECT).   
• Il est préférable de placer dans la list box autant de colonnes qu’il y aura de colonnes SQL dans le résultat de la requête SQL. Si le nombre de colonnes de la list box est inférieur à celui requis par la requête SELECT, des colonnes sont automatiquement ajoutées. Si le nombre de colonnes de la list box est supérieur à celui requis par la requête SELECT, les colonnes superflues sont automatiquement masquées.
  Note : Les colonnes ajoutées automatiquement sont liées à des variables de type tableau temporaire. La durée de vie de ces tableaux temporaires est celle du formulaire. Une variable temporaire est également créée pour chaque en-tête. Lorsque la commande LISTBOX LIRE TABLEAUX est appelée, le paramètre tabVarCols contient des pointeurs vers les tableaux temporaires et le paramètre tabVarEntêtes contient des pointeurs vers les variables d’entête temporaires. Si une colonne ajoutée est par exemple la cinquième, son nom est sql_column5 et son nom d’en-tête sql_header5.
• En mode interprété, les tableaux existants et utilisés pourront être retypés automatiquement en fonction des données renvoyées par la requête SQL.

Exemple
Nous voulons récupérer tous les champs de la table PERSONS et placer leur contenu dans la list box dont le nom de variable est vlistbox. Dans la méthode objet d’un bouton (par exemple), il suffit d’écrire :