4D v16.3
Créer et utiliser des macros
Créer et utiliser des macros
Vous pouvez utiliser des macro-commandes dans vos méthodes. Les macro-commandes permettent de gagner beaucoup de temps lors de la saisie des méthodes.
Une macro-commande est une partie de code 4D accessible en permanence et pouvant être insérée à tout endroit de vos méthodes, quelle que soit la base ouverte. Les macro-commandes peuvent contenir tout type de texte, des commandes et des constantes 4D, ainsi que des balises spéciales, remplacées au moment de l’insertion de la macro par des valeurs issues du contexte de la méthode. Par exemple, une macro-commande peut contenir la balise <method_name/> ; au moment de son insertion, cette balise sera remplacée par le nom de la méthode projet courante.
Les macro-commandes sont stockées dans un ou plusieurs fichier(s) au format XML (texte). Elles peuvent être affichées dans une liste de l’éditeur de méthodes ; elle peuvent également être appelées à l’aide du menu contextuel de l’éditeur ou à l’aide de la fonction de saisie prédictive.
Les macro-commandes de 4D sont écrites au format XML. Vous pouvez utiliser “tel quel” le fichier de macro-commandes par défaut de 4D ou le modifier.
4D charge les macros à partir d’un dossier nommé “Macros v2”. Les macros doivent être présentes sous forme d’un ou plusieurs fichiers xml placés dans ce dossier.
Le dossier “Macros v2” peut être situé :
- dans le dossier 4D actif de la machine. Les macros sont alors partagées pour toutes les bases.
Note : L’emplacement du dossier 4D actif varie en fonction du système d’exploitation. Pour plus d’informations, reportez-vous à la description de la commande Dossier 4D dans le manuel Langage de 4D. - à côté du fichier de structure de la base. Les macros ne sont chargées que pour cette structure.
- pour les composants : dans le dossier Components de la base. Les macros ne sont alors chargées que si le composant est installé.
Ces trois emplacements peuvent être utilisés simultanément : il est possible d’installer un dossier “Macros v2” à chaque emplacement. Les macros seront chargées dans l’ordre suivant : dossier 4D, fichier de structure, composant 1... composant N.
4D propose par défaut un ensemble de macros correspondant notamment à la liste des mots-clés. Ces macros sont incluses dans le fichier Macros.xml, placé dans le dossier “Macros v2” créé dans le dossier 4D actif de la machine lors du premier lancement de 4D.
Vous pouvez modifier ce fichier ou le contenu du dossier comme vous le souhaitez par la suite (cf. paragraphe suivant). En cas de problème avec ce dossier, il vous suffit de le supprimer, 4D le recréera au lancement suivant.
Vous pouvez ajouter des macro-commandes personnalisées dans le fichier “Macros.xml” à l’aide d’un éditeur de texte standard ou par programmation. Vous pouvez également ajouter des fichiers XML de macros personnalisés dans ce dossier.
En mode local, le fichier de macros peut être ouvert pendant l’utilisation de 4D. La liste des macro-commandes disponibles est mise à jour à chaque événement activant 4D. Par exemple, il est possible de faire passer l’éditeur de texte au premier plan, modifier le fichier de macros puis retourner à la méthode : la nouvelle macro est disponible dans l’éditeur de méthodes.
Les macro-commandes vides ou erronées ne sont pas affichées.
Les fichiers de macro-commandes de 4D doivent être conformes à la norme xml. Cela signifie notamment que les lignes de déclaration xml <?xml version="1.0" ...?> et de déclaration de document < !DOCTYPE macros SYSTEM "http://www.4d.com/dtd/2007/macros.dtd"> sont obligatoires au début d’un fichier de macro pour que celui-ci soit chargé. Les différents types d’encodages du XML sont pris en charge. Il est toutefois recommandé d’utiliser un encodage compatible Mac/PC (UTF-8). 4D fournit une DTD permettant de valider les fichiers de macros. Ce fichier est situé à côté de l’application 4D, à l’emplacement suivant :
- Windows : \Resources\DTD\macros.dtd
- Mac OS : :Contents:Resources:DTD:macros.dtd
Si un fichier de macros ne contient pas les lignes de déclaration ou ne peut pas être validé, il n’est pas chargé.
Les macro-commandes 4D sont construites à l’aide de balises XML personnalisées nommées “éléments”.
Certaines balises indiquent un début et une fin de partie de la définition (balises doubles du type <balise> </balise>), d’autres sont remplacées par des valeurs du contexte d’insertion (<balise/>).
Conformément aux spécifications XML, certaines balises d’éléments peuvent comporter des attributs. Sauf indication contraire, ces attributs sont facultatifs et une valeur par défaut est utilisée lorsqu’ils sont omis. La syntaxe des éléments avec attributs est la suivante :
- balises doubles : <balise attribut="valeur"> </macro>
- balises simples : <balise attribut="valeur"/>
Si l’élément accepte plusieurs attributs, vous pouvez les cumuler sur la même ligne de commande, séparés par un espace :
<balise attribut1="valeur" attribut2="valeur" attribut3="valeur"... >
Voici la liste des balises et leur mode d’utilisation :
| Balises d’éléments | Description |
| <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’elle 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". | |
| - method_event : Permet de provoquer l’appel automatique de la macro en fonction de la phase courante de manipulation de chaque méthode (création, fermeture...). Valeurs = "on_load" : la macro est déclenchée à l’ouverture de chaque méthode, "on_save": la macro est déclenchée au moment de la sauvegarde de chaque méthode (fermeture d’une méthode modifiée ou sauvegarde via la commande Fichier>Sauvegarder),"on_create" : la macro est déclenchée à la création de chaque méthode, "on_close" : la macro est déclenchée à la fermeture de chaque méthode. | |
| "on_save" et "on_close" peuvent être utilisés conjointement — en d’autres termes, ces deux événements sont générés dans le cas de la fermeture d’une méthode modifiée. En revanche, "on_create" et "on_load" ne sont jamais générés de façon consécutive. Cet attribut permet par exemple de préformater les méthodes au moment de leur création (commentaires dans la zone d’en-tête) ou d’enregistrer des informations du type date et heure au moment de leur fermeture. | |
| - version : Permet d’activer le nouveau mode de prise en charge des sélections de texte pour la macro (cf paragraphe “A propos de la balise <method>” ci-dessous). Pour activer le nouveau mode, passez la valeur "2". Si vous omettez cet attribut ou passez version="1", l’ancien mode est conservé. | |
| - in_toolbar : Booléen indiquant si la macro doit être présente dans le menu du bouton Macro de la barre d'outils. 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. |
| <method> </method> | Début et fin du nom d’une méthode projet et de son paramètre (facultatif). La méthode est exécutée au moment de l’appel de la macro. Vous pouvez lui passer un paramètre sous la forme ("param1;param2;..."). Ce paramètre sera reçu dans la méthode via les variables $1, $2, etc. Pour des informations complémentaires sur cette balise, reportez-vous au paragraphe “A propos de la balise <method>” ci-dessous. |
| <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. |
| <method_path/> | Balise remplacée par le chemin d'accès complet 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). |
* Les macros peuvent être appelées à l’aide du menu contextuel de l’éditeur de méthodes ou de la saisie prédictive (cf. paragraphe suivant).
** Si vous souhaitez vous conformer aux spécifications du langage XML, vous ne devez pas utiliser de caractères étendus (caractères accentués, guillemets, etc.).
Voici un exemple de définition de macro :
| Contenu de la macro | Commentaires |
| <?xml version=”1.0”...?> | Déclaration XML |
| <!DOCTYPE macros SYSTEM> | Déclaration de document |
| <macros> | Début du fichier xml de macros |
| <macro name="BoucleEnregistrements"> | Début de la définition et nom de la macro |
| <text> | Début du code de la macro |
| Boucle($i;1;Enregistrements trouves(<Selection/>)) | La balise <Selection/> sera remplacée par le code sélectionné dans la méthode 4D au moment de l’insertion de la macro (par exemple un nom de table) |
| STOCKER ENREGISTREMENT(<Selection/>) | |
| ENREGISTREMENT SUIVANT(<Selection/>) | |
| Fin de boucle | |
| </text> | Fin du code de la macro |
| </macro> | Fin de la définition de la macro |
| </macros> | Fin du fichier xml de macros |
La balise <method> permet de générer et d’utiliser des macro-commandes exécutant des méthodes projet 4D. Ce principe autorise notamment les développeurs à créer des fonctions sophistiquées diffusées via des macro-commandes associées à des composants. Par exemple, la macro suivante provoquera l’exécution de la méthode MaMéthode avec le nom de la méthode courante comme paramètre :
<method>MaMéthode("<method_name/>")</method>Le code de la méthode appelée est exécuté dans un nouveau process. Ce process est tué à l’issue de l’exécution de la méthode.
Note : Le process de structure reste figé tant que l’exécution de la méthode appelée n’est pas terminée. Vous devez donc veiller à ce que celle-ci soit rapide et ne risque pas de provoquer de blocage de l’application. Si ce cas se produit, utilisez la combinaison Ctrl+F8 (Windows) ou Commande+F8 (Mac OS) permettant de “tuer” un process.
Par défaut, les macro-commandes peuvent être appelées via le menu contextuel ou la barre d’outils de l’éditeur de méthodes, la saisie prédictive ou une liste spécifique de bas de la fenêtre de l’éditeur.
A noter qu’il est possible de restreindre pour chaque macro les possibilités d’appel via le menu ou la saisie prédictive.
Par défaut, toutes les macro-commandes peuvent être appelées à l’aide du menu contextuel de l’éditeur de méthodes (via la commande hiérarchique Insérer macro) ou du bouton “Liste des macros” de la barre d’outils.
L’attribut in_menu de la balise <macro> permet de définir si la macro doit figurer ou non dans ce menu.
Dans le menu contextuel, les macro-commandes sont affichées dans l’ordre du fichier “Macros.xml” et des fichiers xml additionnels. Il est donc possible de changer cet ordre en modifiant ces fichiers.
Par défaut, toutes les macro-commandes sont accessibles via le mécanisme de la saisie prédictive (cf. section Ecrire une méthode). La macro-commande remplace le texte saisi. L’attribut type_ahead de la balise <macro> permet d’exclure une macro de ce mode de fonctionnement.
Note : Si la macro contient le marqueur <selection/>, elle n’apparaît pas dans la fenêtre de saisie prédictive.
Vous pouvez afficher vos macros dans une liste de l’éditeur de méthodes (cf. section Ecrire une méthode). Il suffit alors de double-cliquer sur un nom de macro dans la liste afin de l’appeler. Il n’est pas possible d’exclure une macro spécifique de cette liste.
La prise en charge des macros évolue entre les versions de 4D. Afin de maintenir la compatibilité entre les différentes versions tout en préservant les personnalisations, 4D n'écrase pas les versions précédentes. Pour bénéficier des dernières nouveautés, vous devez effectuer des adaptations.
Dans les versions de 4D antérieures à la v11, le programme maintenait automatiquement un ensemble de variables process pour la manipulation de texte dans les méthodes lors de l’emploi de la balise <method> : des variables d’entrée (_textSel, _blobSel, _selLen, _textMethod, _blobMethod, _methodLen) pour récupérer du texte et des variables de sortie (_textReplace, _blobReplace, _action) pour insérer du texte. Par compatibilité, ce mécanisme est toujours pris en charge dans 4D, mais depuis la version 11 il est obsolète :
- l’emploi de variables BLOB pour la gestion de textes de taille supérieure à 32000 caractères n’est plus nécessaire,
- la gestion de variables est incompatible avec l'architecture v11 des composants, dans laquelle les espaces d’exécution des variables sont cloisonnés. Un composant v11 ne peut pas accéder aux textes des méthodes de la base hôte et inversement via les variables prédéfinies.
Il est conseillé de gérér les sélections de texte via les commandes LIRE PARAMETRE MACRO et FIXER PARAMETRE MACRO. Ces commandes permettent de s’affranchir du cloisonnement des espaces d’exécution base hôte/composants et autorisent donc la création des composants dédiés à la gestion de macros. Pour activer ce mode pour les macro, vous devez déclarer l’attribut Version avec la valeur 2 dans l’élément Macro. Dans ce cas, 4D ne gère plus les variables prédéfinies _textSel, _textReplace etc. et les commandes LIRE PARAMETRE MACRO et FIXER PARAMETRE MACRO sont utilisables. Cet attribut doit être déclaré ainsi :
<macro name="MaMacro" version="2">
--- Texte de la macro ---
</macro>Si vous ne passez pas cet attribut, le mode précédent est conservé.
Depuis 4D v11, le respect de la norme XML pour les fichiers de macros nécessite l’observation de règles de syntaxe strictes. Ce principe peut entraîner des incompatibilités avec le code de macros créées avec des versions précédentes et empêcher le chargement des fichiers XML. Les principales sources de dysfonctionnements sont les suivantes :
- Les commentaires du type “// mon commentaire”, autorisés à l’intérieur des éléments <macro> dans les versions précédentes de 4D, sont incompatibles avec la syntaxe XML. Les lignes de commentaires doivent respecter la forme standard “<!-- mon commentaire -->”.
- Les symboles <> employés notamment pour les noms des objets interprocess doivent être encodés. Par exemple, la variable <>params devra être écrite <>params.
- La balise de déclaration initiale <macros> pouvait être omise dans les versions précédentes de 4D. Elle est désormais obligatoire, sinon le fichier n’est pas chargé.
Dans la version 12 de 4D, de nouvelles macro-commandes sont disponibles afin de faciliter l’utilisation des commandes SQL. Comme le fichier "Macros.xml" peut être personnalisé, l’installation de la nouvelle version de 4D n’écrase pas automatiquement la version existante de ce fichier dans le dossier 4D actif. Pour pouvoir bénéficier des nouvelles macro-commandes SQL de 4D v12, vous devez soit :
- supprimer le fichier "Macros.xml" dans le dossier "Macros v2" (si vous ne l’avez jamais modifié) puis lancer 4D. Le nouveau fichier sera automatiquement recréé.
- ajouter manuellement les nouvelles macros dans le fichier "Macros.xml" du dossier "Macros v2" (si vous avez déjà personnalisé son contenu). Le nouveau fichier modèle de macros est disponible dans le dossier de l’application 4D, à l’emplacement suivant : 4D\Resources\en.lproj ou 4D\Resources\fr.lproj.
Produit : 4D
Thème : Editer les méthodes
Nom intl. : Creating and using macros
4D - Mode Développement ( 4D v16)
4D - Mode Développement ( 4D v16.1)
4D - Mode Développement ( 4D v16.3)
