X-Git-Url: https://git.cweiske.de/enigma2.git/blobdiff_plain/57534d26a3ec9cc77ab3eedc5ad393897e4dee95..efa3093ea9ba1a1fe452cee9845c496b51b0e720:/doc/PLUGINS

diff --git a/doc/PLUGINS b/doc/PLUGINS
index 96558775..808fd580 100644
--- a/doc/PLUGINS
+++ b/doc/PLUGINS
@@ -5,19 +5,20 @@ Enigma2 plugins are always written in python. If you really have to call
 C/C++ functions from your code, you can supply a python module with it,
 implementing your functions.
 
-Let's write a plugin. We call it "ourSmallTest", and it should be a test
-plugin.
+Let's write a plugin. We call it "OurSmallTest", and it should be a test
+plugin. Thus we choose "DemoPlugins" as a category. The category is just to
+organize plugins in the filesystem.
 
 The simplest plugin looks like the following:
 
-Plugins/ourSmallTest/plugin.py:
+Plugins/DemoPlugins/OurSmallTest/plugin.py:
 
 "from Plugins.Plugin import PluginDescriptor
 
-def main(session):
+def main(session, **kwargs):
 	print "Hello world!"
 
-def Plugins():
+def Plugins(**kwargs):
  	return PluginDescriptor(
 		name="Our Small Test", 
 		description="plugin to test some capabilities", 
@@ -25,8 +26,8 @@ def Plugins():
 		fnc=main)"
 
 Basically, you're writing a "python module", which is called
-Plugins.ourSmallTest.plugin. This corresponds to the
-Plugins/ourSmallTest/plugin.py file.
+Plugins.DemoPlugins.OurSmallTest.plugin. This corresponds to the
+Plugins/DemoPlugins/OurSmallTest/plugin.py file.
 
 This module must define a single function called "Plugins". The functions is
 called for every Plugin, and should return (a list of)
@@ -68,6 +69,33 @@ def main(session):
 
 with MyScreen being a GUI screen.
 
+About the **kwargs:
+This somewhat special syntax (in fact the name 'kwargs' is arbitrary, but
+stands for "keyword arguments") collects all addition keyword arguments
+(i.e. named parameters). For example. the Plugins()-call gets a "path"
+parameter, and probably more in the future. You must ignore all additional
+keywords which you don't need!
+
+skins
+=====
+
+Generally, you can include the skin in your Screens by having a static (or
+non-static, if you really want) variable "skin", for example:
+
+class OurSmallTestScreen(Screen):
+	skin = "<skin>...</skin>"
+	def __init__(self, session):
+		Screen.__init__(self, session)
+		...
+
+However, users can override the skin from their skin.xml. Note that the
+Screen's name (unless you override this, which is possible) is used for
+determining which skin is used. Thus, if you're choosing generic skin names
+like "TheScreen", it's likely to cause namespace clashes.
+
+Thus, please use skin names (i.e. Screen-names, unless you're overriding the
+skin name) which are unique enough to not clash. In doubt, prepend the
+pluginname like in our example.
 
 autostarting plugins
 ====================
@@ -78,8 +106,56 @@ end on shutdown.
 you just have to use "WHERE_AUTOSTART". your entry point must (fnc) look 
 like:
 
-def autostartEntry(raeson):
+def autostartEntry(raeson, **kwargs):
 	if reason == 0: # startup
 		print "startup"
 	elif reason == 1:
 		print "shutdown"
+
+autostart plugins should always be configurable, and should default to an
+OFF state!
+
+Configuration
+=============
+
+Speaking about configuration, plugins must live in 
+
+config.plugins.<Category>.<PluginName>
+
+and nowhere else!
+
+You are, however, free to change settings which are already existing. If you
+
+Dependencies
+============
+
+Plugin dependencies (one plugin requires another plugin) should generally be
+avoided, but are possible. If there are dependencies, the .ipk file must
+list them.
+
+If possible, make them optional. If your plugin doesn't support one feature
+because another plugin isn't installed, that's fine (but should be noted in
+the docs).
+
+Categories
+==========
+
+Currently defined categories are:
+
+* DemoPlugins: Plugins fore pure demonstration purposes
+* Extensions: User interface extensions
+* SystemPlugins: Hardware specific plugins
+
+Plugin Names
+============
+
+A plugin name:
+ - should always start with a Uppercase letter,
+ - must not start with the word "Dream",
+ - nor end with "Plugin",
+ - should be unique even across Categories,
+ - must be understandable by english speaking people,
+   (unless it's a geographically restricted plugin)
+ - is not user changeable (that is, the user is not allowed to rename the
+   plugin directory)
+ - shouldn't be a generic word