# Integrar software existente con GNOME

## Prefacio

GNOME es un proyecto para construir un escritorio completo y una plataforma de desarrollo completamente basada en software libre. Muchas empresas, gobiernos, escuelas, instituciones y personas han instalado el Escritorio GNOME en sus sistemas. Si es un desarrollador de software de una tercera parte («Fabricante de software independiente» o ISV, o «Desarrollador de software independiente» (ISD) si no lo hace comercialmente), quizá quiera asegurarse de que su software se ejecuta correctamente en GNOME. Esta guía explica cómo integrar software existente con GNOME sin tener que reescribir el software para usar explicitamente las bibliotecas y herramientas de desarrollo de GNOME.

Esta guía es útil en las siguientes circunstancias:

- Si es un desarrollador de software o distribuidor que tiene una aplicación que no está diseñada específicamente para trabajar con GNOME, pero quiere asegurarse de que se ejecuta correctamente en un Escritorio GNOME.

- Si es un administrador de sistemas de una institución que ha instalado Escritorios GNOME a sus usuarios. También tiene aplicaciones obsoletas o caseras y quiere que sus usuarios de GNOME puedan acceder a ellas correctamente.

- Está escribiendo una aplicación para GNOME y necesita una lista de cosas básicas para asegurar que su aplicación se integra correctamente con el resto del Escritorio GNOME.

En general esta guía es acerca de integrar software existente en un Escritorio GNOME. .Por otra parte, si está considerando escribir software nuevo, le recomendamos que lo desarrolle con GNOME como su plataforma objetivo; consulte el sitio del desarrollador de GNOME para obtener más información.

Una de las principales preocupaciones de GNOME es la experiencia del usuario. Los usuarios deberían tener un entorno de computación confortable: esto significa tener un escritorio completo y un conjunto de aplicaciones que operan conjuntamente de forma consistente. Con poco trabajo, las aplicaciones que no están escritas explícitamente para GNOME pueden ejecutarse de una forma confortable en un escritorio GNOME.

### Estructura de esta guía

Esta guía está estructurada como una lista de tareas que debe realizar para integrar software existente en GNOME. La guía presenta estas tareas en orden de importancia. Por ejemplo, la tarea de añadir su aplicación a los menús del Escritorio GNOME aparece antes que la tarea de añadir soporte de arrastrar y soltar. Además, esta guía tiene un apéndice con una lista de comprobación para la integración que le ayudará a evaluar su trabajo de integración.

### Estándares y freedesktop.org

Muchas de las tareas de integración de esta guía dependen de estándares que son importantes más allá de GNOME. Otros proyectos de escritorios como el Entorno de Escritorio K (KDE) también usa estos estándares: si quiere integrar su aplicación con GNOME, tendrá que realzar un pequeño trabajo adicional, o ninguno, para hacer que se ejecute también en esos escritorios.

Crear una aplicación perfecta es un sentimiento maravilloso. Independientemente de si es grande o pequeña, querrá que el escritorio reconozca su aplicación para que ellos puedan interactuar con ella apropiadamente. Con la cantidad de escritorios disponible actualmente, lo mejor es que su aplicación sea capaz de integrarse en tantos como sea posible. Aunque no existan reglas oficiales, hay unas especificaciones disponibles en freedesktop.org.

Aunque no sean unos estándares formales, freedesktop.org mantiene un conjunto de guías informales pero generalmente aceptadas. Al seguirlas, estas guías permiten que las aplicaciones se integren en los escritorios que siguen el estándar.

## Integración básica

Este capítulo le enseña los pasos básicos que debe realizar para integrar un programa en el Escritorio GNOME. Estos pasos incluyen lo siguiente:

- Permitir que el usuario lance su aplicación haciendo que aparezca en los menús del panel del escritorio, o cualquier otro mecanismo de lanzamiento en el escritorio.

- Permitir que el escritorio sepa qué tipo de archivos creados por el usuario requiere su aplicación para poderse lanzar.

- Permitir que el escritorio sepa cómo mostrar los iconos apropiados para su programa y los archivos que su programa crea.

### Archivos de escritorio: poner su aplicación en los menús del escritorio

Para ejecutar aplicaciones desde GNOME, los usuarios pulsan en iconos de sus escritorios o seleccionan las aplicaciones que quieren ejecutar de un menú. Por ello, el primer paso para integrar un programa existente con GNOME es registrarlo con el conjunto de aplicaciones que los usuarios pueden ejecutar.

A diferencia de Windows o Mac OS, en GNOME los menús de usuario se construyen automáticamente desde la lista de aplicaciones registradas. Cada aplicación publicada especifica un conjunto de categorías alas que pertenece, y la configuración del menú del sistema las ordena y gestiona. Este mecanismo sigue los estándares de escritorio y de menú de freedesktop.org

Aunque es común en otros escritorios, no se recomienda crear su propio submenú específico para su aplicación. En su lugar, proporcione un elemento de menú para cada aplicación que empaquete. Los elementos adicionales como los archivos de ayuda, los ficheros LÉEME, o enlaces a su página web se pueden empotrar en la aplicación web en si.

En GNOME y algunos otros escritorios que cumplen el estándar de freedesktop.org una aplicación se registra en los menús del escritorio a través de un archivo de escritorio que es un archivo de texto con la extensión `.desktop`. Este archivo de escritorio contiene una lista de la configuración de la aplicación. El escritorio obtiene la información del archivo y lo usa para:

- pónga la aplicación en el Menú principal.

- liste la aplicación en el diálogo Ejecutar aplicación....

- cree los lanzadores apropiados en el menú o en el escritorio.

- asocie el nombre y la descripción de la aplicación.

- use el icono apropiado.

- reconozca el tipo MIME que soporta para abrir archivos.

Para añadir una entrada de menú para su aplicación cree un archivo de escritorio. Debería tener un nombre de archivo único y no existen límites de longitud para evitar abreviaciones y así se sienta libre para incluir nombres de marcas. No obstante no ponga espacios o caracteres internacionales en el nombre de archivo. Por ejemplo «empresafoo-graficos-pro.escritorio» sería un buen nombre de archivo pero «efgp.desktop» sería un mal nombre, así como «Empresa Foo Gráficos Pro.desktop». El archivo debería estar codificado en UTF-8, y parecerse a la siguiente plantilla:

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

Estos archivos .desktop contienen metadatos acerca de su aplicación y juegan un rol central en la integración del programa con GNOME y otros escritorios que cumplen con los estándares. La plantilla que aquí se presenta es la más básica posible. El archivo se puede traducir lingüísticamente de tal forma que el nombre de su aplicación pueda aparecer en el idioma nativo del usuario.

Ponga este archivo en la carpeta `/usr/share/applications` para que sea accesible por todo el mundo, o en `~/.local/share/applications` si quiere que sólo sea accesible para un usuario. Ésto se usa dependiendo de si su aplicación se instaló en el sistema o bien en la carpeta de un usuario. GNOME monitoriza esas carpetas, así que simplemente copiar el archivo a la ubicación correcta es suficiente para registrarlo en el escritorio.

Note que la ubicación `~/.local/share/applications` no está monitorizada por las versiones de GNOME anteriores a 2.10 o en las versiones anteriores a la 2.8 en Fedora Core Linux. Estas versiones de GNOME siguen el estándar obsoleto vfolder, y por ello los archivos de escritorio se deben instalar en `~/.gnome2/vfolders/applications`. Esta ubicación no está soportada por GNOME 2.8 en Fedora Core ni en GNOME 2.10, así que para una máxima compatibilidad entre escritorios, ponga el archivo en ambas ubicaciones.

Note que el Escritorio KDE requiere una ejecución de `kbuildsycoca` para forzar el refresco de los menús.

Cada archivo de escritorio debe seguir el mismo formato. Se muestra un ejemplo básico de un archivo de escritorio en la ex-sample-desktop-file. El archivo está dividido en dos secciones, cada una de ellas comienza con la sección de descripción entre corchetes. En este ejemplo sólo se muestra una sección como la esencial para integrar su aplicación en el escritorio. Entre cada sección, la parte de cada línea antes del signo igual es la clave, mientras que la segunda es el valor. Se muestra una explicación de cada línea en la tb-desktop-file.

A parte de la primera línea que identifica el archivo de escritorio, el orden de las líneas no es importante En la ex-sample-desktop-file la línea `Type=Application` podría estar en la segunda fila, la quina o la última y el resultado sería el mismo.

No obstante, las claves distinguen entre mayúsculas y minúsculas. `Type=Application` no es lo mismo que `type=Application` o `TYPE=Application`.

#### Archivo de escritorio de ejemplo

    [Desktop Entry]
    Type=Application
    Encoding=UTF-8
    Name=Nombre de ejemplo
    Comment=Una aplicación de ejemplo
    Exec=aplicacion
    Icon=aplicación.png
    Terminal=false

### Explicación línea a línea

Línea | Descripción
`[Desktop Entry]` | La primera línea de todo archivo de escritorio y la sección de cabecera para identificar el bloque de los pares de claves asociados con el escritorio. Necesario para que el escritorio reconozca el archivo correctamente.
`Type=Application` | Le dice al escritorio que este archivo de escritorio pertenece a una aplicación. Otros valores válidos para esta clave son `Enlace` y `Carpeta`.
`Encoding=UTF-8` | Describe la codificación de las entradas en este archivo de escritorio.
`Name=Nombre de ejemplo de una aplicación` | Da el nombre a su aplicación para el menú principal y cualquier lanzador.
`Comment=Una aplicación de ejemplo` | Describe la aplicación. Usado como consejo.
`Exec=application` | El comando que inicia la aplicación desde una consola. Puede tener argumentos.
`Icon=aplicación.png` | El nombre del icono asociado con esta aplicación.
`Terminal=false` | Describe si la aplicación se debería ejecutar en un terminal.

#### Iniciar su aplicación

Si su aplicación puede llevar argumentos de la línea de comandos, puede detallarlo usando los campos mostrados en la tb-exec-params.

#### Variables de ejecución

Añadir… | Acepta...
`%f` | un sólo nombre de archivo.
`%F` | múltiples nombres de archivo.
`%u` | un sólo URL.
`%U` | múltiples URL.
`%d` | una sola carpeta. Usado junto con `%f` para ubicar un archivo.
`%D` | múltiples carpetas. Usado junto con `%F` para ubicar archivos.
`%n` | un sólo nombre de archivo sin ruta.
`%N` | múltiples archivos sin rutas.
`%k` | un URI o nombre de archivo local para la localización del archivo de escritorio.
`%v` | el nombre del dispositivo de entrada.

#### Idiomas extranjeros

Para crear nombres y comentarios localizados se deben añadir líneas adicionales para cada local necesaria. Por ejemplo, para añadir la versión en español del comentario, añada la siguiente línea:

`Comment[es]=Ejemplolnombredelprograma`

No existen límites en el número de traducciones para el archivo.

Ya que mantener una larga lista de traducciones en un archivo es muy ineficaz, una mejor forma de crear estas traducciones es usar el paquete intltook. Para obtener más información consulte las páginas del manual de intltool-extract y intltool-merge.

#### Referencias

Especificación de entradas de escritorio; Especificaciones para crear un archivo de escritorio.

### Instalar iconos

En la ex-sample-desktop-file se ha especificado el icono para este archivo como ``aplicacion.png``. Para que esto funcione, necesita poner ese archivo de icono en la carpeta correcto.

El escritorio busca iconos en ela carpeta de temas seleccionado `/usr/share/icons/`. Los iconos de las aplicaciones deberían estar disponibles, al menos, en una resolución de 48x48 píxeles. Ubique el icono en `/usr/share/icons/hicolor/48x48/apps/`. Éste es la carpeta en el que el escritorio busca en caso de que no haya un icono para su aplicación en el tema seleccionado. Si tiene iconos para temas, póngalos en las carpetas apropiados.

Para mejorar la integración visual con el escritorio GNOME, a la vez que mantiene la apariencia nativa de su aplicación al ejecutarse en KDE, Windows XP o Mac OS X, siga las guías de estilo de Tango al crear arte para su aplicación. El documento explica varios aspectos del diseño de iconos, incluyendo los colores, iluminación y tamaño. También se proporciona el típico flujo de trabajo y tutoriales de vídeo.

#### Referencias

Especificación de temas de iconos: Describe cómo instalar y buscar iconos en forma de temas.

Especificación de nombres de iconos: Proporciona un esquema canónico de nombres para los archivos de iconos.

Guías de estilo de Tango: Proporciona una descripción acerca de cómo diseñar arte de iconos limpio y «multiplataforma».

### Añadir tipos MIME

Si su aplicación puede abrir tipos MIME específicos debe hacérselo saber al escritorio en el archivo de escritorio. Por ejemplo, si su aplicación puede aceptar archivos `PNG`, añada la siguiente línea en su archivo de escritorio:

    MimeType=image/png

Se pueden añadir tipos MIME adicionales separando los diferentes tipos con puntos y comas.

El sistema ya conoce un gran número de tipos MIME. No obstante, si está creando uno propio, debe registrar su tipo MIME en la base de datos MIME. En la carpeta `/usr/share/mime/packages/` cree un archivo `XML` con el formato mostrado en la ex-mime-xml.

#### Archivo de ejemplo para registrar un tipo MIME nuevo

    <?xml version="1.0" encoding="UTF-8"?>
    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
       <mime-type type="application/x-ejemplo">
         <comment>Tipo de archivo de ejemplo </comentario>
         <magic priority="50">
           <match value="cadena-de-búsqueda" type="string" offset="10:140"/>
         </magic>
         <glob pattern="*.extensión-nueva"/>
       </mime-type>
    </mime-info>

En este ejemplo, reemplace el tipo MIME de ejemplo con el nombre de su tipo MIME. La sección magic busca archivos para la identificación de cadena. La línea glob usa el sufijo de los nombres de archivo para identificarlos.

Debido a que el comando `magic` fuerza al equipo a abrir los archivos para buscar la cadena, se prefiere el comando `glob`.

Una vez que su nuevo tipo MIME está correctamente descrito en el archivo, ejecute lo siguiente en una consola:

    update-mime-database /usr/share/mime

Para obtener más información acerca de elegir una buena extensión MIME y registrar su tipo MIME, vaya a la página web de la IANA.

#### Referencias

Especificación de información de tipos MIME: Describe el sistema de registro de tipos MIME en detalle.

## Integración más profunda con el Escritorio

Este capítulo contiene una lista de cosas que puede hacer para que su aplicación se integre mejor en GNOME. Por ejemplo, GNOME es capaz de mostrar comentarios al lanzar la aplicación: puede ver cómo activar estos comentarios en la startup-notification. Además, si su software crea documentos u otros datos imprimibles puede instar una utilidad de gestión de miniaturas para permitir al gestor de archivos de GNOME crear imágenes en miniatura específicas para su programa.

### Notificación de inicio

Aunque los campos mostrados en la desktop-files proporcionan suficiente información para que el escritorio reconozca su aplicación, existen otros campos que pueden ser útiles para su caso particular. Uno de estos campos es startup notificacion.

Cuando la notificación de inicio está activada, el panel y el cursor notifican al usuario que la aplicación se ha iniciado. Cunado la aplicación aparece en la pantalla, el panel y el cursor vuelven a su estado normal.

Para permitir que el lanzador sepa que su aplicación soporta la notificación de inicio, añada la siguiente línea a su archivo de escritorio:

`StartupNotify=true`

Este comando en el archivo de escritorio hace que el escritorio use cualquier notificación de inicio incluida ya sea en su aplicación o en su conjunto de herramientas (toolkit). La mayoría de los conjuntos de herramientas modernos funcionan de forma transparente con las notificaciones de inicio del sistema. Si no usa un conjunto de herramientas moderno, la especificación de notificaciones de inicio contiene detalles que debe implementar usted mismo.

Independientemente del conjunto de herramientas, existe un tipo de aplicación donde deberá gestionar los comentarios manualmente. Las aplicaciones con capacidades remotas (donde le dice a un proceso existente que abra una ventana nueva en lugar de iniciar un proceso nuevo) no pueden usar este mecanismo incluido. Su aplicación debe pasar el valor del entorno DESKTOP_LAUNCH_ID y debe notificar al sistema de lanzamientos de su nueva ventana. Si está usando GTK+, la documentación para `gdk_notify_startup_complete()` tiene algo más de información.

#### Referencias

Protocolo de notificación de inicio: Describe los detalles de bajo nivel de cómo se implementa la notificación de inicio en el Sistema X Window.

### Instalar un programa generador de miniaturas

El gestor de archivos de GNOME, Nautilus, puede mostrar pequeñas miniaturas recortadas para cada uno de los archivos en lugar de iconos genéricos, en su lista de archivos. Por ejemplo, un documento de un procesador de textos puede aparecer como una pequeña versión de la primera página del documento. Esto es útil ya que los usuarios pueden ver una pequeña representación de los datos visibles en sus archivos, lo que puede ayudar a saber lo que están buscando. Puede hacer que su aplicación cree esas miniaturas con unos simples pasos.

Un thumbnailer (generador de miniaturas) es un programa sin interfaz de usuario que toma como entrada un archivo y un tamaño de píxel y escribe una miniatura para ese archivo, GNOME determina qué generador de miniaturas usar basándose en el tipo MIME del archivo para el que se debe generar la miniatura. El mapeado entre tipos MIME y los programas generadores de miniaturas se almacena como series de claves de GConf.

Para cada tipo MIME que quera manejar, tendrá que crear un par de claves de GConf:

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

- Type: boolean. Determina si este generador de miniaturas se ejecutará. Puede activar o desactivar individualmente cada generador de miniaturas. Cuando instale un generador de miniaturas nuevo deberá cambiar el valor de esta clave a true.

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

- Type: string. La línea de comando que GNOME usará cuando necesite generar una miniatura para un tipo de archivo `aplicacion@x-foo`. Por ejemplo, el valor podría ser «`application-x-foo-thumbnailer %i %o %s`». Consulte más abajo para obtener una explicación de los signos con porcentajes.

Esto es, cada tipo MIME necesita dos claves de GConf (`enable` y `command`) bajo la misma ruta. El nombre de la ruta puede derivarse del nombre del tipo MIME sustituyendo un «`/`» con «`@`». Por ejemplo, un generador de miniaturas para `image/x-mi-formato` necesitaría dos claves: `/desktop/gnome/thumbnailers/image@x-mi-formato/enable` y `/desktop/gnome/thumbnailers/image@x-mi-formato/comando`.

Dentro de la clave `command` GNOME buscará secuencias de porcentajes y los sustituirá con valores actuales:

`%i` | Nombre del archivo de entrada. Este es el archivo que su generador de miniaturas debe leer.
`%u` | URI de entrada. Si su generador de miniaturas puede gestionar URI en lugar de archivos de nombre planos, use `%u` en lugar de `%i`.
`%o` | Nombre de archivo de salida. Esto es donde su generador de miniaturas debe escribir la imagen en miniatura en formato PNG.
`%s` | Tamaño de la miniatura como un solo entero. Por ejemplo, si esto se sustituye con `128` significa que su generador de miniaturas debería generar una imagen de salida más pequeña de 128x128 píxeles.

Tanto `%i` como `%u` deben aparecer en su línea de comandos, y `%o` también es obligatoria. La sustitución `%s` es opcional, pero se recomienda que su generador de miniaturas la tenga en cuenta.

#### Información adicional

Como un parámetro de configuración adicional puede activar la clave booleana `/desktop/gnome/thumbnailers/disable_all` para desactivar toda la generación de miniaturas.

## Lista de comprobación de la integración

Este apéndice proporciona una lista de comprobación de las diversas tareas presentes a lo largo de esta guía. Puede usar la lista de comprobación para verificar que su software está integrado en GNOME al menos de una forma básica, así como un recurso para planificar futuros trabajos de integración.

1. ¿Aparece su aplicación en los menús del panel de GNOME?

2. ¿Tiene su aplicación un icono para los menús del panel o para el escritorio? Si así es, ¿tiene tamaños múltiples y prerenderizados y una versión SVG?

3. Si su aplicación puede cargar o guardar archivos, ¿registra los tipos MIME que puede manejar?

4. ¿Proporciona su aplicación iconos MIME para el gestor de archivos?

5. ¿Su aplicación soporta notificación de inicio, de tal forma que GNOME pueda mostrarle comentarios al usuario mientras que su aplicación se está lanzando?

6. Si su aplicación crea documentos «imprimibles», ¿instala un creador de miniaturas para que lo use el gestor de archivos?

## Agradecimientos

Muchas gracias a Jakub Steiner por proporcionar una hoja de estilo bonita para la versión HTML de esta guía.