Pratique des macros dans 4D

Un des grands apports en productivité de la version 2003 est l’apparition des macros. Une macro, dans 4e Dimension, c’est la possibilité d’insérer du code en un clic souris. Créer une macro, cela n’a de sens que pour des opérations répétitives. Il en existe déjà dans 4e Dimension et cette Note Technique vous explique comment créer vos propres macros et ainsi vous composer votre propre bibliothèque de macros.

Quand vous lancez 4D, celui-ci recherche la présence d’un fichier texte « macros.xml » dans le dossier 4D actif de l’OS de la machine, le dossier où se stockent les préférences 4D. S’il n’existe pas, 4D le crée avec un contenu basique, mais suffisant pour comprendre comment créer d’autres macros : n’en profitez pas pour interrompre la lecture de cette Note technique !

4D stocke ce fichier dans ses ressources et par conséquent vous devez pouvoir y stocker votre propre fichier « basique ». Le fichier est un fichier .xml éditable dans n’importe quel éditeur de texte type Notepad ou BBedit (dans BBedit Pro vous aurez en plus la colorisation syntaxique). Qui dit xml, dit structuré et si nous n’entrons pas ici dans ce sujet, sachez que pour créer vos macros il convient de respecter une méthodologie rigoureuse, mais simple.

Appliquer une macro dans du code se fait par le menu contextuel de l’éditeur de méthode ou en affichant les listes en bas de l’éditeur :

En choisissant la macro « BoucleTable », après sélection du nom de la table, on obtient ceci :

Le commentaire : la ligne de commentaire commence toujours par un double slash // ce qui fait que cette ligne ne sera pas analysée. Elle décrit ce que fait la macro.

Le nom : s’écrit sous cette forme <macro name=« nom_macro »>
Le libellé entre les guillemets sera celui qui s’affichera dans l’éditeur de 4D. C’est le réglage par défaut, mais notez que cette balise accepte des attributs facultatifs que nous vous conseillons de paramétrer et de placer systématiquement :

<macro name="nom_macro" type_ahead_text="monraccourci" type_ahead="true" in_menu="true">

Les attributs seront configurés comme pour un réglage par défaut ensuite vous aurez l’avantage de pouvoir les modifier aisément. Ainsi :
type_ahead : vous permet d’accéder, ou pas, à la macro via la saisie prédictive
type_ahead_text : le texte à saisir pour accéder à la macro
in_menu : si false, la macro est « invisible » et ne peut être atteinte que par la saisie de son nom. (False et true se traduisent par Faux et Vrai)
Si vous ouvrez une balise <macro>, il convient de la refermer avec </macro>. Il en va ainsi pour beaucoup de balises xml. Certaines, pourtant, marchent isolément.

La balise texte : encadre le code 4D qui doit être « plaqué » automatiquement. S’écrit <text>…</text>.

Sélection : si votre macro contient une balise <selection/> et que du texte est sélectionné avant de plaquer le contenu de la macro dans le code, la balise <selection/> sera remplacée autant de fois qu’elle est présente dans la macro. Une façon rapide, par exemple, de placer le nom d’une table tout au long du code. Les macros contenant le tag <selection/>, n’apparaissent pas dans la fenêtre de saisie prédictive.

Le point d’insertion : à l’intérieur de la balise < text> et par conséquent dans le code 4D, il est possible de positionner le curseur directement à l’endroit de votre saisie grâce au tag <caret/>. C’est une balise solitaire.

Voici l’exemple d’une macro type à coller dans le fichier macro.xml. Notez la balise <macros> </macros> avec un S final pour ouvrir et fermer le fichier xml.

<macros>
// -----------------------------------------
// macro de test
<macro name="CodeModif" type_ahead_text="monraccourci" type_ahead="true" in_menu="true">
        <text>
              ` Modifié par : <user_os/> (<date format="1"/>)
              <caret/>
       </text>
</macro>
// -----------------------------------------
</macros>

Voici le tableau des balises d’une macro (chapitre III) :

<macros> </macros> Début et fin du fichier de macros (balises obligatoires).

<macro> </macro> Début et fin d’une définition de macro et de ses attributs.
Attributs :
name : Nom de la macro telle qu’il apparaîtra dans les menus et les listes de l’éditeur de méthodes (attribut obligatoire).
type_ahead_text : Chaîne de caractères à saisir pour appeler la macro à l’aide de la fonction de saisie prédictive.
in_menu : Booléen indiquant si la macro peut être appelée à l’aide du menu contextuel. Valeurs = « true » (défaut) ou « false ».
type_ahead : Booléen indiquant si la macro peut être appelée à l’aide de la fonction de saisie prédictive. Valeurs = « true » (défaut) ou « false ».

<selection/> Balise remplacée par le texte sélectionné au moment de l’appel de la macro. La sélection peut être vide.

<text> </text> Début et fin du code devant être inséré dans la méthode. Un retour chariot sera ajouté avant et après le code.

<caret/> Emplacement du point d’insertion dans le code après que la macro ait été collée.

<user_4D/> Balise remplacée par le nom de l’utilisateur 4D courant.

<user_os/> Balise remplacée par le nom de l’utilisateur système courant.

<method_name/> Balise remplacée par le nom de la méthode projet courante.

<date/> Balise remplacée par la date du jour.
Attribut :
format : Format 4D utilisé pour afficher la date. Si aucun format n’est défini, le format par défaut est utilisé. Valeurs = numéro de format 4D (0 à 8).

<time/> Balise remplacée par l’heure courante.
Attribut :
format : Format 4D utilisé pour afficher l’heure. Si aucun format n’est défini, le format par défaut est utilisé. Valeurs = numéro de format 4D (0 à 6).

<clipboard/> Balise remplacée par le contenu du Presse-papiers.
Attribut :
index : Presse-papiers à coller. Valeurs = numéro du Presse-papiers (0 à 9).

Surtout si elle est un peu complexe, nous vous conseillons d’écrire la macro classiquement dans 4D, de la tester et ensuite vous la collerez dans votre fichier. C’est ce que nous faisons avec un premier exemple un peu plus sophistiqué qui vous permettra d’insérer les fondations d’une méthode qui lance un nouveau process et attend la fin de celui-ci. Vous aurez tout le loisir de « customiser » ce code comme bon vous semblera. Cette macro fait référence à la Note technique N° 4D-200310-28-FR Exécuter sur serveur.

<macros>

// Executer une methode dans un nouveau process
<macro name="Executer Pseudo recursif" type_ahead_text="pseudo" type_ahead="true" in_menu="true">
<text>
C_ENTIER($I_Process)
`### PENSEZ A TYPER VOS PARAMETRES ###
C_BLOB($1)
`##############################

Au cas ou 

   : (Nombre de parametres=0)
         ` 4DBarber_Open 
         ` 4DBarber_Call ("Patientez")
      B_Message_Read:=Faux
      B_flag:=Faux

      $I_Process:=Nouveau process(Nom methode courante;1024*100;Nom methode courante;"Parameter";*)
         ` $I_Process:=Executer sur serveur(Nom methode courante;1024*100;Nom methode courante;"Parameter";*)

      Repeter 
         ENDORMIR PROCESS(Numero du process courant;60)
         APPELER 4D
         LIRE VARIABLE PROCESS($I_Process;B_Flag;B_flag)
      Jusque (B_flag)

         ` 4DBarber_Close 
      B_Message_Read:=Vrai
      ECRIRE VARIABLE PROCESS($I_Process;B_Message_Read;B_Message_Read)

   Sinon 

      B_flag:=Faux
      B_Message_Read:=Faux
         ` ##############################
         ` ICI LE CODE A EXECUTER
         ` ATTENTION : DANS LE CADRE D’UN EXECUTER SUR SERVEUR,
         ` IL EST IMPOSSIBLE DE METTRE DES ELEMENTS  D’INTERFACE (ALERTE, DEMANDER, ETC.)

          <caret/>
         ` FIN DU CODE A EXECUTER
         ` ##############################
      B_flag:=Vrai

      Repeter 
         APPELER 4D
         ENDORMIR PROCESS(Numero du process courant;3)
      Jusque (B_Message_Read)

Fin de cas 

   ` Fin de la methode

</text>
</macro>

</macros>

Si par la suite vous devez modifier une macro, sachez qu’il n’est pas requis de quitter 4D. La seule contrainte est de fermer la méthode puis de l’ouvrir à nouveau afin que la macro corrigée soit prise en compte.

Les fichiers de démos joints à cette Note comportent la DTD ( Document Type Declaration) des macros de 4D. Une DTD, c’est le profil d’un fichier xml. La DTD explique à l’application qui aura à analyser le fichier xml comment l’interpréter. Si vous n’avez pas encore fait votre analyseur en pur 4D et que vous ne possédez pas d’utilitaire d’une tierce partie alors, ouvrez votre fichier xml dans un navigateur web récent. Pour que l’analyseur tienne compte de la DTD, il vous suffit d’ajouter l’instruction suivante sur la première ligne du fichier de macros :

<!DOCTYPE macros SYSTEM "c:\macros.dtd">

(… où « c:\macros.dtd » indique le chemin d’accès du fichier DTD que vous avez créé)

Cette note technique est accompagnée des fichiers macros2.xml, macros3.xml et macros 4.xml que vous pouvez intégrer à votre propre fichier macros.xml (en copiant-collant la partie entre <macro-name> et </macros>).

Les macros de 4D sont la façon la plus rapide de plaquer du code répétitif dans vos méthodes.

Téléchargez la base exemple :

Base pour Windows

Base pour Mac OS