Tags:    c++ Af: Mikkel Meyer Andersen

Introduktion

Denne artikel vil indeholde en guide til, hvordan man laver sin egen applet til Gnome-panelet (herfra vil det blot blive kaldt applet, men der menes hver gang at det er til et Gnome-panel) i C. Det er forventet, at du kender lidt basal *nix, ved hvad en applet er og samtidig kan en smule XML og C. Hvis du føler dig usikker på om du kan, så læs endelig videre, men hvis de opremsede begreber er som sort magi for dig, er det nok ikke den rigtige artikel at starte med. Som sidebemærkning kan jeg dog hurtigt nævne, at en applet er en lille program, man kan tilføje panelet i Gnome - som f.eks. uret.

Jeg kører selv Debian GNU/Linux, og det er på dette, jeg har testet koden - jeg har ikke prøvet på andre platforme, men der skulle ikke være noget problem på andre *nix'er. Der vil blive brugt et rigtigt eksempel for at lette forståelsen, og gøre det hele lidt mere klart og håndgribeligt. Kort sagt går eksemplet ud på, at jeg ønsker at kunne se tiden i andre tidszoner end min egen i mit panel. Dette eksempel er godt, da det både indeholder lidt parsing af XML i form af konfigurationsfilen (hvilken tidszone og formatet på tiden)

Hello World

Før vi går i gang med selve eksemplet, vil jeg dog lige vise, hvordan man laver en "Hello World"-applet. Det er hovedsageligt taget fra [1], men jeg har alligevel valgt at medtage det her, da jeg synes der mangler et par småting, og for samtidig at holde det på dansk for dem, der har det bedst med det. Derudover skaber det en mere sammenhængende artikel.

Appletter er ikke enkeltstående programmer, og rent teknisk er det noget, der hedder Bonobo kontroller. Det skal du dog ikke spekulere mere over, men du vil støde på navnet Bonobo et par gange (bl.a. i diverse fillokationer).

Som nævnt er appletter ikke enkeltstående programmer, men skal køre i et andet miljø - her er det i Bonobo. For at det kan det, skal Bonobo bruge nogle oplysninger om det, man ønsker at køre for at kunne kalde det ordentligt osv. Det er ene detaljer, du heller ikke skal bekymre dig så meget om - det eneste du skal er at lave en lille fil med bl.a. sti til programmet, navn, beskrivelse osv. Når du først har lavet den en gang, skal der sjældent rettes så meget i den. Et eksempel på en sådan - såkaldt .server-fil - er denne:

<oaf_info>
	<oaf_server iid="OAFIID:HelloWorldApplet_Factory" type="exe"
			location="/home/mikl/coding/applets/helloworld">

		<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="Hello World Applet Factory"/>
		<oaf_attribute name="description" type="string" value="Factory to create the helloworld"/>
	</oaf_server>

	<oaf_server iid="OAFIID:HelloWorldApplet" type="factory"
		location="OAFIID:HelloWorldApplet_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="Hello World Applet"/>
		<oaf_attribute name="name-da" type="string" value="Hello World Applet" />
		<oaf_attribute name="name-en_CA" type="string" value="Hello World Applet" />
		<oaf_attribute name="name-en_GB" type="string" value="Hello World Applet" />
		
		<oaf_attribute name="description" type="string" value="En Hello World applet"/>
		<oaf_attribute name="description-da" type="string" value="En Hello World applet" />
		<oaf_attribute name="description-en_CA" type="string" value="A Hello World-applet" />
		<oaf_attribute name="description-en_GB" type="string" value="A Hello World-applet" />

		<oaf_attribute name="panel:category" type="string" value="Amusements"/>
		<oaf_attribute name="panel:icon" type="string" value="/home/mikl/coding/applets/someicon.png"/>
	</oaf_server>
</oaf_info>

Læg mærke til følgende ting:
- stien til den applet, vi koder (/home/mikl/coding/applets/helloworld)
- stien til det ikon, der skal benyttes i "Add to panel"-funktionen på Gnome-panelet (/home/mikl/coding/applets/someicon.png) - hvis du ikke angiver en sti, bliver der søgt efter filen i /usr/share/pixmaps/
- at man kan angive forskellige navne og beskrivelser (name-da, name-en_GB osv.)

Du kan nu kalde denne fil HelloWorldApplet.server (eller hvad du ellers ønsker, det skal blot ende på ".server"). Læg denne fil i biblioteket /usr/lib/bonobo/servers/ (højst sandsynligt vha. sudo).

Derudover er der ikke så meget andet end nogle teknikaliteter, som indtil videre er fine nok til små, simple appletter. Bemærk dog, at her har jeg sat navnet til det samme alle stederne (fordi jeg er doven), så jeg kunne lige så blot have haft opgivet name og ikke de sprogspecifikke. Jeg har dog valgt at medtage det for at vise, at det er muligt både ved navn (name) og beskrivelse (description).

Så nu har vi altså "de kedelige ting" på plads - lad os se noget kode!

#include <string.h>
#include <panel-applet.h>
#include <gtk/gtklabel.h>

static gboolean helloworld_applet_fill (PanelApplet *applet, const gchar *iid, gpointer data)
{
	GtkWidget *label;

	if (strcmp (iid, "OAFIID:HelloWorldApplet") != 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:HelloWorldApplet_Factory",
							PANEL_TYPE_APPLET,
							"Hello World Applet",
							"0",
							helloworld_applet_fill,
							NULL);

Læg mærke til følgende ting:
- overensstemmelsen mellem iid'erne i vores .server-fil og i C-koden!
- det er "ligemeget" hvad vi kalder vores "main" (som ikke er main, men blot en funktion med en bestemt prototype, nemlig static gboolean function_name(PanelApplet*, const gchar*, gpointer)), da vi i "PANEL_APPLET_BONOBO_FACTORY" specificerer den funktion, der skal kaldes
- vi benytter GTK i stor stil - dette er en rar iagttagelse, for dette skal vi senere benytte i det praktiske eksempel
- vi benytter appletten som en gtk-container - det er ikke så vigtigt
- vi includer dels panel-applet.h, der giver os nogle ting til appletten, og dels gtk/gtklabel.h så vi kan skrive noget tekst på appletten

Filen skal naturligvis kompileres, og "resultatet" skal hedde "helloworld" og ligge i biblioteket /home/mikl/coding/applets/ jf. vores specifikation i .server-filen. Antag du har gemt overstående kode i filen helloworld.c, så foregår kompileringen således:
gcc $(pkg-config --cflags --libs libpanelapplet-2.0) -o helloworld helloworld.c

Som du kan se, skal du bruge visse development-pakker. Så hvis du får fejl, så vær sikker på, du har dem installeret. Du kan derudover også prøve at køre følgende for at se, om den melder fejl:
pkg-config --cflags --libs libpanelapplet-2.0

Din bruger hedder næppe mikl, så du skal nok vælge noget andet i .server-filen. Normalt plejer man ligeledes ikke at lægge appletter i hjemmebiblioteker, men under udviklingen er det ret behændigt, da det letter mange ting (ikke mindst rettighedsproblematikker).

Nu burde du kunne tilføje appletten til dit panel uden problemer.

Debugging

Og nu til et forholdsvist stort problem - eller udfordring om man vil. Debugging. For du kan måske ikke tilføje appletten uden fejl. Og du kan uden tvivl ikke fremover. Der er altså fejl i det kode, du laver, og det skal rettes gennem en debugging proces. Nogle bruger gdb, andre bruger stadig printf-debugging - uanset hvad, er det stadig svært at debugge. Man kan godt tilføje appletten gennem kommandoer, men mine erfaringer er stadig, at det bliver lidt noget skrammel (for nu at sige det rent ud). Det, der virker bedst for mig (men ikke nødvendigvis for dig), er at jeg splitter koden tilpas meget op, og laver både en konsolversion og en applet-version. Det betyder, at koden der adskiller de to er interfacet, og dermed kan logikken i programmet være fælles. Det gør, at man ved at debugge consolapplikationen (hvilket i mine øjne er langt nemmere), finder mange af fejlene i logikken, og dermed måske dem, der får appletten til at crashe. Så er der udelukkende den smule kode tilbage, der benyttes til at skabe selve appletten tilbage. Det kan stadig være en stor mundfuld, men indtil videre synes jeg den omtalte metode virker fint for mig, og især i disse appletter uden meget interface.

Dette leder videre, da jeg i denne artikel ikke beskæftiger mig med ret meget brugerinterface - der er hverken kontekstmenuer eller lignende på appletten, udelukkende en enkelt label, der kan vise lidt. Det er helt med vilje, da dette dels er en begynderartikel, og dels synes jeg ikke at GUIs er så sjove at lege med; jeg foretrækker de nedre lag, så at sige. Det var blot en sidebemærkning, for det er naturligvis muligt at lave mouse-events, kontekstmenuer osv., hvilket [1] hurtigt viser.

Case-study

Okay, nu er introduktionen overstået, så lad os komme i gang med at kæde lidt flere ting sammen. Grunden til jeg egentlig gik i gang med at lave en applet, var fordi jeg manglede noget (sådan er det jo tit). Jeg må nok også hellere nævne, at det kun er en uge siden jeg begyndte på det her appletprogrammering, så jeg er ikke så rutineret endnu, hvilket jeg ikke håber artiklen bærer alt for meget præg af. Problemet var, at jeg gerne ville kunne se tidspunktet i en anden tidszone i mit panel, men der var ingen eksisterende applet, der kunne det. Jeg fandt dog efter lidt søgen frem til, at man kunne gøre det således:
TZ=America/Los_Angeles date +"Klokken i LA er %R"
Kommandoen gør det, at den først midlertidigt i det efterfølgende kald sætter miljøvariablen TZ til en zone, der er at finde i /usr/share/zoneinfo/zone.tab, og derefter kalder den altså kommandoen date i dette nye miljø. Efter eksekveringen genetableres det oprindelige miljø, og TZ er således ved sin oprindelige værdi før kaldet. Det er altså kun et nyt midlertidigt miljø, man kreerer på denne måde.

Dette kan implementeres i C vha. putenv-funktionen. Man kan også få og formattere tiden med time-, localtime- og strftime-funktionerne. Med disse er det muligt at lave en statisk applet, der viser en fastindkodet tid i en anden tidszone i det øjeblik appletten loades. Nu går tiden jo også i den anden tidszone, hvilket stiller et krav om en timer således vores applet kan blive opdateret løbende med den nye tid. Jeg vil dog også gerne kunne ændre både tidszonen og formatteringen mens appletten kører - dvs. uden at skulle genindlæse appletten, og især uden at skulle renkompilere den. Dette sætter et krav om en konfigurationsfil (jeg har valgt at lave den i XML, hvilket igen kræver noget XML-parsing med libxml2). Det følgende er faktisk min første applet, men jeg synes eksemplet var godt, da det netop skal kombinere nogle ting. Jeg kører faktisk selv med den nu. Jeg har valgt at forklare alle aspekterne, og ikke blot de appletspecifikke elementer. Det er jo ret rart at kunne parse en XML-fil også, så det tager vi med. Det er heller ikke noget, jeg har gjort så meget i C (læs: aldrig), så det er også første gang. Jeg håber nu alligevel det kan bruges, for det er nu meget rart at kunne lave sin egen applet, hvis man pludselig står og mangler noget.

Som tidligere nævnt har jeg fundet frem til, at jeg deler interfacet op i to: en applet og en konsol. Nu da jeg har afsløret, at jeg er nybegynder indenfor det her, så er det meget muligt, at der er meget bedre måder, så hvis der er det, må I endelig sige til! Det fjerner dog ikke den realitet, at denne opsplitning betyder at man er tvunget til at modularisere sin applikation, hvilket er godt! Så på den måde, har metoden om ikke andet retfærdiggjort sig selv.

Projektet har jeg valgt at kalde Freed Clok (eller Befriet Ur, om man vil), og består af følgende filer (husk at du nu både har brug for udviklingsfiler til panels og til libxml2!):
~/.freed-clock (konfigurationsfil)
Freed-Clock-Applet.server
common.h
common.c
freed-clock-applet.c
freed-clock-console.c

Først kommer alt koden til filerne, og derefter kommer jeg med kommentarer til filerne individuelt.

~/.freed-clock ser således ud:

<Freed-Clock>
	<Config>
		<!-- /usr/share/zoneinfo/zone.tab -->
		<Time-zone>America/Los_Angeles</Time-zone>
		
		<!-- Maximum 200 chars are available -->
		<Format>%R i LA</Format> 
		
		<!-- Uncomment if to be updated every second instead of	every minute
			 It is nessecary to reload the applet in order for this to take effect.
		<Update-interval>sec</Update-interval> 	
		-->
	</Config>
</Freed-Clock>

Freed-Clock-Applet.server ser således ud:

<oaf_info>

	<oaf_server iid="OAFIID:Freed_Clock_Factory" type="exe" location="/home/mikl/coding/gnome-panels/freed-clock/freed-clock-applet">
		<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="Freed Clock Factory" />
		<oaf_attribute name="description" type="string" value="Factory to create Freed Clock Applet" />
	</oaf_server>

	<oaf_server iid="OAFIID:Freed_Clock" type="factory" location="OAFIID:Freed_Clock_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="Freed Clock" />
		<oaf_attribute name="name-da" type="string" value="Befriet Ur" />
		<oaf_attribute name="name-en_CA" type="string" value="Freed Clock" />
		<oaf_attribute name="name-en_GB" type="string" value="Freed Clock" />
		
		<oaf_attribute name="description" type="string" value="Show the date and time in any given time-zone" />
		<oaf_attribute name="description-da" type="string" value="Vis datoen og tiden i en valgfri tidszone." />
		<oaf_attribute name="description-en_CA" type="string" value="Show the date and time in any given time-zone" />
		<oaf_attribute name="description-en_GB" type="string" value="Show the date and time in any given time-zone" />
		
		<oaf_attribute name="panel:category" type="string" value="Amusements" />
		<oaf_attribute name="panel:icon" type="string" value="/usr/share/pixmaps/gnome-set-time.png" />
	</oaf_server>

</oaf_info>

common.h ser således ud:

#ifndef COMMON_H
#define COMMON_H

#define RESULT_SIZE 201

#define STD_OPT_TIMEZONE "America/New_York"
#define STD_OPT_FORMAT 	 "%c"
#define STD_OPT_INTERVAL 60000

typedef struct
{
	char* timezone;
	char* format;
	int update_interval;
} options;

/* Global options to make far less throwing around with and allocating this */
options opt;

void initialize_opt();
char* get_time();
void load_options(options*);
char* get_node_value(const xmlNodeSetPtr, const char*);
int file_exists(const char*);

#endif

common.c ser således ud:

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <assert.h>
#include <time.h>

#include <libxml/tree.h>
#include <libxml/parser.h>
#include <libxml/xpath.h>
#include <libxml/xpathInternals.h>

#include "common.h"

void initialize_opt()
{
	opt.update_interval = 0;
}

/*
Don't free(cmd) earlier than just before the return 
or else the local time is returned!
*/
char* get_time()
{
	load_options(&opt);
	
	static char result[RESULT_SIZE];
		
	/* The 4 are strlen("TZ=") (including \\0-char), 
	 * and 1's are for the \\0-terminating char 
	 */
	char* cmd = (char*)malloc(sizeof(char) * (4 + strlen(opt.timezone) + 1));
	strcpy(cmd,"TZ=");
	strcat(cmd, opt.timezone);

	if (putenv(cmd) != 0)
	{
		free(cmd);
		return "ERROR: Could not set time-zone!";
	}
	
	else
	{	
		time_t t;
		struct tm *tm_ptr;
		
		t = time(NULL);
		tm_ptr = localtime(&t);
		
		if (tm_ptr == NULL) 
		{
			free(cmd);
			return "ERROR: Could not get time";
		}

		else 
		{			
			if (strftime(result, RESULT_SIZE * sizeof(char), opt.format, tm_ptr) == 0) 
			{
				free(cmd);
				return "ERROR: No time";
			}
			
			else
			{
				free(cmd);			
				return result;
			}
		}		
	}	
}

void load_options(options* opt) 
{
	if (opt != NULL)
	{
		opt->timezone = NULL;
		opt->format = NULL;
	 
		char* filepath = getenv("HOME");

		if (filepath == NULL) 
		{
			filepath = ".";
		}
		
		char* filename = "/.freed-clock";
		
		/* The 1's are for the \\0-terminating char */
		char* location = (char*)malloc(sizeof(char) * (strlen(filepath) + 1 + strlen(filename) + 1));

		strcpy(location, filepath);
		strcat(location, filename);
	
		if (file_exists(location))
		{
			xmlInitParser();
			LIBXML_TEST_VERSION

			xmlDocPtr doc;
			xmlXPathContextPtr xpathCtx; 
			xmlXPathObjectPtr xpathObj; 

			doc = xmlParseFile(location);
		 
			if (doc != NULL) 
			{
				xpathCtx = xmlXPathNewContext(doc);
			 
				if(xpathCtx != NULL) 
				{
					xpathObj = xmlXPathEvalExpression((xmlChar*)"/Freed-Clock/Config/*", xpathCtx);
				 
					if(xpathObj != NULL) 
					{
						opt->timezone = get_node_value(xpathObj->nodesetval, "Time-zone");
						opt->format = get_node_value(xpathObj->nodesetval, "Format");
										 
						/* The interval can only be change at load because that's
						* where the timer is set
						*/
						if (opt->update_interval == 0)
						{
							char* upd_int_val = get_node_value(xpathObj->nodesetval, "Update-interval");
							opt->update_interval = (upd_int_val != NULL && strcmp(upd_int_val, "sec") == 0) ? 1000 : STD_OPT_INTERVAL;
						}
					 
						xmlXPathFreeObject(xpathObj);
					}
				
					xmlXPathFreeContext(xpathCtx); 
				}
			
				xmlFreeDoc(doc); 
			}
		 
			xmlCleanupParser();
			xmlMemoryDump();
		}
		
		free(location);
		
		if (opt->timezone == NULL) 
		{
			opt->timezone = STD_OPT_TIMEZONE;
		}
		
		if (opt->format == NULL) 
		{
			opt->format = STD_OPT_FORMAT;
		}
	}
}

char* get_node_value(const xmlNodeSetPtr nodes, const char* name)
{
	int size;
	int i;

	size = (nodes) ? nodes->nodeNr : 0;

	for(i = 0; i < size; ++i) 
	{
		if (nodes->nodeTab[i] == NULL)
		{
			break;
		}
		
		if(nodes->nodeTab[i]->type == XML_ELEMENT_NODE) 
		{
			if (strcmp((char*)nodes->nodeTab[i]->name, name) == 0)
			{
				return (char*)xmlNodeListGetString(NULL, nodes->nodeTab[i]->xmlChildrenNode, i);
			}
		}
	}

	return NULL;
}

int file_exists(const char* filename)
{
	FILE* file;
	
	file = fopen(filename, "r");
	
	if (file != NULL)
	{
		fclose(file);
		return 1;
	}

	return 0;
}

freed-clock-applet.c ser således ud:

#include "common.c"

#include <panel-applet.h>
#include <gtk/gtklabel.h>

gint update_time(gpointer data)
{
	/* By contract from the timeout-def we're getting the label */
	GtkWidget* label = (GtkWidget *)data;
	
	/* The time is found with get_time from common.h */
	gtk_label_set_text(GTK_LABEL(label), get_time());
	
	/* This function should be run once again */
	return 1;
}

static gboolean freed_clock_applet_fill (PanelApplet *applet, const gchar *iid, gpointer data)
{
	GtkWidget *label;

	if (strcmp (iid, "OAFIID:Freed_Clock") != 0)
	{
		return FALSE;
	}	
		
	label = gtk_label_new("Getting time...");
	
	update_time(label);
	g_timeout_add(opt.update_interval, update_time, label);
	
	gtk_container_add(GTK_CONTAINER(applet), label);
	gtk_widget_show_all(GTK_WIDGET(applet));

	return TRUE;
}

PANEL_APPLET_BONOBO_FACTORY ("OAFIID:Freed_Clock_Factory",
							PANEL_TYPE_APPLET,
							"The Freed Clock Applet",
							"0",
							freed_clock_applet_fill,
							NULL);

freed-clock-console.c ser således ud:

#include "common.c"

int main(int argc, char** argv)
{
	printf("%s\\n", get_time());
	return 0;
}

Og så til kommentarerne.

~/.freed-clock:
Time-zone findes som sagt i /usr/share/zoneinfo/zone.tab (sudo)
Formatet er fastlåst da der i parsningen er brugt en XPath og der bliver søgt efter bestemte elementnavne.

Freed-Clock-Applet.server:
Der er vist ikke så meget anderledes over denne end den, du så i starten.

common.h:
Her defineres nogle stanardværdier, hvis der er problemer med at hente dem fra konfigurationsfilen.

common.c:
Alt logikken er heri. Der er nogle kommentarer i koden, som burde hjælpe lidt. Der er dog et par indforståede ting, som kan være svære at ræsonnere sig frem til. Eksempelvis bliver opdateringsintervallet kun indlæst i starten, og det er således ikke muligt at ændre dette interval mens appletten kører. Det betyder, at hvis du har valgt at intervallet er et minut og har valgt et format med sekunder, så ændres sekundtantallet kun hvert minut - også selvom konfigurationsfilen ændres således den burde opdatere hvert minut. Grunden til det er, at GTK benyttes til at styre denne timer, og hvis man skulle ændre den, ville det kræve noget mere kode, som ville fjerne fokus fra det det egentlige, så derfor har jeg lavet det således. Hvis du er i tvivl om nogle af funktionerne, så søg på nettet - der er rigelig dokumentation tilgængeligt.

freed-clock-applet.c:
Der er nu to funktioner: én til der skal køres ved hver opdatering og så den, der skal startes op sammen med appletten.

freed-clock-console.c
Ele(g/f)ant!

Alt i alt giver det en applet, hvor du, mens den kører, kan ændre både tidszone og formattering, og dette vil så blive benyttet næste gang opdateringen sker (hvert minut eller hvert sekund afhængigt af konfigurationen, da du loadede appletten).

Husk nu at få styr på alle navne, filplaceringer osv. osv., da dette kan give anledning til mange, mange fejl.

Appletten kompileres med følgende (libxml2 skal med denne gang):

gcc -Wall $(pkg-config --cflags --libs libpanelapplet-2.0) $(xml2-config --cflags) freed-clock-applet.c -o freed-clock-applet

Og tilsvarende for konsollen:

gcc -Wall $(pkg-config --cflags --libs libpanelapplet-2.0) $(xml2-config --cflags) freed-clock-console.c -o freed-clock-console

Kom meget gerne med kommentarer, rettelser, gode forslag osv.

Kilder:
[1]: http://www.gnome.org/projects/ORBit2/appletstutorial.html

Hvad synes du om denne artikel? Giv din mening til kende ved at stemme via pilene til venstre og/eller lægge en kommentar herunder.

Del også gerne artiklen med dine Facebook venner:  

Karma barometer (30 dage)

IT jobs | Kontakt | Om Udvikleren.dk | Om karma | IT nyheds arkiv | Annoncering

X