Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script

Chapitre 7 : Système de formulaire

Retour à la table des matières


Introduction

Définition

TSD Script offre un système de formulaires qui permet de créer des fenêtres à partir d'un fichier (ressource) de description.

Un formulaire est une fenêtre contenant un certain type de formulaire de saisie de données. Dans un environnement à interface graphique, le formulaire constitue le principal moyen d'interaction entre l'utilisateur et l'application. Le développeur y place des contrôles qu'il sélectionne à partir d'une barre d'outils. Les contrôles de formulaire sont les suivants :

Contrôles de formulaire

Un contrôle de formulaire est un élément qui sert soit à obtenir des informations de l'utilisateur, soit à lui fournir des informations. Par exemple, un formulaire de saisie de données comprend généralement un ou plusieurs contrôles de type zone de texte, un bouton OK et un bouton Annuler (ou Annulation). Vous pouvez utiliser le module Interface Designer (concepteur d'interfaces) du Developer's Toolkit pour ajouter des contrôles à un formulaire (pour plus de détails, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide du concepteur d'interfaces).

La liste suivante répertorie tous les contrôles de formulaire pris en charge par TSD Script.

Nom de contrôle Description
Sous-formulaire Contrôle complexe qui englobe plusieurs autres contrôles.
Zone de texte Zone rectangulaire permettant à l'utilisateur de saisir une seule ligne d'informations. Si le texte entré dépasse la limite droite de la zone, celle-ci défile automatiquement.
Zone de texte multiligne Zone rectangulaire utilisée pour saisir plusieurs lignes de texte. Elle peut être configurée pour le renvoi automatique à la ligne.
Boîte à liste Boîte rectangulaire contenant une liste de choix déterminés. L'utilisateur ne peut pas y saisir de texte.
Boîte mixte Zone de texte à laquelle est associée une boîte à liste. L'utilisateur peut soit saisir une valeur dans la zone de texte, soit sélectionner un choix prédéfini dans la liste déroulante. La valeur sélectionnée apparaît dans la zone de texte, tandis que la liste se referme.
Arbre Contrôle qui affiche des données sous forme hiérarchique.
Bouton d'option Bouton utilisé pour sélectionner une option parmi plusieurs options qui s'excluent mutuellement. Le bouton sélectionné comporte un cercle noir.
Case à cocher Case correspondant à une option que l'utilisateur peut activer ou désactiver. Plusieurs cases peuvent être cochées en même temps.
Curseur de défilement Barre dont le déplacement est interactif.
Bouton (de fonction) Bouton rectangulaire déclenchant une action.
Texte Zone affichant un texte. L'utilisateur ne peut pas modifier ce texte.
Horloge Horloge horaire ou compteur de temps écoulé.
Table Données organisées en lignes et en colonnes.
Hypertexte Région affichant du texte dans un format hypertexte.
Boîte d'option Cadre rectangulaire qui regroupe plusieurs contrôles suivant la fonction de ces derniers.
Image Champ qui affiche une image issue d'un fichier.

Fichiers formulaire

Les formulaires sont gérés en tant que ressources d'application séparées. Le Developer's Toolkit vous permet de créer un ensemble de spécifications de formulaire et de les stocker dans des fichiers identifiés par l'extension (ou suffixe) .df. Comme pour les fichiers de base de connaissances, il existe un fichier source et un fichier objet pour de telles spécifications. Un fichier .df autorise la spécification de menus, de barres d'outils et de chaînes.

Le Générateur d'interface est un programme TSD Script qui, à partir d'un fichier source .df, crée un fichier objet .dfc. Les fichiers .dfc sont chargés et affichés par le Developer's Toolkit au moment de l'exécution.

Exemple de code de formulaire

L'exemple suivant est un fragment de code TSD Script qui met en jeu un formulaire.

  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
       END; 
   VARIABLES 
      employee: EmployeeRecord; 
   ACTIONS 
  IF DlgBox($Desktop,'EMPLOYEE.DFC[ADDFORM]',
            $NullHandler,employee) > 0 THEN
        SQLInsert('EMPLOYEES',employee); 
       END; 

Dans cet exemple, un nouveau type EmployeeRecord est déclaré dans la section TYPES. La section VARIABLES comporte également une variable de ce type. Le nom des champs d'enregistrement est identique au nom des contrôles de formulaire.

Voici ce que fait l'instruction DlgBox, dans la section ACTIONS :

En générale, les formulaires contiennent également des boutons OK et Annuler.

Arguments de l'instruction DlgBox

L'instruction DlgBox reçoit quatre arguments :

Titre d'argument Description
Fenêtre mère Descripteur de la fenêtre mère du nouveau formulaire.
Fichier formulaire Nom d'un fichier de spécification de formulaire compilé. Si celui-ci contient plusieurs spécifications de formulaire, le nom
du formulaire souhaité doit être indiqué entre crochets à la suite du nom du fichier.
Gestionnaire d'événements Comme les fenêtres génériques décrites précédemment, tous les formulaires ont un gestionnaire d'événements qui leur est associé.

Il est parfois souhaitable que le gestionnaire entreprenne l'action par défaut pour chaque événement. Pour tous ces cas, vous pouvez
spécifier $NullHandler, ce qui permet à l'utilisateur de se déplacer de contrôle en contrôle et de saisir
des valeurs dans le formulaire.

Lorsque l'utilisateur choisit le bouton OK, TSD Script copie automatiquement le contenu des contrôles du formulaire
dans les champs correspondants de la variable résultat.

Variable résultat Variable de type enregistrement dont les champs correspondent chacun à un contrôle du formulaire.

Lorsque l'utilisateur quitte le formulaire en sélectionnant OK, le contenu de chaque contrôle est copié dans
les champs correspondants de la variable enregistrement. Cette variable peut ensuite être écrite dans une base de données, affichée
dans une fenêtre ou soumise à toute opération correspondant aux besoins de l'application.

Exemple d'instruction DlgBox

Etudiez cet autre exemple :

  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
       END; 
   VARIABLES 
      employee: EmployeeRecord; 
   ACTIONS 
  SQLSelectInto('SELECT * FROM EMPLOYEES WHERE
              SSN=305-33-4111',employee);
  IF DlgBox($Desktop,'EMPLOYEE.DFC[EDITFORM]',
            $NullHandler{employee},employee) >> 0 THEN
    SQLUpdate('EMPLOYEES','WHERE SSN=''' &
            employee.snn & '''',employee);
       END; 

Dans cet exemple, le code procède aux opérations suivantes :

Deux modifications ont été apportées à cette instruction DlgBox :

Dans cet exemple, l'utilisateur voit s'afficher les données extraites de la table EMPLOYEES dans le formulaire, et il est en mesure d'accéder à n'importe quel contrôle et d'en modifier le contenu.

Gestionnaires d'événements de formulaire

Pour mettre en oeuvre des fonctions avancées, telles qu'un bouton provoquant l'affichage de la photo d'un employé, ou encore la validation du format d'un numéro de sécurité sociale, vous devez faire appel à un gestionnaire d'événements. Il faut pour cela créer des gestionnaires d'événements de formulaire.

Exemple de gestionnaire d'événements

Cette section présente un formulaire fonctionnant avec un gestionnaire d'événements. L'exemple sur lequel elle s'appuie met en jeu une base de connaissances appelée Employees, qui implémente une seule fonction publique ayant pour nom AddEmployee. Le corps de AddEmployee est similaire à celui des exemples précédents, sauf qu'au lieu d'utiliser $NullHandler, il référence un gestionnaire d'événements appelé EmployeeEvent.

KNOWLEDGEBASE Employees;
  USES
  Globals;
  TYPES
    EmployeeRecord IS RECORD
      first, last, ssn : STRING;
      salary : REAL;
      department : STRING;
          END; 
    ROUTINES 
    FUNCTION AddEmployee: BOOLEAN;
PRIVATE
    ROUTINES 
    EVENT EmployeeEvent(REF employee:
                        EmployeeRecord) IS
    ROUTINES
      FUNCTION ValidSSN(VAL ssn: STRING): BOOLEAN IS
   VARIABLES 
        i: INTEGER;
   ACTIONS 
        IF StrLength(ssn) <> 11 THEN
        EXIT(FALSE); 
       END; 
        FOR i:=1 TO 11 DO
          IF (i = 4 OR i = 7) AND (ssn[i] <> '-') THEN
        EXIT(FALSE); 
          ELSIF StrPos('0123456789',ssn[i]) = 0 THEN
        EXIT(FALSE); 
       END; 
       END; 
        EXIT(TRUE);
      END (* Valid SSN *);
       ACTIONS 
WHEN $Event IS $MsgSelect THEN 
        WHEN $FieldName IS 'SSN' THEN
          IF NOT ValidSSN(employee.ssn) THEN
            Exit(0);
       END; 
        ELSWHEN 'PICTURE_BUTTON' THEN
          ShowPicture(employee.last_name & '.BMP');
       END; 
       END; 
    END (* Employee Event *);
    FUNCTION AddEmployee: BOOLEAN IS
   VARIABLES 
      employee: EmployeeRecord;
   ACTIONS 
      IF DlgBox(mainWindow, 'EMPLOYEE.DFC[ADDFORM]',
                EmployeeEvent{employee},employee) > 0 THEN 
        SQLInsert('EMPLOYEES',employee);
        EXIT(TRUE);
      ELSE
        EXIT(FALSE);
       END; 
    END (* Add Employee *); 

EmployeeEvent est un descripteur d'événements qui reçoit par référence un paramètre unique du même type que la variable de retour transmise dans DlgBox.

Le gestionnaire d'événements teste un seul événement, $MsgSelect. Il est généré chaque fois que le formulaire est sur le point de faire sortir le curseur du contrôle en cours.

Si l'utilisateur tape une valeur dans un contrôle de type zone de texte et qu'il appuie ensuite sur la touche de tabulation, un événement $MsgSelect est généré. Le nom du contrôle que l'utilisateur est sur le point de quitter accompagne l'événement dans un paramètre "invisible" appelé $FieldName.

Etudions plus en détail le corps du gestionnaire EmployeeEvent.

WHEN $Event IS $MsgSelect THEN
        WHEN $FieldName IS 'SSN' THEN
          IF NOT ValidSSN(employee.ssn) THEN
            Exit(0);
       END; 
        ELSWHEN 'PICTURE_BUTTON' THEN
          ShowPicture(employee.last_name & '.BMP');
       END; 
       END; 

Le comportement obtenu est le suivant :

Le résultat par défaut est "1", valeur qui indique le succès de l'opération. Il existe toutefois des cas où il est nécessaire de renvoyer une valeur différente.

L'événement $MsgSelect

Certains événements générés automatiquement par TSD Script sont refusés lorsque le gestionnaire d'événements sort (Exit) avec la valeur 0. $MsgSelect fait partie de ces événements.

EmployeeEvent traite l'événement $MsgSelect associé au champ SSN et, s'il détermine qu'un numéro de sécurité sociale non valide a été saisi, il sort avec la valeur 0.

On dit alors que l'événement est refusé. Ce refus a deux conséquences :

Génération d'un événement $MsgSelect

Généralement, l'événement $MsgSelect signale que quelque chose a changé dans le formulaire. Il peut être généré de trois manières :

Remarque : $MsgSelect est généré uniquement lorsque la nouvelle valeur insérée est différente de l'ancienne.

Remarque : Appuyer sur la touche Entrée revient à sélectionner le bouton de fonction par défaut, s'il y en a un de défini. Cela génère un événement $MsgAccept. Si aucun bouton par défaut n'est défini, un message $MsgSelect est généré.

Lorsque le gestionnaire d'événements reçoit l'événement $MsgSelect, les données d'instance de la fenêtre (que le gestionnaire référence avec son argument enregistrement) sont mises à jour pour refléter le changement. Par exemple, lorsque l'utilisateur tape une valeur dans la zone de texte SSN et appuie sur la touche de tabulation, la valeur saisie est copiée dans le champ SSN de la variable d'instance de la fenêtre et un événement $MsgSelect est généré. La précédente valeur du champ est disponible dans le premier paramètre sans nom de l'événement.

La valeur du contrôle est indéfinie tant que l'envoi du message Select n'est pas terminé. Par conséquent, elle ne peut pas être interrogée.

Autres événements de formulaire

Les formulaires peuvent générer d'autres événements, dont voici la liste :

Evénement de formulaire Description
$MsgInitialize Version spéciale de $MsgSelect qui est générée uniquement pendant la phase de création du formulaire.
$MsgCreate Reçu juste avant l'affichage du formulaire. C'est le moment idéal pour opérer les initialisations telles que
l'ajout de la liste des choix possibles à une boîte à liste, etc.
$MsgDestroy Reçu juste avant la fermeture du formulaire.
$MsgAccept Reçu lorsque l'utilisateur valide le formulaire, généralement en appuyant sur Entrée ou en sélectionnant OK.
$MsgCancel Reçu lorsque l'utilisateur annule le formulaire, généralement en appuyant sur Echap ou en choisissant Annuler.
$MsgEnterField Reçu lorsque le curseur est sur le point de désigner un nouveau contrôle. $FieldName contient le nom du
nouveau contrôle.
$MsgExitField Reçu lorsque le curseur est sur le point de quitter un contrôle. Le nom de ce contrôle est contenu dans $FieldName.
$MsgHelp Reçu lorsque l'utilisateur choisit Aide ou appuie sur F1.
$MsgMandField Reçu lorsque l'utilisateur tente de valider un formulaire alors qu'une ou plusieurs zones de texte obligatoires ne sont pas remplies.

$FieldName contient alors le nom de la première zone obligatoire vide. Par défaut, le système affiche
affiche un message signalant à l'utilisateur son erreur. Retournez 0 si vous voulez empêcher l'affichage de ce message.

Noms des contrôles de formulaire

Chaque contrôle présent dans un formulaire porte un nom. Dans les exemples étudiés précédemment, un formulaire est utilisé pour obtenir les informations nécessaires au remplissage d'une variable de type EmployeeRecord. Etant donné que cet enregistrement comporte un champ appelé FIRST_NAME (prénom), le formulaire doit comporter un contrôle portant le même nom. Ainsi, lorsque l'utilisateur entre une valeur dans le contrôle FIRST_NAME, cette valeur est copiée dans le champ FIRST_NAME de l'enregistrement.

Remarque : Certains contrôles ne transportent pas de données. Par exemple, les boutons de fonction ne possèdent pas de valeur ; ils génèrent simplement des événements. C'est pourquoi il n'est pas nécessaire de prévoir des champs d'enregistrement pour ces boutons.

Autres attributs de contrôle

D'autres attributs peuvent être spécifiés pour les contrôles d'un formulaire :

Attribut Description
Read Only La donnée du contrôle est initialisée par l'enregistrement d'instance de la fenêtre et ne peut pas être modifiée par l'utilisateur.
Mandatory L'utilisateur ne peut pas valider le formulaire tant qu'il n'a pas fourni une valeur pour chacun des contrôles possédant cet attribut (qui signifie "obligatoire").
Input Length Indique le nombre de caractères que l'utilisateur peut entrer dans le contrôle, lorsqu'il s'agit d'une zone de texte.

Il existe aussi d'autres attributs qui concernent uniquement certains contrôles. Par exemple, dans le cas des zones de texte multilignes, vous pouvez activer ou désactiver le renvoi automatique à la ligne.

Table

Description

Table est une fenêtre utilisée pour visualiser une table de résultats SQL, c'est-à-dire un ensemble de lignes et de colonnes.

Table est utilisé comme contrôle de formulaire. Il permet d'effectuer les opérations suivantes :

Les colonnes de Table sont redimensionnables. Les colonnes sont séparées par une fine barre verticale, que l'utilisateur peut déplacer pour changer leur largeur.

L'expression de sélection (SELECT...) peut être spécifiée dans le fichier .df ou par programmation.

Instruction Description
DlgSQLSelect Lorsqu'il reçoit cette instruction, TSD Script émet la requête SQL spécifiée et met à jour le contenu du contrôle Table indiqué pour y faire apparaître les résultats de cette requête.

Cette instruction prend trois arguments :

  • Le descripteur du formulaire.
  • Le nom du contrôle Table.
  • Une expression sous forme de chaîne représentant l'instruction SQLSelect.

Il s'agit du moyen le plus efficace d'extraire des données d'une base de données pour les placer dans un contrôle de type table.

DlgFieldValue Peut être utilisée pour extraire une ligne sélectionnée.
Cette instruction prend trois arguments :
  • Le descripteur du formulaire.
  • Le nom du contrôle.
  • Une variable enregistrement qui reçoit les informations de la ligne mise en évidence.

Les colonnes de la ligne sont copiées dans les champs de l'enregistrement qui possèdent le même nom (par exemple, le contenu de la colonne "FIRST_NAME" est copié dans r.FIRST_NAME).

DlgListBoxInsert Insère une nouvelle ligne dans Table. Son rôle n'est pas d'exécuter une instruction SQLInsert, mais d'ajouter une nouvelle ligne au contrôle désigné.

Cette instruction prend trois arguments :

  • Le descripteur du formulaire.
  • Le nom du contrôle.
  • Une variable enregistrement dont les champs sont mis en correspondance avec les noms des colonnes du contrôle Table.

Les valeurs des champs qui ont un homonyme dans le contrôle sont copiées dans les colonnes correspondantes, tandis que les champs auxquels aucune colonne ne correspond sont ignorés.

DlgListBoxUpdate Met à jour une ligne sélectionnée dans Table. Son rôle n'est pas d'exécuter une instruction SQLUpdate, mais de mettre à jour les informations dans le formulaire.

Cette instruction prend trois arguments :

  • Le descripteur du formulaire.
  • Le nom du contrôle.
  • Une variable enregistrement dont les champs sont mis en correspondance avec les noms des colonnes du contrôle Table.

Les valeurs des champs qui ont un homonyme dans le contrôle sont copiées dans les colonnes correspondantes, tandis que les champs auxquels aucune colonne ne correspond sont ignorés.

DlgListBoxDelete Supprime la ligne sélectionnée dans le contrôle Table. Son rôle n'est pas d'exécuter une instruction SQLDelete, mais de supprimer une ligne du contrôle indiqué, dans le formulaire.

Cette instruction prend deux arguments :

  • Le descripteur du formulaire.
  • Le nom du contrôle Table.

Exemple de contrôle Table

Dans cet exemple, on crée une base de connaissances appelée Users, qui comporte une seule procédure publique nommée WorkWithUsers.

KNOWLEDGEBASE Users;
  TYPES
    UserRecord IS RECORD
      $Select : String;
      user_ID : String;
      user_name : String;
      user_rights : Integer;
       END; 
    ROUTINES 
    PROCEDURE WorkWithUsers;
PRIVATE
    ROUTINES 
    EVENT UserEvent(REF user: UserRecord) IS;
   VARIABLES 
      i: Integer;
    ROUTINES
      PROCEDURE AddUser IS;
   VARIABLES 
        newUser: UserRecord;
   ACTIONS 
        IF DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent,
           newUser) > 0 AND
SQLInsert('USERS',newUser) > 0 THEN
           DlgListBoxInsert($Handle,'USERLIST',newUser);
       END; 
     END (* Add User *);
     PROCEDURE EditUser IS;
   ACTIONS 
       IF DlgFieldValue($Handle,'USERLIST',user)
          > 0 AND 
          DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent
{user},user) > 0 AND 
         SQLUpdate('USERS','USER_ID='''
          user.user_ID & '''',user) > 0 THEN
          DlgListBoxUpdate($Handle,'USERLIST',user);
       END;
     END (* Edit User *);
     PROCEDURE DeleteUser IS;
   ACTIONS 
IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND 
          SQLDelete('USERS','USER_ID='''&user.user_ID&'''')
              > 0 THEN 
          DlgListBoxDelete($Handle,'USERLIST',user);
       END;
     END (* Delete User *);
      ACTIONS 
     WHEN $Event IS $MsgCreate THEN
       DlgSQLSelect($Handle,'USERLIST',user.$select);
     ELSWHEN $MsgSelect THEN
       WHEN $FieldName IS 'ADD_BUTTON' THEN
         AddUser;
       ELSWHEN 'EDIT_BUTTON' THEN
         EditUser;
       ELSWHEN 'DELETE_BUTTON' THEN
         DeleteUser;
       END;
       END; 
   END (* User Event *);
   PROCEDURE WorkWithUsers IS;
   VARIABLES
     UserWindow: WINDOW;
     user: UserRecord;
   ACTIONS
     user.$select = 'SELECT * FROM USERS';
     DlgCreate($Desktop,userWindow,
               'USERS.DFC [WORKWITHUSERS]',
               UserEvent{user});
   END (* Work With Users *); 

Explication de l'exemple

Le rôle de WorkWithUsers est de créer un formulaire comportant les contrôles suivants :

Le gestionnaire d'événements UserEvent du formulaire traite les événements suivants :

Le contrôle Table détient seulement les informations spécifiées par la description de ses colonnes. Il peut s'agir d'un sous-ensemble des colonnes de la table de résultats SQL. Lorsque vous utilisez l'instruction DlgFieldValue pour récupérer une ligne du contrôle Table, seuls les champs correspondant aux colonnes présentes dans ce contrôle sont renvoyés. Pour compléter le reste de l'enregistrement, il se peut que vous deviez recourir aux opérations SQLSelectInto ou SQLSelect.

Création de formulaires

Le processus de création d'un formulaire par TSD Script implique plusieurs étapes :

Remarque : Les données de la variable enregistrement d'instance supplantent les valeurs d'initialisation fournies dans le fichier de spécification de formulaire.

Formulaires modaux

On dit d'un formulaire qu'il est modal lorsque le programme attend, avant de poursuivre, que l'utilisateur ait validé ou annulé le contenu de ce formulaire. Lorsqu'une boîte de dialogue modale est affichée, aucune autre fenêtre ne peut être sélectionnée.

Les formulaires modaux se créent à l'aide de l'instruction DlgBox. L'instruction qui fait suite à DlgBox n'est pas exécutée tant que l'utilisateur n'en a pas terminé avec le formulaire créé par DlgBox. Les informations spécifiées par l'utilisateur sont renvoyées dans le quatrième argument de DlgBox. Il s'agit de la variable enregistrement de sortie.

L'utilisation de formulaires modaux doit être réservée aux messages d'erreur importants ou aux boîtes de dialogue dans lesquelles l'utilisateur doit impérativement fournir une réponse. Il peut s'agir, par exemple, d'un message invitant l'utilisateur à confirmer la suppression de fichiers.

Formulaires non modaux

On dit d'un formulaire qu'il est non modal (ou amodal) lorsque l'application n'a pas besoin d'une réponse de l'utilisateur dans ce formulaire pour poursuivre son exécution. Cela signifie que l'utilisateur est en mesure de basculer vers d'autres fenêtres alors que le formulaire est affiché à l'écran.

Les formulaires non modaux se créent à l'aide de l'instruction DlgCreate. Un appel à l'instruction DlgCreate démarre le processus de création d'un formulaire. Cependant, l'exécution de l'instruction suivante se déroule simultanément.

Le nouveau formulaire possède sa propre interface utilisateur et son propre programme (son gestionnaire d'événements). Son existence dure jusqu'à ce que l'utilisateur le valide ou l'annule, ou jusqu'à ce qu'une autre partie de l'application lui envoie un message de fermeture ($MsgClose).

Remarque : En programmation événementielle, les formulaires non modaux sont préférés aux formulaires modaux.

Formulaires à onglets

TSD Script permet de créer des formulaires à onglets. Chaque onglet correspond à une page. Pour accéder à une page particulière, l'utilisateur clique simplement sur l'onglet correspondant.

Pour créer un formulaire à onglets dans le module Interface Designer (concepteur d'interfaces) du Developer's Toolkit, vous devez spécifier un ou plusieurs formulaires à combiner. A l'exécution, ces formulaires s'utilisent exactement comme les autres types de formulaires. Ils peuvent être créés soit avec l'instruction DlgBox, soit avec DlgCreate. Pour gérer leurs événements, vous pouvez créer un gestionnaire d'événements.

Lorsque vous travaillez sur des formulaires à onglets, tenez compte des points suivants :


Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script

Retour à la table des matières

Copyright