Categories: Symbian C++ (Português) | Exemplos de código Symbian C++ | Lang-PT

This page was last modified 21:47, 26 October 2007.

From Forum Nokia Wiki

Tradução do original Using Resource files in symbian.

Definição

Um arquivo de recursos é um arquivo texto com extensão .rss, usado para especificar elementos de interface da aplicação, fora do código fonte C++. Arquivos de recurso são usados para se especificar o layout de componentes da interface, como menus, caixas de diálogo e listas, assim como qualquer tipo de texto visível utilizado pela aplicação. Todas as aplicações S60 possuem pelo menos um arquivo de recurso associado a elas.

Um arquivo de recursos é compilado para um arquivo binário e durante o processo um arquivo de cabeçalho (.rsg) é também gerado. O arquivo binário é aberto pela aplicação no início de sua execução e cada componente é carregado conforme for necessário.

A vantagem dessa abordagem é que a aparência da aplicação pode ser alterada externamente sem ter que recompilar novamente toda a aplicação. Dessa forma, o processo de localização (tradução para outros idiomas) torna-se mais simples, já que nesse caso apenas os arquivos de recursos precisam ser modificados e recompilados.

Sintaxe do arquivo de recursos

A sintaxe dos arquivos de recursos é similar à da linguagem C++. O pré-processador é utilizado no início da compilação dos arquivos de recursos, por isso diretivas como #include, #define, #if, #else e #endif, bem como comentários no estilo C e C++ podem ser usados. Todos o espaço em branco dentro do arquivo é ignorado, a não ser que faça parte de alguma string. As linhas seguintes exemplificam o uso de algumas diretivas do pré-processador:

/**
*
* @brief Exemplo de arquivo  de recursos
*
* @copyright ABC Software Ltd 
* @version 1.0
*/
 
 
//  IDENTIFICADOR DE RECURSOS
NAME   RSF1 // id de 4 letras
 
//  INCLUDES
 
#include <avkon.rh>
#include <avkon.rsg>
#include <eikon.rh>
#include <eikon.rsg>
 
...

Arquivos de recursos também podem conter definições de tipos enumerados. Isso significa que um arquivo de cabeçalho (.h) contendo apenas definições de tipos enumerados pode ser compartilhado entre arquivos de recursos e arquivos de código C++. Essa abordagem é utilizada normalmente.

Estrutura do arquivo de recursos

Esta subseção descreve a estrutura dos arquivos de recurso da Series60. Essa estrutrutura pode ser dividida, em termos gerais, em duas partes:

• Um cabeçalho contendo diretivas de inclusão e outras informações padrões sobre o arquivo de recursos que devem ser usadas pelo compilador de recursos e pelo framework de aplicação;

• O corpo, que define alguns recursos. Cada declaração de recurso inicia-se com a palavra reservada RESOURCE.

A seguir, essas seções são descritas com maiores detalhes.

Cabeçalho

O cabeçalho de um arquivo de recursos contém os seguintes elementos:

• Nome - Definido através da diretiva NAME, que deve ser a primeira linha do arquivo de recursos (que não seja comentário nem espaços). Essa diretiva especifica um código de quatro letras que é usado para se diferenciar arquivos de recursos para o caso de uma aplicação usar mais de um. Dessa forma, o nome precisa ser único na aplicação, não precisando ser globalmente único. Uma outra coisa a se considerar é que o nome deve ser diferente de nomes utilizados no sistema, que estão disponíveis para todas as aplicações;

• Diretivas de inclusão - Assim como no C e C++, a diretiva #include serve para se importar outros arquivos, permitindo que o arquivo de recursos utilize símbolos definidos em outros lugares;

• Assinatura - A assinatura, definida por RSS_SIGNATURE, é requerida pelo framework de aplicações, e caso esta não esteja presente pode ocorrer um erro do tipo "panic" no momento que a aplicação é carregada para ser executada. Entretanto, o conteúdo da assinatura é ignorado na prática. Dessa forma, deve-se deixar seu conteúdo vazio, como no exemplo desta subseção;

• Nome do documento - Este é um campo TBUF que especifica o nome do documento padrão da aplicação. No caso de a aplicação não utilizar documentos, esse valor é irrelevante, mas mesmo assim é preciso incluí-lo no recurso. Caso o nome não esteja presente, o framework irá gerar um "panic" no momento de carregar a aplicação. Não é necessário especificar uma extensão para o documento, já que os documentos nativos da S60 não usam extensões.

• Recurso de informação da aplicação - O recurso EIK_APP_INFO especifica vários controles padrões para a aplicação, como o painel de status. É comum criar um recurso que define o painel de status e, então, referir-se a ele no campo status_pane do recurso EIK_APP_INFO.

Exemplo:

/**
*
* @brief Arquivo de recursos 
*
* Copyright (c) EMCC Software Ltd
* @version 1.0
*/
 
//  IDENTIFICADOR DE RECURSOS
NAME   CONT // id de 4 letras
 
//  INCLUDES
#include <avkon.rh>
#include <avkon.rsg>
#include <eikon.rh>
#include <eikon.rsg>
#include "Controls.hrh"
#include "Controls.loc"
 
// DEFINIÇÕES DE RECURSOS
RESOURCE RSS_SIGNATURE { }
 
RESOURCE TBUF { buf = "Controls" } // Nome padrão do documento
 
RESOURCE EIK_APP_INFO
{
 status_pane = r_controls_status_pane;
}

Corpo

Body part

O corpo do arquivo de recursos define os recursos que a aplicação usará. Cada recurso é declarado utilizando-se a palavra reservada RESOURCE, como a seguir:

RESOURCE STRUCTNAME resource-name
{
  resource-initializer-list
}

Você deve substituir STRUCTNAME pelo tipo de recurso que deseja usar. Tipicamente, esses são definidos em arquivos .rh, que devem ser incluídos nos arquivos .rss. Os tipos de recursos definidos pelo sistema encontram-se em avkon.rh, uikon.rh e eikon.rh.

Para recursos que são batizados com nomes, deve-se substituir resource-name pelo nome único do recurso. O nome escolhido para o recurso deve ser definido utilizando-se apenas caracteres minúsculos. Por convenção, os nomes iniciam-se por r_. Por exemplo, para definir uma buffer chamado r_buffer_1:

RESOURCE TBUF r_buffer_1
{
   buf = "text here";
}

Quando o arquivo de recursos for compilado, uma constante será criada para representar o recurso, sendo armazenada no arquivo .rsg (gerado pelo compilador de recursos). O nome gerado pelo compilador é o mesmo nome do recurso, só que em caixa-alta (maiúsculas). Dessa forma, o compilador irá criar a constante R_BUFFER_1 para representar o recurso definido anteriormente.

O arquivo .rsg é armazenado no diretório \epoc\include, e possui o mesmo nome base do arquivo .app da aplicação. Esse arquivo .rsg é incluído globalmente na aplicação, de modo que seja possível acessar os recursos. Os valores definidos nesse arquivo são chamados de IDs de recursos.

O campo resource-initializer-list define um conjunto de valores iniciais para os itens do recurso. Cada inicializador dessa lista deve terminar com um ponto-e-vírgula.

Recursos de texto (strings)

Recursos de texto podem ser incluídos no arquivo de recursos como TBUFs. Todo texto que é visível ao usuário, e dependente de idioma, deve ser especificado em arquivos de recursos, e não diretamente no código fonte. Isso tudo para facilitar a tradução da aplicação para outros idiomas.

Usualmente, strings são definidas em um arquivo .loc, ou um arquivo .lxx que é específico para um idioma. Esse procedimento torna o processo tradução ainda mais simples, porque os tradutores precisam mexer apenas nos arquivos que contêm o texto (e não em todo o arquivo .rss).

A abordagem de usar arquivos .lxx permite que diversos desses arquivos sejam usados para definir o mesmo texto em várias línguas. O xx deve ser substituído por um código de idioma de dois dígitos, definido em e32std.h (TLanguage enumeration). Os arquivos .lxx são então incluídos pelo arquivo .loc, dependendo o idioma atual que estiver selecionado no arquivo .mmp do projeto. Exemplos dessa abordagem são mostrados abaixo:

Inicialmente, o arquivo .rss inclui o arquivo .loc.

#include "MyApp.loc"
RESOURCE TBUF r_hello
{
 
 buf = STR_HELLO; // nota: nenhum literal string no arquivo .rss!
 
}

O arquivo .loc, por sua vez, inclui múltiplos arquivos .lxx, dependendo da configuração atual:

#ifdef LANGUAGE_01     // 01 = Inglês (Inglaterra)
 
 #include "MyApp.l01"
 
#endif
 
#ifdef LANGUAGE_02     // 02 = Francês
 
#include "MyApp.l02"
 
#endif

Pontuação

Use as seguintes regras para decidir sobre a pontuação:

• Ponto-e-vírgula é necessário após uma atribuição;
• Elementos em uma lista são separados por vírgulas;
• Não deve existir ponto-e-vírgula após uma definição de recursos, ou depois do último elemento de uma lista.

Por exemplo:

RESOURCE AVKON_VIEW r_myapp_view
{
 
 menubar = r_myapp_menubar; // atribuição: precisa de ;
 cba     = r_myapp_cba;     // atribuição: precisa de ;
 
}                           // fim da definição de recursos:
                            // não é necessário colocar ;
 
...
 
 
RESOURCE TAB_GROUP r_myapp_tabgroup
{
 tab_width = EAknTabWidthWithTwoTabs;
 
 active = 0;
 
 tabs = {             // início de uma lista
 
          TAB         // primeira estrutura TAB da lista
 
            {
 
                id  = ENavigationPaneTab1;
                txt = TAB1_TEXT;
 
            },        // vírgula entre elementos da lista
 
          TAB         // segunda estrutura TAB da lista
 
            {
 
               id = ENavigationPaneTab2;
               txt = TAB2_TEXT;
 
            }         // fim da lista: não precisa de ;
 
        };            // fim da atribuição a "tabs": precisa de ;
 
 
 
 }        // fim da definição do recurso
          // não precisa de ;

Especificando uma estrutura de recursos

Enquanto a diretiva RESOURCE cria uma instância de um recurso, a diretiva STRUCT define o tipo do recurso, de maneira análoga à uma classe C++. Isso permite que se criem recursos personalizados. Todos as declarações de recursos devem estar em um arquivo .rh.

A diretiva STRUCT é composta por um nome para o tipo e uma lista de atributos (campos) desse tipo:

STRUCT MYCONTROL
{
 
  BUF buf;          // string que não precisa terminar em zero
  LONG value = 0;   // inteiro 32-bit com valor padrão igual a zero
 
}

É importante observar que o nome do tipo deve estar em caixa-alva, sem espaços, e iniciar com uma letra. Caracteres subseqüentes podem ser letras, números ou underscores. O nome também não pode ser iniciado com palavras como GLOBAL, STRUCT, LEN, RESOURCE ou qualquer nome dos tipos básicos que podem ser inseridos nas estruturas.

Cada campo da estrutura é definido pelo tipo, seguido do nome do campo. Opcionalmente, é possível especificar um valor padrão para o campo. Se esse valor existir, então esse campo pode ser omitido na definição RESOURCE que use uma estrutura desse tipo. Nesse caso, o valor padrão será usado.