par Andrew Burton traduit par Renaud Guezennec
<adb@iinet.net.au>
| Historique |
| Révision 1.1 |
6 septembre 2007 |
RG |
| Ajout d’une copie de makefile et traduction française V0.5. |
| Révision 1.0 |
20 Decembre 2005 |
ADB |
| Ajout du lien pour télécharger l’applet. |
| Revision 0.02 |
15 Avril 2004 |
ADB |
| Version basé sur les retours de la liste de diffution: gnome-doc-list mailing. Utilisation de Docbook 4.2, amélioration de la section sur la compilation, Utilisation apropriée des marqueurs pour la FAQ, Modification du code. |
| Revision 0.01 |
13 Avril 2004 |
ADB |
| Version initiale. |
Mise en bouche
Les applets Gnome sont de petites applications qui s’intègrent à Gnome. Elles fournissent des fonctionnalités simples et utiles pour l’utilisateur. Il y a quelques différences avec l’écriture d’une application Gnome normale. Le but de ce tutorial est d’expliquer; comment créer un petit applet.
Table des matières
- Qu’est-ce qu’un Applet?
- Construire l’infrastructure
- Le rendre intéressant
- Création d’un menu contextuel
- Foire aux Questions
- Conclusion
- plus informations
Qu’est-ce qu’un Applet?
Dans Gnome, un applet est une petite application destinée à s’intégrer au tableau de bord de Gnome, donnant un accès rapide et facile sur un contrôle, comme un contrôleur de volume, un indicateur d’activité réseau, ou encore une information météorologique.
Les applets nécessitent la bibliothèque “libpanel-applet” pour s’exécuter et si vous souhaitez en développer un, vous aurez besoin d’installer le paquet de développement (souvent distinguer par -dev ou -devel en fin, cela dépend de votre distribution). En raison de leur symbiose avec Gnome, ils sont souvent moins complexes et plus facile à maîtriser pour un programmeur débutant dans l’environnement Gnome.
Après une installation de Gnome, sur un ordinateur de bureau, vous aurez la date et un applet de contrôle du volume dans le coin supérieur droit. Sur un ordinateur portable, vous trouverez aussi une barre d’état de votre batterie.
Construire l’infrastructure
Sur un plan technique, Les applets sont des contrôles “Bonobo” intégrés au tableau de bord de Gnome. Cela signifie qu’il y a plusieurs différences avec un programme Gnome classique. La première différence est que chaque applet nécessite un fichier avec l’extension ‘.server’, qui contient la description pour le rendre compréhensible par “Bonobo”. Si vous ne comprenez pas très bien ceci ne vous inquiétez pas. La seule chose que le développeur a à faire est d’éditer le fichier, et remplacer certains champs par les spécificités de son applet.
Voici un exemple d’un fichier “.server” appellé “sample.server”.
Example 1. Un exemple de fichier .server
<oaf_info>
<oaf_server iid="OAFIID:ExampleApplet_Factory" type="exe"
location="/usr/lib/gnome-panel/myexample">
<oaf_attribute name="repo_ids" type="stringv">
<item value="IDL:Bonobo/GenericFactory:1.0"/>
<item value="IDL:Bonobo/Unknown:1.0"/>
</oaf_attribute>
<oaf_attribute name="name" type="string" value="Example Applet Factory"/>
<oaf_attribute name="description" type="string"
value="Factory to create the example applet"/>
</oaf_server>
<oaf_server iid="OAFIID:ExampleApplet" type="factory"
location="OAFIID:ExampleApplet_Factory">
<oaf_attribute name="repo_ids" type="stringv">
<item value="IDL:GNOME/Vertigo/PanelAppletShell:1.0"/>
<item value="IDL:Bonobo/Control:1.0"/>
<item value="IDL:Bonobo/Unknown:1.0"/>
</oaf_attribute>
<oaf_attribute name="name" type="string" value="Example Applet"/>
<oaf_attribute name="description" type="string" value="An example applet"/>
<oaf_attribute name="panel:category" type="string" value="Amusements"/>
<oaf_attribute name="panel:icon" type="string" value="myicon.png"/>
</oaf_server>
</oaf_info>
Il y a quelques trucs à noter. Premièrement, il faut définir l’emplacement de l’exécutable, définie dans l’attribut “location” de oaf_server, N’oublier pas d’indiquer le type en “exe”. Dans cet exemple, notre fichier exécutable s’appelle myexample et est placé dans /usr/lib/gnome-panel/ . (Emplacement traditionnel de tous les applets) Secondement, nous définissons le nom de notre ‘applet Factory’ , ExampleApplet_Factory. Nommer votre .serveur et placer le dans /usr/lib/bonobo/servers/.
Après avoir ajouter le .server dans le dossier, nous pouvons commencer à écrire le code source du notre applet. Voici, un exemple simple: un applet “Hello World”.
Exemple 2. Hello World!
#include <string.h>
#include <panel-applet.h>
#include <gtk/gtklabel.h>
static gboolean
myexample_applet_fill (PanelApplet *applet,
const gchar *iid,
gpointer data)
{
GtkWidget *label;
if (strcmp (iid, "OAFIID:ExampleApplet") != 0)
return FALSE;
label = gtk_label_new ("Hello World");
gtk_container_add (GTK_CONTAINER (applet), label);
gtk_widget_show_all (GTK_WIDGET (applet));
return TRUE;
}
PANEL_APPLET_BONOBO_FACTORY ("OAFIID:ExampleApplet_Factory",
PANEL_TYPE_APPLET,
"The Hello World Applet",
"0",
myexample_applet_fill,
NULL);
La compilation ce fait avec cette commande:
bash~$ gcc $(pkg-config --cflags --libs libpanelapplet-2.0) -o myexample my_applet.cPour un Makefile, voici mon exemple:
PKGCONFIG = /usr/bin/pkg-config
CFLAGS = $(shell $(PKGCONFIG) –cflags libpanelapplet-2.0)
LDFLAGS = $(shell $(PKGCONFIG) –libs libpanelapplet-2.0)
OPTION = -g -Wall
all:myexample
myexample: my_applet.c
gcc $(OPTION) $(CFLAGS) $(LDFLAGS) -o myexample my_applet.cinstall:myexample sample.server
cp myexample /usr/lib/gnome-applets/
cp sample.server /usr/lib/bonobo/servers/
clean:
rm /usr/lib/gnome-applets/myexampleNoter que la variable d’environnement PKG_CONFIG_PATH doit contenir le chemin vers libpanelapplet-2.0.pc. Si vous obtenez l’erreur suivante:
Package libpanelapplet-2.0 was not found in the pkg-config search path.
Perhaps you should add the directory containing `libpanelapplet-2.0.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libpanelapplet-2.0' found
Vous avez besoin d’exécuter les commandes suivantes:
bash$ PKG_CONFIG_PATH=/usr/lib/pkgconfig
bash$ export $PKG_CONFIG_PATH
Placer l’exécutable dans le répertoire /usr/lib/gnome-panel/ (souvenez-vous que le fichier .server doit être défini). Notre applet sera représenté (dans la fenêtre d’ajout d’applet) par l’icone myicon.png, qui doit être placé dans /usr/share/pixmaps/.
Nous ajoutons notre applet au tableau de bord Gnome par un clique droit sur la barre de Gnome, et choisissez “ajouter au tableau de bord…” dans la rubrique “Amusements”: Example Applet.
Comment Gnome fait pour lier le code C et le fichier .server? Le lien se fait grâce a l’appel de la fonction PANEL_APPLET_BONOBO_FACTORY. Cet appel utilise un nombre important de paramètres, et le prototype de la fonction est:
PANEL_APPLET_BONOBO_FACTORY (iid, type, name, version, callback, data)
Le premier paramètre spécifie le OAFIID, c’est l’identifiant pour Bonobo, et il devrait être le nom que vous avez défini dans le fichier .server, “ExampleApplet_Factory”. Le deuxième paramètre définit le type; pour un applet donc PANEL_TYPE_APPLET. Le troisième paramètre est le nom qui s’affichera lorsque vous exécuterez l’interface Bonobo. Le quatrième est le version. Nous devons aussi donner la fonction à exécuter,La fonction d’entrée dans notre code source est myexample_applet_fill(). Pour le dernier paramètre, nous spécifions l’envoi à la méthode d’entrée n’importe quel type de données. Dans notre exemple,nous ne passons rien ainsi nous mettons “NULL” comme valeur de paramètre.
Dans notre code, la définition de la méthode pour myexample_applet_fill () est:
myexample_applet_fill (applet, iid, data)
Noter que le nom de cette méthode doit être présent dans la définition de la “factory”.
Premièrement, nous testons que l’iid corresponde avec l’iid passé en paramètre. Si ce n’est pas le cas, nous annulons la création de l’applet, dans les autres cas, nous continuons avec le reste de la méthode.
if (strcmp (iid, "OAFIID:ExampleApplet") != 0)
return FALSE;
Il est préférable pour la fonction “main” qu’elle n’aie pas beaucoup de fonctionnalités. Assurez-vous que le OAFIID corresponde avec l’identifiant de Bonobo. Dessiner un ‘label’ dans l’applet, et afficher le. Facile mais pas vraiment utile. Après avoir fait tout cela, notre applet existe. Si vous faites un clique droit dessus, vous avez trois possibilités : Enlever l’applet, le déplacer et le fixer.
Le rendre intéressant
Nous allons changer le ‘widget’ avec le texte “Hello World” par un petit image. D’abord ajoutons une “GtkImage” dans l’applet:
image = gtk_image_new_from_file ("/usr/share/pixmaps/mypicture.png");
Alors, les widget GtkImage ne peuvent recevoir d’évènement (c’est vrai) et ainsi ils ne peuvent pas réagir vis à vis d’un clique de souris, Nous avons besoin de mettre le GtkImage dans GtkEventBox:
event_box = gtk_event_box_new ();
gtk_container_add (GTK_CONTAINER (event_box), image);
g_signal_connect (G_OBJECT (event_box), "button_press_event",
G_CALLBACK (on_button_press),
image);
N’oublier pas de supprimer le code pour la création du label avec “Hello World”.
Maintenant, nous avons faire que l’applet réagisse quand nous cliquons sur l’icône du “tableau de bord”. Bien sûr, nous avons besoin d’une fonction qui intercepte le clique de souris:
Example 3. Traiter un clique de souris dans votre applet.
static gboolean
on_button_press (GtkWidget *event_box, GdkEventButton *event,
gpointer data)
{
static int window_shown;
static GtkWidget *window, *box, *image, *label;
/* Don't react to anything other than the left mouse button;
return FALSE so the event is passed to the default handler */
if (event->button != 1)
return FALSE;
if (!window_shown) {
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
box = GTK_BOX (gtk_vbox_new (TRUE, 12));
gtk_container_add (GTK_CONTAINER (window), box);
image = GTK_IMAGE (gtk_image_new_from_file ("/usr/share/pixmaps/mypicture.png"));
gtk_box_pack_start (GTK_BOX (box), image, TRUE, TRUE, 12);
label = gtk_label_new ("Hello World");
gtk_box_pack_start (GTK_BOX (box), label, TRUE, TRUE, 12);
gtk_widget_show_all (window);
}
else
gtk_widget_hide (GTK_WIDGET (window));
window_shown = !window_shown;
return TRUE;
}
Dans la fonction on_button_press() ci-dessus, nous créons une nouvelle fenêtre avec un peu de texte. Quand nous cliquons sur le bouton la fenêtre s’affiche si vous recliquez, elle disparaît.
Içi la capture d’écran de la fenêtre affichée quand on clique sur l’applet avec le bouton gauche de la souris:
Création d’un menu contextuel
Quand on clique avec le bouton droit sur l’icône d’un applet sur le tableau de bord, un menu par défaut s’affiche avec la possibilité de: supprimer l’applet, le déplacer ou le figer. Il est possible d’ajouter quelques options – un bouton d’aide, une fenêtre “à propos” et une fenêtre de préférences.
Pour créer un menu “pop-up”, nous définissons en premier lieu le menu lui même. Vous pouvez le faire avec le code suivant:
static const char Context_menu_xml [] =
"<popup name=\"button3\">\n"
" <menuitem name=\"Properties Item\" "
" verb=\"ExampleProperties\" "
" _label=\"_Preferences...\"\n"
" pixtype=\"stock\" "
" pixname=\"gtk-properties\"/>\n"
" <menuitem name=\"About Item\" "
" verb=\"ExampleAbout\" "
" _label=\"_About...\"\n"
" pixtype=\"stock\" "
" pixname=\"gnome-stock-about\"/>\n"
"</popup>\n";
ou dans un fichier, charger pendant l’exécution avec la fonction panel_applet_setup_menu_from_file (). Les valeurs utilisées ici devrait être simple à comprendre. Nous ajoutons 2 éléments au menu, le nom apparaîtra dans le menu après un clique droit avec une icône ‘stockée’, défini dans GtkStockItem (les Stock sont des éléments présent dans gnomes permettant une internationnalisation facile des applications).
En suite, nous définissons les actions graphiques Bonobo:
static const BonoboUIVerb myexample_menu_verbs [] = {
BONOBO_UI_VERB ("ExampleProperties", display_properties_dialog),
BONOBO_UI_VERB ("ExampleAbout", display_about_dialog),
BONOBO_UI_VERB_END
};
Ceci lie les actions avec leurs fonctions spécifiées ci-dessus, et exécute les fonctions. Autrement dit, quand l’utilisateur choisit “Préférences…” depuis le menu contextuel, votre applet entre dans la fonction display_properties_dialog ().
En fin, nous avons besoin de construire le menu, rassemblons ensemble ces deux étapes:
panel_applet_setup_menu (PANEL_APPLET (myexample->applet),
Context_menu_xml,
myexample_menu_verbs,
myexample);
Notons que le dernier paramètre est un pointeur, qui peut être utilisé dans la fonction de gestion d’un évènement.
Vos gestionnaires d’évènements ont le prototype suivant:
static void
myexample_applet_properties_dialog (BonoboUIComponent *uic,
struct MultiRes *applet) {
/* Construire la fenêtre des propriétes et l'afficher ici */
...
}
Foire aux questions
- 1. Comment débogguer mon applet ? J’utilise souvent des appels à printf () pour voir ce que fait mon code, mais je ne peux pas le faire avec un applet!
- 2. Comment débogguer mon applet ? J’utilise souvent gdb, comment l’utiliser?
- 3.Je n’ai pas d’icône pour mon applet, je ne peux dont pas l’inclure dans le .server. Je ne peux pas trouver mon applet dans la liste des applets disponibles quand j’essaie de l’ajouter à mon tableau de bord.
- 4.Mon applet n’est pas visible dans le menu d’ajout au tableau de bord.
| 1. |
Comment débogguer mon applet ? J’utilise souvent des appels à printf() pour voir ce que fait mon code, mais je ne peux pas le faire avec un applet! |
|
Exécuter votre applet par la ligne de commande /usr/lib/gnome-applet/my_example, Ensuite ajouter le à votre “tableau de bord”, ainsi tous les appels vers les sorties standards seront visibles dans la console (une astuce de Glynn Foster). |
| 2. |
Comment débogguer mon applet ? J’utilise souvent gdb, comment l’utiliser! |
|
Exécuter votre applet par la ligne de commande gdb /usr/lib/gnome-applet/my_example, puis faites ‘run’ dans gdb. Ensuite, ajouter à votre “tableau de bord”, ainsi vous pouvez maintenant utiliser gdb comme vous en avait l’habitude. |
| 3. |
Je n’ai pas d’icône pour mon applet, je ne peux donc pas l’inclure dans le .server. Je ne peux pas trouver mon applet dans la liste des applets disponibles quand j’essaie de l’ajouter à mon tableau de bord. |
|
Les Applets nécessitent une icône pour être afficher dans la listes d’ajout. |
| 4. |
Mon applet n’est pas visible dans le menu d’ajout au tableau de bord. |
|
L’applet est installé dans /usr/local/ par défaut. Gnome le cherche dans /usr. Vous pouvais exécuter ./configure –prefix=/usr pour installer votre applet dans un autre répertoire. Vous aurez besoin de vous fermer la session Gnome et de la rouvrir pour que les changement soit pris en compte. |
Conclusion
Créer un applet n’est pas difficile. Cependant, il peut être aussi complexe que vous le souhaitez. Il est parfois plus raisonnable de créer une application. Exemple: vous désirez ajouter plus de widgets, Utiliser Glade combiné avec libxml sera plus facile pour construire votre IHM(Interface Homme Machine).
Un avertissement important en ce qui concerne l’exemple employé dans ce tutorial. J’ai compilé l’applet par la ligne de commande par simplicité ; pour un vrai applet, employer un fichier makefile. Cela tient compte des particularités matérielles (comme l’emplacement de l’icône), la maintenance n’en sera que plus facile.
Plus d’Information
- Télécharger l’applet d’exemple Voici l’applet créé dans ce tutorial. L’archive (.tar) inclut aussi les ‘makefiles’ appropriés pour configurer et installer votre applet.
- Les applets Gnome sont disponible au téléchargement dans le CVS de gnome sous le répertoire gnome-applets.
- Installer la documentation de la bibliothèque libpanel-applet2 donne une bonne aide (bien qu’incomplète) pour écrire des applets.
- Voici un vieux tutorial pour réaliser des applets avec GTK1.0
Le site des développer Gnome.
- Version originale de ce tutorial: cliquez-ici.
