JBrout http://jbrout.free.fr/gfx/jbrout.png Home Sources Download dev info doc faq mailinglist/forum old forum

Plugin Interface

Here is the minimal plugin, the most simple you can do. In the "plugins/" folder of the application, create a folder "minimal", and copy/paste the code behind in the file plugins/minimal/__init__.py : 

#!/usr/bin/python
# -*- coding: utf-8 -*-

from __main__ import JPlugin

class Plugin(JPlugin):
    """ the minimal plugin """
    __author__ = "you"
    __version__ = "1.0"

    def menuEntries(self,l):
        return [ (1,"say hello",False,self.sayHello,None), ]

    def sayHello(self,l):
        self.MessageBox("%d photos are selected" % len(l))
        return False

Now, run jbrout, and you will have a new entry in the contextual menu which will be named "say hello". Select it, and it will display the number of pictures which are selected ! Congratulations, you have made your first jbrout's plugin !!!

How it works

Now, let's see how it works :

As you can see you must create a class "Plugin" which subclass JPlugin ! Your class should be named "Plugin", but in fact, the name/identifier of the plugin is the name of the folder. Here it is "minimal" !

the JPlugin interface

The JPlugin interface provide some facilities. It exposes some usefull attributs :

  • id, a string, which is the name/identifier of the plugin (here it is "minimal")
  • path, a string, which is the relative path from jbrout to your plugin
  • conf, a dict, which can be used to store some preferences between 2 jbrout session (keys must be strings)

And it exposes some GUI methods :

  • MessageBox(self,message,title=None) : display a message box
  • InputBox(self,val,message,title=None) : ask to modify the "val" in a message box, return the new val or None
  • InputQuestion(self,message,title=None) : ask to response yes or no, returns a boolean
  • showProgress(self,num=None,max=None,message=None) : display the progress bar at the position "num" on "max"
  • showProgress(self) : hide the progress bar

The menuEntries

Your class must provide a method named "menuEntries", which receive a list of photonode, and must return a list of tuples ! This tuple must contain :

  • a number, which is the position of the entry in the contextual menu
  • a string, which is the label of the entry
  • a boolean, which inform jbrout if this entry could alter the database. (thus, it will not be available when jbrout is run in view mode)
  • a callback, a pointer to a method. It's this method which will be called when you select the menu
  • a string (or None), which can define the relative path to a picture, thus the entry appears like an icon in the main toolbar too.

notes

  • when the plugin is called, it is executed in its context path. So when you use relative path, make sure they are relatives at your code !
  • the list of photonode is available as a parameter in the menuEntries method : so you can decide to display or not some entries, in function of the content of this list.

The callback

The callback is the action ! it must receive one parameter : the list of "photonode" ! And must return a boolean, which is used by jbrout to be able to know if the action has modified a photonode (redated, rotated, ...). (true if something has been modified, else false)

A photonode

It's an instance of a PhotoNode (see PhotoNode class in db.py). In fact : it's a picture. PhotoNode expose a lot of attributs and methods, but i will let you see that in the db.py file ...

Translations

You can provide some translations in the gettext/pot/mo way. By creating the right translation structure in a folder named "po" in the directory of your plugin ... Jbrout provide a function "_()" to the plugins ...

... to be continued ...

To help you to developp your plugin, you should look thoses which are now in your jbrout. The simplest is rotate, which use internal methods of PhotoNode to rotate the pictures or rebuild internal exif thumbs ... "openExplorer" is really easy too ...