# Integrando software preexistente ao GNOME

## Prefácio

O GNOME é um projeto para construir, apenas com software livre, um ambiente completo e uma plataforma de desenvolvimento de software. Várias empresas, governos, escolas, instituições e indivíduos implantaram o GNOME em seus sistemas. Se você for um fornecedor independente de software (ISV — Independent Software Vendor) ou um desenvolvedor independente de software (ISD — Independent Software Developer), você pode querer garantir que seu software seja executado adequadamente sob o GNOME. Esse guia explica como integrar software preexistente com o GNOME, sem ter que reescrever o software para usar as ferramentas de desenvolvimento ou as bibliotecas da plataforma do GNOME.

Esse guia será útil nas seguintes situações:

- Você é um desenvolvedor ou distribuidor de software e tem um aplicativo que não foi criado para ser usado no especificamente GNOME, mas você quer garantir que o aplicativo seja executado confortavelmente dentro do ambiente GNOME.

- Você é um administrador de sistemas de uma instituição que implantou o ambiente GNOME para os usuários. Você também tem aplicativos legados ou produzidos internamente, e quer que seus usuários do GNOME sejam capazes de acessá-los confortavelmente.

- Você está escrevendo um aplicativo para o GNOME, e quer uma lista básica do que conferir para garantir que seu aplicativo se integre bem com o resto do ambiente.

Esse guia é basicamente sobre como integrar software preexistente em um ambiente GNOME. Por outro lado, se você está considerando escrever software novo, nós o encorajamos a desenvolvê-lo tendo completamente o GNOME como plataforma alvo. Por favor, vá para o site dos desenvolvedores do GNOME para mais informações.

Uma das maiores preocupações do GNOME é a experiência do usuário. Os usuários devem ter um ambiente de computação confortável: isso significa um ambiente completo e um conjunto de aplicativos que trabalhem em conjunto de uma forma consistente. Com relativamente pouco trabalho, aplicativos que não foram escritos explicitamente para o GNOME podem passar a ser executados confortavelmente em um ambiente de trabalho GNOME.

### Estrutura do guia

Esse guia é estruturado como uma lista de tarefas que você precisa realizar para integrar um software preexistente ao GNOME. Esse guia apresenta essas tarefas aproximadamente em ordem de importância. Por exemplo, a tarefa de adicionar seu aplicativo aos menus do ambiente GNOME aparece antes da tarefa de adicionar suporte a arrastar-e-soltar. Além disso, esse guia tem um apêndice com uma lista de verificação para ajudá-lo a avaliar seu trabalho de integração.

### Padrões e freedesktop.org

Muitas das tarefas de integração desse guia estão baseadas em padrões que são relevantes não apenas para o GNOME. Outros ambientes, como o KDE (K Desktop Environment), também usam esses padrões: se você integrar seus aplicativos ao GNOME, deverá ter pouco ou nenhum trabalho para fazê-los ser executados nesses outros ambientes também.

Criar um aplicativo perfeito é um sentimento maravilhoso. Grande ou pequeno, você vai querer que seu aplicativo seja reconhecido pelo ambiente, e que eles interajam de forma adequada. Com múltiplos ambientes de trabalho disponíveis, o melhor para seu aplicativo é integrar-se bem ao maior número possível deles. Mesmo que não sejam regras oficiais, existe um conjunto de especificações disponíveis no freedesktop.org.

Mesmo não sendo um organismo formal de normatização, o freedesktop.org mantém um conjunto de diretrizes informais mas acordadas. Quando seguidas, essas diretrizes permitem aos aplicativos que se integrem aos ambientes de trabalho em conformidade.

## Integração básica

Esse capítulo lhe ensina os passos básicos a serem seguidos para integrar um programa ao ambiente GNOME. Esses passos dizem respeito ao seguinte:

- Permitir ao usuário que lance seu aplicativo, fazendo ele aparecer nos menus do painel do ambiente, ou qualquer mecanismo de lançamento do ambiente.

- Permitir ao ambiente saber que tipos de arquivos criados pelo usuário precisam de seu aplicativo para serem lançados.

- Permitir ao ambiente que saiba como exibir os ícones apropriados para seu programa e os arquivos por ele criados.

### Arquivos desktop: colocando seu aplicativo nos menus do GNOME

Para executar aplicativos no GNOME, os usuários clicam em ícones em suas áreas de trabalho ou selecionam os aplicativos desejados a partir de um menu. Portanto, o primeiro passo para integrar um programa preexistente ao GNOME é registrá-lo no conjunto de aplicativos executáveis pelo usuário.

Ao contrário do Windows do Mac OS, no GNOME os menus são construídos automaticamente a partir de uma lista de aplicativos registrados. Cada aplicativo especifica um conjunto de categorias ao qual pertence, e o GNOME ordena e organiza os aplicativos. Esse mecanismo segue os padrões de menu e de entrada desktop do freedesktop.org.

Apesar disso ser comum em outros ambientes, criar um submenu específico para seu aplicativo é desencorajado. Em vez disso, forneça somente um item de menu para cada aplicativo distribuído. Itens extra, como arquivos de ajuda, LEIAMEs ou links para seu website devem ser embutidos no próprio aplicativo.

No GNOME e outros ambientes em conformidade com o freedesktop.org, um aplicativo é registrado no menu do ambiente através de uma entrada desktop, ou seja, um arquivo de texto com a extensão `.desktop`. Esse arquivo contém uma lista de informações sobre seu aplicativo. O ambiente usa as informações do arquivo .desktop para:

- Colocar o aplicativo no menu principal.

- Listar o aplicativo no diálogo Executar aplicativo.

- Criar lançadores apropriados no menu ou na área de trabalho.

- Associar o nome e a descrição do aplicativo.

- Usar o ícone apropriado.

- Reconhecer os tipos MIME dos arquivos que o aplicativo pode abrir.

Para adicionar uma entrada de menu para seu aplicativo, crie um arquivo .desktop. Ele deve ter um nome de arquivo único, e não existe limite de comprimento, então evite abreviaturas e fique à vontade para incluir nomes de marca. No entanto, não coloque espaços ou caracteres internacionais no nome de arquivo. Por exemplo, "foocorp-painter-pro.desktop" seria uma boa escolha para nome de arquivo, mas "fcpp.desktop" seria um nome ruim, assim como seria "FooCorp Painter Pro.desktop". O arquivo deve ser codificado com UTF-8, e deve seguir esse modelo:

    	[Desktop Entry]
    	Encoding=UTF-8
    	Name=FooCorp Painter Pro
    	Exec=foocorp-painter-pro
    	Icon=foocorp-painter-pro
    	Type=Application
    	Categories=Application;

Os arquivos desktop contêm metadados sobre seu aplicativo, e desempenham um papel central na integração do programa com o GNOME e outros ambientes em conformidade com os padrões. O modelo apresentado aqui é o mais básico possível. O arquivo pode ser traduzido, de forma que o nome de seu aplicativo possa aparecer no idioma nativo do usuário.

Coloque esse arquivo no diretório `/usr/share/applications` para que ele seja acessível a todos, ou em `~/.local/share/applications` se você quiser torná-lo acessível a apenas um usuário. O diretório a ser usado depende se seu aplicativo está instalado para todo o sistema ou dentro do diretório pessoal de um usuário. O GNOME monitora esses diretórios, de forma que simplesmente copiar o arquivo para a localização correta é o suficiente para registrá-lo no ambiente.

Note que a localização `~/.local/share/applications` não é monitorada por versões do GNOME anteriores à 2.10, ou, no Fedora Core Linux, anteriores à versão 2.8. Essas versões do GNOME seguem o padrão hoje obsoleto vfolder, e nesse caso os arquivos desktop devem ser instalados em `~/.gnome2/vfolders/applications`. Essa localização não recebe suporte a partir do GNOME 2.10 ou, no Fedora Core, a partir da versão 2.8, de forma que para máxima compatibilidade com os ambientes implantados pode ser necessário instalar o arquivo desktop nas duas localizações.

Note que o KDE necessita de que o comando `kbuildsycoca` seja executado para forçar a atualização dos menus.

Cada arquivo desktop deve seguir o mesmo formato. Um exemplo mínimo de um arquivo desktop pode ser conferido no ex-sample-desktop-file. O arquivo está dividido em seções, cada uma começando com o descritor da seção entre colchetes. Nesse exemplo, apenas uma seção foi mostrada, que é a seção essencial na integração de seu aplicativo com o ambiente. Dentro de cada seção, a parte da linha antes do sinal de igual é a chave, e a outra parte é o valor. Uma explicação de cada linha está disponível na tb-desktop-file.

Fora a primeira linha, que identifica o arquivo desktop, a ordem das linhas não é importante. No ex-sample-desktop-file, a linha `Type=Application` poderia ter sido a segunda linha, a quinta ou a última, e o resultado teria sido o mesmo.

No entanto, as chaves fazem diferença entre maiúsculas e minúsculas. `Type=Application` não é o mesmo que `type=Application` ou `TYPE=Application`.

#### Arquivo desktop de exemplo

    [Desktop Entry]
    Type=Application
    Encoding=UTF-8
    Name=Nome do Aplicativo de Exemplo
    Comment=Um aplicativo exemplar
    Exec=aplicativo
    Icon=aplicativo.png
    Terminal=false

### Explicação linha a linha

Linha | Descrição
`[Desktop Entry]` | A primeira linha de cada arquivo desktop, e o cabeçalho da seção que identifica o bloco de pares chave-valor associado ao ambiente. Necessária para que o ambiente reconheça o arquivo corretamente.
`Type=Application` | Diz ao ambiente que esse arquivo desktop pertence a um aplicativo. Outros valores válidos para essa chave são `Link` e `Directory`.
`Encoding=UTF-8` | Descreve a codificação das entradas nesse arquivo desktop.
`Name=Nome do Aplicativo de Exemplo` | Nomes de seu aplicativo para o menu principal e quaisquer lançadores.
`Comment=Um aplicativo exemplar` | Descreve a aplicação. Usado como dica de ferramenta (tooltip).
`Exec=aplicativo` | O comando que inicia esse aplicativo a partir de um shell. Pode ter argumentos.
`Icon=application.png` | O nome do ícone associado ao aplicativo.
`Terminal=false` | Descreve se o aplicativo deve ser executado em um terminal.

#### Iniciando seu aplicativo

Se seu aplicativo pode receber argumentos de linha de comando, você pode representá-los usando os campos mostrados na tb-exec-params.

#### Variáveis da entrada Exec

Adicione... | Para aceitar...
`%f` | um único arquivo.
`%F` | múltiplos arquivos.
`%u` | um único URL.
`%U` | múltiplos URLs.
`%d` | um único diretório. Usada com `%f` para localizar um arquivo.
`%D` | múltiplos diretórios. Usada com `%F` para localizar arquivos.
`%n` | um único nome de arquivo sem caminho.
`%N` | múltiplos nomes de arquivo sem caminho.
`%k` | um URI ou nome de arquivo com a localização do arquivo desktop.
`%v` | o nome da entrada Device.

#### Idiomas estrangeiros

Para criar nomes e comentários localizados, são necessárias linhas adicionais para cada localidade. Por exemplo, para adicionar uma versão sueca do comentário, adicione a seguinte linha:

`Comment[sv]=Exempelprogramnamn`

Não existe limite para o número de traduções em um arquivo.

Manter uma longa lista de traduções em um único arquivo pode ser um incômodo. Existe um jeito melhor de criar essas traduções, com o pacote intltool. Leia as páginas do manual para intltool-extract e intltool-merge para mais informações.

#### Referências

Desktop Entry Specification — Especificações para a criação de um arquivo desktop.

### Instalando ícones

No ex-sample-desktop-file, especificamos o ícone para esse aplicativo como ``aplicativo.png``. Para que isso funcione, nós precisamos colocar o arquivo do ícone no diretório correto.

O ambiente procura pelos ícones no diretório do tema selecionado dentro de `/usr/share/icons/`. Os ícones de aplicativos devem estar disponíveis ao menos na resolução de 48×48 pixels. Coloque o ícone em `/usr/share/icons/hicolor/48x48/apps/`. Esse é o diretório onde o ambiente procura se o tema selecionado não tiver qualquer ícone para seu aplicativo. Se você tiver ícones com temas, coloque-os nos diretórios apropriados.

Para integrar bem seu aplicativo ao visual do ambiente GNOME, sem que ele deixe de parecer nativo ao ser executado sob o KDE, o Windows XP ou o Mac OS X, siga as diretrizes de estilo Tango ao criar sua arte. O documento explica vários aspectos da criação de ícones, como a seleção de cores, a iluminação e os tamanhos. Também estão disponíveis alguns tutoriais, inclusive em formato de vídeo.

#### Referências

Icon Theme Specification — Descreve como instalar e encontrar ícones levando em consideração os temas.

Icon Naming Specification — Fornece um esquema canônico de nomeação para arquivos de ícone.

Tango Style Guidelines — Fornece uma descrição de como criar ícones limpos e "multiplataforma".

### Adicionando tipos MIME

Se o seu aplicativo pode abrir determinados tipos MIME, você precisa informar isso ao ambiente através do arquivo desktop. Por exemplo, se o seu aplicativo aceita arquivos PNG, adicione as seguintes linhas em seu arquivo desktop:

    MimeType=image/png

Você pode acrescentar tipos MIME separando os diferentes tipos com ponto-e-vírgulas.

O sistema já conhece um grande número de tipos MIME. No entanto, se você estiver criando seu próprio tipo, vai precisar registrá-lo no banco de dados MIME. No diretório `/usr/share/mime/packages/`, crie um arquivo XML seguindo o formato mostrado no ex-mime-xml.

#### Arquivo de exemplo para o registro de um novo tipo MIME

    <?xml version="1.0" encoding="UTF-8"?>
    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
       <mime-type type="application/x-exemplo">
         <comment>Example file type </comment>
         <magic priority="50">
           <match value="expressão-pesquisada" type="string" offset="10:140"/>
         </magic>
         <glob pattern="*.novaextensão"/>
       </mime-type>
    </mime-info>

Nesse exemplo, substitua o tipo MIME de exemplo com o nome de seu tipo MIME. A seção "magic" pesquisa por uma expressão (string) no conteúdo dos arquivos para identificá-los, e a linha "glob" usa o sufixo dos nomes de arquivo para a identificação.

Como o comando `magic` força o computador a abrir o computador para pesquisar pela expressão, o comando `glob` é preferível.

Uma vez que seu tipo MIME tenha sido adequadamente descrito em um arquivo, execute o seguinte comando em um shell:

    update-mime-database /usr/share/mime

Para mais informações sobre como escolher uma boa extensão MIME e registrar seu tipo MIME, confira o website da IANA.

#### Referências

Shared MIME Info Specification — Descreve detalhadamente o sistema de registro MIME.

## Integração mais forte com o ambiente

Esse capítulo contém uma lista de coisas que você pode fazer para que o seu aplicativo seja mais integrado ao GNOME do que o mínimo indispensável. Por exemplo, o GNOME é capaz de dar feedback ao lançar um aplicativo: você pode saber como habilitar isso na startup-notification. Além disso, se o seu software cria documentos ou outros dados "imprimíveis", você pode instalar um utilitário de miniaturização para permitir que o gerenciador de arquivos do GNOME crie imagens de miniatura específicas para o seu programa.

### Notificação de inicialização

Ainda que os campos mostrados em desktop-files forneçam informações suficientes para que o ambiente reconheça seu aplicativo, existem outros campos potencialmente úteis para seu aplicativo. Um desses campos é o de notificação de inicialização.

Quando uma inicialização é notificada, o painel e o cursor notificam o usuário de que o aplicativo foi inicializado. Quando o aplicativo aparece na tela, o painel e o cursor voltam ao normal.

Para permitir que o lançador saiba que o seu aplicativo tem suporte a notificação de inicialização, adicione a seguinte linha ao seu arquivo .desktop:

`StartupNotify=true`

Esse comando no arquivo desktop habilita o ambiente a usar a notificação de inicialização fornecida pelo seu aplicativo ou pelo seu toolkit (GTK+, QT, etc). A maioria dos toolkits trabalha de forma transparente com o sistema de notificação de inicialização. Se você não estiver usando um toolkit moderno, a Especificação de Notificação de Inicialização tem os detalhes do que você precisa implementar por conta própria.

Qualquer que seja o seu toolkit, existe um tipo de aplicativo em que você precisa lidar manualmente com o feedback. Aplicativos com recursos de comunicação remota (em que você pode dizer a um processo em andamento para abrir uma nova janela, em vez de iniciar um novo processo) não podem usar os mecanismos do toolkit. O valor da variável de ambiente DESKTOP_LAUNCH_ID tem que ser examinado pelo seu aplicativo, e você deve notificar o sistema sobre a sua nova janela. Se você usar o GTK+, veja mais informações no manual da função `gdk_notify_startup_complete()`.

#### Referências

Startup Notification Protocol — Descreve os detalhes de baixo nível de como a notificação de inicialização é implementada no Sistema de Janelas X.

### Instalando um programa miniaturizador

O gerenciador de arquivos do GNOME, o Nautilus, pode exibir miniaturas específicas para cada arquivo em vez de ícones genéricos em sua lista de arquivos. Um documento de processador de textos, por exemplo, pode aparecer como uma versão pequena da primeira página do documento. Isso é útil porque permite aos usuários que vejam uma representação em pequena escala dos dados visíveis de seus arquivos, ajudando-os a lembrar se aquele é o arquivo pelo qual procuram. Você pode fazer seu aplicativo criar essas miniaturas em poucos passos simples.

Um miniaturizador é um programa sem interface de usuário que aceita um arquivo e um tamanho em pixels como argumentos, e grava uma miniatura do arquivo. O GNOME determina qual programa miniaturizador usar com base no tipo MIME do arquivo para o qual a miniatura será gerada. O mapeamento entre os tipos MIME e os programas miniaturizadores é armazenado como uma série de chaves do GConf.

Para cada tipo MIME com os qual você queira lidar, você deve criar um par de chaves do GConf:

`/desktop/gnome/thumbnailers/`application@x-exemplo`/enable`

- Tipo: boolean. Determina se esse miniaturizador será executado. Você pode habilitar ou desabilitar cada miniaturizador específico. Naturalmente, quando você instala um novo miniaturizador, você deve definir o valor dessa chave como true.

`/desktop/gnome/thumbnailers/`application@x-exemplo`/command`

- Tipo: string. O comando que o GNOME vai usar quando precisar gerar uma miniatura de um arquivo do tipo `application@x-exemplo`. O valor pode ser, por exemplo, "`application-x-exemplo-miniaturizador %i %o %s`". Veja abaixo para uma explicação dos sinais de percentual.

Dessa forma, cada tipo MIME necessita de duas chaves do GConf (`enable` e `command`) no mesmo caminho. O nome do caminho pode ser derivado do tipo MIME substituindo um "`/`" por um "`@`". Por exemplo, um miniaturizador para `image/x-meu-formato`" precisaria de duas chaves: `/desktop/gnome/thumbnailers/image@x-meu-formato/enable` e `/desktop/gnome/thumbnailers/image@x-meu-formato/command`.

Dentro da chave `command`, o GNOME vai procurar pelas seqüências de percentual e substituí-las com os valores reais:

`%i` | Nome do arquivo de entrada. Esse é o arquivo que o seu miniaturizador precisa ler.
`%u` | URI de entrada. Se o seu miniaturizador puder lidar com URIs em vez de simples nomes de arquivo, use `%u` em vez de `%i`.
`%o` | Nome do arquivo de saída. É nele que seu miniaturizador deve gravar a miniatura em formato PNG.
`%s` | Tamanho da miniatura como um inteiro simples. Se for substituído por `128`, por exemplo, isso significa que seu miniaturizador deve gerar uma imagem com 128×128 pixels ou menos.

Ou `%i` ou `%u` deve aparecer em seu comando, e `%o` também é obrigatório. A substituição `%s` é opcional, mas recomendados que seu miniaturizador preste atenção a ela também.

#### Informações adicionais

Como um parâmetro de configuração adicional, você pode ativar a chave booleana `/desktop/gnome/thumbnailers/disable_all` para desabilitar a geração de todas as miniaturas.

## Lista de verificação de integração

Esse apêndice fornece uma lista de verificação das várias tarefas apresentadas ao longo desse guia. Você pode usar a lista de verificação para garantir que o seu software seja integrado ao GNOME ao menos da forma básica, e também pode usá-la como um recurso para planejar o trabalho de integração a ser feito.

1. Seu aplicativo aparece nos menus do Painel do GNOME?

2. Seu aplicativo tem um ícone para os menus do painel ou a área de trabalho? Caso sim, ele tem múltiplos tamanhos pré-renderizados e uma versão escalável em SVG?

3. Caso seu aplicativo possa abrir ou salvar arquivos, ele registra os tipos MIME com os quais ele pode lidar?

4. Seu aplicativo fornece ícones MIME para o gerenciador de arquivos?

5. Seu aplicativo tem suporte a notificação de inicialização, de forma que o GNOME possa informar ao usuário que o seu aplicativo está sendo lançado?

6. Caso seu aplicativo crie documentos "imprimíveis", ele instala um miniaturizador para uso do gerenciador de arquivos?

## Agradecimentos

Muito obrigado a Jakub Steiner por fornecer uma bela folha de estilo CSS para a versão HTML desse guia!