|
Écrire une applet |
|
Depuis la version 2.1.0 de Cairo-Dock vous pouvez également écrire une applet dans un autre langage que le C.
Rendez vous alors dans la section Contrôlez votre dock avec DBus
Une documentation complète est à la disposition des développeurs
Vous la trouvez à cette adresse : http://doc.glx-dock.org/
Cairo-Dock met à votre disposition un canevas dédié à une écriture rapide et normalisée de ses applets.
Mettons qu'on veuille écrire une applet (appelons-la 'truc'). Rendez vous dans le répertoire 'plug-ins' des sources via SVN. Dedans s'y trouve un script generate-new-applet.sh.
Lancez-le, et répondez aux quelques questions. Voilà, vous avez une applet fonctionnelle !
Pour aller plus loin, regardons les 3 points importants :
Structure de l'applet Arborescence des sources L'arborescence des sources est basique et peut être repompée de n'importe quelle applet déjà existante :
truc ---> configure.ac, Makefile.am
+--> src -> applet-init.c/h, applet-config.c/h, applet-notifications.c/h, etc
+--> data -> truc.conf.in, preview.png, readme.in, etc
+--> po -> Makefile.in.in, LINGUAS, POTFILES.in, *.po
Les noms des fichiers ne sont pas imposés; simplement, respecter ces conventions permet de s'y retrouver tout de suite en lisant une applet qu'on ne connaît pas.
Répertoire des sources Dans ./src nous avons :
- applet-init.c : contient la fonction d'initialisation de l'applet, et la fonction d'arrêt de celle-ci.
- applet-config.c : contient la fonction qui lit le fichier de conf.
- applet-notifications.c : contient les fonctions qui sont appelées lorsque l'applet est notifiée par Cairo-Dock qu'il se passe quelques chose d'intéressant pour elle.
- *.c : les autres peuvent contenir ce que bon nous semble (connexion à un serveur, fonctions de dessins, calculs, etc)
Répertoire des données Dans ./data on trouve :
- preview.png : une image donnant une pré-visualisation de l'applet (affichée dans le panneau de conf de Cairo-Dock à côté de la liste des applets)
- readme.in : un fichier donnant l'auteur de l'applet (vous ), et un bref résumé de celle-ci (le texte sera aussi affiché dans le panneau de conf de Cairo-Dock à côté de la liste des applets)
- truc.conf.in : le fichier de conf de l'applet, qui contient tous les paramètres sur lesquels peut jouer l'utilisateur.
Répertoire des traductions Dans ./po on trouve :
- Makefile.in.in : reprendre à l'identique un déjà existant.
- LINGUAS : la liste des langues disponibles.
- POTFILES.in : la liste des fichiers où on trouve des messages à traduire.
- *.po : des fichiers contenant les traductions de chaque message.
Arborescence de l'installation L'arborescence de l'installation est encore plus simple :
- le contenu du répertoire data est recopié dans /usr/share/cairo-dock/plug-ins/truc
- le plug-in en lui-même se retrouve en /usr/share/cairo-dock/plug-ins/libcd-truc.so
- les fichiers de traduction vont dans /usr/share/locale/$lang/LC_MESSAGES/cd-truc.mo, où $lang = fr, jp, ...
Les fichiers de compil Comme plus haut, prenez ceux existants et remplacez par le nom de votre applet partout où cela est nécessaire
Le configure.ac est composé de plusieurs macros propres à autoconf/automake et de définition de variables :
- AC_INIT : définissez-y concensieusement le numéro de version de votre applet, ainsi que l'auteur de l'applet (vous !), et le nom du pug-in (pour éviter toute collision avec une librairie déjà existante sur votre système, préfixez-le par 'cd-' : cd-truc)
- GETTEXT_PACKAGE : usuellement on mettra le nom de l'applet ('cd-truc'), ce qui fera un fichier de traduction 'cd-truc.mo'
- pkgdatadir : on ecrase la valeur par defaut avec celle donnee par Cairo-Dock pour s'installer dans son répertoire des plug-ins.
- PKG_CHECK_MODULES : listez ici toutes les dépendance de votre module.
- AC_CONFIG_FILES : listez ici tous les fichiers qui seront générés par le configure (Makefile et autres)
Le src/Makefile.am definit les macros liées aux fichiers de l'applets :
- MY_APPLET_SHARE_DATA_DIR : le répertoire où sont installées les données de l'applet (typiquement "/usr/share/cairo-dock/plug-ins/truc").
- MY_APPLET_README_FILE : nom du ficher contenant un bref descriptif de l'applet (typiquement "readme").
- MY_APPLET_PREVIEW_FILE : nom de l'image donnant un aperçu de l'applet (typiquement "preview.png").
- MY_APPLET_CONF_FILE : nom du fichier de conf de l'applet (typiquement "truc.conf").
- MY_APPLET_USER_DATA_DIR : nom du répertoire de l'applet côté utilisateur, dans ~/.cairo-dock/current_theme/plug-ins (typiquement "truc").
- MY_APPLET_VERSION : version de l'applet (par exemple "1.2.3").
- MY_APPLET_GETTEXT_DOMAIN : nom du domaine de traduction de l'applet (typiquement "cd-truc").
- MY_APPLET_DOCK_VERSION : version du dock pour laquelle a été compilée l'applet (par exemple "1.4.7").
Le code de base init CD_APPLET_DEFINITION : "nom de l'applet", version minimale nécessaire du dock).
CD_APPLET_INIT_BEGIN (erreur) ---> lecture du fichier de conf.
- abonnement aux notifications utiles
- définition de variables et structures utiles
CD_APPLET_INIT_END
CD_APPLET_STOP_BEGIN
- désabonnement des notifications.
- mises à zéro des variables, libération de toutes les ressources utilisées.
CD_APPLET_STOP_END
config CD_APPLET_CONFIG_BEGIN ("nom d'étiquette par défaut" ou NULL, "icône par défaut" ou NULL)
parametres = CD_CONFIG_GET_xxx ("nom de groupe", "nom de clé", valeur par défaut);
CD_APPLET_CONFIG_END
notifications CD_APPLET_ABOUT (_D("Brève description de l'applet et de l'auteur"))
CD_APPLET_ON_CLICK_BEGIN
action au clic gauche.
CD_APPLET_ON_CLICK_END
CD_APPLET_ON_BUILD_MENU_BEGIN
CD_APPLET_ADD_SUB_MENU ("étiquette", pSubMenu, CD_APPLET_MY_MENU)
CD_APPLET_ADD_IN_MENU_WITH_DATA ("étiquette", fonction callback, pSubMenu, données)
...
CD_APPLET_ADD_ABOUT_IN_MENU (pSubMenu)
CD_APPLET_ON_BUILD_MENU_END
CD_APPLET_ON_MIDDLE_CLICK_BEGIN
action au clic milieu.
CD_APPLET_ON_MIDDLE_CLICK_END
Coding Convetion Si possible, c'est mieux de suivre les mêmes conventions de code que nous trouvons partout ailleurs dans le code de Cairo-Dock et ses plugins:
- Écrire des commentaires (in English) pour toutes les choses complexes
- Essayer d'utiliser des variables avec un nom explicite, ayant une première lettre donnant un indice sur le type et en évitant les underscores, ex.: bBoolean, cString, pPointer.
- À propos des espaces, n'hésitez pas à en abuser avant d'ouvrir une parenthèse, entre un signe égal, avant un astérisque, etc. et ajouter une nouvelle ligne avant un {, par ex.:
static void _subdock_icon_set_new_name (GldiIcon *pIcon) {
(...)
if (bResult)
{
gchar *cNewName = my_function (pIcon->cName, pIconData);
gldi_icon_set_new_name (pIcon, cNewName);
g_free (cNewName);
}
else
{
(...)
}
}
- Éviter l'utilisation de 'struct' en utilisant un 'typedef'.
- Essayer de ne pas avoir de très longues lignes
Debug Vous pouvez utiliser cette fonction Bash pour démarrer le dock et n'afficher que les messages de log liés à une appletcairo-dock-filter () {
cairo-dock -l debug --colors | sed -n "/$1\// {N;p;}"
}
Une fois dans votre .profile/.bashrc/.zshrc/..., vous pouvez l'utiliser comme ceci: cairo-dock-filter System-Monitor |
|