4D Doc Center : Criar e utilizar macros

4D v14.3

Criar e utilizar macros

É possível utilizar os comandos macros em seus métodos, o que lhe economiza muito tempo durante a entrada de métodos.

O que é uma macro?

Um comando macro é uma parte de código 4D acessível permanentemente que pode ser inserida em qualquer parte de seus métodos, sem importar o tipo de banco de dados aberto. Os macros comandos podem conter qualquer tipo de texto, comandos e constantes 4D, assim como etiquetas especiais as quais são substituídas no momento da inserção da macro pelos valores derivados do contexto do método. Por exemplo, um macro comando pode conter a etiqueta <nome_método/>; no momento da inserção do macro, esta etiqueta será substituída pelo nome do método de projeto atual.

Os comandos macros são salvos em um ou mais arquivos em formato XML (texto). Podem ser colocados em uma lista do ; também podem ser chamados com a ajuda do menu contextual ou utilizando a função de autocompletar.

Os comandos macros de 4D são escritos em formato XML. É possível utilizar o arquivo de macro comandos como está ou modificá-lo.

Localização de macros

4D carrega as macros de uma pasta chamada “Macros v2.” As macros devem estar em forma de um ou vários arquivos XML localizados nesta pasta.

A pasta “Macros v2” pode estar localizada:

Na pasta 4D ativa da máquina. As macros depois são compartilhadas por todos os bancos.

Nota A localização da pasta ativa 4D varia em função do sistema operacional. Para maiores informações, consulte a descrição do comando Get 4D folder no Manual de linguagem 4D.

Junto ao arquivo de estrutura do banco. As macros são carregadas somente para esta estrutura.
Para os componentes: na pasta Components do banco. As macros só são carregadas se o componente estiver instalado.

Estas três localizações podem ser utilizadas simultaneamente: é possível instalar uma pasta “Macros v2” em cada localização. As macros serão carregadas na seguinte ordem: pasta 4D, arquivo de estrutura, componente 1... componente X:

Macros padrões

4D oferece um conjunto de macros padrões que correspondem particularmente a lista de palavras chaves nas versões anteriores de 4D. Estas macros são incluídas no arquivo “Macros.xml”, localizado na pasta “Macros v2” craida na pasta 4D ativa da máquina durante a primeira inicialização de 4D.

É possível modificar este arquivo ou o conteúdo da pasta posteriormente (ver o parágrafo a seguir). No caso em que se apresentem problemas com este arquivo, você pode exclui-lo e 4D o criará novamente no próximo lançamento.

Adicionar macros personalizadas

É possível adicionar macros personalizadas ao arquivo “Macros.xml” utilizando um editor de texto padrão ou por programação. Também é possível adicionar arquivos XML de macros personalizadas nesta pasta.

Em modo local, o arquivo de macros pode ser aberto enquanto você utiliza 4D. A lista de comandos macro disponíveis é atualizada em cada evento de ativação 4D.
Por exemplo, é possível trazer o editor de texto ao primeiro plano, modificar o arquivo de macros, logo regressar ao métodos: a nova macro está disponível no editor de métodos.

As macros vazias ou equivocadas não são exibidas.

Verificar a sintaxe de macros personalizadas

Os arquivo de comandos macro de 4D devem cumprir com a norma XML. Isto significa particularmente que as linhas de declaração XML <?xml version="1.0" ...?> e de declaração de documento < !DOCTYPE macros SYSTEM "http://www.4d.com/dtd/v11/macros.dtd"> são obrigatórias ao começo de um arquivo de macro para que seja carregado.

São suportados os diferentes tipos de codificação XML. Entretanto, é recomendável utilizar a codificação compatível Mac/PC (UTF-8). 4D oferece um DTD que pode ser utilizado para validar os arquivos de macros. Este arquivo é encontrado na seguinte localização:

Windows: 4D Developer/Resources/DTD/macros.dtd
Mac OS: 4D Developer.app:Contents:Resources:DTD:macros.dtd

Se um arquivo de macros não contém as linhas de declaração ou não pode ser validado, não é carregado.

Sintaxe das macros 4D

Os comandos macros 4D são construídos com a ajuda de etiquetas personalizadas XML chamadas “elementos”.

Algumas etiquetas indicam o início e o final da definição (etiquetas duplas do tipo <tag> </tag>), outras são substituídas pelos valores do contexto de inserção (<tag/>).

Conforme as especificações XML, algumas etiquetas de elementos podem incluir atributos. Ao menos que você indique o contrário, estes atributos são opcionais e se utiliza um valor padrão quando são omitidos. A sintaxe dos elementos com atributos é a seguinte:

etiquetas duplas: <etiqueta atributo="valor"> </macro>
etiquetas simples: <etiqueta atributo="valor"/>

Se o elemento aceita vários atributos, é possível agrupá-los na mesma linha de comando, separados por um espaço:
<etiqueta atributo1="valor" atributo2="valor" atributo3="valor"... >
Esta é a lista de etiquetas e seu modo de utilização:

Etiquetas de elementos	Descrição
<macros> </macros>	Início e fim do arquivo macro (etiqueta obrigatória).
<macro> </macro>	Início e fim da definição de uma macro e seus atributos.
	Atributos:
	- nome ** da macro tal como aparece nos menus e nas listas do editor de métodos (atributo obrigatório).
	- type_ahead_text: cadeia de caracteres ** a ser introduzida para chamar a macro utilizando a função de digitação preditiva*.
	- in_menu: booleano que indica se a macro pode ser chamada utilizando o menu contextual*. Valores = “true” (padrão) ou “false”.
	- type_ahead: booleano que indica se a macro pode ser chamada utilizando a função de autocompletar*. Valores = “true” (padrão) ou “false”.
	- method_event: utilizado para disparar a chamada automática da macro em função da fase atual de manipulação de cada método (criação, fechamento, etc.). Valores = “on_load”: a macro é disparada ao abrir cada método. “on_save”: a macro é disparada ao salvar cada método, “on_close”: a macro é disparada ao fecha cada método. "on_save" e "on_close" podem ser utilizados em conjunto, em outras palavras, ambos os eventos são gerados caso se feche um método modificado. Por outro lado, “on_create” e “on_load” nunca são gerados de maneira consecutiva. Este atributo pode ser utilizado, por exemplo, para pré-formatar os métodos no momento de sua criação (os comentários na área de cabeçalho) ou gravar a informação tal como a data e hora no momento de fechá-los.
	- version: permite ativar o novo modo de suporte de seleções de texto para a macro (ver “Sobre a etiqueta <method>”). Para ativar este novo modo, entre o valor "2". Se omitir este atributo ou entra versão="1", se conserva o modo anterior.
	- in_toolbar: Booleano que indica se a macro deve ser apresentada no menu do botão Macro da barra de ferramentas. Valores= "true" (por padrão) ou "false".
<selection/>	Etiqueta substituída pelo texto selecionado no momento da chamada à macro. A seleção pode estar vazia
<text> </text>	Início e fim do código que deve ser inserido no método. Um retorno de carro será adicionado antes e depois do código.
<method> </method>	Início e fim do nome do método de projeto e de seu parâmetro (opcional). O método é executado quando a macro é chamada. Pode passar um parâmetro no formato ("param1;param2;..."). Este parâmetro será recebido no método utilizando as variáveis $1, $2, etc.. Para informação adicional sobre esta etiqueta, consulte a seção “Sobre a etiqueta <method>”.
<caret/>	Localização do ponto de inserção no código depois de inserida a macro.
<user_4D/>	Etiqueta substituída pelo nome do usuário 4D atual.
<user_os/>	Etiqueta substituída pelo nome do usuário do sistema atual..
<method_name/>	Etiqueta substituída pelo nome do método de projeto atual.
<method_path/>	Etiqueta substituída pela via de acesso completa do método projeto atual.
<date/>	Etiqueta substituída pela data atual.
	Atributo:
	- format: formato 4D utilizado para mostrar a data. Se não existe um formato definido, o formato padrão é utilizado. Valores = número de formato 4D (0 a 8).
<time/>	Etiqueta substituída pela hora atual.
	Atributo:
	- format: formato 4D utilizado para mostrar a hora. Se não existe um formato definido, é utilizado o formato padrão. Valores = número de formato 4D (0 a 6).
<clipboard/>	Etiqueta substituída pelo conteúdo da área de transferência
	Atributo:
	- index: Área de transferência a ser colada. Valores = número de área de transferência (0 a 9).

*As macros podem ser chamados utilizando o menu contextual do editor de métodos ou utilizando a função de autocompletar (ver o parágrafo a seguir).
** Se você quer manter-se nas especificações da linguagem XML, não deve utilizar caracteres externos (caracteres acentuados, aspas, etc.).

Este é um exemplo de definição de macro:

Conteúdo da macro	Comentários
<?xml version=”1.0”...?>	Declaração XML
<!DOCTYPE macros SYSTEM>	Declaração de documento
<macros>	Início de arquivo XML de macros
<macro name="RecordLoop">	Início da definição e nome da macro
<text>	Início do código da macro
For($i;1;Records in selection(<Selection/>))	A etiqueta <Selection/> será substituída pelo código selecionado no método 4D no momento da inserção da macro (por exemplo, um nome de tabela)
SAVE RECORD(<Selection/>)
NEXT RECORD(<Selection/>)
End for
</text>	Fim do código da macro
</macro>	Fim da definição da macro
</macros>	Fim do arquivo XML de macros

Sobre a etiqueta <method>

A etiqueta <method> permite gerar e utilizar os comandos macros que executam os métodos de projeto de 4D. Este princípio permite aos desenvolvedores criar funções sofisticadas que podem ser distribuídas via os comandos macros associados aos componentes. Por exemplo, a macro a seguir provocará a execução do método MeuMétodo com o nome do método atual como parâmetro:

<method>MeuMetodo("<method_name/>")</method>

O código do método chamado é executado em um novo processo. Este processo é terminado uma vez que o método é executado.

Nota: O processo de estrutura permanece congelado até que se termine a execução do método chamado. Você deve se assegurar que a execução seja rápida e de que não haja risco de bloquear a aplicação. Se isto ocorrer, utilize a combinação Ctrl+F8 (Windows) ou Comando+F8 (Mac OS) para terminar o processo.

Chamar macros

Por padrão, as macros podem ser chamadas utilizando o menu contextual ou a barra de ferramentas do editor de métodos, a função de digitação preditiva, ou uma lista específica ao final da janela do editor de métodos.

Note que é possível restringir para cada macro a possibilidade de chamada utilizando o menu contextual e/ou a função de digitação preditiva.

Menu contextual e barra de ferramentas

Por padrão, todas as macros podem ser chamadas através do menu contextual do editor de métodos (utilizando o comando hierárquico Inserir macro) ou o botão “Macros” da barra de ferramentas.

O atributo in_menu da etiqueta <macro> é utilizado para definir se a macro aparecerá ou não neste menu.

No menu contextual, os macros são exibidos na ordem do arquivo “Macros.xml” e os arquivos XML adicionais. Portanto é possível alterar a ordem modificando estes arquivos.

Autocompletar

Por padrão, todas as macros são acessível utilizando a função de autocompletar (consulte Escrever um método). O atributo type_ahead da etiqueta <macro> permite excluir uma macro deste tipo de operação.

Nota: Se a macro contém a etiqueta <selection/>, não aparecerá na janela de autocompletar.

Lista do editor de métodos

É possível mostrar suas macros em uma lista do editor de métodos (consulte [#title id="3256"/]). Simplesmente faça um duplo clique no nome de uma macro na lista para chamá-la. Não é possível excluir uma macro específica desta lista.

Notas de compatibilidade

O suporte das macro pode mudar de uma versão de 4D para outra. Para manter a compatibilidade entre as diferentes versões, preservando sua personalização, 4D não elimina as versões anteriores. Se deseja usar as funcionalidades mais recentes disponíveis, deve realizar adaptações.

Variáveis de Seleção de texto para métodos

Nas versões de 4D anteriores a v11, o programa mantinha automaticamente um conjunto de variáveis processo para a manipulação de texto nos métodos ao utilizar a etiqueta <method>: as variáveis de entrada (_textSel, _blobSel, _selLen, _textMethod, _blobMethod, _methodLen) para recuperar texto e variáveis de saída (_textReplace, _blobReplace, _action) para inserir texto. Por motivos de compatibilidade, este mecanismo ainda é suportado por 4D, mas desde a versão 11 se tornou obsoleto pelas seguintes razões:

o uso de variáveis BLOB para a gestão de textos de tamanho superior a 32.000 caracteres já não é necessário,
a gestão de variáveis é incompatível com a arquitetura v11 dos componentes na qual os espaços de execução das variáveis são particionados. Um componente versão 11 não pode acessar os textos dos métodos do banco local e vice-versa utilizando as variáveis pré-definidas.

Portanto, é recomendável administras as seleções de texto através dos comandos GET MACRO PARAMETER e SET MACRO PARAMETER. Estes comandos podem ser utilizados para superar a partição dos espaços de execução banco local/componentes e autoriza a criação de componentes dedicados a gestão de macros. Para ativar este novo modo para uma macro, você deve declarar o atributo Version com o valor 2 no elemento Macro. Neste caso, 4D não administra mais as variáveis pré-definidas _textSel, _textReplace, etc. e são utilizados os comandos GET MACRO PARAMETER e SET MACRO PARAMETER. Este atributo deve ser declarado desta forma:

<macro name="MyMacro" version="2">

--- Texto de la macro --- </macro>

Se você não passar este atributo, o modo anterior é conservado.

Incompatibilidades relacionadas com a norma XML

A partir de 4D v11, as normas de sintaxe devem ser seguidas estritamentes para que os arquivos de macros respeitem o padrão XML. Caso contrário, podem ser produzidas incompatibilidades no código das macros criadas com códigos anteriores, evitando a carga dos arquivos XML. A seguir, você encontra as principais fontes de mau funcionamento.

Os comentarios de tipo “//meu comentário”, permitidos nos elementos <macro> nas versões anteriores de 4D, não são compatíveis com a sintaxe XML. As linhas de comentários devem respeitar a forma padrão “<!—meu comentário -->”.
Os símbolos <> utilizados particularmente para os nomes dos objetos interprocesso devem ser codificados. Por exemplo, a variável <> params deve ser escrita como <>params.
A etiqueta de declaração inicial <macros> podia ser omitida nas versões anteriores de 4D. Agora é obrigatória, caso contrário, o arquivo não será carregado.

Atualizar o arquivo Macros.xml

Na versão 12 de 4D, há novos comando de macro disponíveis para facilitar o uso dos comandos SQL. Como pode personalizar o arquivo "Macros.xml", a instalação de uma nova versão de 4D não substitui automaticamente a versão existente do arquivo. para usar os novos comando de macro SQL de 4D v12, é necessário:

apagar o arquivo "Macros.xml" na pasta "Macros v2" (se já não o tiver modificado), depois lançar 4D para criar o novo arquivo de forma automática.
adicionar manualmente as novas macros no arquivo "Macros.xml" da pasta "Macros v2" (se já tiver personalizado o conteúdo). O novo arquivo modelo de macros é encontrado na pasta da aplicação 4D: 4D\Resources\en.lproj ou 4D\Resources\ fr.lproj.