Enigma2:Plugin-Erstellung

Aus DreamboxWIKI
Wechseln zu: Navigation, Suche

Allgemeines

Grundsätzlich liegen die Plugins in /usr/lib/enigma2/python/Plugins. Dort dann halt entsprechend den vorhandenen Unterverzeichnissen ein Verzeichnis für das neue Plugin anlegen.

Voraussetzung und Erstellung

In dem Verzeichnis müssen sein:

  • __init__.py (kann leer sein. wird aber benötigt, da Python das Verzeichnis sonst nicht als Modul erkennt)
  • plugin.py (das Hauptskript für jedes Plugin)

plugin.py muss enthalten:

 from Plugins.Plugin import PluginDescriptor # importiert den PluginDescriptor (s.u.)<br>
 # diese Funktion wird aufgerufen und gibt einen einzelnen PluginDescriptor oder eine Liste von PluginDescriptoren zurück
 # das **kwargs einfach ignorieren! (näheres dazu in docs/PLUGINS im enigma-baum) ***
 def Plugins(**kwargs):
   # Beispiel für ein einzelnes Plugin, welches im Plugin-Menü erscheint
   return PluginDescriptor(name="File-Manager", description="Let's you view/edit files in your Dreambox", where = 
   PluginDescriptor.WHERE_PLUGINMENU, fnc=main)
   
   # Beispiel für eine Liste von Plugins, das erste erscheint im Plugin-Menü, das zweite wird beim E2-Start aufgerufen (Autostart)
   return [PluginDescriptor(name="Plugin1", description="Example Plugin", where = PluginDescriptor.WHERE_PLUGINMENU, fnc=main),
   PluginDescriptor(where = PluginDescriptor.WHERE_AUTOSTART, fnc = autostart) ]

Der Filemanager ruft dann, wenn man auf den Menüpunkt "File-Manager" im Plugin-Menü geht, die Funktion "main" auf. Die muss so aussehen:

 def main(session, **kwargs): # **kwargs einfach ignorieren, s.o. ***

Der session-Parameter enthält dann die Session, welche man z.B. zum Erstellen von Screen braucht.

Will man dann in <code> einen Screen aufrufen, macht man das so:

 session.open("<screen>")

So ein Screen ist eigentlich immer recht einheitlich aufgebaut, Beispiel Filemanager:

 class FileManager(Screen):
 	skin = """
 		<screen position="100,100" size="550,400" title="Test" >
 			<widget name="list" position="10,0" size="190,250" scrollbarMode="showOnDemand" />
 			<widget name="pixmap" position="200,0" size="190,250" alphatest="on" />
 		</screen>"""
 	def __init__(self, session, args = None):
 		Screen.__init__(self, session)<br>
 		self["list"] = FileList("/", matchingPattern = "^.*\.(png|avi|mp3|mpeg|ts)")
 		self["pixmap"] = Pixmap()<br>		
 		self["actions"] = NumberActionMap(["WizardActions", "InputActions"],
 		{
 			"ok": self.ok,
 			"back": self.close,
 #			"left": self.keyLeft,
 #			"right": self.keyRight,
 			"1": self.keyNumberGlobal,
 			"2": self.keyNumberGlobal,
 			"3": self.keyNumberGlobal,
 			"4": self.keyNumberGlobal,
 			"5": self.keyNumberGlobal,
 			"6": self.keyNumberGlobal,
 			"7": self.keyNumberGlobal,
 			"8": self.keyNumberGlobal,
 			"9": self.keyNumberGlobal,
 			"0": self.keyNumberGlobal
 		}, -1)

skin = ... definiert einen lokalen Skin in diesem Plugin. Die Syntax entspricht der in skin.xml, bis auf den Screen-Namen, der wird hier nicht benötigt. Dann haben wir die Konstruktor-Methode __init__, welche dann den Screen-Konstruktor mit gleichen Parametern aufruft, da FileManager von Skin abgeleitet ist. Die Widgets, die wir im Skin definiert haben, sind noch leer. Diese werden dann in den nächsten Zeilen mit Funktion gefüllt:

 self["pixmap"] = Pixmap() <-- das erstellt zum Beispiel ein Bild
 self["list"] = FileList("/", matchingPattern = "^.*\.(png|avi|mp3|mpeg|ts)") <-- das eine in der gleichen Datei definierte
 FileListe.

Als nächstes wird noch angegeben, was bei Tastendrücken passieren soll. Dafür sind die Actionmaps da.

 self["actions"] = NumberActionMap(["WizardActions", "InputActions"] <-- wir benutzen aus der keymap.xml-Datei die Abschnitte
 "WizardActions" und "InputAction"

Für die in der keymap.xml definierten Tastendrücke wird dann im folgenden angegeben, welche Methode der Klasse bei welchem Tastendruck aufgerufen werden soll. Also z.B. "ok": self.ok ruft die Methode 'ok' auf, wenn man auf die Taste, die in der Keymap.xml als Action "ok" hat, gedrückt wird.

Unterstützung von Lokalisierungen in einem Plugin

Um ein Plugin in alle möglichen Sprachen übersetzbar zu machen müssen als alle Strings von der Funktion _() umgeben werden. Um also z.B. den Titel des o.g. Filebrowsers übersetzbar zu machenm müsste man den code wie folgt gestalten:

 	skin = """
 		<screen position="100,100" size="550,400" title="%s" >
 			<widget name="list" position="10,0" size="190,250" scrollbarMode="showOnDemand" />
 			<widget name="pixmap" position="200,0" size="190,250" alphatest="on" />
 		</screen>""" %(_("test"))

Da die Funktion _() in Plugins jedoch leider nicht umittelbar zur Verfügung steht müssen wir die __init__.py unseres Plugins wie folgt ergänzen

 from Components.Language import language
 from Tools.Directories import resolveFilename, SCOPE_PLUGINS
 import os,gettext
 
 PluginLanguageDomain = "FileBrowser"
 PluginLanguagePath = "Extensions/FileBrowser/locale"
 
 def localeInit():
    lang = language.getLanguage()[:2] # getLanguage returns e.g. "fi_FI" for "language_country"
    os.environ["LANGUAGE"] = lang # Enigma doesn't set this (or LC_ALL, LC_MESSAGES, LANG). gettext needs it!
    print "[WebInterface] set language to ", lang
    gettext.bindtextdomain(PluginLanguageDomain, resolveFilename(SCOPE_PLUGINS, PluginLanguagePath))
 
 def _(txt):
    t = gettext.dgettext(PluginLanguageDomain, txt)
    if t == txt:
        print "[%s] fallback to default translation for %s" %(PluginLanguageDomain, txt)
        t = gettext.gettext(txt)
    return t
 
 localeInit()
 language.addCallback(localeInit)

Alles noch fehlt ist folgender Import in allen Dateien die Übersetzungen unterstützen sollen:

 from __init__ import _

Vorrausetzung für die Funktio der neu definierten _() Funktion ist dass die kompilierten gettext Sprachdateien sich in dem in der Variablen "PluginLanguagePath" angegebenen Pfad befinden.

Die notwendigen .po und die .pot - also das Template für neue Übersetzungen - Dateien kommen am besten in ein eigenes verzeichnis namens "po". Erstellen kann man die enstprechenden Files z.B. mit PoEdit.

Sollen die Sprachdateien mithilfe der Openembedded Toolchain kompiliert werden so ist noch ein entsprechendes Makefile notwendig. Dieses kann wie folgt aufgebaut werden:

 #
 # to use this for the localisation of other plugins,
 # just change the DOMAIN to the name of the Plugin.
 # It is assumed, that the domain ist the same as
 # the directory name of the plugin.
 #
 
 DOMAIN=FileBrowser
 installdir = /usr/lib/enigma2/python/Plugins/Extensions/$(DOMAIN)
 #GETTEXT=./pygettext.py
 GETTEXT=xgettext
 
 #MSGFMT = ./msgfmt.py
 MSGFMT = msgfmt
 
 LANGS := de tr nl fy es
 LANGPO := $(foreach LANG, $(LANGS),$(LANG).po)
 LANGMO := $(foreach LANG, $(LANGS),$(LANG).mo)
 
 default: $(DOMAIN).pot $(LANGPO) merge $(LANGMO)
 	for lang in $(LANGS); do \
 		mkdir -p $$lang/LC_MESSAGES; \
 		cp $$lang.mo $$lang/LC_MESSAGES/$(DOMAIN).mo; \
 	done
 
 merge:
 	for lang in $(LANGS); do \
 		msgmerge --no-location -s -N -U $$lang.po $(DOMAIN).pot; \
 	done
 
 
 # the TRANSLATORS: allows putting translation comments before the to-be-translated line.
 $(DOMAIN).pot:
 	$(GETTEXT) -L python --add-comments="TRANSLATORS:" -d $(DOMAIN) -s -o $(DOMAIN).pot ../src/*.py
 	msguniq -o $(DOMAIN)uniq.pot $(DOMAIN).pot
 	$(RM) $(DOMAIN).pot
 	mv $(DOMAIN)uniq.pot $(DOMAIN).pot
 
 .PHONY: $(DOMAIN).pot
 
 
 %.mo: %.po
 	$(MSGFMT) -o $@ $<
  
 %.po:
 	msginit -l $@ -o $@ -i $(DOMAIN).pot --no-translator
 
 CLEANFILES = $(foreach LANG, $(LANGS),$(LANG).mo)
 
 clean-local:
 	$(RM) -r $(LANGS)
 
 install-data-am: default
 	for lang in $(LANGS); do \
 		mkdir -p $(DESTDIR)$(installdir)/locale/$$lang/LC_MESSAGES; \
 		cp $$lang.mo $(DESTDIR)$(installdir)/locale/$$lang/LC_MESSAGES/$(DOMAIN).mo; \
 	done

Entwicklungsprozess

Die meisten Plugins werden beim Booten der Dreambox - dem Start von Enigma2 - geladen.

Enigma2 neustarten

Um Änderungen an Plugins zu testen, muss man die Box nicht neu booten, sondern kann einfach enigma2 neustarten. Dazu per ssh/telnet zur dreambox verbinden und folgendes ausführen:

$ init 4
$ init 3

Hängt Enigma2 fest, so kann man es auch hart beenden:

$ init 4
$ killall -9 enigma2

Beim Entwickeln ist es oftmals hilfreich, Loggingausgaben zu haben:

$ init 4
$ enigma2 > /tmp/enigma2.log 2>&1

Hier wird enigma2 beendet, neu gestartet und alle Ausgaben nach /tmp/enigma2.log geschrieben. Mit

$ less /tmp/enigma2

kann man sich die Loggingausgaben (und Fehlermeldungen!) anschauen.

Plugins automatisch neu laden

Aus dem Entwicklerforum:

Es ist möglich, module automatisch neu zu laden, wenn das Plugin benutzt wird.

plugin.py enthält dabei nur das Minimum an Code, der Rest liegt in einem eigenen Modul:

from Plugins.Plugin import PluginDescriptor
import YourModule

def main(session, servicelist, **kwargs):
	reload(YourModule)
	try:
		session.open(YourModule.YourScreen)
	except:
		import traceback
		traceback.print_exc()

def Plugins(**kwargs):
	return PluginDescriptor(name = "YourPlugin",
				description = "Your test plugin",
				where = PluginDescriptor.WHERE_PLUGINMENU,
				fnc = main)

Der eigentliche Plugincode liegt in YourModule.py. Im Beidpiel wird der Screen in dieser Datei definiert. Diese Datei wird dann bearbeitet, und immer wenn das Plugin gestartet wird, lädt der Code in plugin.py das Modul neu. Damit muss enigma2 nicht neugestartet werden.


Crashes verhindern

Wenn man beim Entwicklen verhindern will, dass ganz Enigma abstürzt, sollte man den eigenen code in try - except einschliessen.


Weiterführende Themen



Grundlagen - Installation - Hardware - Entwicklung - Portal

Enigma - Enigma2 - Plugins - Spiele - Software - Tools - Howto - FAQ - Images

Hauptseite - News - Alle Artikel - Bewertungen - Gewünschte Seiten - Index - Neue Artikel - Impressum - Meilensteine - Team

Hilfeportal - Seite bearbeiten - Bilder - Links - Tabellen - Textgestaltung