Desenvolver componentes

4D v16.3

Como um componente se apresenta em forma de uma base de dados 4D, o desenvolvimento de um componente é similar ao desenvolvimento de uma funcionalidade de um banco. Existem, no entanto, restrições e regras específicas relacionadas com a natureza dos componentes.

Objetos utilizáveis e não utilizáveis

Um componente pode chamar a maioria dos objetos de 4D: métodos de projeto, formulários de projeto, barras de menus, listas de seleção, imagens da livraria, etc.

Somente os seguintes objetos não podem ser utilizados por um componente:

tabelas e campos, 4D padrão (mas pode criar e usar as tabelas e campos através dos bancos externos),
formulários tabela seus métodos de formulário associados (por outro lado, um componente pode chamar um formulário tabela do banco local),
formularios usuário,
métodos de banco e triggers.

Não é necessário eliminar estes elementos se existem nas bases matrizes. Quando um objeto “não utilizável” está presente, simplesmente se ignora uma vez instalado o componente.

Nota: Os usuários e grupos assim como os possíveis direitos de acesso definidos no banco matriz são ignorados no banco local.

Somente são visíveis os métodos de projeto compartilhados pelo componente e podem ser selecionados em modo Desenho na base local. Por outro lado, os métodos de projeto compartilhados da base local podem ser chamados pelo componente. Para maiores informações, consulte Compartilhar métodos projeto.

Só os formulários "publicados" pelo componente podem ser visíveis e serem integrados nos formulários do banco local como subformulários. Para maior informação, consulte Compartilhar formulários.

Os outros objetos do componente (formulários de projeto, listas de seleção, menus, etc.) podem ser utilizados pelo componente, mas não serão acessíveis como objetos de estrutura desde a base local. Note que certos objetos estão divididos e outros são compartilhados entre a base local e os componentes. Para mais informação, consulte Objetos compartilhados e não compartilhados.

Um componente pode utilizar os plug-ins instalados na aplicação 4D ou na base local. Não é possível instalar plug-ins na pasta do componente.

Os métodos banco e os parâmetros genéricos dos bancos matrizes (pasta Web, Preferências, etc.) nunca são consideradas.

Comandos não utilizáveis

Os seguintes comandos não são compatíveis para serem utilizados dentro de um componente porque modificam o arquivo de estrutura, aberto em modo somente leitura. Sua execução em um componente provoca o erro: -10511, “The CommandName command cannot be called from a component”:

ON EVENT CALL
Method called on event
SET PICTURE TO LIBRARY
REMOVE PICTURE FROM LIBRARY
SAVE LIST
ARRAY TO LIST
EDIT FORM
CREATE USER FORM
DELETE USER FORM
CHANGE PASSWORD
EDIT ACCESS
Set group properties
Set user properties
DELETE USER
CHANGE LICENSES
BLOB TO USERS
SET PLUGIN ACCESS

Notas:

O comando Current form table devolve Nil quando se chama no contexto de um formulário de projeto. Portanto, não pode ser utilizado em um componente.
Os comandos SQL de definição de dados (CREATE TABLE, DROP TABLE, etc.)

Gerenciar erros

Um método de gerenciamento de erro instalado pelo comando ON ERR CALL apenas apolica para o banco de dados sendo executado. No caso de um erro gerado por um componente, o método de gerenciamento de erros ON ERR CALL do banco de dados host não é chamado, e vice versa.

Uso de formulários

Somente os “formulários projeto” (formulários não associados a uma tabela específica) podem ser utilizados em um componente. Todos os formulários de projeto presentes na base matriz podem ser utilizados pelo componente.

Um componente pode chamar aos formulários tabela da base local. Note que neste caso é necessário utilizar ponteiros no lugar de nomes de tabela entre colchetes [] para especificar os formulários no código do componente.
Nota: Se um componente utiliza o comando ADD RECORD, o formulário de entrada atual da base local se mostrará, no contexto da base local. Portanto, se o formulário inclui variáveis, o componente não terá acesso a ele (ver Interação entre componentes e bancos de dados locais).

Pode publicar formulários de componentes como subformulários nos bancos locais. Isso significa que pode, particularmente, desenvolver componentes oferecendo objetos gráficos. Por exemplo, os Widgets oferecidos por 4D estão baseados no uso de subformulários em componentes. Isso é descrito em Compartilhar formulários.

Uso de tabelas e campos

Um componente não pode usar as tabelas e os campos definidos na estrutura 4D do banco matriz. Entretanto, pode criar e usar os bancos externos e usar as tabelas e os campos em função de suas necessidades. Os bancos externos são criados e administrados através da linguagem SQL. Um banco externo é um banco 4D independente do banco 4D principal, mas manipulada desde o banco 4D principal. Usar um banco externo significa designar temporáriamente este banco como banco atual, em outras palavras, como o banco objetivo de petições SQL executadas por 4D. Pode criar bancos externos usando o comando SQL CREATE DATABASE.

Para maior informação sobre os bancos externos, consulte Sobre as bases externas.

Exemplo

O seguinte código é incluído em um componente e realiza três ações básicas com um banco de dados externo:

Cria o banco de dados externo se não existe,
Agrega dados no banco de dados externo,
Leitura de dados desde o banco de dados externo.

Criação do banco de dados externo:

 <>MyDatabase:=Get 4D folder+"\MyDB" // (Windows) guarda los dados em um diretório autorizado

 Begin SQL

        CREATE DATABASE IF NOT EXISTS DATAFILE :[<>MinhaBase];

        USE DATABASE DATAFILE :[<>MinhaBase];

        CREATE TABLE IF NOT EXISTS KEEPIT

        (

        ID INT32 PRIMARY KEY,

        kind VARCHAR,

        name VARCHAR,

        code TEXT,

        sort_order INT32

        );

 

        CREATE UNIQUE INDEX id_index ON KEEPIT (ID);

 

        USE DATABASE SQL_INTERNAL;

 

 End SQL

Escritura no banco de dados externo:

 $Ptr_1:=$2 // recuperação dos dados da base local por meio de ponteiros

 $Ptr_2:=$3

 $Ptr_3:=$4

 $Ptr_4:=$5

 $Ptr_5:=$6

 Begin SQL

 

        USE DATABASE DATAFILE :[<>MinhaBase];

 

        INSERT INTO KEEPIT

        (ID, kind, name, code, sort_order)

        VALUES

        (:[$Ptr_1], :[$Ptr_2], :[$Ptr_3], :[$Ptr_4], :[$Ptr_5]);

 

        USE DATABASE SQL_INTERNAL;

 

 End SQL

Leitura desde uma base externa:

 $Ptr_1:=$2 // acesso aos dados da base local por meio de ponteiros

 $Ptr_2:=$3

 $Ptr_3:=$4

 $Ptr_4:=$5

 $Ptr_5:=$6

 

 Begin SQL

 

    USE DATABASE DATAFILE :[<>MinhaBase];

 

    SELECT ALL ID, kind, name, code, sort_order

    FROM KEEPIT

    INTO :$Ptr_1, :$Ptr_2, :$Ptr_3, :$Ptr_4, :$Ptr_5;

 

    USE DATABASE SQL_INTERNAL;

 

 End SQL

Uso de recursos

Os componentes podem utilizar recursos (antigos recursos Mac OS “clássicos” ou arquivos de tipo XLIFF).

Conforme os princípios de gestão de recursos (ver Arquitetura do Banco de Dados), os arquivos de recursos dos componentes devem estar localizados em uma pasta Resources, localizada junto ao arquivo .4db ou .4dc do componente. Se o componente é de arquitetura .4dbase (arquitetura recomendada), a pasta Resources deve estar localizada dentro desta pasta.

Os mecanismos automáticos são operacionais: os arquivos XLIFF presentes na pasta Resources de um componente serão carregados por este componente. Um componente também utilizará automaticamente os recursos Mac OS “clássicos” localizados no arquivo .rsr junto ao arquivo .4db ou .4dc. Os arquivos de recursos “clássicos” localizados na pasta Resources devem carregar-se explicitamente no componente utilizando os comandos do tema “Recursos”.

Em um banco local contém um ou mais componentes, cada componente assim como os bancos locais têm sua própria “cadeia de recursos.” Os recursos são divididos entre os diferentes bancos: não é possível acessar aos recursos do componente A desde o componente B ou ao banco local (ver Objetos compartilhados e não compartilhados).

Ajuda on-line para componentes

Um mecanismo específico foi implementado para permitir aos desenvolvedores adicionar ajudas on-line a seus componentes. O princípio é o mesmo proposto para as bancos de dados 4D (ver Apêndice A: Designar um arquivo de ajuda personalizado):

a ajuda do componente deve ser oferecida como arquivo .htm, .html ou (apenas no Windows) .chm,
o arquivo de ajuda deve estar localizado junto ao arquivo de estrutura do componente e ter o mesmo nome que o arquivo de estrutura,
este arquivo se carrega automaticamente no menu Ajuda da aplicação com a etiqueta “Ajuda para...” seguido pelo nome do arquivo de ajuda.