This is a documentation about how to write plugins for Glipper. Plugins are written in the programming language Python. Glipper searches in the following pathes for plugins: If you write a plugin, make sure it is in one of this directories in order to use it, and that it has the extension *.py. It is a good idea to use only one .py file (and possibly a *.glade file) for one plugin, and not several. Also it's a good idea to look at the plugins that are shipped with glipper. The communication between the plugins and Glipper consists of events (method calls by Glipper into your plugin) and api calls (method calls by your plugin into Glipper). This documentation is only a very brief overview. Maybe you want to look at History.py to get an idea how the history works exactly. Here is a list of all events. If you want to use one of these, you have to do it by defining a function with this name at the global scope (so not in a class). - "info" Every plugin has to implement this method. It should return a dictionary which gives glipper the information about the name, the description and wether a preferences dialog is available or not. Here is an example how the newline plugin uses it: def info(): info = {"Name": "New line", "Description": "Example plugin that adds a newline character at the end of items in the clipboard", "Preferences": False} return info - "on_new_item" This event gets sent if a new item is added to the glipper history. This item is delivered by the parameter. This example prints every new item: def on_new_item(item): print item - "init" This event is sent after your plugin is started. You can do initialization for your plugin here. No parameters and no return value. - "stop" The opposite of "init". This gets called if the user askes glipper to stop the plugin. The main intend of this event is to let your plugin stop all threads it uses (see the notes about thread programming below). No parameters and no return value. - "on_activate" Gets called if the menu item that you have possibly edited (or one of it's subitems, see the "add_menu_item" call below) gets clicked. The first parameter is the widget that caused the call, the second is the string that the menuentry contains. For an example how to use it see the snippets plugin for example. - "on_show_preferences" Gets called if the user asks glipper to show the preferences of your plugin. Please show a gtk window here. Although it may be possible to use other toolkits, it would "fit" into glipper. The parameter is the parent widget. Please use it, because otherwise your window is maybe not shown at the front. Now about the api calls. You have to import the module "glipper" in order to use them. All of these calls are throwing exceptions if necessary, so make sure to catch them. - "add_menu_item(menu_item)" Adds the gtk MenuItem widget, given by the parameter "menu_item", to the glipper menu. The item will be removed automatically when the plugin gets stopped. IMPORTANT: Only call this within the "init" event, or else undefinied behaviour will occur. - "add_history_item(item)" Adds a new item to the clipboard(s), and so also to the top of the history. - "set_history_item(index, item)" Sets the history entry specified by "index" to "item". Beware, if your index is 0, the item will stand on the top of the list, but won't be in the clipboard. This makes the state of glipper inconsistent. Consider using add_history_item instead. Tip: If you want to replace the item at the top of the history with a new entry, AND synchronize the clipboard(s) with it, just do it the same way the newline plugin does: glipper.set_history_item(0, i) glipper.add_history_item(i) #this doesn't change the history, only the clipboards, because "i" is already on the top - "get_history_item(index)" Returns the item at position "index" from the history. - "remove_history_item(index)" Removes the item at position "index" from the history. - "clear_history()" Clears the whole history. - "format_item(item)" Formats the item (or generally the string) the same way like in the history popup. So it returns a shortened string, which is exactly as long as given by the gconf preferences. Tip: if you use this, consider that the user has the possibility to change the gconf settings at runtime. If this happens, you have must format your items again to stay consistent. You can get informations about gconf key changes by registering a notify handler. See below and see the snippet plugin. About infinite recursive "event - api call" constructs: If your plugin uses the on_new_item event, and within this, it uses the add_history_item() function, an infinite recursive loop would occur, because the add_hisotry_item() function causes Glipper to call on_new_item() again, which will of course call add_history_item() again, and so on... Take a look at the newline plugin to see how you can work around this problem. About gconf: You can use the object "GCONF_CLIENT" in the glipper module to have access to the Glipper's gconf preferences. For example the following call will register a notify handler, which calls the function "update_menu()" (through a lambda wrapper) every time the key GCONF_MAX_ITEM_LENGTH (this is the value for the maximum string size of the entries in the history) changes: glipper.GCONF_CLIENT.notify_add(glipper.GCONF_MAX_ITEM_LENGTH, lambda x, y, z, a: update_menu()) You can ask for a value by doing: max_length = glipper.GCONF_CLIENT.get_int(glipper.GCONF_MAX_ITEM_LENGTH) See the gconf documentation and our plugins for more informations. About using threads in your plugin: If your plugin uses threads, you should ALWAYS keep one thing in mind: Stop all your threads in the "stop()" event. If you don't do this, you plugin keeps running, also if the user has told Glipper to stop it. This behaviour is not desired!!! If you want to see an example for a plugin using threads, take a look at the network plugin. About storing preferences and other data belonging to your plugin: Please store the settings into a file in the ~/.glipper/plugins/ directory. You can get this directory in python by doing dir = os.environ["HOME"] + "/.glipper/plugins" Please make also sure that this directory really exists: if not os.path.exists(dir): os.makedirs(dir) About debugging: The easiest way to debug your plugin is by putting print statements to your program. These will be printed to standard output. To see the standard output, you have to start glipper from console before you add it to the panel. For example if the glipper executable is in the /usr/lib/glipper/ dir, you have to type "/usr/lib/glipper/glipper" in the console and then add glipper to the panel.