# Integrar software existente con GNOME

## Prefacio

GNOME é un proxecto para construír un escritorio e plataforma de desenvolvemento completos con software libre. Algunhas empreas, gobernos, escolas, institucións e persoas instalaron o Escritorio GNOME nos seus sistemas. Se vostede é un desenvolvedor de software dunha terceira parte («Fabricante de software independente» ou ISV, ou «Desenvolvedor de software independente» (ISD)) se non o fai comercialmente), quizáis queira asegurarse de que o seu software se executa correctamente en GNOME. Esta guía explica como integrar software existente con GNOME sen ter que reescribir o software para usar explicitamente as bibliotecas e ferramentas de desenvolvemento de GNOME.

Esta guía é útil nas seguintes circunstancias:

- Se é un desenvolvedor de software ou distribuidor que ten un aplicativo que non está deseñada especificamente para traballar con GNOME, pero quere asegurarse de que se executa correctametne nun Escritorio GNOME.

- Se é un administrador de sistemas dunh institucición que teña instalados Escritorios GNOME aos seus usuarios. Tamén ten aplicativos obsoletod ou caseriso e quere que os usuarios de GNOME poidan acceder a elas correctamente.

- Está escribindo un aplicativo para GNOME e precisa unha lista de cousas básicas para asegurar que o seu aplicativo se integra correctametne co resto do Escritorio de GNOME.

En xeral esta guía é sobre a ingración de softwrae existente no Escritorio GNOME. Por outra parte, se está considerando escribir software novo, recomendámoslle que o desenvolva con GNOME como a súa plataforma obxectivo, consulte o sitio do desenvolvedor de GNOME para obter máis información.

Unha das principais preocupacións de GNOME é a experiencia do usuario. Os usuarios deberían ter un contorno de computación confortábel: isto significa ter un escritorio completo e un conxunto de aplicativos que operan conxuntamente de forma consistente. Con pouco traballo, os aplicativos que non están escritos explicitamente para GNOME poden executarse dunha forma confortábel nun escritorio GNOME.

### Estrutura desta guía

Esta guía está estruturada como unha lista de tarefas que debe realizar para integrar software existente en GNOMe. A guía presenta estas tarefas en orde de importancia. Por exemplo, a tarefa de engadir o seu aplicativo aos menús do Escritorio GNOME aparece antes que a tarefa de engadir compatibilidade de arrastrar e soltar. Ademais, esta guía ten un apéndice cunha lista de comprobación para a integración que lle axudará a avaliar o seu traballo de integración.

### Estándares e freedesktop.org

Moitas das tarefas de integración desta guía dependen de estándares que son importantes máis aló do GNOME. Outros proxectos de escritorio como o Contorno de Escritorio k (KDE) tamén usan estes estándares: se quere integrar o seu aplicativo con GNOME, terá que realizar un pequeno traballo adicional, ou ningún, para facer que se execute tamén neses escritorios.

Crear un aplicativo prefecto é un sentimento maravilloso. Independentemente de se é grande ou pequeno, quererá que o escritorio reconoza o seu aplicativo para que eles poidan interactuar con el axeitadamente. Coa cantidade de escritorios dispoñíbeis actualmente, o mellor é que o seu aplicativo sexa capaz de integrarse en tantos como sexa posíbel. Aínda que non existan regras oficiais, hai unhas especificacións dispoñíbeis en freedesktop.org.

Aínda que non sexan uns estándares formais, freedesktop.org mantén un conxunto de guías informais pero xeralmente aceptadas. Ao seguilas, estas guías permiten que os aplicativos se integren nos escritorios que seguen o estándar.

## Integración básica

Este capítulo enséñalle os pasos básicos que debe realizar para integrar un programa co Escritorio de GNOME. Estes pasos inclúen o seguinte:

- Permitir que o usuario inicie o seu aplicativo facendo que apareza nos menús do panel do escritorio, ou calquera outro mecanismo de inicio no escritorio.

- Permitir que o escritorio saiba que tipo de ficheiros creados polo usuario requiren o seu aplicativo para poderse iniciar.

- Permitir que o escritorio saiba como mostrar as iconas axeitadas para o seu programa e os ficheiros que o seu programa crea.

### Ficheiros de escritorio: poñer o seu aplicativo nos menús do escritorio

Para executar aplicativos desde GNOME, os usuarios premen en iconas nos seus escritorios ou seleccionan os aplicativos que queren executar desde un menú. Para iso, o primeiro paso para integrar un programa existente con GNOME é rexistralo co conxunto de aplicativos que os usuarios pode executar.

A diferenza de Windows ou Mac OS, en GNOME os menús de usuario constrúen automaticamente desde a lista de aplicativos rexistradas. Cada aplicativo publicado especifica un conxunto de categorías ás que pertencen, e a configuración do menú do sistema ordénaas e xestiona. Este mecanismo segue os estándares de escritorio e de menú de freedesktop.org

Aínda que é común noutros escritorios, non se recomenda crear o seu propio submenú específico para o seu aplicativo. No se lugar forneza un elemento de menú para cada aplicativo que empaquete. Os elementos adicionais como os ficheiros de axuda, os ficheiros LEAME, ou ligazóns á súa páxina web pódense empotrar no aplicativo en si.

En GNOME e algúns escritorios que cumpren o estándar de freedesktop.org un aplicativo rexístrase nos menús do escritorio a través dun ficheiro de escritorio que é un ficheiro de texto coa extensión `.desktop`. Este ficheiro de escritorio contén unha lista de configuración do aplicativo. O escritorio obtén a información do ficheiro e úsao para:

- put the application in the Main Menu. To find a list of valid categories, take a look into FreeDesktop.org's Desktop Menu Specification.

- liste o aplicativo no diálogo Executar aplicativo....

- cree os iniciadores axeitados no menú ou no escritorio

- asocie o nome e a descrición do aplicativo.

- use a icona axeitada.

- recoǹeza o tipo MIME que admite para abir ficheiros.

Para engadir unha entrada de menú par ao seu aplicativo cree un ficheiro de escritorio. Debería ter un nome de ficheiro único e non existen límites de lonxitude para evitar abreviacións e así se sinta libre para incluír nomes de marcas. Porén non poña espazos ou caracteres internacionais no nome de ficheiro. Por exemplo «empresafoo-graficos-pro.desktop» sería un bo nome de ficheiro pero «fcpp.desktop» é un mal nome, así como «Empresa Foo Gráficos Pro.desktop» O ficheiro debería estar codificado en UTF-8, e parecerse á seguinte plantilla:

    	[Desktop Entry]
    	Name=FooCorp Painter Pro
    	Exec=foocorp-painter-pro
    	Icon=foocorp-painter-pro
    	Type=Application
    	Categories=GTK;GNOME;Utility;

Esetes ficheiros .desktop conteñen metadatos sobre o seu aplicativo e xogan un rol central na integración do programa con GNOME e outros escritorios que cumpren cos estándares. A plantilla que aquí se presenta é a máis básica posíbel. O ficheiro pódese traducir lingüísticamente de tal forma que o nome do seu aplicativo poida aparecer no idioma nativo do usuario.

Poña este ficheiro no cartafol `/usr/share/applications` para que sexa accesíbel para todo o mundo, ou en `̣~/.local/share/applications` se quere que só sexa accesíbel para un usuario. Isto úsase dependendo de se o seu aplicativo se instalou no sistema ou ben no cartafol dun usuario. GNOME monitoriza estes cartafoles, así que simplemente copiar o ficheiro á localización correcta é dabondo para rexistralo no escritorio.

Teña en conta que a localización `~/.local/share/applications` non está monitorizada polas versións de GNOME anteriores a 2.10 ou nas versións anteriores á 2.8 en Fedora Core Linux. Estas versións de GNOME seguien o estándar obsoleto vfolder, e por iso os ficheiros de escritorio débense instalar en `~/.gnome2/vfolders/applications`. Esta localización non é compatíbel con GNOME 2.8 en Fedora Core nin en GNOME 2.10, así que par aunha máxima compatibilidade entre escritorios, poña o ficheiro en ámbalas dúas localizacións.

Teña en conta que o Escritorio KDE requrie unha execución de `kbuildsycoca` para forzar o refresco dos menús.

Cada ficheiro desktop debe seguir o mesmo formato. Móstrase un exemplo básico dun ficheiro de escritorio na ex-sample-desktop-file. O ficheiro está dividido en dúas seccións, cada unha delas comeza coa sección de descrición entre corchetes. Neste exemplo só se mostra unha sección como a esencial para integrar o seu aplicativo no escritorio. Entre cada sección, a parte de cada liña antes do signo igual é a chave, nementres que a segunda é o valor. Móstrase unha explicación de cada liña na tb-desktop-file.

A parte da primeira liña que identifica o ficheiro de escritorio, a orde das liñas non é importante. A ex-sample-desktop-fileliña `Type=Application` podería estar na segunda ringleira, na quinta ou na última e o resultado sería o mesmo.

Porén, as chaves distinguen entre maiúsculas e minúsculas. `Type=Application` non é o mesmo que `type=application` ou `TYPE=Application`.

#### Ficheiro de escritorio de exemplo

    [Desktop Entry]
    Type=Application
    Encoding=UTF-8
    Name=Nome de exemplo de aplicativo
    Comment=O mesmo aplicativo
    Exec=application
    Icon=application.png
    Terminal=false

### Explicacións liña a liña

Liña | Descrición
`[Desktop Entry]` | A primeira liña de todo ficheiro de escritorio e a sección de cabeceira para identificar o bloque de pares de chaves asociados co escritorio. Necesario para que o escritorio recoñeza o ficheiro correctamente.
`Type=Application` | Dílle ao escritorio que este ficheiro de escritorio pertence a un aplicativo. Outros valores válidos para esta chave son `Ligazón` e `Cartafol`.
`Encoding=UTF-8` | Describe a codificación das entradas neste ficheiro de escritorio.
`Name=Nome de exemplo de aplicativo` | Dalle o nome ao seu aplicativo para o menú principal e calquera iniciador.
`Comment=Un aplicativo de exemplo` | Describe o aplicativo. Usando un consello.
`Exec=application` | A orde que inicia o aplicativo desde consola. Pode ter argumentos.
`Icon=application.png` | O nome da icona asociada con este aplicativo.
`Terminal=false` | Describe se o aplicativo se debería executar nun terminal.

#### Iniciar o seu aplicativo

Se o seu aplicativo pode levar argumentos desde a liña de ordes, pode detallalo usando os campos mostrados na tb-exec-params

#### Variábeis de execución

Engadir… | Acepta…
`%f` | un só nome de ficheiro.
`%F` | múltiples nomes de ficheiro.
`%u` | un só URL.
`%U` | múltiples URL.
`%d` | un só cartafol. Usado xunto con `%f` para localizar un ficheiro.
`%D` | múltiples cartafoles. Usado xunto con `%F` para localizar ficheiros.
`%n` | un só nome de ficheiro sen ruta.
`%N` | múltiples ficheiros sen rutas.
`%k` | un URI ou nome de ficheiro local para a localización do ficheiro de escritorio.
`%v` | o nome do dispositivo de entrada.

#### Idiomas estranxeiros

Para crear nomes e comentarios localizados débese engadir liñas adicionais para cada local necesaria. Por exemplo, para engadir a versión en galego do comentario engada a seguinte liña

`Comment[gl]=Exemplo do nome do programa`

Non existen límites no número de traducións para o ficheiro.

Xa que manter unha longa lista de traducións nun ficheiro é moi ineficaz, unha mellor forma de crear estas traducións é usar o paquete intltook. Para obter máis información consulte as páxinas do manual de intltool-extract e intltool-merge.

#### Referencias

Especificación de entradas de escritorio; Especificacións para crear un ficheiro de escritorio.

### Instalar iconas

Na ex-sample-desktop-file especificouse a icona para este ficheiro como ``aplication.png``. Para que esto funcione, precisa poñer ese ficheiro de icona no cartafol correcto.

O escritorio busca iconas no cartafol de temas seleccionado `/user/share/icons`. As iconas dos aplicativos deberían estar dispoñíbeis, cando menos, nunha resolución de 48x48 píxeles. Poña a icona en `/usr/share/iconas/hicolor/48x48/apps/`. Este é o cartafol no que o escritorio busca en caso de qeu non teña unha icona para o seu aplicativo no tema seleccionado. Se ten iconas para temas, pópaos nos cartafoles axeitados.

Para mellorar a integración visual co escritorio GNOME, á vez que manten a aparencia nativa do seu aplicativo ao executarse en KDE, Windows XP ou Mac OS X, siga as guías de estilo de Tango ao crear arte para o seu aplicativo. O documento explica varios aspectos do deseño de iconas, incluíndo as cores, iluminación e tamaño. Tamén fornécese o típico fluxo de traballo e titoriais en vídeo.

#### Referencias

Especificación de temas de iconas: Describe como instalar e buscar iconas en forma de temas.

Especificación de nomes de iconas: Fornece un esquema canónico de nomes para os ficheiros de iconas.

Guías de estilo para Tango: Fornece unha descrición sobre como deseñar arte de iconas limpos e «multiplataforma»

### Engadir tipos MIME

Se o seu aplicativo pode abrir tipos MIME específicos debe facerllo saber ao escritorio no ficheiro desktop. Por exemplo, se o seu aplicativo pode aceptar ficheiros PNG, engada a seguinte liña no seu ficheiro desktop:

    MimeType=image/png

Pode engadir tipos MIME adicionais separando os diferentes tipos con puntos e comas.

O sistema xa coñece un gran número de tipos MIME. Porén, se está creando un propio, debe rexistrar o seu tipo MIME na base de datos MIME. No cartafol `/usr/share/mime/packages/` cree un ficheiro

#### Ficheiro de exemplo para rexistrar un tipo MIME novo

    <?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>Tipo de ficheiro de exemplo </comment>
         <magic priority="50">
           <match value="cadena-de-busca" type="string" offset="10:140"/>
         </magic>
         <glob pattern="*.extensión-nova"/>
       </mime-type>
    </mime-info>

Neste exemplo, substitúa o tipo MIME de exemplo co nome do seu tipo MIME, A sección magic busca ficheiros para a identificación de cadea, A liña glob usa o sufixo dos nomes de ficheiro para identificalos.

Xa que a orde `magic` forza ao equipo a abrir os ficheiros para buscar a cadea, prefírese a orde `glob`.

Unha vez que o seu novo tipo MIME está correctamente descrito no ficheiro, execute o seguinte nunha consola:

    update-mime-database /usr/share/mime

Para obter máis información sobre elixir unha boa extensión MIME e rexistrar o seu tipo MIME, vaia á páxina web da IANA.

#### Referencias

Especificación de información de tipos MIME: Describe o sistema de rexistro de tipos MIME en detalle.

## Integración máis profunda co Escritorio

ESte capítulo contén unha lista de cousas que pode facer para que o seu aplicativo se integre mellor en GNOME. Por exemplo, GNOME pode mostrar comentarios ao iniciar o aplicativo: pode ver como activar estes comentarios na startup-notification. Ademais, se o seu software crea documentos ou outros datos imprimíbeis pode instanciar instalar unha utilidade de xestión de miniaturas para permitir ao xestor de ficheiros de GONME crear imaxes en miniatura específicas para o seu programa.

### Notificación de inicio

Ainda que os campos mostrados na desktop-files fornecen suficiente información para que o escritorio recoñeza o seu aplicativo, existen outros campos que poden ser útiles para o seu caso particular. Un destes campos é startup notification.

Cando a notificación de inicio está activada, o panel e o cursor notifican ao usuario que o aplicativo iniciouse. Cando o aplicativo aparece na pantalla, o panel e o cursor volven ao seu estado normal.

Para permitir que o iniciador saiba que o seu aplicativo admite a notificación de inicio, engada a seguinte liña ao seu ficheiro de escritorio:

`StartupNotify=true`

Esta orde no ficheiro desktop fai que o escritorio use calquera notificación de inicio incluída xa sexa no seu aplicativo ou no seu conxunto de ferramentas (toolkit). A maioría dos conxuntos de ferramentas modernos funcionan de forma transparente coas notificacións de inicio de sistema. Se non usa un conxunto de ferramentas moderno, a especificación de notificacións de inicio contén detalles que debe implementar vostede mesmo.

Independentemente do conxunto de ferramentas, existe un tipo de aplicativo onde deberá xestionar os comentarios manualmente. Os aplicativos con capacidades rmeotas (onde lle día a un proceso existente que abra unha xanela nova no lugar de iniciar un proceso novo) non pode usar este mecanismo incluído. O seu aplicativo debe pasar o valor de retorno DESKTOP_LAUNCH_ID e debe notificar ao sistema de inicios da súa nova xanela. Se está usando GTK+, a documentación para `gdk_notify_startup_complete()` ten algo máis de información.

#### Referencias

Protocolo de notificación de inicio: Describe os detalles de baixo nivel de como se comporta a notificación de inicio no sistema X Window.

### Instalar un programa xerador de miniaturas

O xestor de ficheiros de GNOME, Nautilus, pode mostrar pequenas miniaturas recortadas para cad un dos ficheiros no lugar de iconas xenéricas, na súa lista de ficheiros. Por exemplo, un documento dun procesador de textos pode aparecer como unha pequena versión da primeira páxina do documento. Isto é útil xa que os usuarios poden ver unha pequena representación dos datos visíbeis nos seus ficheiros, o que axuda a saber o que están buscando. Pode facer que o seu aplicativo cree esas miniaturas cuns simples pasos.

Un thumbnailer (xerador de miniaturas) é un programa sen interface de usuario que toma como entrada un ficheiro e un tamaño de píxel e escribe unha miniatura para este ficheiro, GNOME determina que xerador de miniaturas usar baseándose no tipo MIME do ficheiro para o que se debe xerar a miniatura. O mapeado entre tipos MIME e os programas xeradores de miniaturas almacénanse como series de chaves de GConf.

Para cada tipo MIME que queira manexar, terá que crear un par de chaves de GConf:

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

- Type: boolean. Deermian se este xerador de miniaturas se executará. Pode activar ou desactivar individualmente cada xerador de miniaturas. Cando instale un xerador de miniaturas novo deberá cambiar o valor desta chave a true.

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

- Type: string. A liña de orde que GNOME usará cando precise xerar unha miniatura para un tipo de ficheiro `application@x-foo`. Por exemplo, o valor podería ser «`application-x-foo-thumbnailer %i %o %s`». Consulte máis abaixo para obter unha explicación dos signos con porcentaxes.

Isto é, cada tipo MIME precisa dúas chaves de GConf (`enable` e `command`) baixo a mesma ruta. O nome da ruta pode derivarse do nome do tipo MIME substituíndo un «`/`» con «`@`». Por exemplo, un xerador de miniaturas para `image/x-meu-formato` precisaría dúas chaves `/desktop/gnome/thumbnailers/image@x-mei-formato/enable` e `/desktop/gnome/thumbnailers/image@x-meu-formato/comando`.

Dentro da chave `command` GNOME buscará secuencias de porcentaes e os substituirá con valores actuais:

`%i` | Nome do ficheiro de entrada. Isto é o ficheiro que o seu xerador de miniaturas debe ler.
`%u` | URI de entrada. SE o seu xerador de miniatura pode xestionar URI no lugar de ficheiros de nomes planos, use `%u` no lugar de `%i`.
`%o` | Nome do ficheiro de saída. Isto é onde o seu xerador de miniaturas debe escribir a imaxe en miniatura en formato PNG.
`%s` | Tamaño da miniatura cun só enteiro. Por exemplo, se isto se substitúe con `128` significa que o seu xerador de miniaturas debería xerar unha imaxe de saída máis pequena de 128x128 píxeles.

TAnto `%s` como `%u` deben aparecer na súa liña de ordes e `%o` tamén é obrigatoria. A substitución `%s` é opcional, pero recoméndase que o seu xerador de miniaturas a teña en conta.

#### Información adicional

Como un parámetro adicional pode activar a chave booleana `/desktop/gnome/thumbnailers/disable_all` para deactivar a xeración tódalas miniaturas.

## Lista de comprobación da integración

Este apéndice fornece unha lista de comprobación das diversas tarefas presentes ao longo desta guía. Pode usar a lista de comprobación para verificar que o seu software está integrado en GNOME cando menos dunha forma básica, así como un recurso para planificar futuros traballos de integración.

1. Aparece o seu aplicativo nos menús do panel de GNOME?

2. Ten o seu aplicativo unha icona para os menús do panel ou para o escritorio? Se é así, ten tamaños múltiples e prerenderizados e unha versión SVG?

3. Se o seu aplicativo pode cargar ou gardar ficheiros, rexistra os tipos MIME que poida manexar?

4. Fornece o seu aplicativo iconas MIME para o xestor de ficheiros?

5. O seu aplicativo admite notificación de inicio, de tal forma que GNOME poida mostrarlle comentarios ao usuario mentras que o seu aplicativo se está iniciando?

6. Se o seu aplicativo crea documentos «imprimíbeis», instala un creador de miniaturas para que o use o xestor de ficheiros?

## Agradecementos

Moitas grazas a JAkub Steiner por fornecer unha folla de setilo bonita para a versión HTML desta guía.