4D v16.3
Crear y utilizar macros
Crear y utilizar macros
Puede utilizar los macro comandos en sus métodos, lo cual le ahorra mucho tiempo durante la entrada de métodos.
Un macro comando es una parte de código 4D accesible permanentemente que puede insertarse en cualquier parte de sus métodos, sin importar el tipo de base de datos abierta. Los macro comandos pueden contener todo tipo de texto, comandos y constantes 4D, así como etiquetas especiales las cuales se reemplazan en el momento de la inserción del macro por los valores derivados del contexto del método. Por ejemplo, un macro comando puede contener la etiqueta <nombre_metodo/>; en el momento de la inserción del macro, esta etiqueta se reemplazará por el nombre del método de proyecto actual.
Los macro comandos se guardan en uno o más archivos en formato XML (texto). Pueden colocarse en una lista del WA SET URL FILTERS; también pueden llamarse con la ayuda del menú contextual o utilizando la función de entrada predictiva.
Los macro comandos de 4D se escriben en formato XML. Puede utilizar el archivo de macro comandos como está o modificarlo.
4D carga las macros de una carpeta llamada “Macros v2.” Las macros deben estar en forma de uno o varios archivos XML ubicados en esta carpeta.
La carpeta “Macros v2” puede estar:
- En la carpeta 4D activa de la máquina. Las macros luego son compartidas por todas las bases.
Nota: la ubicación de la carpeta activa 4D varia en función del sistema operativo. Para mayor información, consulte la descripción del comando Get 4D folder en el manual Lenguaje 4D. - Junto al archivo de estructura de la base. Las macros se cargan únicamente para esta estructura.
- Para los componentes: en la carpeta Components de la base. Las macros sólo se cargan si el componente está instalado.
Estas tres ubicaciones pueden utilizarse simultáneamente: es posible instalar una carpeta “Macros v2” en cada ubicación. Las macros se cargarán en el siguiente orden: carpeta 4D, archivo de estructura, componente 1... componente X.
4D ofrece por defecto un conjunto de macros que corresponden particularmente a la lista de palabras clave en las versiones anteriores de 4D. Estas macros se incluye en el archivo “Macros.xml”, ubicado en la carpeta “Macros v2” creada en la carpeta 4D activa de la máquina durante el primera lanzamiento de 4D.
Puede modificar este archivo o el contenido de la carpeta posteriormente (ver el siguiente párrafo). En caso de que se presenten problemas con este archivo, puede borrarlo y 4D lo creará nuevamente en el próximo lanzamiento.
Puede añadir macros personalizadas al archivo “Macros.xml” utilizando un editor de texto estándar o por programación. También puede añadir archivos XML de macros personalizadas en esta carpeta.
En modo local, el archivo de macros puede abrirse mientras utiliza 4D. La lista de macro comandos disponibles se actualiza en cada evento de activación 4D. Por ejemplo, es posible traer el editor de texto al primer plano, modificar el archivo de macros, luego regresar al método: el nuevo macro está disponible en el editor de métodos.
Los macros vacíos o erróneos no se muestran.
Los archivos de macro comandos de 4D deben cumplir con la norma XML. Esto significa particularmente que las líneas de declaración XML <?xml version="1.0" ...?> y de declaración de documento < !DOCTYPE macros SYSTEM "http://www.4d.com/dtd/v11/macros.dtd"> son obligatorias al comienzo de un archivo de macro para que sea cargado. Se soportan los diferentes tipos de codificación XML. Sin embargo, se recomienda utilizar la codificación compatible Mac/PC (UTF-8). 4D ofrece un DTD que puede utilizarse para validar los archivos de macros. Este archivo se encuentra en la siguiente ubicación:
- Windows: \Resources\DTD\macros.dtd
- Mac OS: :Contents:Resources:DTD:macros.dtd
Si un archivo de macros no contiene las líneas de declaración o no puede validarse, no se carga.
Los macros comandos 4D se construyen con la ayuda de etiquetas personalizadas XML llamadas “elementos.”
Algunas etiquetas indican el inicio y el final de la definición (etiquetas doble del tipo <tag> </tag>), otras son reemplazadas por los valores del contexto de inserción (<tag/>).
Conforme a las especificaciones XML, algunas etiquetas de elementos pueden incluir atributos. A menos de que se indique lo contrario, estos atributos son opcionales y se utiliza un valor por defecto cuando se omiten. La sintaxis de los elementos con atributos es la siguiente:
- etiquetas dobles: <etiqueta atributo="valor"> </macro>
- etiquetas sencillas: <etiqueta atributo="valor"/>
Si el elemento acepta varios atributos, puede agruparlos en la misma línea de comando, separados por un espacio:
<etiqueta atributo1="valor" atributo2="valor" atributo3="valor"... >
Esta es la lista de etiquetas y su modo de utilización:
| Etiquetas de elementos | Descripción |
| <macros> </macros> | Inicio y fin del archivo macro (etiqueta obligatoria). |
| <macro> </macro> | Inicio y fin de la definición de un macro y sus atributos. |
| Atributos: | |
| - nombre** del macro tal como aparece en los menús y las listas del editor de métodos (atributo obligatorio). | |
| - type_ahead_text: cadena de caracteres ** a introducir para llamar al macro utilizando la función de tecleo predictivo*. | |
| - in_menu: booleano que indica si el macro puede llamarse utilizando el menú contextual*. Valores = "true" (por defecto) o "false." | |
| - type_ahead: booleano que indica si la macro puede llamarse utilizando la función de tecleo predictivo*. Valores = "true" (por defecto) o "false." | |
| - method_event: utilizado para disparar la llamada automática de la macro en función de la fase actual de manipulación de cada método (creación, cierre, etc.). Valores = "on_load": se dispara el macro al abrir cada método, "on_save": se dispara el macro al guardar cada método (cierre de un método modificado o al guardar utilizando el comando Archivo>Guardar, "on_create": la macro se dispara al crear cada método, "on_close": la macro se dispara al cierre de cada método. | |
| "on_save" y "on_close" pueden utilizarse en conjunto, en otras palabras, ambos eventos se generan en caso de que se cierre un método modificado. Por otra parte, "on_create" y "on_load" nunca se generan de manera consecutiva. Este atributo puede utilizarse, por ejemplo, para preformatear los métodos en el momento de su creación (los comentarios en el área de encabezado) o grabar información tal como la fecha y hora al momento de cerrarlos. | |
| - version: permite activar el nuevo modo de soporte de selecciones de texto para el macro (ver la sección “Acerca de la etiqueta <method>”). Para activar este nuevo modo, pase el valor "2". Si omite este | |
| atributo o pasa version="1", se conserva el modo anterior. | |
| - in_toolbar: Booleano que indica si la macro debe presentarse en el menú del botón Macro de la barra de herramientas. Valores= "true" (por defecto) o "false". | |
| <selection/> | Etiqueta reemplazada por el texto seleccionado en el momento de la llamada al macro. La selección puede estar vacía. |
| <text> </text> | Inicio y fin del código que debe insertarse en el método. Un retorno de carro se añadirá antes y después del código. |
| <method> </method> | Inicio y fin del nombre del método de proyecto y de su parámetro (opcional). El método se ejecuta cuando se llama la macro. Puede pasar un parámetro en la forma ("param1;param2;..."). Este parámetro será recibido en el método utilizando las variables $1, $2, etc.. Para información adicional sobre esta etiqueta, consulte la sección “Acerca de la etiqueta <method>”. |
| <caret/> | Ubicación del punto de inserción en el código después de insertada la macro. |
| <user_4D/> | Etiqueta reemplazada por el nombre del usuario 4D actual. |
| <user_os/> | Etiqueta reemplazada por el nombre del usuario del sistema actual. |
| <method_name/> | Etiqueta reemplazada por el nombre del método de proyecto actual. |
| <method_path/> | Etiqueta reemplazada por la ruta de acceso completa del método proyecto actual. |
| <date/> | Etiqueta reemplazada por la fecha actual. |
| Atributo: | |
| - format: formato 4D utilizado para mostrar la fecha. Si no hay un formato definido, se utiliza el formato por defecto. Valores = número de formato 4D (0 a 8). | |
| <time/> | Etiqueta reemplazada por la hora actual. |
| Atributo: | |
| - format: formato 4D utilizado para mostrar la hora. Si no hay un formato definido, se utiliza el formato por defecto. Valores = número de formato 4D (0 a 6). | |
| <clipboard/> | Etiqueta reemplazada por el contenido del portapapeles. |
| Atributo: | |
| - index: Portapapeles a pegar. Valores = número de portapapeles (0 a 9). |
* Los macros pueden llamarse utilizando el menú contextual del editor de métodos o utilizando la función de tecleo predictivo (ver la siguiente sección).
** Si quiere ceñirse a las especificaciones del lenguaje xml, no debe utilizar caracteres externos (caracteres acentuados, comillas, etc.).
Este es un ejemplo de definición de macro:
| Contenido de la macro | Comentarios |
| <?xml version=”1.0”...?> | Declaración XML |
| <!DOCTYPE macros SYSTEM> | Declaración de documento |
| <macros> | Inicio de archivo XML de macros |
| <macro name="RecordLoop"> | Inicio de la definición y nombre de la macro |
| <text> | Inicio del código de la macro |
| For($i;1;Records in selection(<Selection/>)) | La etiqueta <Selection/> se reemplazará por el código seleccionado en el método 4D al momento de la inserción de de la macro (por ejemplo, un nombre de tabla) |
| SAVE RECORD(<Selection/>) | |
| NEXT RECORD(<Selection/>) | |
| End for | |
| </text> | Fin del código de la macro |
| </macro> | Fin de la definición de la macro |
| </macros> | Fin del archivo XML de macros |
La etiqueta <method> permite generar y utilizar los macro comandos que ejecutan los métodos de proyecto de 4D. Este principio permite a los desarrolladores crear funciones sofisticadas que pueden distribuirse vía los macro comandos asociados a los componentes. Por ejemplo, el siguiente macro provocará la ejecución del método MiMetodo con el nombre del método actual como parámetro:
<method>MiMetodo("<method_name/>")</method>El código del método llamado se ejecuta en un nuevo proceso. Este proceso se termina una vez se ejecuta el método.
Nota: el proceso de estructura permanece congelado hasta que termine la ejecución del método llamado. Debe asegurarse de que la ejecución sea rápida y de que no haya riesgo de bloquear la aplicación. Si esto ocurre, utilice la combinación Ctrl+F8 (Windows) o Comando+F8 (Mac OS) para terminar el proceso.
Por defecto, los macros pueden llamarse utilizando el menú contextual o la barra de herramientas del editor de métodos, la función de tecleo predictivo, o una lista especifica al final de la ventana del editor de métodos.
Note que es posible restringir para cada macro la posibilidad de llamada utilizando el menú contextual y/o la función de tecleo predictivo.
Por defecto, todas los macros pueden llamarse vía el menú contextual del editor de métodos (utilizando el comando jerárquico Insertar macro) o el botón “Macros” de la barra de herramientas.
El atributo in_menu de la etiqueta <macro> se utiliza para definir si el macro aparecerá o no en este menú.
En el menú contextual, los macros se muestran en el orden del archivo “Macros.xml” y los archivos XML adicionales. Por lo tanto es posible cambiar el orden modificando estos archivos.
Por defecto, todos los macros son accesibles utilizando la función de tecleo predictivo (consulte Escribir un método). El atributo type_ahead de la etiqueta <macro> permite excluir un macro de este tipo de operación.
Nota: si el macro contiene la etiqueta <selection/>, no aparecerá en la ventana tecleo predictivo.
Puede mostrar sus macros en una lista del editor de métodos (consulte Escribir un método). Simplemente haga doble clic en el nombre de un macro en la lista para llamarlo. No es posible excluir un macro específico de esta lista.
El soporte de las macro puede cambiar de una versión de 4D a otra. Para mantener la compatibilidad entre las diferentes versiones, preservando sus personalizaciones, 4D no elimina las versiones anteriores. Si desea utilizar las funcionalidades más recientes disponibles, debe efectuar adaptaciones.
En las versiones de 4D anteriores a la v11, el programa mantuvo automáticamente un conjunto de variables proceso para la manipulación de texto en los métodos cuando se utiliza la etiqueta <method>: las variables de entrada (_textSel, _blobSel, _selLen, _textMethod, _blobMethod, _methodLen) para recuperar texto y las variables de salida (_textReplace, _blobReplace, _action) para insertar texto. Por razones de compatibilidad, este mecanismo aún es soportado, pero desde la versión 11 se ha quedado obsoleto por las siguientes razones:
- El uso de variables BLOB para la gestión de textos con un tamaño superior a los 32 000 caracteres ya no es necesario,
- La gestión de variables no es compatible con la arquitectura v11 de los componentes, en la que los espacios de ejecución de las variables se particionan. Un componente de la versión 11 no puede acceder a los textos de los métodos de la base local (y viceversa) utilizando variables predefinidas.
Por lo tanto, se recomienda administrar las selecciones de texto con los comandos GET MACRO PARAMETER y SET MACRO PARAMETER. Estos comandos permiten superar la partición de los espacios de ejecución base local/componentes y permite la creación de componentes dedicados a la gestión de macros. Para activar este modo para una macro, debe declarar el atributo Version con el valor 2 en el elemento Macro. En este caso, 4D ya no genera más las variables predefinidas _textSel , _textReplace, etc. y se utilizan los comandos GET MACRO PARAMETER y SET MACRO PARAMETER. Este atributo se debe declarar así:
<macro name="MyMacro" version="2">
--- Texto de la macro ---
</macro>Si no pasa este atributo, el modo anterior se mantiene.
A partir de 4D v11, deben observarse reglas de sintaxis estrictas para que los archivos de macros respeten el estándar XML. Esto puede dar lugar a incompatibilidades con el código de las macros creadas con versiones anteriores y evitar la carga de archivos XML. Las siguientes son las principales fuentes de fallas del sistema:
- Los comentarios de tipo "// mi comentario", permitidos al interior de elementos <macro> en las versiones anteriores de 4D, no son compatibles con la sintaxis XML. Las líneas de comentarios deben respetar la forma estándar "<!-- mi comentario -->".
- Los símbolos <> empleados particularmente para los nombres de objetos interproceso deben ser codificados. Por ejemplo, la variable <>params debe escribirse <>params.
- La etiqueta de declaración inicial <macros> podía omitirse en las versiones anteriores de 4D. Ahora es obligatoria, de lo contrario, el archivo no se cargará.
En la versión 12 de 4D, hay nuevos macro comandos disponibles para facilitar el uso de los comandos SQL. Como puede personalizar el archivo "Macros.xml", la instalación de una nueva versión de 4D no reemplaza automáticamente la versión existente del archivo. Para usar los nuevos macro comandos SQL de 4D v12, debe:
- borrar el archivo "Macros.xml" en la carpeta "Macros v2" (si no lo ha modificado), luego lanzar 4D para crear el nuevo archivo de forma automática.
- añadir manualmente las nuevas macros en el archivo "Macros.xml" de la carpeta "Macros v2" (si ya ha personalizado el contenido). El nuevo archivo plantilla de macros se encuentra en la carpeta de la aplicación4D 4D\Resources\en.lproj o 4D\Resources\ fr.lproj.
Producto: 4D
Tema: Editar métodos
Manual de Diseño ( 4D v16)
Manual de Diseño ( 4D v16.1)
Manual de Diseño ( 4D v16.3)
