Le Manuel de Programmation de KDevelop: Utilisation du Système de Fichiers dans les Projets KDevelop

Page suivante Page précédente Table des matières

### 14. Utilisation du Système de Fichiers dans les Projets KDevelop

Le chapitre précédent couvrait le standard du Système de Fichiers de KDE, et celui-ci traite de ce que vous avez à faire pour utiliser ce système de fichiers. Un projet KDE utilise le système de fichiers au moins pour les procédures d'installation ; nous parlerons donc des paramètres d'installation des fichiers de votre projet. Votre application peut utiliser des fichiers installés par la suite, il est donc important de savoir comment récupérer le chemin relatif par le standard. Cela permet à votre application de travailler où que soit le système de fichier KDE et évite d'avoir à coder en dur les informations sur les fichiers.

### 14.1 Accéder à des Fichiers pendant l'Exécution

Après l'installation de votre projet par les utilisateurs, votre application peut avoir besoin d'informations sur les fichiers pendant l'exécution. Lors de la période de développement, vous rencontrerez au moins une erreur au moment où vous lancerez votre application dans l'environnement KDevelop : dans "Aide"-"Contenu" ou en appuyant sur la touche F1, le manuel de l'application sera manquant. Cela se manifeste par un message indiquant que le fichier index.html est introuvable - si vous n'avez pas installé votre application dans votre système de fichiers KDE. Votre application demande à KDEHelp d'ouvrir votre page d'index en cherchant le répertoire d'installation à travers les méthodes de `KApplication` pour accéder au système de fichiers, nous allons donc regarder ce que `KApplication` propose et examiner quelques exemples d'utilisation. D'autres classes de `KDE-Core`, telles que `KIconLoader` et `KLocale`, font aussi usage du système de fichier KDE ; nous en reparlerons plus loin.

### 14.2 Méthodes de KApplication

La classe KApplication offre les méthodes suivantes pour accéder au système de fichiers KDE :

> `

>     void invokeHTMLHelp ( QString aFilename, QString aTopic ) const
>     static const QString& kde_htmldir ()
>     static const QString& kde_appsdir ()
>     static const QString& kde_icondir ()
>     static const QString& kde_datadir ()
>     static const QString& kde_localedir ()
>     static const QString& kde_cgidir ()
>     static const QString& kde_sounddir ()
>     static const QString& kde_toolbardir ()
>     static const QString& kde_wallpaperdir ()
>     static const QString& kde_bindir ()
>     static const QString& kde_configdir ()
>     static const QString& kde_mimedir ()
>     static QString localkdedir ()
>     static QString localconfigdir ()
>     static QString findFile ( const char *file )

> `

Les méthodes sont généralement utilisées avec l'instance de `KApplication` de votre application, où `KApplication` offre une macro `kapp` destinée à recevoir le pointeur :

#define kapp KApplication::getKApplication()

Les méthodes sont donc généralement utilisées de la façon suivante :

> `

>     QString sounddir=kapp->kde_sounddir();

> `

Cet exemple enregistre le chemin du répertoire son de KDE sous forme d'une `QString`, où vous ajouterez par exemple le nom d'un fichier son. Vous pouvez ensuite utiliser cette information et jouer un fichier son qui se trouve là. Vous devriez toujours tester l'existence d'un fichier en utilisant la méthode `exists()` de la classe `QFileInfo`.

Au sein de ces méthodes,

> `

>     void invokeHTMLHelp( QString aFilename, QString aTopic ) const [public]

> `

occupe une place privilégiée, puisqu'elle sert à appeler l'aide de KDE. Généralement, vous devriez l'employer partout où l'utilisateur peut avoir besoin d'aide, par exemple lorsqu'on lui présente une boîte de dialogue. La touche F1 ne servira pas à afficher le contenu de l'aide, mais la page d'aide correspondante. Pour en faire bon usage, ajoutez un bouton "Aide" à votre boîte de dialogue et créez un slot à connecter au signal `pressed()`. Dans cette méthode, utilisez `invokeHTMLHelp()` avec la page et le sujet correspondants ; au cas où la documentation de votre application n'est pas terminée, laissez cette section vide afin de la compléter par la suite.

La documentation de `KApplication` dit :

Appelle le visualiseur d'aide HTML kdehelp.

Paramètres : aTopic : cela permet l'aide contextuelle. Sa valeur sera concaténée au nom de fichier, précédé d'un "#" (dièse).

aFilename : le nom du fichier à charger. Son emplacement est déterminé automatiquement selon le KFSSTND. Si aFilename est vide, on utilise le nom logique de l'application (appname) suivi de .html.

Les méthodes de `KApplication` extrairont les chemins suivants :

> `

>     kde_htmldir()         kdedir()/share/doc/HTML         Renvoie le répertoire où KDE enregistre
>                                                           sa documentation HTML

>     kde_appsdir()         kdedir()/share/applnk           Renvoie le répertoire où les applications KDE
>                                                           enregistrent leur fichier .kdelnk

>     kde_icondir()         kdedir()/share/icons            Renvoie le répertoire où les icônes KDE sont stockées

>     kde_datadir()         kdedir()/share/apps             Renvoie le répertoire où les applications KDE
>                                                           enregistrent leurs données propres

>     kde_localedir()       kdedir()/share/locale           Renvoie le répertoire où les information relatives aux pays
>                                                           (comme les messages traduits par exemple) sont enregistrées

>     kde_cgidir()          kdedir()/cgi-bin                Renvoie le répertoire où sont stockés les scripts cgi

>     kde_sounddir()        kdedir()/share/sounds           Renvoie le répertoire où les données sonores sont stockées.
>                                                           Ce répertoire est destiné aux sons spécifiques à KDE.
>                                                           Les données sonores des applications devraient aller
>                                                           dans le répertoire kde_datadir()

>     kde_toolbardir()      kdedir()/share/toolbar          Renvoie le répertoire où les icônes de barres d'outils sont stockées

>     kde_wallpaperdir()    kdedir()/share/wallpapers       Renvoie le répertoire où les fonds d'écran KDE sont stockés

>     kde_bindir()          kdedir()/bin                    Renvoie le répertoire où les binaires des applications KDE sont stockés

>     kde_configdir()       kdedir()/share/config           Renvoie le répertoire où les fichiers de configuration sont stockés

>     kde_mimedir()         kdedir()/share/mimelnk          Renvoie le répertoire où les types MIME sont stockés

>     localkdedir()         $HOME/.kde                      Renvoie le répertoire de base de KDE

>     localconfigdir()      $HOME/.kde/share/config         Renvoie le répertoire de configuration local de KDE

> `

Pour rechercher un fichier particulier, utilisez `findFile(const char *file)` qui recherchera parmi plusieurs chemins du Système de Fichiers de KDE :

1. $KDEDIR
2. $KDEPATH
3. "[KDE Setup]:Path=" entrée dans un fichier de configuration

Si le fichier est introuvable, la méthode isEmpty() de la classe QString renverra True (Vrai)

### 14.3 Les Méthodes de KIconLoader

QPixmap loadIcon ( const QString &name, int w = 0, int h = 0 )

QPixmap reloadIcon ( const QString &name, int w = 0, int h = 0)

QPixmap loadMiniIcon ( const QString &name , int w = 0, int h = 0 )

QPixmap loadApplicationIcon ( const QString &name, int w = 0, int h = 0 )

QPixmap loadApplicationMiniIcon ( const QString &name, int w = 0, int h = 0 )

bool insertDirectory ( int index, const QString &dir_name )

### 14.4 Configurer l'Installation des Fichiers

Nous avons vu plus haut où les applications KDE devraient placer leurs fichiers et comment accéder à ceux-ci pendant l'exécution, nous allons maintenant voir comment régler les propriétés des fichiers correctement afin qu'ils s'installent au bon endroit. Les Makefiles supportent un ensemble de macros permettant d'installer vos fichiers dans le Système de Fichiers de KDE, celles-ci doivent être utilisées pour configurer l'installation des fichiers.

Pour définir les propriétés, ouvrez votre projet et sélectionnez "Projet"-"Propriétés du Fichier" ce qui ouvrira la boîte de dialogue des Propriétés du Fichier. Celle-ci apparaîtra si vous sélectionnez un nom de fichier actuellement inclus dans le projet. Tout d'abord, un fichier a un type, qui peut être l'un des suivants :

- HEADER : spécifie un fichier comme fichier d'en-tête
- SOURCE : spécifie un fichier comme fichier source
- SCRIPT : spécifie un fichier comme fichier script
- DATA : spécifie un fichier comme fichier de données, qui s'installe généralement comme une icône ou une documentation HTML
- PO : spécifie un fichier comme fichier de traduction
- KDEV_DIALOG : spécifie un fichier comme fichier de boîte de dialogue destiné à être interprété par la bibliothèque des boîtes de dialogue

Par la suite, un fichier est inclus dans le projet, si "Inclure dans la Distribution" est coché. Cela permet de s'assurer que le fichier sera inclus dans l'archive tar ou le paquetage.

Si un fichier doit être installé, vous devez activer "Installer". Cela permettra de fixer le chemin d'installation pour le fichier sélectionné, là où le nom du fichier est déjà inséré.

Maintenant, comme nous l'avons vu plus haut, le Makefile dispose déjà d'un ensemble de macros pour le Système de Fichiers Standard. Celles-ci sont utilisées pour fixer le chemin d'installation et s'assurer que les fichiers vont réellement se retrouver sur le système de fichiers de KDE et pas ailleurs. Les macros qui peuvent être utilisées doivent être encadrées de parenthèses et sont précédées d'un dollar. Lorsque le script configure construit les Makefiles sur le système de l'utilisateur final, il va déterminer les valeurs pour ces macros qui correspondent au vrai nom de répertoire et étendra la macro Makefile.am vers sa vraie destination.

Si vous regardez un projet d'application KDE standard, vous remarquerez dans les propriétés de votre fichier `index.html` qu'il utilise déjà une macro permettant de déterminer où il doit aller :

$(kde_htmldir)/en/kscribble/index.html

Cela signifie que make doit installer le fichier index.html dans le répertoire kde-html, sous-répertoire en pour English (Anglais), sous-répertoire de l'application et le nom du fichier. Vous pourriez tout aussi bien utiliser un autre nom de fichier si vous souhaitez le renommer à la destination de l'installation.

Pour la destination des binaires vous devez pour le moment éditer le Makefile.am du projet si vous souhaitez que la destination ne soit pas la section "Application" du tableau de bord :

APPSDIR = $(kde_appsdir)/Applications

Valeurs possibles (selon le Standard du Système de Fichiers de KDE) :

- Applications
- Games
- Graphics
- Internet
- Multimedia
- Settings
- System
- Utilities

Si vous ne précisez pas de répertoire, votre lien ira directement à la racine du tableau de bord.

La liste suivante contient les macros qui peuvent être utilisées lors de la configuration de l'installation des fichiers :

> `

>     kde_htmldir       Où vos docs doivent aller. (contient un sous-répertoire par langue)
>     kde_appsdir       Où le fichier application (.kdelnk) doit aller.
>     kde_icondir       Où votre icône doit aller.
>     kde_minidir       Où votre mini-icône doit aller.
>     kde_datadir       Où installer les données de votre application. (Utilisez un sous-répertoire)
>     kde_locale        Où les traductions doivent aller. (contient un sous-répertoire par langue)
>     kde_cgidir        Où les exécutables cgi-bin doivent aller.
>     kde_confdir       Où les fichiers de configuration doivent aller.
>     kde_mimedir       Où les types MIME doivent aller.
>     kde_toolbardir    Où les icônes de barres d'outils doivent aller.
>     kde_wallpaperdir  Où les fonds d'écran doivent aller.

> `

Utilisez ces macros avec les sous-répertoires et les noms de fichiers adéquats pour configurer les propriétés d'installation. Par défaut, la destination des fichers de documentation HTML, du fichier kdelnk, de l'Icône, de la Mini-icône et des traductions est déjà configurée ; vous n'avez donc pas à faire de modification, puisque ceci a été réalisé par l'assistant d'application de KDevelop.

### 14.5 Organiser les Données du Projet

Un autre problème apparaît souvent dans la création d'un projet, si le développeur souhaite inclure des données supplémentaires qui devront être installées avec le projet. Vous savez où vous voudrez les installer, mais comment les organiser dans l'arborescence du source ?

Il est de bon conseil de rassembler toutes les données dans des répertoires qui correspondent plus ou moins aux Standards du Système de Fichiers de KDE. Prenons par exemple les icônes de barre d'outils dont peut avoir besoin votre application. Créer ces icônes dans le répertoire principal du projet n'est pas une très bonne idée car elles seront difficiles à retrouver avec un visualiseur de fichier externe et les supprimer serait plus ardu. Créez donc votre icône avec "Fichier"-"Nouveau" et choisissez le sous-répertoire `toolbar` ; si ce répertoire n'existe pas, il peut facilement être créé avec la boîte de dialogue "sélection du répertoire". Les icônes existantes peuvent être copiées et incluses dans le projet avec "Projet"-"Ajouter fichier(s) existant(s)", où vous devez choisir le fichier et sa destination. Lorsque vous sélectionnez le répertoire destination, vous pouvez créer le sous-répertoire `toolbar` avant tout dans la boîte de dialogue. Quand vous avez terminé, appuyez sur OK et les fichiers seront copiés et inclus dans le projet.

À titre d'exemple, une icône de barre d'outils peut aller au chemin suivant :

$(kde_datadir)/<appname>/toolbar/<youricon>.xpm

Les images et les icônes supplémentaires non utilisées comme les icônes de barre d'outils peuvent être stockées dans un sous-répertoire pics au lieu de toolbar.

### 14.6 Le Fichier `kdelnk`

Le fichier <appname>.kdelnk actuellement inclu dans votre projet s'installera dans la structure du tableau de bord de KDE. Vous pourriez penser qu'il est déjà créé, et que vous n'auriez pas d'autres informations à apporter. Malgré les qualités avancées de KDevelop pour vous aider à créer, programmer et concevoir des applications, il ne peut pas déterminer le but exact de votre application - et c'est cette information que vous devez ajouter au fichier kdelnk. Comme c'est un fichier texte, sélectionnez le depuis le RFV ou le LFV ; il sera ouvert dans la fenêtre Fichier En-Tête/Ressources.

Le fichier kdelnk par défaut ressemblera à ça :

> `

>     # KDE Config File
>     [KDE Desktop Entry]
>     Type=Application
>     Exec=kscribble
>     Icon=kscribble.xpm
>     DocPath=kscribble/index.html
>     Comment=
>     Comment[de]=
>     Terminal=0
>     Name=kscribble
>     Name[de]=kscribble

> `

Il contient déjà la configuration de base pour les données propres à l'application comme l'icône, le nom du binaire, le nom de l'application, etc. Vous pouvez voir que la section Comment (Commentaire) est toujours vide. Vous devez ajouter la bulle d'aide qui sera affichée lorsque le curseur de la souris passera au dessus de l'icône sur le bureau ou dans le tableau de bord. Si scribble était un petit programme de dessin, vous écririez par exemple :

> `

>     Comment=Un simple programme de dessin

> `

Chaque ligne de commentaire contiendra par la suite la même description traduite dans la langue symbolisée par les crochets. Demandez aux traducteurs d'ajouter une bonne traduction dans leur langue maternelle ou incluez le fichier kdelnk lorsque vous demandez à ce que le fichier po soit traduit ; la même remarque s'applique au nom de l'application fixée dans les lignes Name.

> Pour plus d'informations sur le but du fichier kdelnk, en particulier pour l'interprétation de la ligne de commande, voir Référence des Bibliothèques KDE

Page suivante Page précédente Table des matières