4D Doc Center : Recursos

4D v12.4

Notas de compatibilidade sobre manutenção de recursos (4D v11)

A gestão de recursos foi modificada em 4D a partir da v11. De acordo com as direções especificadas por Apple e implementadas nas versões Mac OS mais recentes, o conceito de recursos no sentido mais estrito (ver a definição mais adiante) agora é obsoleto e se abandonará progressivamente. Foram implementados novos mecanismos para apoiar as necessidades que antes eram atendidas pelos recursos: arquivos XLIFF para a tradução de cadeia de caracteres, arquivos de imagens .png... Na verdade, os arquivos de recursos serão substituídos por arquivos de tipo padrão. 4D acompanha esta evolução e a partir da versão 11, oferece novas ferramentas para a gestão de traduções de bancos de dados, enquanto mantém a compatibilidade com os sistemas existentes.

Compatibilidade

Para manter a compatibilidade e com o fim de permitir a adaptação progressiva às aplicações existentes, os mecanismos de gestão de recursos continuam funcionando em 4D v11, com umas pequenas diferenças:

Quando estão presentes, os arquivos de recursos ainda são compatíveis com 4D e o principio da "cadeia de arquivos de recursos" (abertura sucessiva de vários arquivos de recursos) continua sendo válida. A "cadeia de arquivos de recursos" inclui particularmente os arquivos .rsr ou . 4dr de bancos de dados convertidos (abertos automaticamente) e os arquivos de recursos personalizados abertos utilizando os comandos deste tema.
Entretanto, por razões relacionadas com la evolução da arquitetura interna, já não é possível acessar diretamente aos recursos da aplicação 4D nem a aqueles do sistema, ou seja através dos comandos deste tema ou utilizando referências dinâmicas. Alguns desenvolvedores utilizam os recursos internos de 4D para suas interfaces (por exemplo, os recursos que contém os nomes dos meses ou dos comandos da linguagem). Esta prática agora está proibida. Na maioria dos casos, é possível utilizar outros meios ao invés dos recursos internos de 4D (constantes, comandos da linguagem, etc.). Para limitar o impacto desta modificação em bancos existentes, foi implementado um sistema de substituição, baseado em exteriorizar os recursos que são utilizados com mais freqüência. Entretanto, é recomendado modificar os bancos convertidos e eliminar as chamadas a recursos internos de 4D.
Os bancos de dados criados com 4D a partir da v11 não incluem por padrão os arquivos .RSR (recursos de estrutura) e .4DR (recursos de dados).

Princípios de administração de Novos Recursos

Em 4D v11, a noção de "recursos" agora deve ser compreendida como "arquivos necessários para a tradução da interface das aplicações." A nova arquitetura de recursos está baseada em uma pasta, chamada Resources, que deve estar localizado ao lado do arquivo de estrutura do banco (.4db ou .4dc). A pasta não é criada normalmente; terá que ser criada se seu banco utiliza recursos. Nesta pasta, deve colocar todos os arquivos que são necessários para a tradução ou personalização da interface da aplicação (arquivos de tipo imagem, arquivos de tipo texto, arquivos XLIFF, etc.)

Também pode conter arquivos de recursos de "antiga geração" da banco (arquivos .rsr). Atenção, estes arquivos não são incluídos automaticamente na cadeia de recursos; devem ser abertos utilizando os comandos padrão de gestão de recursos 4D. 4D utiliza mecanismos automáticos quando trabalha com os conteúdos dessa pasta, particularmente para a gestão de arquivos XLIFF (este ponto é coberto no Manual de Desenho). Dois comandos do tema "Recursos" podem ser utilizados para aproveitar esta arquitetura (ver os comandos Get indexed string e STRING LIST TO ARRAY). ).

Gestão de Recursos (princípios tradicionais)

Nota de compatibilidade: os princípios tradicionais de gestão de recursos estão sendo abandonados progressivamente em 4D (ver parágrafo anterior). Para bancos novos, agora é recomendável confiar na arquitetura XLIFF ou utilizar os arquivos padrão.

O que é um recurso?

Um recurso reagrupa dados de todo tipo, estruturados em um formato definido, e guardado em um arquivo separado ou no resource fork ("parte de recursos") de um arquivo Mac OS. Geralmente, os recursos contém cadeia de caracteres, imagens, ícones, etc. Na verdade, pode criar e utilizar seus próprios tipos de recursos e guardar todos os dados que queira neles.

Data Fork, Resource Fork e arquivo Resource

Originalmente, em Macintosh, os dados e os recursos eram guardados no mesmo arquivo, formado por um data fork ("parte de dados") e um resource fork (parte de recursos). O data fork de um arquivo Macintosh é o equivalente a um arquivo Windows ou UNIX. O resource fork de um arquivo Macintosh contém os recursos específicos Mac OS do arquivo e não tem equivalente direto em Windows ou UNIX.

Mesmo esta característica ainda sendo compatível com 4D, agora em Mac OS como também em Windows, os recursos são armazenados em um arquivo separado (de tipo "data fork" em Mac OS). Este principio é administrado de maneira transparente por 4D e permite intercambiar os arquivos entre as diferentes plataformas sem realizar conversões.

Os comandos de gestão de arquivos de recursos (Create resource file e Open resource file) podem trabalhar diretamente em data fork para uma melhor compatibilidade multiplataforma.

Arquivos Resource

Nos bancos de dados criados com uma versão de 4D anterior a v11, 4D criava automaticamente um arquivo .rsr para guardar os recursos do arquivo de estrutura e um arquivo .4dr para os recursos dos arquivos de dados.

A mesma aplicação 4D utiliza recursos, guardados em um arquivo ".RSR". Os Plug-ins 4D como por exemplo 4D Write, podem também utilizar recursos.

Criar seus próprios arquivos de Resource

Além dos arquivos de recursos oferecidos por 4D, pode criar e utilizar seus próprios arquivos de recursos utilizando os comandos 4D Create resource file e Open resource file. Estes dois comandos devolvem um número de referencia do arquivo de recursos que identifica de maneira única o arquivo de recursos aberto. Este número equivale ao número de referência do documento devolvido para arquivos padrão, pelos comandos do tema Documentos do sistema, tal como Open document. Todos os comandos 4D de gestão de recursos esperam um número de referencia do arquivo de recursos (opcional). Quando tiver terminado com um arquivo de recursos, lembre de fechá-lo utilizando o comando CLOSE RESOURCE FILE.

Fila de arquivos de recursos

Quando trabalha com um banco 4D, pode utilizar todos os arquivos de recursos abertos ou um arquivo de recursos específico.

É possível abrir simultaneamente vários arquivos de recursos. Este é sempre o caso quando se utiliza um banco 4D. Os seguintes arquivos estão abertos:

Em Macintosh, o arquivo de recursos do sistema.
Em Windows, o arquivo ASIPORT.RSR (contém parte dos recursos sistema de Macintosh).
O arquivo de recursos da aplicação 4D.
O arquivo de recursos da estrutura da banco (se existir).
O arquivo de recursos de dados da banco (se existir).
Finalmente, você pode abrir seu próprio arquivo de recursos com ajuda do comando Open resource file.

Esta lista de arquivos de recursos abertos se chama a fila de arquivos de recursos. Pode buscar um recurso em particular de duas formas:

Se passa um número de referência do arquivo de recursos a um comando 4D de gestão de recursos, o recurso é procurado apenas nesse arquivo de recursos.
Se não passa um número de referência do arquivo de recursos ao comando 4D, o recurso é procurado em todos os arquivos de recursos abertos, começando pelo arquivo aberto mais recentemente e terminando com o primeiro arquivo aberto. A fila dos arquivos abertos de recursos se revisa em sentido contrario a la abertura, o último arquivo de recursos aberto se revisa de primeiro.

Tipo de Resource

O formato interno de um arquivo de recursos é bastante estruturado. Além dos dados de cada recurso, o arquivo contém um cabeçalho e um mapa que descreve completamente seu conteúdo.

Os recursos estão classificados por tipos. O tipo de um recurso se indica por uma cadeia de 4 caracteres. Os caracteres diacríticos e las maiúsculas/minúsculas são consideradas. Por exemplo, os tipos de recursos “Olá_!”, “olá_!” e “OLÁ_!” são todos diferentes.

Importante: os tipos de recursos com caracteres em minúsculas estão reservados para o sistema operativo. Evite designar seus próprios tipos de recursos com caracteres em minúsculas.

A seguinte é uma lista de alguns dos tipos de recursos mais comumente utilizados:

Um recurso de tipo “STR#” é um recurso que contém uma lista de cadeias Pascal. Este recurso se chama recurso lista de cadeias.
Um recurso de tipo “STR ” (note que o quarto caractere é um espaço) é um recurso que contém uma cadeia Pascal individual. Este recurso se chama recurso cadeia.
Um recurso de tipo “TEXT” é um recurso que contém uma cadeia de texto sem longitude declarada. Este recurso se chama um recurso texto.
Um recurso de tipo “PICT” é um recurso que contém uma imagem QuickDraw Macintosh que pode utilizar e mostrar em Macintosh e Windows com 4D. Este recurso se chama um recurso imagem.
Um recurso de tipo “cicn” é um recurso que contém um ícone de cor Macintosh que pode utilizar e mostrar em Mac OS e Windows com 4D. Este recurso se chama recurso cor ícone. Por exemplo, um recurso “cicn” pode ser associado a um elemento de uma lista hierárquica, utilizando o comando SET LIST ITEM PROPERTIES.

Além dos tipos de recursos padrão, pode criar seus próprios tipos. Por exemplo, pode decidir trabalhar com recursos de tipo “MTYP” (para “Meu Tipo”).

Para obter a lista de tipos de recursos presentes em todos os arquivos de recursos abertos ou em um arquivo de recursos em particular, utilize o comando RESOURCE TYPE LIST. Para obter a lista de recursos de um certo tipo nos arquivos de recursos abertos ou em um arquivo de recurso em particular, utilize o comando RESOURCE LIST Este comando devolve os identificadores e os nomes (ver a próxima seção) de todos os recursos de um tipo dado.

Advertência: muitas aplicações se apóiam no tipo dos recursos para tratar seu conteúdo. Por exemplo, quando acessem a um recurso “STR#”, as aplicações esperam encontrar uma lista de cadeias. NÃO armazene dados inconsistentes em recursos de tipo padrão; isso pode provocar erros do sistema em sua aplicação 4D ou em outras aplicações.

Advertência: um recurso é um arquivo muito estruturado, NÃO deve acessar ao arquivo de recursos com comandos diferentes aos comandos de recursos. Note que nada evitará que você passe um número de referência de arquivo de recursos (em forma de uma expressão 4D de tipo hora como o número de referência do documento) a um comando como SEND PACKET. Entretanto, se o fizer, provavelmente danificará o arquivo de recursos.

Advertência: um arquivo de recursos pode conter cerca de 2.700 recursos individuais. NÃO tente ultrapassar este limite. Leve em consideração que nada evitará que o faça; entretanto, danificará o arquivo de recursos e o tornará inutilizável.

Nome de Recurso e ID de Recurso

Um recurso tem um número de recurso. Um número de recurso pode conter até 255 caracteres, leve em consideração os caracteres diacríticos mas não diferencia entre maiúsculas e minúsculas. Os nomes dos recursos podem ser utilizados para a identificação visual, mas você acessa a um recurso utilizando seu tipo e seu número de identificação. Os nomes dos recursos não são únicos; vários recursos podem ter o mesmo nome.

Todo recurso tem um número de identificação (número de ID ou ID). Este número é único ao interior de um tipo e de um arquivo de recursos. Por exemplo:

Um arquivo de recurso pode conter um recurso “ABCD” ID=1 e um recurso “EFGH” ID=1.
Dois arquivos de recursos podem conter um recurso do mesmo tipo e do mesmo número.

Quando acessa a um recurso através de um comando 4D, indique seu tipo e seu número. Se não especifica o arquivo de recursos no qual procurar o recurso, o comando devolve a ocorrência do recurso encontrado. Lembre que os arquivos de recursos são examinados na ordem inversa da qual foram abertos.

Os números dos recursos estão entre -32.768 e 32.767.

Importante: utilize a faixa entre 15.000 e 32.767 para seus próprios recursos. NÃO utilize números de recursos negativos; estes estão reservados para o sistema operativo. NÃO utilize números entre 0 e 14.999; esta faixa está reservada para 4D.

Para obter os identificadores e os nomes dos recursos de um tipo qualquer, utilize o comando RESOURCE LIST.

Para obter o nome de um recurso individual, utilize o comando Get resource name

Para modificar o nome de um recurso individual, utilize o comando SET RESOURCE NAME.

Como cada comando 4D aceita de maneira opcional um número de referência do arquivo de recursos, pode facilmente tratar recursos que tem o mesmo tipo e número mas que estão em dois arquivos de recursos diferentes. O exemplo a seguir copia todos os recursos “PICT” de um arquivo de recursos a outro:

  ` Abertura de um arquivo de recursos existente

 &NBSP;$vhResArquivoA:=Open resource file("")

 &NBSP;If(OK=1)

 &NBSP; ` Criação de um novo arquivo de recursos

 &NBSP;$vhResArquivoB:=Create resource file("")

 &NBSP;If(OK=1)

 &NBSP; ` Recuperar a lista de números e de nomes de todos os recursos de tipo "PICT"

 &NBSP; ` localizados no arquivo de recursos A

 &NBSP;RESOURCE LIST("PICT";$aiResID;$asResNome;$vhResArquivoA)

 &NBSP; ` Para cada recurso:

 &NBSP;For($vlElem;1;Size of array($aiResID))

 &NBSP;$viResID:=$aiResID{$vlElem}

 &NBSP; ` Carregar o recurso do arquivo A

 &NBSP;GET RESOURCE("PICT";$viResID;vxResData;$vhResArquivoA)

 &NBSP; ` Se puder carregar o recurso

 &NBSP;If(OK=1)

 &NBSP; ` Adicionar e escrever o recurso no arquivo B

 &NBSP;SET RESOURCE("PICT";$viResID;vxResData;$vhResArquivoB)

 &NBSP; ` Se o escrito pode ser adicionado e escrito

 &NBSP;If(OK=1)

 &NBSP; ` Copie também o nome do recurso

 &NBSP;SET RESOURCE NAME("PICT";$viResID;$asResNome{$vlElem};$vhResArquivoB)

 &NBSP; ` Assim como suas propriedades (ver Resource Properties mais adiante) $vlResAttr:=Get resource properties("PICT";$viResID;$vhResArquivoA)

 &NBSP;SET RESOURCE PROPERTIES("PICT";$viResID;$vlResAttr;$vhResArquivoB)

 &NBSP;Else

 &NBSP;ALERT("O recurso PICT ID="+String($viResID)+" não pode ser adicionado.")

 &NBSP;End if

 &NBSP;Else

 &NBSP;ALERT("O recurso PICT ID="+String($viResID)+" não se pode carregar.")

 &NBSP;End if

 &NBSP;End for

 &NBSP;CLOSE RESOURCE FILE($vhResArquivoB)

 &NBSP;End if

 &NBSP;CLOSE RESOURCE FILE($vhResArquivoA)

 &NBSP;End if

Propriedades dos recursos

Além de seu tipo, nome e número, um recurso tem propriedades adicionais (também chamadas atributos). Por exemplo, um recurso pode ser purgável ou não. Este atributo indica ao sistema operativo se o recurso pode ser purgado ou não, uma vez que se carregue em memória, quando seja necessário liberar memória para localizar outro objeto. Como é mostrado no exemplo anterior, durante a criação ou cópia de um recurso, pode ser importante não só copiar o recurso, se não também seu nome e propriedades. Para maior informação sobre as propriedades dos recursos, consulte a descrição dos comandos Get resource properties e SET RESOURCE PROPERTIES

Gerenciamento do conteúdo dos recursos

Para carregar um recurso de qualquer tipo em memória, utilize GET RESOURCE, que devolve o conteúdo do recurso em um BLOB.

Para criar ou reescrever um recurso em disco, chame SET RESOURCE, que utiliza o conteúdo do BLOB que você passa para o conteúdo do recurso.

Para apagar um recurso existente, utilize o comando DELETE RESOURCE.

Para simplificar o manejo dos recursos, 4D dispõe de comandos integrados adicionais para evitar ter que analisar um BLOB para extrair os dados do recurso:

STRING LIST TO ARRAY preenche um array de tipo Alfa ou Texto com as cadeias de caracteres contidas em um recurso lista de cadeias.
ARRAY TO STRING LIST cria ou reescreve um recurso lista de cadeias com os elementos de um array de tipo Alfa ou Texto.
Get indexed string devolve uma cadeia particular de um recurso lista de cadeias.
Get string resource devolve a cadeia de um recurso cadeia.
SET STRING RESOURCE cria ou reescreve um recurso cadeia.
Get text resource devolve o texto de um recurso texto.
SET TEXT RESOURCE cria ou reescreve um recurso texto.
GET PICTURE RESOURCE devolve a imagem de um recurso imagem.
SET PICTURE RESOURCE cria ou reescreve um recurso imagem.
GET ICON RESOURCE devolve um ícone cor como uma imagem.

Note que estes comandos são oferecidos com o fim de simplificar o emprego dos recursos de tipo padrão; entretanto, pode utilizar GET RESOURCE e SET RESOURCE com BLOBs. Por exemplo, a linha de código seguinte:

ALERT(Get text resource(20000))

é o equivalente curto de:

 GET RESOURCE("TEXT";20000;vxData)

 &NBSP;If(OK=1)

 $vlOffset:=0

 &NBSP;ALERT(BLOB to text(vxData;Text without length;$vlOffset;BLOB size(vxData)))

 &NBSP;End if

Os comandos 4D e os recursos

Além dos comandos de recursos descritos neste capítulo, há outros comandos 4D que permitem trabalhar com arquivos de recursos:

Em Macintosh, DOCUMENT TO BLOB e BLOB TO DOCUMENT podem carregar e escrever a totalidade do recurso fork de um arquivo Macintosh.
Utilizando os comandos SET LIST ITEM PROPERTIES e SET LIST PROPERTIES, pode associar os recursos de imagens ou ícones de cor aos elementos de uma lista ou utilizar os recursos ícones cor com nós de uma lista.
O comando PLAY executa os recursos “snd ” em Macintosh e Windows.
O comando SET CURSOR muda a aparência do mouse utilizando recursos “CURS”.