# Intégration d'un logiciel existant dans GNOME

## Préface

GNOME est un projet de conception d'un bureau complet et d'une plateforme de développement entièrement basés sur des logiciels libres. De nombreuses entreprises, gouvernements, écoles, institutions et individus ont déjà installé le bureau GNOME sur leur infrastructure. Si vous êtes un développeur de logiciels tiers (« fournisseur de logiciels indépendants » (Independent Software Vendor : ISV) ou « développeur de logiciels indépendants » (Independent Software Developer : ISD), si vous ne le faites pas dans un but commercial), il se peut que vous désiriez vous assurer que votre logiciel existant fonctionne correctement sous GNOME. Ce guide explique comment intégrer un logiciel existant dans GNOME, sans pour autant réécrire ce logiciel pour qu'il utilise explicitement les librairies et les outils de développement de la plateforme GNOME.

Ce guide est utile dans les situations suivantes :

- Vous êtes un développeur ou un distributeur de logiciels qui possède une application qui n'est pas spécialement conçue pour fonctionner sous GNOME, mais vous voulez vous assurer qu'elle fonctionne convenablement dans un bureau GNOME.

- Vous êtes un administrateur système d'une institution qui déploie des bureaux GNOME pour ses utilisateurs. Vous possédez également des applications pré-existantes ou internes et vous désirez que vos utilisateurs de GNOME soient capables d'accéder convenablement à ces applications.

- Vous êtes en train d'écrire une application purement GNOME et vous avez besoin d'une liste de contrôle avec les éléments de base à vérifier pour s'assurer que votre application s'intègre bien avec le reste du bureau GNOME.

D'une manière générale, ce guide traite de l'intégration de logiciels existants dans un bureau GNOME. D'un autre côté, si vous pensez écrire un nouveau logiciel, nous vous encourageons à le développer complètement en choisissant GNOME comme plateforme cible ; veuillez vous référer au site des développeurs GNOME pour plus d'informations.

Une des préoccupations majeures de GNOME est l'interaction avec l'utilisateur. Les utilisateurs doivent être à l'aise dans leur environnement informatique, c'est-à-dire avoir un bureau complet et un ensemble d'applications qui fonctionnent conjointement de manière cohérente. Avec relativement peu de travail, des applications qui n'ont pas été explicitement conçues pour GNOME peuvent être modifiées pour une utilisation aisée dans un bureau GNOME.

### Structure de ce guide

Ce guide se présente sous la forme d'une liste de tâches à réaliser afin d'intégrer un logiciel existant dans GNOME. Ce guide présente ces tâches à peu près par ordre d'importance. Par exemple, la tâche consistant à ajouter votre application dans les menus du bureau GNOME apparaît avant celle consistant à ajouter la prise en charge du glisser-déposer. De plus, ce guide possède un appendice contenant une liste de contrôle d'intégration pour vous aider à estimer votre travail d'intégration.

### Standards et freedesktop.org

De nombreuses tâches d'intégration figurant dans ce guide reposent sur des standards qui ne sont pas uniquement applicables à GNOME. D'autres projets de bureau, comme le bureau KDE, utilisent également ces standards : si vous intégrez vos applications dans GNOME, vous n'aurez que peu ou pas de tâches supplémentaires à effectuer pour les faire fonctionner correctement avec ces autres environnements.

La création d'une application parfaite procure des sensations merveilleuses. Que votre application soit grosse ou petite, vous voulez que le bureau la reconnaisse et que celle-ci interagisse d'une manière appropriée. Avec les nombreux bureaux disponibles actuellement, il vaut mieux que votre application s'intègre bien avec le plus grand nombre possible d'entre eux. Même si aucune règle officielle n'a été adoptée, il existe un ensemble de spécifications disponibles sur freedesktop.org.

Bien que n'étant pas un organisme officiel de création de standards, freedesktop.org maintient un ensemble de lignes directrices informelles mais couramment acceptées. Lorsque vous suivez ces directives, elles permettent aux applications d'être intégrées dans les bureaux les respectant.

## Intégration de base

Ce chapitre vous enseigne les étapes essentielles à suivre pour intégrer un programme dans le bureau GNOME. Ces étapes sont les suivantes :

- permettre à l'utilisateur de lancer votre application en la faisant apparaître dans les menus du tableau de bord du bureau ou en utilisant n'importe quelle autre procédure de lancement du bureau ;

- permettre au bureau de savoir quels types de fichiers créés par les utilisateurs nécessitent le lancement de votre application ;

- permettre au bureau de savoir comment afficher les icônes appropriées pour votre programme et quels sont les fichiers créés par celui-ci.

### Fichiers desktop : positionnement de votre application dans les menus du bureau

Pour lancer des applications à partir de GNOME, les utilisateurs cliquent sur des icônes sur leur bureau ou sélectionnent les applications à exécuter dans un menu. Par conséquent, la première étape pour l'intégration d'un programme existant dans GNOME est de l'enregistrer parmi l'ensemble des applications que les utilisateurs peuvent lancer.

Contrairement à Windows ou MacOS, les menus utilisateurs sous GNOME sont automatiquement construits à partir de la liste des applications enregistrées. Chaque application déclarée indique un ensemble de catégories auquelles elle appartient et le système de configuration du menu les trie et les range. Ce mécanisme suit les standards freedesktop.org d'entrée et de menu desktop.

Bien que très fréquent pour les autres bureaux, la création de vos propres sous-menus spécifiques à votre application n'est pas recommandée. Associez plutôt un seul élément de menu à chaque application fournie. Les éléments supplémentaires tels que les fichiers d'aide, les fichiers LISEZMOI ou les liens vers votre site Web devraient être intégrés dans l'application elle-même.

Sous GNOME et les autres bureaux obéissant aux directives freedesktop.org, une application est enregistrée dans les menus du bureau grâce à un fichier desktop qui est un fichier texte possédant l'extension `.desktop`. Ce fichier contient une liste des configurations de votre application. Le bureau récupère les informations dans ce fichier et les utilise pour :

- positionner l'application dans le menu principal,

- lister l'application dans la boîte de dialogue Lancer une application,

- créer les lanceurs adéquats dans le menu ou sur le bureau,

- associer le nom à la description de l'application,

- utiliser l'icône appropriée,

- reconnaître les types MIME pris en charge pour l'ouverture des fichiers.

Pour ajouter une entrée de menu pour votre application, créez un fichier desktop. Son nom doit être unique et il n'y a pas de limitation de longueur, évitez donc les abréviations et n'hésitez pas à inclure des mots marquants. Cependant, ne mettez pas d'espaces ni de caractères internationaux dans le nom du fichier. Par exemple, « societetoto-peintre-pro.desktop » serait un bon choix de nom de fichier mais « stpp.desktop » en serait un mauvais, tout comme « societetoto peintre pro.desktop ». Le fichier doit être codé en UTF-8 et doit ressembler au modèle suivant :

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

Ces fichiers desktop contiennent des métadonnées à propos de l'application et jouent un rôle central pour l'intégration du programme dans GNOME et les autres bureaux respectant les standards. Le modèle présenté ici est le plus basique qui soit. Le fichier peut être traduit dans d'autres langues afin que le nom de votre application puisse apparaître dans la langue maternelle de l'utilisateur.

Placez ce fichier dans le répertoire `/usr/share/applications` afin que celui-ci soit accessible par tout le monde ou dans `~/.local/share/applications` si vous souhaitez qu'il ne soit accessible qu'à un seul utilisateur. Celui qui sera utilisé dépend du fait que votre application soit installée pour tout le système ou bien dans le dossier personnel d'un utilisateur. GNOME surveille les modifications de ces répertoires, donc une simple copie du fichier au bon emplacement est suffisant pour le faire enregistrer par le bureau.

Notez que l'emplacement `~/.local/share/applications` n'est pas surveillé par les versions de GNOME antérieures à la version 2.10 ou sous Fedora Core Linux antérieur à la version 2.8. Ces versions de GNOME suivent le standard vfolder qui est maintenant déconseillé et par conséquent les fichiers de bureau doivent être installés dans `~/.gnome2/vfolders/applications`. Cet emplacement n'est pas pris en charge par GNOME 2.8 sous Fedora Core ni dans les versions amonts de GNOME 2.10, donc pour un maximum de compatibilité avec les bureaux existants, placez le fichier aux deux emplacements.

Notez qu'avec le bureau KDE, il est nécessaire de lancer la commande `kbuildsycoca` pour forcer la mise à jour des menus.

Tous les fichiers desktop actifs doivent respecter le même format. Un exemple minimal de fichier desktop est affiché ici : ex-sample-desktop-file. Le fichier est découpé en sections, chacune commençant par un descripteur de section entre crochets. Dans cet exemple, seule une section est affichée car c'est celle qui est indispensable à l'intégration du programme dans le bureau. Dans chaque section, la partie de la ligne avant le signe égal est la clé alors que la seconde moitié est la valeur. Pour chaque ligne, une explication est fournie dans le tb-desktop-file.

Excepté pour la première ligne servant à identifier le fichier desktop, l'ordre des lignes est sans importance. Dans ex-sample-desktop-file, la ligne `Type=Application` pourrait être la seconde, la cinquème ou la dernière ligne sans incidence sur le résultat.

Cependant, les clés sont sensibles à la casse. `Type=Application` n'est pas identique à `type=Application` ou `TYPE=Application`.

#### Exemple de fichier desktop

    [Desktop Entry]
    Type=Application
    Encoding=UTF-8
    Name=Nom de l'application exemple
    Comment=Une application exemple
    Exec=programme
    Icon=programme.png
    Terminal=false

### Explication ligne par ligne

Ligne | Description
`[Desktop Entry]` | C'est la première ligne de tous les fichiers desktop et l'en-tête de la section identifiant le bloc de paires clé-valeur associé au bureau. Elle est nécessaire pour que le bureau reconnaisse le fichier de manière correcte.
`Type=Application` | Indique au bureau que ce fichier desktop est du type application. Les autres valeurs possibles pour cette clé sont `Link` et `Directory`.
`Encoding=UTF-8` | Indique le codage du contenu de ce fichier desktop.
`Name=Nom de l'application exemple` | Nom de l'application pour le menu principal et tous les lanceurs.
`Comment=Une application exemple` | Décrit l'application et est utilisé comme infobulle.
`Exec=programme` | La commande qui lance l'application à partir d'un shell. Elle peut posséder des paramètres.
`Icon=programme.png` | Le nom de l'icône associée à l'application.
`Terminal=false` | Indique si l'application doit s'exécuter dans un terminal.

#### Lancement du programme

Si votre application accepte des paramètres en ligne de commande, vous pouvez indiquer ceux-ci en utilisant les champs montrés dans la tb-exec-params.

#### Variables pour l'exécution

Ajouter... | Correspond à...
`%f` | Un nom de fichier unique.
`%F` | Plusieurs noms de fichier.
`%u` | Une URL unique.
`%U` | Plusieurs URL.
`%d` | Un répertoire unique. Utilisé conjointement à `%f` pour localiser un fichier.
`%D` | Plusieurs répertoires. Utilisé conjointement à `%F` pour localiser des fichiers.
`%n` | Nom de fichier unique sans chemin.
`%N` | Plusieurs noms de fichier sans chemin.
`%k` | Un URI ou un nom de fichier local indiquant l'emplacement du fichier desktop.
`%v` | Nom du dispositif d'entrée.

#### Langues étrangères

Pour créer des noms et des commentaires traduits, des lignes supplémentaires pour chaque version traduite doivent être ajoutées. Par exemple, pour ajouter une version suédoise du commentaire, ajouter la ligne suivante :

`Comment[sv]=Exempelprogramnamn`

Il n'y a aucune limite au nombre de traductions dans le fichier.

Comme il est lourd de maintenir une longue liste de traductions dans un fichier, une meilleure solution pour créer ces traductions est d'utiliser le paquet intltool. Consultez les pages man de intltool-extract et de intltool-merge pour plus d'informations.

#### Références

Spécification des entrées desktop — Spécifications pour la création d'un fichier desktop.

### Installation d'icônes

Dans le fichier ex-sample-desktop-file, nous avons indiqué comme icône pour cette application le fichier ``programme.png``. Afin que cela fonctionne, il faut placer ce fichier icône dans le bon répertoire.

Le bureau recherche les icônes dans le sous-répertoire du thème choisi dans `/usr/share/icons/`. Les icônes du programme doivent être au moins disponibles avec une résolution de 48x48 pixels. Placez l'icône dans `/usr/share/icons/hicolor/48x48/apps/`. Il s'agit du répertoire dans lequel le bureau recherche s'il n'y a pas d'icône pour votre programme dans le thème sélectionné. Si vous possédez des icônes à thème, placez-les dans les répertoires appropriés.

Pour intégrer visuellement au mieux votre application au bureau GNOME tout en lui conservant un aspect visuel natif si elle est utilisée sous KDE, Windows XP ou Mac OS X, suivez les Conseils pour le style Tango lorsque vous réalisez vos graphismes. Le document explique divers aspects de la conception d'icônes dont les couleurs, l'éclairage et les tailles. Quelques flux de travaux et des tutoriels en vidéo sont également fournis.

#### Références

Spécification de thème d'icônes — Décrit comment installer et concevoir des icônes en respectant un thème.

Spécification pour la dénomination des icônes — Fournit un schéma canonique pour la dénomination des fichiers icône.

Conseils pour le style Tango — Donne des explications sur la manière de concevoir artistiquement des icônes propres et « multi-plateformes ».

### Ajout de types MIME

Si votre application peut ouvrir des types MIME spécifiques, vous devez le faire savoir au bureau dans le fichier desktop. Par exemple, si votre application accepte les fichiers PNG, ajoutez la ligne suivante dans votre fichier desktop :

    MimeType=image/png

Des types MIME supplémentaires peuvent être ajoutés en séparant les différents types par des points-virgules.

Le système connaît déjà un grand nombre de types MIME. Cependant, si vous en créez un vous-même, vous devez faire enregistrer votre type MIME dans la base de données MIME. Dans le répertoire `/usr/share/mime/packages/`, créez un fichier XML respectant le format de l'ex-mime-xml.

#### Exemple de fichier pour enregistrer un nouveau type MIME

    <?xml version="1.0" encoding="UTF-8"?>
    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
       <mime-type type="application/x-exemple">
         <comment>Exemple de type de fichier </comment>
         <magic priority="50">
           <match value="chaine_de_recherche" type="string" offset="10:140"/>
         </magic>
         <glob pattern="*.nouvelle_extension"/>
       </mime-type>
    </mime-info>

Dans cet exemple, remplacez l'exemple de type MIME par le nom de votre type MIME. La section magic recherche dans les fichiers la chaîne de recherche pour faire l'identification. La ligne glob utilise le suffixe des noms de fichiers pour l'identification.

Parce que la commande `magic` oblige l'ordinateur à ouvrir les fichiers pour rechercher la chaîne, la commande `glob` est préférable.

Une fois que votre nouveau type MIME est correctement décrit dans le fichier, tapez ce qui suit dans un terminal :

    update-mime-database /usr/share/mime

Pour plus d'informations sur la manière de faire un bon choix d'extension MIME et d'enregistrer votre type MIME, consultez le site de l'IANA.

#### Références

Spécification des informations MIME partagées — Décrit en détails le système de déclaration MIME.

## Intégration plus complète avec le Bureau

Ce chapitre contient une liste de choses à faire pour permettre à votre application une intégration dans GNOME meilleure que le strict minimum. Par exemple, GNOME est capable de fournir un retour à l'utilisateur pendant que l'application est lancée : vous trouverez comment activer ce retour à la startup-notification. Si votre logiciel crée des documents ou d'autres données « imprimables », vous pouvez installer un utilitaire pour la création de vignettes pour permettre au gestionnaire de fichiers de GNOME de créer des vignettes spécifiques à votre programme.

### Notification au démarrage

Bien que les champs detaillés à la desktop-files fournissent suffisamment d'informations pour que le bureau reconnaisse votre programme, il existe d'autres champs qui peuvent être utiles dans votre cas particulier. L'un de ces champs est celui de la notification au démarrage.

Quand la notification de démarrage est activée, le tableau de bord et le curseur indiquent à l'utilisateur que l'application a été lancée. Lorsque l'application apparaît à l'écran, le tableau de bord et le curseur retournent dans leur état normal.

Pour faire savoir au lanceur que votre application prend en charge la notification du démarrage, ajoutez la ligne suivante à votre fichier desktop :

`StartupNotify=true`

Cette commande dans le fichier desktop permet au bureau d'utiliser n'importe quelle notification au démarrage existante pour votre application ou votre toolkit. La plupart des toolkits modernes fonctionnent de manière transparente avec le système de notification. Si vous n'utilisez pas un toolkit moderne, le lien sur les spécifications pour la notification au démarrage vous explique en détail ce dont vous avez besoin pour la mettre en place vous-même.

Indépendemment du toolkit, il y a un type d'applications pour lequel vous devez gérer manuellement les retours. Les applications capables de contrôle à distance (celles qui disent à un processus existant d'ouvrir une nouvelle fenêtre au lieu de lancer un nouveau processus) ne peuvent utiliser le mécanisme intégré. La valeur de l'environnement DESKTOP_LAUNCH_ID doit être transmise par votre application et celle-ci doit notifier l'ouverture de cette fenêtre au système de lancement. Si vous utilisez GTK+, la documentation de `gdk_notify_startup_complete()` contient quelques informations supplémentaires.

#### Références

Protocole de notification au démarrage — Décrit de manière très détaillée comment la notification au démarrage est mise en place dans le système X Window.

### Installation d'un générateur de vignettes

Le gestionnaire de fichiers GNOME, Nautilus, est capable d'afficher dans ses listes de fichiers des petites vignettes adaptées à chaque fichier à la place des icônes génériques. Par exemple, un document d'un traitement de texte peut prendre l'apparence d'une version miniature de la première page du document. Ceci est utile car cela permet aux utilisateurs d'avoir une petite représentation des données consultables dans leurs fichiers, ce qui peut aider à se souvenir du fichier qu'ils recherchent. Il est possible de rendre capable votre application de créer ces vignettes en quelques étapes simples.

Un générateur de vignettes est un programme sans interface graphique dont les valeurs en entrée sont un fichier et une taille en pixels et qui crée une vignette pour ce fichier. GNOME choisit le générateur de vignettes à utiliser sur la base du type MIME du fichier pour lequel il faut générer une vignette. La correspondance entre les types MIME et les générateurs de vignettes est enregistrée comme une série de clés GConf.

Pour chaque type MIME que vous souhaitez prendre en charge, vous devez créer une paire de clés GConf :

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

- Type : booléen. Détermine si ce générateur de vignettes doit être utilisé. Vous pouvez activer ou désactiver chaque générateur individuellement. Lorsque vous installez un nouveau générateur de vignettes, vous devez évidement définir la valeur de cette clé à true (vrai).

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

- Type : chaîne. Il s'agit de la commande que GNOME doit utiliser pour générer une vignette concernant un fichier de type `application@x-toto`. Par exemple, la valeur pourrait être « `application-x-toto-vignette %i %o %s` ». Voir ci-dessous pour une explication des symboles pourcentage.

Par conséquent, chaque type MIME nécessite deux clés GConf (`enable` et `command`) sous le même chemin. Le nom du chemin peut être obtenu à partir du nom du type MIME en substituant un « `/` » par un « `@` ». Par exemple, un générateur de vignettes pour le type `image/x-mon-format` nécessite deux clés : `/desktop/gnome/thumbnailers/image@x-mon-format/enable` et `/desktop/gnome/thumbnailers/image@x-mon-format/command`.

Dans la clé `command`, GNOME cherche les séquences avec pourcentage et les remplace par leur valeur réelle :

`%i` | Nom du fichier d'entrée. C'est le fichier que votre générateur de vignettes doit lire.
`%u` | URI d'entrée. Si votre générateur de vignettes peut prendre en charge des URI au lieu des noms de fichiers standards, utilisez `%u` au lieu de `%i`.
`%o` | Nom du fichier de sortie. C'est sous ce nom que votre générateur de vignettes doit écrire l'image vignette au format PNG.
`%s` | Taille de la vignette sous la forme d'un entier unique. Par exemple, s'il s'agit de `128`, cela signifie que votre programme de création de vignettes doit fournir une image pas plus grande que 128x128 pixels.

Soit `%i` soit `%u` doit apparaître dans votre commande et `%o` est également obligatoire. Le terme `%s` est optionnel mais il est recommandé que votre générateur de vignettes y prête attention.

#### Informations supplémentaires

Comme paramètre de configuration supplémentaire, vous pouvez activer la clé booléenne `/desktop/gnome/thumbnailers/disable_all` pour désactiver la génération de toutes les vignettes.

## Liste de contrôle pour l'intégration

Cet appendice fournit une liste de contrôle des diverses tâches présentées dans ce guide. Vous pouvez utiliser cette liste de contrôle pour vous assurer que votre logiciel est intégré au bureau GNOME au moins à un niveau très élémentaire et également comme ressource pour planifier la continuation de votre travail d'intégration.

1. Est-ce que votre programme apparaît dans les menus du tableau de bord GNOME ?

2. Est-ce que votre programme possède une icône pour les menus du tableau de bord ou du bureau ? Dans ce cas, possèdent-elles des tailles pré-rendues et une version SVG redimensionnable ?

3. Si votre programme peut charger et enregistrer des fichiers, est-ce que les types MIME gérés sont enregistrés ?

4. Est-ce que votre programme fournit des icônes MIME pour le gestionnaire de fichiers ?

5. Est-ce que votre programme prend en charge la notification au démarrage afin que GNOME puisse fournir un retour à l'utilisateur pendant que l'application est chargée ?

6. Si votre programme crée des documents « imprimables », est-ce qu'il installe un générateur de vignettes utilisable par le gestionnaire de fichiers ?

## Remerciements

Un grand merci à Jakub Steiner pour avoir fourni une très belle feuille de style CSS pour la version HTML de ce guide !