Sous-formulaire 4D v12 : programmables et portables grâce au composant

Sous-formulaire 4D v12 : programmables et portables grâce au composant Par Bertrand SOUBEYRAND, SOUBEYRAND Consultant Note technique 4D-201012-23-FR Version 1 - Date 1 décembre 2010 Résumé Un formulaire inclus peut être présenté sous forme de liste (liste de lignes de facture dans une saisie de facture, par exemple) ou sous forme de page, de formulaire détaillé. Il devient ainsi possible de placer plusieurs instances d un sous-formulaire dans plusieurs formulaires saisie. C est ce type de présentation que la Note technique va s attacher à vous expliquer. 4D Notes techniques Copyright 1985-2010 4D SAS - Tous droits réservés Tous les efforts ont été faits pour que le contenu de cette note technique présente le maximum de fiabilité possible. Néanmoins, les différents éléments composant cette note technique, et le cas échéant, le code, sont fournis sans garantie d'aucune sorte. L'auteur et 4D SAS déclinent donc toute responsabilité quant à l'utilisation qui pourrait être faite de ces éléments, tant à l'égard de leurs utilisateurs que des tiers. Les informations contenues dans ce document peuvent faire l'objet de modifications sans préavis et ne sauraient en aucune manière engager 4D SAS. La fourniture du logiciel décrit dans ce document est régie par un octroi de licence dont les termes sont précisés par ailleurs dans la licence électronique figurant sur le support du Logiciel et de la Documentation afférente. Le logiciel et sa documentation ne peuvent être utilisés, copiés ou reproduits sur quelque support que ce soit et de quelque manière que ce soit, que conformément aux termes de cette licence. Aucune partie de ce document ne peut être reproduite ou recopiée de quelque manière que ce soit, électronique ou mécanique, y compris par photocopie, enregistrement, archivage ou tout autre procédé de stockage, de traitement et de récupération d'informations, pour d'autres buts que l'usage personnel de l'acheteur, et ce exclusivement aux conditions contractuelles, sans la permission explicite de 4D SAS. 4D, 4ème Dimension, 4D Server, ainsi que tous les logos sont des marques enregistrées de 4D SAS. Windows,Windows NT, Vista, Windows 7, Win 32s et Microsoft sont des marques enregistrées de Microsoft Corporation. ICU Copyright 1995-2010 International Business Machines Corporation and others - iodbc Copyright 1995-2006: Open Linck Software - LibZip Copyright 2006 Dieter Baron and Thomas Klausner. OpenSSL : OpenSSL Project for use in the OpenSSL Toolkit. - SYNAPSE Copyright 1994-2010 Synapse Developement - XALAN Copyright 2010 4D SAS/ XERCES Copyright 2010 4D SAS - zlib Copyright 1995-2010 Jean-Loup Gailly and Mark Adler. Apple, Macintosh, QuickTime sont des marques enregistrées ou des noms commerciaux de Apple Computer,Inc. Mac2Win Software Copyright 1990-2002 est un produit de Altura Software,Inc. Tous les autres noms de produits ou appellations sont des marques déposées ou des noms commerciaux appartenant à leurs propriétaires respectifs. 1 / 11

Sous-formulaire 4D v12 : programmables et portables grâce au composant 4e Dimension version 12 augmente les capacités des sous-formulaires qui deviennent programmables et portables grâce aux composants. À présent que toutes les nouvelles fonctionnalités de 4D v11 SQL ont bien été assimilées et voire maîtrisées, cette note technique vous propose d aborder sereinement les sous-formulaires 4D v12. On les croyait relégués au plus profond des antiquités de 4D, les sous-formulaires rebondissent avec 4D v12 : un sacré coup de fouet et une nouvelle jeunesse! Un formulaire inclus peut être présenté sous forme de liste (liste de lignes de facture dans une saisie de facture, par exemple) ou sous forme de page, de formulaire détaillé. Il devient ainsi possible de placer plusieurs instances d un sous-formulaire dans plusieurs formulaires "saisie". C est ce type de présentation que la note technique va s attacher à vous expliquer. Note : les sous-formulaires de 4D v12 aiment les pointeurs. Si utiliser les pointeurs n est pas une obligation, il apparaît qu ils sont très vite pratiques dans le contexte qui nous intéresse. Si vous n avez pas de notion de ce que sont les pointeurs dans 4D nous vous conseillons vivement de vous référer à la documentation et à la note technique "4D v11 SQL : Les pointeurs revisités", réf. 4D-200906-12-FR. Le nouveau vocabulaire 1. Le formulaire hôte 2. Le sous-formulaire 3. Le container de sous-formulaire 4. L instance de sous-formulaire Le formulaire hôte Le formulaire hôte, la documentation de 4D parle aussi de formulaire parent, est le formulaire qui reçoit le sous-formulaire. Le sous-formulaire Le sous-formulaire aussi appelé formulaire inclus est un formulaire classiquement réalisé dont la vocation est d être embarqué sur un formulaire hôte. Le sous-formulaire peut être représenté plusieurs fois dans le formulaire hôte. Le container de sous-formulaire Placé dans le formulaire hôte, le container de sous-formulaire est l objet à partir duquel on désigne le formulaire inclus. L instance de sous-formulaire 2 / 11

Comme il a été dit plus haut un sous-formulaire peut être représenté plusieurs fois dans un formulaire hôte. Chaque représentation de ce sous-formulaire est une instance du sous-formulaire. En résumé il est possible d avoir un formulaire PAPA dans lequel on place 2 containers de sous-formulaire. Dans un composant ou bien dans la base de données elle-même on a un formulaire JUMEAUX destiné à être incorporé 2 fois dans PAPA. On aura alors une instance A de JUMEAUX sur PAPA et une instance B de JUMEAUX SUR PAPA. Pour placer un container de sous-formulaire dans un écran, vous cliquez sur la dernière icône de la palette des outils l icône qui rassemble les zones Web, les zones de plugins et les containers de sous-formulaire. Une fois le container tracé, pour choisir le formulaire à embarquer, allez dans la liste des propriétés, sous section «sous-formulaire». N oubliez pas de préciser si le sous-formulaire est de type détaillé ou en liste. Un formulaire qui provient d'un composant doit être explicitement partagé. Dans l'explorateur : formulaires projet clic droit sur le formulaire à partager propriétés du formulaire Les commandes 4D dans le contexte des sous-formulaires : APPELER CONTENEUR SOUS FORMULAIRE OBJET Lire pointeur OBJET Lire nom EXECUTER METHODE DANS SOUS FORMULAIRE APPELER CONTENEUR SOUS FORMULAIRE Pour passer un événement 4D ou personnalisé entre le sous-formulaire et le formulaire hôte 3 / 11

OBJET Lire pointeur Pour récupérer un pointeur sur une variable placée dans un sous-formulaire ou sur la variable associée à un container de sous-formulaire OBJET Lire nom Pour récupérer le nom de l objet qui a le focus dans le sous-formulaire EXECUTER METHODE DANS SOUS FORMULAIRE EXECUTER METHODE DANS SOUS FORMULAIRE permet d'exécuter du code dans le contexte du sous-formulaire et sans interférence avec le formulaire hôte. La méthode appartient à la base hôte ou au composant qui embarque le sous-formulaire et peut recevoir des paramètres, retourner un $0. Nouvelles propriétés pour le container de sous-formulaire 4Dv12 Il peut être appelé par un nom de variable ou un nom d objet ; Il peut recevoir une méthode objet ; Il réagit à sept événements standards 1. Sur chargement 2. Sur libération 3. Sur validation 4. Sur données modifiées 5. Sur gain focus 6. Sur perte focus 7. Sur modif variable liée et un événement personnalisé par le développeur : L événement personnalisé est un code d événement que le développeur souhaite faire passer du sousformulaire vers la méthode objet du container de sous-formulaire (qui lui est partie intégrante du formulaire hôte quand le sous-formulaire peut lui appartenir à un composant). Ce code d événement peut être un code d événement natif 4D ou un code qui n a de signification que pour le développeur. La documentation conseille de passer un code négatif afin de ne pas interférer avec les codes de 4D présents ou à venir. Pour faire transiter un code de la sorte, 4D propose une nouvelle commande : APPELER CONTENEUR SOUS FORMULAIRE (code événement) Cette commande sera placée dans la méthode formulaire du sous-formulaire ou dans la méthode objet des divers objets que compte le sous-formulaire. 4D v12 introduit un nouveau concept de variable : la variable dynamique 4 / 11

De tout temps une variable était représentée dans un formulaire par : Un nom de variable Un nom d objet Il était possible d écrire ceci : CHOIX VISIBLE(lebouton;Vrai) ` CHOIX VISIBLE est renommée en v12! CHOIX VISIBLE(*;"truc_à_cliquer";Faux) Cette façon de faire est toujours valide en 4Dv12 mais il faut aussi compter sur les variables dynamiques qui ont au moins deux bonnes raisons d'exister : 1. Mémoire : avec un formulaire et ses variables process une instance de celles-ci est créée pour chaque process en mode compilé même si le formulaire n'est pas utilisé. En laissant faire 4D on économisera beaucoup de mémoire vive (Les listbox ne sont pas concernées par ce mécanisme). 2. Sous-formulaires : un sous-formulaire pouvant être utilisé une ou plusieurs fois dans un formulaire hôte, utiliser des variables "statiques" dans un sous-formulaire reviendrait à adresser les variables de chaque instance de ses sous-formulaires. Avec le nouveau fonctionnement, pour un objet donné, 4Dv12 va dynamiquement créer une variable ; elle sera différente pour chaque instance de sous-formulaire. 4D détruit automatiquement la variable après usage. Communication inter-formulaire par la variable du container L'échange de données entre le formulaire hôte et le sous-formulaire via la variable associée au container ne permet le transfert que d'une seule information. 5 / 11

Dans la base exemple : 1. L'utilisateur fait glisser une variable curseur qui fait bouger un indicateur de progression 2. L'utilisateur ajuste à la souris l'indicateur de progression : le curseur doit s'adapter La variable du container peut être typée selon la donnée à transférer. Par défaut c'est du texte et nous l'ajustons au type du curseur : entier long 1 L'utilisateur déplace le curseur depuis le formulaire hôte Modification de la valeur de la variable du container Interception de cet événement dans la méthode formulaire du sous-formulaire Faire quelque chose Quand la valeur de la variable du container de sous-formulaire est modifiée (même si on lui assigne la même valeur) il est possible d'intercepter ce changement en testant le nouvel événement formulaire Sur modif variable liée. Ce test doit impérativement se faire dans la méthode formulaire du sous-formulaire : : (Evenement formulaire=sur modif variable liée) // Obtenir un pointeur sur le container de ce sous-formulaire 6 / 11

$P_Container:=OBJET Lire pointeur(objet conteneur sous formulaire) $L_Valeur_curseur:=$P_Container-> // le curseur et le container: même variable! // Obtenir un pointeur sur la variable dynamique // qui a pour nom d'objet «thermo» $P_Thermo:=OBJET Lire pointeur(objet nommé;"thermo") // Et lui passer la valeur du curseur $P_Thermo->:=$L_Valeur_curseur Fin de cas Ce que fait ce code : Test de l'événement Sur modif variable liée dans la méthode formulaire du formulaire inclus Récupérer un pointeur sur le container de ce sous-formulaire Lire la valeur de la variable du container (à travers $P_Container dépointé) Récupérer un pointeur sur l'objet thermo dont la méthode formulaire est en cours Donnez une nouvelle valeur à l'indicateur de progression «thermo» 2 L'utilisateur clique sur l'indicateur de progression Note : cliquer sur un indicateur de progression n a pas beaucoup d intérêt mais pour notre exercice ça sera tout de même très amusant. Faire une action dans un objet du sous-formulaire Appeler le container de sous-formulaire avec un code d événement spécialisé (ou pas) Traiter en fonction du code (spécialisé) Le but est de cliquer sur l'indicateur de progression situé sur le sous-formulaire et d'en avertir le formulaire hôte. Une fois averti le formulaire hôte fera une action // Méthode objet de l'indicateur de progression dans le sous-formulaire : (Evenement formulaire=sur clic) $L_MonEvenement:=-100 APPELER CONTENEUR SOUS FORMULAIRE($L_MonEvenement) Fin de cas // Méthode objet du container sur le formulaire hôte : (Evenement formulaire=-100) $T_Message:="Le clic sur l'indicateur de progression du sous-formulaire a envoyé un code -100" $T_Message:=$T_Message+" et c'est la méthode objet du container qui répond ici" ALERTE($T_Message) // Le code -100 nous dit de mettre à jour le curseur 7 / 11

// On récupère la valeur de la variable dynamique «thermo» // Le container de sous-formulaire qui embarque le sous-formulaire // s'appelle «toto_le_sous_form» $P_Thermo:=OBJET Lire pointeur(objet nommé;"thermo";"toto_le_sous_form") $L_La_valeur_Thermo:=$P_Thermo-> ruler4:=$l_la_valeur_thermo Fin de cas Ce que font ces deux morceaux de code : Le sous-formulaire reçoit une action de l'utilisateur ou par programmation ; Il envoie un code d'événement au container ; Le container intercepte ce code d'événement ; Il fait quelque chose. La commande OBJET Lire pointeur dans le contexte des sous-formulaires : Vous passez en 1er paramètre un sélecteur sous forme de constante : - Objet conteneur sous formulaire : Si vous passez ce sélecteur, la commande retourne un pointeur vers la variable liée au conteneur du sous-formulaire. Les deux derniers paramètres optionnels sont ignorés s ils sont passés. Ce sélecteur ne peut donc être utilisé que dans le contexte d un formulaire utilisé comme sous-formulaire, afin d accéder à la variable liée à l objet conteneur. - Objet nommé : Si vous passez ce sélecteur, vous devez également passer le deuxième paramètre, nomobjet. Dans ce cas, la commande retourne un pointeur vers la variable associée à l objet dont vous avez passé le nom dans ce paramètre. Note : Si nomobjet correspond à un sous-formulaire et que l option "Sous-formulaire liste" est cochée, la commande retourne un pointeur vers la table du sous-formulaire si une table source est définie et Nil dans le cas contraire. Fonctionnement hors contexte sous-formulaire : - Objet courant ou selecteur omis : Si vous omettez le paramètre selecteur ou passez ce sélecteur, la commande retourne un pointeur vers la variable associée à l objet courant (objet dont la méthode formulaire est en cours d exécution). Note : Ce fonctionnement équivaut strictement à celui de la commande historique Self. La commande Self est conservée pour des raisons de compatibilité uniquement. - Objet avec focus : Si vous passez ce sélecteur, la commande retourne un pointeur vers la variable associée à l objet ayant le focus dans le formulaire. Les deux derniers paramètres optionnels sont ignorés s ils sont passés. Note : Ce fonctionnement équivaut strictement à celui de la commande Objet focus. La commande Objet focus est obsolète à compter de 4D v12. Communication interformulaires (trouver un meilleur titre) 8 / 11

Dans les cas précédents, en travaillant avec la variable du container, on passait une valeur au container et c'est dans la méthode formulaire du sous-formulaire que la variable thermomètre était renseignée. Dans l'exemple qui suit, nous allons toucher les variables du sous formulaire à travers un container désigné par son nom. Cela impose de connaître tous les noms d'objet des différentes variables. Tirés de la base de démonstration, ces deux clics au sein des curseurs s'adressent directement aux mêmes variables de sous-formulaires et c'est le nom d'objet du container subform/subform1 qui fait aiguillage : : (Evenement formulaire=sur clic) $P_Pointeur:=OBJET Lire pointeur(objet nommé;"thermo";"subform") $P_Pointeur->:=OBJET Lire pointeur-> $P_Pointeur:=OBJET Lire pointeur(objet nommé;"time";"subform") $P_Pointeur->:=Chaine(Heure courante) Fin de cas : (Evenement formulaire=sur clic) $Ptr:=OBJET Lire pointeur(objet nommé;"thermo";"subform1") $Ptr->:=OBJET Lire pointeur-> $Ptr:=OBJET Lire pointeur(objet nommé;"time";"subform1") $Ptr->:=Chaine(Heure courante) 9 / 11

Fin de cas Depuis le formulaire hôte nous avons touché toutes les variables que nous voulions modifier! Note : les exemples ci-dessus imposent d utiliser des variables dynamiques et OBJET Lire pointeur. En effet en s adressant directement à un nom de variable écrit en dur dans le sous-formulaire, toutes les instances de ces sous-formulaires réagiraient simultanément. Dans le 3ème curseur, le code continue de la même façon de valoriser l objet "time" et l objet "thermo" mais en plus on y demande l'exécution du code d une méthode écrite dans la base hôte qui va modifier les positions de "time" et de "thermo" dans le formulaire. Pour que cette méthode s exécute dans le contexte de l instance du sous-formulaire subform2, on écrit ceci : // Méthode objet du curseur "ruler3" : (Evenement formulaire=sur clic) $Ptr:=OBJET Lire pointeur(objet nommé;"thermo";"subform2") $Ptr->:=OBJET Lire pointeur -> $Ptr:=OBJET Lire pointeur(objet nommé;"time";"subform2") $Ptr->:=Chaine(Heure courante) EXECUTER METHODE DANS SOUS FORMULAIRE("Subform2";"bouge_ton_inclus") Fin de cas Ce que fait le code : Récupère deux pointeurs sur les deux objets à valoriser et les valorise ; Exécute la méthode bouge_ton_inclus dans le contexte du sous-formulaire subform2. La finalité de bouge_ton_inclus n est pas essentielle ici. Exécution du code dans le sous-formulaire : EXECUTER METHODE DANS SOUS FORMULAIRE ("Subform";"méthode";*; param1 ; param2) Nous sommes dans le formulaire parent (la documentation de la 12.1 dit d utiliser la commande EXECUTER METHODE DANS SOUS FORMULAIRE dans la méthode formulaire du formulaire hôte et nous, ici, nous l utilisons avec succès dans la méthode objet du curseur). Le 1er paramètre : il nous dit dans quelle instance de sous-formulaire exécuter le code ; n oublions pas que le sous-formulaire est représenté trois fois à travers trois containers (subform, subform1, subform2). Le 2e paramètre : c est le nom de la méthode à exécuter placée entre guillemets. 10 / 11

La méthode peut appartenir à la base hôte ou le cas échéant au composant embarquant le sousformulaire. La méthode peut recevoir des paramètres ($1, $2, ) La méthode peut retourner un $0. Si la méthode ne retourne rien mettez la légendaire * étoile. Conclusion Les sous-formulaires de type "page" trouvent un nouveau souffle avec 4D v12. La capacité de pouvoir faire communiquer le formulaire hôte et son sous-formulaire dans les deux sens ouvre de nouvelles perspectives au développeur 4D qui pourra réaliser des interfaces, parfois, génériques et toujours plus sophistiquées. Note : La base exemple utilise un composant. Mais à visée pédagogique, il est également montré que l'on peut utiliser les sous-formulaires page sans passer par un composant. C'est ce que vous ferez en choisissant la ligne de menu "Démo (sans composant)" qui utilise le formulaire-projet "Papa_hote(sans composant)". 11 / 11