Saltar para o conteúdo principal
Versão: 20 R6 BETA

Macros do editor de formulários

O editor de formulários 4D suporta macros. A macro is a set of instructions to perform an action or a sequence of actions. When called upon, the macro will execute its instructions and automatically perform the action(s).

For example if you have a recurring report with specific formatting (e.g., certain text must appear in red and certain text must appear in green), you can create a macro to automatically set the color. É possível criar macros para o editor de 4D Form que podem:

  • Criar e executar código 4D
  • Exibir diálogos
  • Seleccionar objectos do formulário
  • Adicionar / excluir / modificar formulários, objetos de formulário e suas propriedades
  • Modificar ficheiros de projeto (atualizar, apagar)

El código de las macros soporta funciones de clase y las propiedades de objeto de formulario en JSON para permitir definir toda funcionalidad personalizada en el editor de formularios.

Macros can been defined for the host project or for components within the project. Usually, you will create a macro and install it within the components you use for development.

Quando chamada, uma macro substitui qualquer comportamento especificado anteriormente.

Exemplo prático

In this short example, you'll see how to create and call a macro that adds a "Hello World!" alert button in the top left corner of your form.

  1. En un archivo formMacros.json dentro de la carpeta Sources de su proyecto, escriba:
{
"macros": {
"Add Hello World button": {
"class": "AddButton"
}
}
}
  1. Cree una clase 4D llamada AddButton.

  2. En la clase AddButton, escriba la siguiente función:

Function onInvoke($editor : Object)->$result : Object

var $btnHello : Object

// Create a "Hello" button
$btnHello:=New object("type"; "button"; \
"text"; "Hello World!"; \
"method"; New object("source"; "ALERT(\"Hello World!\")"); \
"events"; New collection("onClick"); \
"width"; 120; \
"height"; 20; \
"top"; 0; \
"left"; 0)

// Add button in the current page
$editor.editor.currentPage.objects.btnHello:=$btnHello

// Select the new button in the form editor
$editor.editor.currentSelection.clear() //unselect elements
$editor.editor.currentSelection.push("btnHello")

// Notify the modification to the 4D Form editor
$result:=New object("currentSelection"; $editor.editor.currentSelection;\
"currentPage"; $editor.editor.currentPage)

You can then call the macro:

Chamar macros no editor de formulários

When macros are defined in your 4D project, you can call a macro using the contextual menu of the Form editor:

Este menú se crea sobre el archivo de definición de macros formMacros.json. Os itens de macro estão ordenados por ordem alfabética.

Este menu pode ser chamado numa área vazia ou numa seleção no formulário. Selected object are passed to $editor.currentSelection or $editor.target in the onInvoke function of the macro.

Uma única macro pode executar várias operações. Si se selecciona, la función Deshacer del editor de formularios puede utilizarse para revertir las operaciones de las macros de forma global.

Localização do ficheiro macro

Todas las macros del editor de formularios 4D se definen en un único archivo JSON por proyecto o componente: FormMacros.json.

Este archivo debe estar ubicado en la carpeta Project > Sources local o del componente:

Declaração de macros

La estructura del archivo formMacros.json es la siguiente:

{
"macros": {
<macroName>: {
"class": <className>,
<customProperty> : <value>
}
}
}

Eis a descrição do conteúdo do ficheiro JSON:

AtributoTipoDescrição
macrosobjectlista de macros definidas
<macroName>objectdefinição macro
"class"stringnome da classe macro
<customProperty>any(opcional) valor personalizado a obter no construtor

Las propiedades personalizadas, cuando se utilizan, se pasan a la función constructor de la macro.

Exemplo

{
"macros": {
"Open Macros file": {
"class": "OpenMacro"
},
"Align to Right on Target Object": {
"class": "AlignOnTarget",
"myParam": "right"
},
"Align to Left on Target Object": {
"class": "AlignOnTarget",
"myParam": "left"
}
}
}

Instanciando macros em 4D

Cada macro que quiera instanciar en su proyecto o componente debe ser declarada como una clase 4D.

El nombre de la clase debe coincidir con el nombre definido mediante el atributo class del archivo formMacros.json.

As macros são instanciadas no arranque da aplicação. Consequently, if you modify the macro class structure (add a function, modify a parameter...) or the constructor, you will have to restart the application to apply the changes.

Funções macro

Cada clase de macro puede contener un Class constructor y dos funciones: onInvoke() y onError().

Class constructor

Class constructor($macro : Object)

ParâmetroTipoDescrição
$macroObjectObjeto de declaración de macros (en el archivo formMacros.json)

Las macros se instancian utilizando una función class constructor, si existe.

The class constructor is called once during class instantiation, which occurs at application startup.

Las propiedades personalizadas añadidas a la declaración macro se devuelven en el parámetro de la función class contructor.

Exemplo

En el archivo formMacros.json:

{
"macros": {
"Align to Left on Target Object": {
"class": "AlignOnTarget",
"myParam": "left"
}
}
}

Você pode escrever:

// Class "AlignOnTarget" Class constructor($macro : Object)
This.myParameter:=$macro.myParam //left
...

onInvoke()

onInvoke($editor : Object) -> $result : Object

ParâmetroTipoDescrição
$editorObjectObjeto Form Editor Macro Proxy que contém as propriedades do formulário
$resultObjectObjeto Form Editor Macro Proxy que devolve as propriedades modificadas pela macro (opcional)

La función onInvoke se ejecuta automáticamente cada vez que se llama a la macro.

Cuando la función es llamada, recibe en la propiedad $editor.editor una copia de todos los elementos del formulario con sus valores actuales. Pode então executar qualquer operação sobre estas propriedades.

Una vez completadas las operaciones, si la macro resulta en la modificación, adición o eliminación de objetos, puede pasar las propiedades editadas resultantes en $result. The macro processor will parse the returned properties and apply necessary operations in the form. Obviously, the less properties you return, the less time processing will require.

Estas son las propiedades devueltas en el parámetro $editor:

PropriedadeTipoDescrição
$editor.editor.formObjectO formulário completo
$editor.editor.fileFileObjeto File do ficheiro do formulário
$editor.editor.nameStringNome do formulário
$editor.editor.tablenumberNúmero da tabela do formulário, 0 para formulário projecto
$editor.editor.currentPageNumbernumberO número da página actual
$editor.editor.currentPageObjectThe current page, containing all the form objects and the entry order of the page
$editor.editor.currentSelectionCollectionColecção de nomes de objectos seleccionados
$editor.editor.formPropertiesObjectPropriedades do formulário atual
$editor.editor.targetstringNome do objeto sob o rato quando clicado numa macro

Estas son las propiedades que puede pasar en el objeto $result si quiere que el macro procesador ejecute una modificación. Todas as propriedades são opcionais:

PropriedadeTipoDescrição
currentPageObjectcurrentPage incluindo os objectos modificados pela macro, se existirem
currentSelectionCollectioncurrentSelection se modificada pela macro
formPropertiesObjectformProperties se modificada pela macro
editor.groupsObjectinformação do grupo, se os grupos forem modificados pela macro
editor.viewsObjectview info, se as vistas forem modificadas pela macro
editor.activeViewStringNome da vista activa

Por exemplo, se objectos da página actual e grupos tiverem sido modificados, pode escrever:

	$result:=New object("currentPage"; $editor.editor.currentPage ; \ 
"editor"; New object("groups"; $editor.editor.form.editor.groups))

atributo method

Cuando se maneja el atributo method de los objetos de formulario, se puede definir el valor del atributo de dos maneras en las macros:

PropriedadeTipoDescrição
sourceStringCódigo do método

4D creará un archivo con el nombre del objeto en la carpeta "objectMethods" con el contenido del atributo source. Esta funcionalidade só está disponível para o código macro.

Propiedad $4dId en currentPage.objects

La propiedad $4dId define un ID único para cada objeto de la página actual. Esta clave es utilizada por el procesador de macros para controlar los cambios en $result.currentPage:

  • si la llave $4dId falta tanto en el formulario y en un objeto en $result, el objeto se crea.
  • si la llave $4dId existe en el formulario pero falta en $result, el objeto se elimina.
  • si la llave $4dId existe tanto en el formulario y en un objeto en $result, el objeto se modifica.

Exemplo

You want to define a macro function that will apply the red color and italic font style to any selected object(s).

Function onInvoke($editor : Object)->$result : Object
var $name : Text

If ($editor.editor.currentSelection.length>0)
// Set stroke to red and style to italic for each selected object
For each ($name; $editor.editor.currentSelection)
$editor.editor.currentPage.objects[$name].stroke:="red"
$editor.editor.currentPage.objects[$name].fontStyle:="italic"

End for each

Else
ALERT("Please select a form object.")
End if

// Notify to 4D the modification
$result:=New object("currentPage"; $editor.editor.currentPage)

onError()

onError($editor : Object; $resultMacro : Object ; $error : Collection)

ParâmetroTipoDescrição
$editorObjectObjeto enviado a onInvoke
$resultMacroObjectObjeto devuelto por onInvoke
$errorCollectionPilha de erros
[].errCodeNumberCódigo de erro
[].messageTextDescrição do erro
[].componentSignatureTextAssinatura da componente interna

La función onError se ejecuta cuando el procesador de macros encuentra un error.

When executing a macro, if 4D encounters an error which prevents the macro from being cancelled, it does not execute the macro. É o caso, por exemplo, se a execução de uma macro resultar em:

  • eliminar ou modificar um script cujo ficheiro é só de leitura.
  • criar dois objectos com o mesmo ID interno.

Exemplo

Em uma definição de classe macro, você pode escrever o seguinte código de erro genérico:

Function onError($editor : Object; $resultMacro : Object; $error : Collection)
var $obj : Object
var $txt : Text
$txt:=""

For each ($obj; $error)
$txt:=$txt+$obj.message+" \n"
End for each

ALERT($txt)