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)

O código de macros suporta [funções de classe] (Concepts/classes.md) e [propriedades de objeto de formulário em JSON] (FormObjects/properties_Reference.md) para permitir que você defina qualquer recurso personalizado no editor de formulários.

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. Em um arquivo formMacros.json na pasta Sources do seu projeto, você escreve:
{
"macros": {
"Add Hello World button": {
"class": "AddButton"
}
}
}
  1. Crie uma classe 4D chamada AddButton.

  2. Na classe AddButton, escreva a seguinte função:

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

var $btnHello : Object

// Criar um botão "Hello"
$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)

// Adicionar botão na página atual
$editor.editor.currentPage.objects.btnHello:=$btnHello

// Selecionar o novo botão no editor de formulários
$editor.editor.currentSelection.clear() //desmarcar elementos
$editor.editor.currentSelection.push("btnHello")

// Notificar a modificação no editor de formulários 4D
$result:=New object("currentSelection"; $editor.editor.currentSelection;\
"currentPage"; $editor.editor.currentPage)

Em seguida, você pode chamar a 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:

Esse menu é construído com base no formMacros.json [arquivo(s) de definição de macro] (#localização-de-macros). 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. O objeto selecionado é passado para $editor.currentSelection ou $editor.target na função onInvoke do macro.

Uma única macro pode executar várias operações. Se selecionado, o recurso Desfazer do editor de Formulário pode ser usado para reverter as operações macro globalmente.

Localização do ficheiro macro

Todas as macros do 4D Form Editor são definidas em um único arquivo JSON por projeto ou componente: FormMacros.json.

Esse arquivo deve estar localizado na pasta Project > Sources do host ou do componente:

Declaração de macros

A estrutura do arquivo formMacros.json é a seguinte:

{
"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

As propriedades personalizadas, quando usadas, são passadas para a função constructor da 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 você deseja instanciar em seu projeto ou componente deve ser declarada como uma [classe 4D] (Concepts/classes.md).

O nome da classe deve corresponder ao nome definido usando o atributo class do arquivo formMacros.json.

As macros são instanciadas no arranque da aplicação. Consequentemente, se você modificar a estrutura da classe de macro (adicionar uma função, modificar um parâmetro...) ou o constructor, você terá que reiniciar o aplicativo para aplicar as alterações.

Funções macro

Toda classe de macro pode conter um construtor Class e duas funções: onInvoke() e onError().

Class constructor

Class constructor($macro : Object)

ParâmetroTipoDescrição
$macroObjectObjeto declaração de macro (no arquivo formMacros.json)

As macros são instanciadas usando uma função [construtor de classe] (Concepts/classes.md#class-constructor), se ela existir.

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

As propriedades personalizadas adicionadas à [declaração de macro] (#declaring-macros) são retornadas no parâmetro da função do construtor da classe.

Exemplo

No arquivo 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)

A função onInvoke é executada automaticamente sempre que a macro for chamada.

Quando a função for chamada, ela recebe na propriedade $editor.editor uma cópia de todos os elementos do formulário com seus valores atuais. Pode então executar qualquer operação sobre estas propriedades.

Depois que as operações forem concluídas, se a macro resultar na modificação, adição ou remoção de objetos, você poderá passar as propriedades editadas resultantes em $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.

Aqui estão as propriedades retornadas no 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

Aqui estão as propriedades que você pode passar no objeto $result se quiser que o processador de macro execute uma modificação. 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

Ao lidar com o atributo 'método' de objetos de formulário, você pode definir o valor do atributo de duas maneiras nas macros:

  • Usando uma [string contendo o nome/caminho do arquivo do método] (FormObjects/properties_Action.md#method).

  • Utilizar um objeto com a seguinte estrutura:

PropriedadeTipoDescrição
sourceStringCódigo do método

O 4D criará um arquivo usando o nome do objeto na pasta "objectMethods" com o conteúdo do atributo source. Esta funcionalidade só está disponível para o código macro.

Propiedad $4dId en currentPage.objects

A propriedade $4dId define um ID exclusivo para cada objeto na página atual. Essa chave é usada pelo processador de macro para controlar as alterações em $result.currentPage:

  • Se a chave $4dId estiver ausente no formulário e em um objeto em $result, o objeto será criado.
  • Se a chave $4dId existir no formulário, mas estiver ausente em $result, o objeto será excluído.
  • Se a chave $4dId existir tanto no formulário quanto em um objeto em $result, o objeto será modificado.

Exemplo

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

Função onInvoke($editor : Objeto)->$result : Objeto
├var $name : Texto

(ESIf ($editor.editor.currentSeletion. ength>0)&
├// Ajuste um golpe em vermelho e estilo em itálico para cada objeto selecionado
├Para cada ($name; $editor. ditor.currentSeletion)
├ $editor.editor.currentPage.objects[$name]. troke:="red"
├ $editor.editor.currentPage.objects[$name].fontStyle:="italic"

「End para cada

ct, Else
├ALERT("Por favor, selecione um objeto de formulário. )
schar@@0o final se

char@@1 Notificar para 4D a modificação
$result:=Novo objeto("currentPage"; $editor.editor.currentPage)

onError()

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

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

A função onError é executada quando o processador de macros encontra um erro.

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)