Le guide Oracle Forms 9i/10g

Une liste de valeurs est un outil d'aide à la saisie.
Elle se matérialise sous la forme d'une boite de dialogue dans laquelle sont affichées les valeurs qui correspondent à l'information attendue dans le champ en cours de saisie.

Une telle liste permet de filtrer les valeurs et donc d'obliger l'utilisateur à saisir une valeur conforme.

Une LOV est alimentée par un groupe d'enregistrements (Record group), lui même alimenté par un ordre SELECT.

On peut considérer une LOV comme une vue n'affichant que les valeurs souhaitées.

Elle peut être affichée par programme ou à la demande de l'utilisateur.

Il existe deux façons de créer une liste de valeurs:

Pour créer une LOV dans la forme en cours, cliquez sur le nœud : LOV dans le navigateur d'objets puis cliquez sur l'icône , ou double-cliquez sur le nœud : LOV
Une boite de dialogue vous demande si vous souhaitez utiliser l'assistant ou créer la LOV manuellement

Création d'une LOV à l'aide de l'assistant

Cet écran permet d'indiquer si la LOV sera basée sur un groupe d'enregistrements existant ou sur un groupe que vous allez définir.

Créons le groupe d'enregistrements

Il s'agit de définir la requête SQL qui permettra d'alimenter le groupe d'enregistrements.
Toute instruction SQL valide portant sur une ou plusieurs tables/vues est autorisée, incluant les opérateurs UNION, UNION ALL, INTERSECT et MINUS, ainsi que l'utilisation de variables de substitution (en l'occurrence un item ( :nom_bloc.nom_item) ou un paramètre ( :PARAMETER.nom_paramétre))

Dans l'exemple, nous ramenons les colonnes DEPTNO, DNAME et LOC de la table DEPT.

Le bouton : Générer interrogation SQL... permet de construire la requête à l'aide d'un outil graphique.
Le bouton Importer interrogation SQL... permet de récupérer une requête stockée dans un fichier.
Le bouton : Vérifier la syntaxe permet de s'assurer que la requête ne comporte pas d'erreur.

L'écran suivant permet de définir quelles colonnes du groupe d'enregistrements seront affichées dans la LOV (un même groupe peut alimenter plusieurs LOV).
Nous souhaitons afficher les colonnes DEPTNO et DNAME.

Chaque colonne peut être adaptée au niveau des titre, largeur d'affichage ainsi que l'item de la forme qui recevra la valeur sélectionnée.
Pour sélectionner l'item de retour de la valeur, cliquez la colonne correspondante puis sur le bouton : Rechercher l'élément récepteur.

Cette liste affiche les items de la forme pour vous permettre de sélectionner celui qui recevra la valeur de la LOV.
Répéter l'opération autant de fois que nécessaire afin d'alimenter tous les items de réception.

L'écran suivant permet de définir quelques caractéristiques de la LOV:

Une information de positionnement automatique de la LOV lors de son affichage:

Cet écran permet d'indiquer le nombre de lignes qui seront lues à chaque fois depuis la base.

La case a cocher : Régénérer les données stipule que le groupe d'enregistrements sera rafraîchi à chaque fois que le LOV sera invoquée. Il est prudent de décocher cette case si le groupe d'enregistrements ramène un nombre très important de lignes, afin d'éviter le temps d'attente avant l'affichage de la LOV. Dans ce cas, le groupe sera alimenté seulement à la première invocation de la LOV.

La case a cocher : Autoriser l'utilisateur à filtrer oblige l'utilisateur à saisir un ou plusieurs caractères dans la LOV pour réduire le nombre de lignes ramenées.

Une fois les éléments récepteurs définis dans l'écran précédent, vous pouvez indiquez les items du bloc sur lesquels la LOV pourra être invoquée (à l'aide des touches Ctrl+L).

Après le retour de l'assistant, nous constatons la présence d'un nouveau groupe d'enregistrements et d'une nouvelle LOV dans le navigateur.
A tout moment, il est possible de modifier les propriétés associées à ces objets en faisant apparaître la fenêtre de propriétés (F4).

La propriété de la LOV : Propriétés de correspondance de colonnes permet de (re)définir la correspondance entre les colonnes de la LOV et les items de réception des valeurs dans le bloc.

L'item :EMP_DEPT.DEPTNO recevra la valeur de la colonne DEPTNO de la LOV.
L'item :EMP_DEPT.DNAME recevra la valeur de la colonne DNAME de la LOV.

Le bouton : Parcourir... affiche la liste des items du bloc si vous souhaitez changer l'item de réception.
La largeur d'affichage de chaque colonne de la LOV ainsi que son titre sont également modifiable.

Compilons et exécutons la forme.

Positionnons le curseur sur le champ Deptno.

La barre de statut en bas d'écran affiche : Liste de valeurs... pour indiquer qu'une LOV est disponible sur ce champ.
Déclenchons l'affichage de la LOV avec les touches Ctrl+L

La boite de dialogue apparaît et affiche les lignes ramenées par le groupe d'enregistrements.

La liste des valeurs peut être réduite par l'utilisateur en saisissant une lettre au clavier.

Rappel : la fonction de recherche n'agit que sur la première colonne de la LOV


Création manuelle d'une LOV

La création manuelle d'une LOV ne fait que créer un Nouvel objet LOV dans le navigateur.
C'est a vous de gérer le groupe d'enregistrements qui sera lié et de régler les propriétés de la LOV, propriétés détaillées dans la section suivante.


Les propriétés d'un objet LOV

Fonctionnel

Titre Chaîne de caractères apparaissant dans le titre de la boite de dialogue
Cette propriété peut être changée à l'exécution en utilisant la fonction Set_Lov_Property( nom_lov | id_lov, TITLE, nouveau_titre )
Type de liste
Groupe d'enregistrements permet d'indiquer le nom du groupe d'enregistrement qui alimentera la LOV
Cette propriété peut être changée à l'exécution en utilisant la fonction Set_Lov_Property(nom_lov | id_lov, GROUP_NAME )
Correspondance des colonnes permet d'indiquer l'item du bloc qui recevra la valeur de la colonne de la LOV
Permet également d'indiquer le titre de la colonne ainsi que sa largeur
Une largeur égale à 0 permet de ne pas afficher la colonne dans la LOV
Filtrer avant afficher indique que la LOV sera affichée vide et que l'utilisateur devra insérer un ou plusieurs caractères de filtrage avant l'affichage des valeurs
Affichage automatique positionné à Oui permet d'afficher automatiquement la LOV dès que le focus entre dans l'item qui la supporte.
Positionné à Non, l'utilisateur doit commander manuellement l'affichage de la LOV avec les touches Ctrl+L
Régénération automatique positionné à Oui demande à Forms de réactualiser le groupe d'enregistrements à l'aide de l'ordre SELECT à chaque fois que la LOV est invoquée. Cela permet de s'assurer que les données présentées sont actualisées.
Positionné à Non indique que le groupe d'enregistrement ne sera alimenté par l'ordre SELECT que lors de la première invocation de la LOV.
Le positionnement de cette propriété mérite une considération particulière:
Si les données affichées dans la LOV doivent absolument refléter l'état actuel de la base alors la propriété doit être valorisée à OUI.
Si la LOV est basée sur un groupe d'enregistrements qui ramène un nombre très important de lignes et qu'il n'est pas nécessaire que celles-ci reflètent absolument l'état actuel de la base, vous devez positionner cette propriété à Non.
(Un groupe d'enregistrement basé sur un ordre SELECT qui ramène un très grand nombre de lignes "gèlera" l'application durant la période d'alimentation du groupe d'enregistrements. Si cette LOV doit être fréquemment utilisée dans l'écran vous risquez fort de vous attirer les foudres de l'utilisateur !)
La régénération du groupe d'enregistrements intervient également lorsque la LOV est utilisée pour la validation de l'item.
Cette propriété peut être changée à l'exécution en utilisant la fonction Set_Lov_Property(nom_lov | id_lov, AUTO_REFRESH, PROPERTY_TRUE | PROPERTY_FALSE )
Sélection automatique la propriété Oui provoque le fonctionnement suivant :
Si, après filtrage la LOV n'affiche plus qu'une seule ligne, alors la saisie est auto-validée comme si l'utilisateur avait pressé le bouton Ok.
Si elle est positionnée à Non, l'utilisateur doit valider la boite de dialogue, même si une seule ligne reste affichée dans la LOV.
Saut automatique lorsque la valeur vaut Oui, la sélection dans la LOV renseigne l'item qui la supporte et le curseur saute automatiquement à l'item suivant
Lorsqu'elle vaut Non, l'item est renseigné en sortie de LOV, mais le curseur reste à sa place.
Cette propriété peut être changée à l'exécution en utilisant la fonction Set_Item_Property(nom_lov | id_lov, AUTO_SKIP, PROPERTY_TRUE | PROPERTY_FALSE )
Position automatique indique si le positionnement à l'affichage est géré par l'application ou s'il doit tenir compte des propriétés Position X et Position Y.
Largeur de colonne automatique indique si Forms adapte la largeur des colonnes de la LOV en fonction de la plus grande largeur, ou s'il utilise les propriétés fixées dans la fenêtre de correspondance de colonnes.


Physique

Position X indique dans le système de coordonnées en cours la position en abscisse du coin supérieur gauche de la LOV
Position Y indique dans le système de coordonnées en cours la position en ordonnée du coin supérieur gauche de la LOV
Ces deux propriétés peuvent être changées à l'exécution en utilisant la fonction Set_Lov_Property(nom_lov | id_lov, POSITION, position_x, position_y )

Largeur indique dans le système de coordonnées la largeur de la LOV
Hauteur indique dans le système de coordonnées la hauteur de la LOV
Ces deux propriétés peuvent être changées à l'exécution en utilisant la fonction Set_Lov_Property(nom_lov | id_lov, LOV_SIZE, largeur, hauteur )


Utilisation d'une LOV pour valider un item

Il est possible, lorsqu'une LOV est attachée à un item de l'utiliser pour valider le contenu de l'item.
Pour ce faire, il suffit de positionner à Oui la propriété de l'item : Valider à partir de la liste.
Toute valeur saisie dans cet item qui n'est pas retrouvée dans la LOV ne sera pas acceptée.
Ce fonctionnement évite d'avoir à saisir du code supplémentaire pour valider la saisie.

Rappel : Seule la première colonne de la LOV est utilisée pour valider la valeur saisie.


Fonctions natives liées à l'utilisation d'une LOV

Fonctions liées à une LOV

Varchar2 = Get_Lov_Property( nom_lov | id_lov , nom_propriété ) ;
Set_Lov_Property( nom_lov | id_lov , nom_propriété, valeur [,valeur] ) ;
nom_propriété peut être:

Lov = Find_Lov( nom_lov ) ;
Cette fonction retourne l'identifiant interne de la LOV dont le nom est passé en argument.
La valeur de retour peut être testée avec la fonction Id_Null() qui retourne TRUE ou FALSE

Declare
  Lv_id  Lov ;
Begin
 Lv_Id := Find_Lov( 'ma_lov' ) ;
 If Id_Null( Lv_Id ) Then
   Message('La LOV : ma_lov n''existe pas' );
   Raise Forms_trigger_failure ;
End if ;
End ;

Fonctions liées à une colonne d'une LOV

Varchar2 = Get_Lov_Column_Property( nom_lov | id_lov , numéro_colonne, nom_propriété ) ;
Set_Lov_Column_Property( nom_lov | id_lov , nom_propriété, numéro_colonne, valeur ) ;

nom_propriété peut être:

Boolean Show_Lov( nom_lov | id_lov [, position x, position y] ) ;
Cette fonction déclenche l'affichage de la LOV dont le nom est passé en argument.
Il est possible d'indiquer également les coordonnées X et Y de positionnement du bord supérieur gauche de la fenêtre.

Declare
  LB$Ok  Boolean ;
Begin
  LB$Ok := Show_Lov( 'ma_lov' ) ;
  If not LB$Ok Then
    Message('Vous n'avez sélectionné aucune valeur');
    Raise Form_Trigger_Failure ;
  End if ;
End ;

Fonctions liées à un groupe d'enregistrements

Find_Group()
Create_Group()
Create_group_From_Query()
Add_Group_Column()
Add_Group_Raw()
Populate_Group()
Populate_Group_From_Query()
Get_Group_Char_Cell()
Get_Group_Date_Cell()
Get_Group_Number_Cell()
Get_Group_Record_Number()
Get_Group_Row_Count()
Get_Group_Selection_Count()
Get_Group_Selection()

Les fonctions liées au groupes d'enregistrements sont détaillées dans le chapitre : Les groupes d'enregistrements.


Fonctions liées à un item

Varchar2 = Get_Item_Property( nom_item | id_item , nom_propriété ) ;
Set_Item_Property( nom_item | id_item , nom_propriété, valeur ) ;
nom_propriété peut être:

List_Values( [ RESTRICT | NO_RESTRICT ] ) ;
Permet de forcer l'affichage d'une LOV sur l'item en cours lorsque une LOV lui est attachée.
RESTRICT permet de tenir compte de la valeur actuelle de l'item afin de restreindre la liste. Si celle-ci ne ramène plus qu'une seule valeur, elle n'est pas affichée et retourne cette valeur dans l'item.


Déclencheur lié à une LOV

KEY_LISTVAL
Permet d'intercepter la demande d'affichage de la LOV et d'exécuter le code voulu avant son affichage par List_Values() ou Show_Lov().

C'est le déclencheur idéal pour construire ou associer dynamiquement un groupe d'enregistrements différent à la LOV.


Manipulation au cours de l'exécution

Il n'est pas possible de créer une LOV au cours de l'exécution. Celle-ci doit avoir été préalablement créée lors de la conception.
Toutefois, le groupe d'enregistrements qui l'alimente peut faire l'objet d'un certain nombre de manipulations.

Ce que vous pouvez faire en cours d'exécution:

Cas d'école : Gestion dynamique d'un groupe d'enregistrements

En fonction des éléments saisis dans l'écran par l'utilisateur, notre LOV doit afficher des données qui ne proviennent par toujours de la même table.
Le nombre et le nom des tables visées n'étant pas figé, nous ne pouvons pas créer au moment du design autant de groupes d'enregistrements que nécessaire.

Nous allons donc créer le groupe d'enregistrements dynamiquement au cours de l'exécution, le remplir et l'attacher à la LOV avant son affichage.

La procédure suivante : Build_Group() accepte trois arguments:

Elle peut être invoquée depuis un déclencheur Key-Listval sur l'item :

Déclencheur : KEY_LISTVAL
Begin
  If ... Then
     Build_Group( 'Table1', 'code','Libelle' ) ;
  Else
     Build_Group( 'Table2', 'id','nom' ) ;
  End if ;
End ;

PROCEDURE Build_Group
-- Unité de programme : Build_Group --
PROCEDURE Build_Group
  (
   PC$Nom_table IN VARCHAR2,
   PC$Nom_colonne_1 IN VARCHAR2,
   PC$Nom_colonne_2 IN VARCHAR2
  )
 IS
  LC$Req Varchar2(512) ; -- chaîne d'accueil de la requête
  RG_NAME Varchar2(15) := 'RG_GROUP' ; -- Nom du groupe
  rg_id RecordGroup ; -- Identifiant interne du groupe
  errcode NUMBER ; -- code retour
  LB$Ok Boolean ;
BEGIN
  -- constitution de la requête --
  LC$Req := 'Select ' 
          || PC$Nom_colonne_1 || ',' 
          || PC$Nom_colonne_2 || ' From ' 
          || PC$Nom_table || ' order by 1' ;

  -- recherche de l'identifiant interne du groupe --
  rg_id := Find_Group( rg_name );
  IF Not Id_Null(rg_id) THEN
    -- il existe déjà, on le supprime --
    Delete_Group( rg_id ) ;
  Else
    -- création du groupe --
    rg_id := Create_Group_From_Query( rg_name, LC$Req ) ;
  End if ;

  -- remplissage du groupe --
  errcode := Populate_Group( rg_id );

  -- Attachement du groupe à la LOV --
  Set_Lov_Property( 'ma_lov', GROUP_NAME, rg_id ) ;

  -- Ajustement du titre de la LOV --
  Set_Lov_Property( 'ma_lov', TITLE, 'Le titre de la LOV' ) ;
 
  -- Ajustement des colonnes de la LOV --
  Set_Lov_Column_Property( 'ma_lov', 1, TITLE, 'Code' ) ;
  Set_Lov_Column_Property( 'ma_lov', 1, WIDTH, 30 ) ;

  Set_Lov_Column_Property( 'ma_lov', 2, TITLE, 'Libellé' ) ;
  Set_Lov_Column_Property( 'ma_lov', 2, WIDTH, 110 ) ;

  -- Affichage de la LOV --
  LB$Ok := Show_Lov( 'ma_lov' ) ;

END;