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 OBJECT SET FORMAT.

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 INSERT ROWS ou LISTBOX INSERT COLUMN) 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 INSERT ROWS et LISTBOX DELETE ROWS 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 String(Milliseconds)). L’expression peut également être une méthode projet (devant retourner une valeur dans $0), une variable ou un élément de tableau.
La commande LISTBOX SET 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 Objets de formulaires 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 Objets de formulaires 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 GET ARRAYS.

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 OBJECT SET 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 OBJECT SET 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 OBJECT SET 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 OBJECT Get pointer utilisée avec la constante Object with focus ou Object current (anciennement fonctions Focus object 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, OBJECT Get pointer 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, OBJECT Get pointer 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 OBJECT SET SCROLL POSITION (thème “Objets (Formulaires)”) 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 EDIT ITEM (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 REDRAW (thème "Interface utilisateur") provoque la mise à jour des données affichées dans la list box.

La commande Displayed line number (thème “Sélections”) fonctionne dans le contexte de l'événement On Display Detail 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 Form event.

La gestion du glisser-déposer de données dans les list box est prise en charge par les commandes Drop position et DRAG AND DROP PROPERTIES. 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 MOVED ROW NUMBER et LISTBOX MOVED COLUMN NUMBER.

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 On Before Data Entry, $0 ne retourne pas -1.
  Lorsque le curseur arrive dans la cellule, l’événement On Before Data Entry 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 On Before Data Entry est retourné avant On Getting 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 SORT COLUMNS et/ou en combinant les événements formulaire On Header Click et On After Sort (cf. commande Form event) et les commandes 4D de gestion des tableaux.

Note : La propriété “Triable” concerne uniquement le tri utilisateur standard, la commande LISTBOX SORT COLUMNS 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é par défaut $ListboxSetN (N débute à 0 et est incrémenté en fonction du nombre de list box dans le formulaire), que vous pouvez modifier si nécessaire. 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 SELECT ROW 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 Count in array 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 Print object (les formulaires projet et les formulaires table sont pris en charge). La commande LISTBOX GET PRINT INFORMATION 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 GET PRINT INFORMATION.
• 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 OBJECT SET SCROLL POSITION 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 à Print object permettent d’imprimer à chaque fois un nouvel ensemble de lignes. La commande LISTBOX GET PRINT INFORMATION permet de contrôler le statut de l’impression durant l’impression.

Vous disposez de plusieurs possibilités pour définir des couleurs de fond, des couleurs de police et des styles de police dans les list box :

• au niveau des propriétés de l’objet list box,
• au niveau des propriétés de la colonne,
• en utilisant des tableaux ou des méthodes pour la list box et/ou pour chaque colonne,
• au niveau du texte de chaque cellule (si texte multistyle).

Des principes de priorité et d'héritage sont observés.

Lorsqu’une même propriété de style ou de couleur est définie à plusieurs niveaux, l’ordre de priorité suivant est appliqué :

Par exemple, si vous définissez un style de caractères dans les propriétés de la list box et un autre via un tableau de styles pour la colonne, ce dernier sera pris en compte.

Soit une list box dont les lignes ont une couleur alternée gris/gris clair, définies dans les propriétés de la list box. Un tableau de couleur de fond a également été défini pour la list box afin de passer en orange clair les lignes dont au moins une valeur est négative :

Vous souhaitez désormais afficher en fond orange foncé les cellule ayant une valeur négative. Pour cela, vous définissez un tableau de couleur de fond pour chaque colonne, par exemple <>_BgndColor_1, <>_BgndColor_2 et <>_BgndColor_3. Les valeurs de ces tableaux seront prioritaires sur celles définies dans les propriétés de la list box et celles du tableau global de couleur de fond :

Vous pouvez obtenir le même résultat à l’aide des commandes LISTBOX SET ROW FONT STYLE et LISTBOX SET ROW COLOR. Elles ont pour avantage d’éviter de devoir prédéfinir les tableaux de style/couleur des colonnes : ils sont créés dynamiquement par les commandes.

Pour chaque attribut (style, couleur et couleur de fond), un héritage est mis en oeuvre lorsque la valeur par défaut est utilisée :

• pour les attributs des cellules : valeurs d’attributs des lignes
• pour les attributs des lignes : valeurs d’attributs des colonnes
• pour les attributs des colonnes : valeurs d’attributs de la list box

Ainsi, si vous souhaitez qu’un objet hérite de la valeur d’attribut du niveau supérieur, il vous suffit de passer lk inherited (valeur par défaut) à la commande de définition ou directement dans l’élément de tableau de style/couleur correspondant.

Soit une list box contenant un style de caractère standard et des couleurs alternées : 

Vous effectuez les modifications suivantes :

• le fond de la ligne 2 est passé en rouge via la propriété Tableau couleurs de fond de l’objet list box,
• le style de la ligne 4 est passé en italique via la propriété Tableau de styles de l’objet list box
• deux élements de la colonne 5 sont passés en gras via la propriété Tableau de styles de l’objet colonne 5
• les éléments 2 de la colonne 1 et 2 sont passés en fond bleu via la propriété Tableau couleurs de fond des objets colonne 1 et 2 :

Pour restaurer l’apparence initiale de la list box, il suffit de :

• passer la constante lk inherited dans les éléments 2 des tableaux de fond des colonnes 1 et 2 : ils héritont alors de la couleur de fond rouge de la ligne.
• passer la constante lk inherited dans les éléments 3 et 4 des tableaux de style de la colonne 5 : ils héritont alors du style standard, hormis l’élément 4, qui passera en italique comme défini dans le tableau de style de la list box).
• passer la constante lk inherited dans l’élément 4 du tableau de style de la list box afin de supprimer le style italique.
• passer la constante lk inherited dans l’élément 2 du tableau de couleurs de fond de la list box afin de restaurer la couleur alternée d’origine de la list box.

Des propriétés d'interface "masquée", "désactivée" et "sélectionnable" sont configurables pour chaque ligne de list box de type tableau.

Ces fonctionnalités sont gérées via le tableau de propriétés Tableau de contrôle des lignes, que vous pouvez désigner à l'aide de la commande LISTBOX SET ARRAY ou via la Liste des propriétés :

Le tableau de contrôle des lignes doit être de type Entier long et comporter le même nombre de lignes que la list box. Pour plus d'informations, reportez-vous à la section Propriétés spécifiques des List box.

Chaque élément du Tableau de contrôle des lignes définit le statut d'interface de la ligne correspondante dans la list box. Trois propriétés d'interface sont accessibles via les constantes du thème "List Box" :

Pour modifier le statut d'une ligne, il vous suffit de passer la ou les constante(s) appropriée(s) dans l'élément correspondant. Par exemple, si vous souhaitez que la ligne n°10 ne soit pas sélectionnable, vous pouvez écrire :

Vous pouvez définir plusieurs propriétés d'interface en un seul appel :

A noter que la définition d'une propriété pour un élément écrase toutes les autres valeurs définies pour cet élément (si elles n'ont pas été réinitialisées). Par exemple :

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 Begin SQL/End 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 dynamiques de type tableau. La durée de vie de ces tableaux dynamiques est celle du formulaire. Une variable dynamique est également créée pour chaque en-tête. Lorsque la commande LISTBOX GET ARRAYS est appelée, le paramètre tabVarCols contient des pointeurs vers les tableaux dynamiques et le paramètre tabVarEntêtes contient des pointeurs vers les variables d’entête dynamiques. 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 :