NOTE: Some of this post is no longer relevant. Please use Universal Applet’s internal documentation.
At the moment, there’s very little documentation for developers describing the Universal Applets architecture. I’m hoping to roll out a stable release within the next week or two, and I should have the time to write up some docs after that.
In the meantime, this post should provide adequate installation instructions and a quick developer overview for those of you who have been asking. If you haven’t already done so, please read this article first.
Installing Universal Applets and Getting the Server to Run
1. Grab a copy of the branch off of bzr with the following command:
bzr co http://bazaar.launchpad.net/~aantny/screenlets/universal-applets
2. Install Universal Applets with the following:
sudo make install
3. Start the server with the following: chmod u+x src/share/examples/server.py src/share/examples/server.py
4. Start any screenlet or applet. There’s a non-screenlet-based test applet in src/share/examples/test-applet.py
The Universal Applets architecture is heavily built on XEmbed and DBUS. Any application can create an applet using a GtkPlug (or the equivalent widget in any X toolkit) and any application can display an applet using a GtkSocket. All communication between the applet (the process containing the GtkPlug) and the server (the process containing the GtkSocket) is done over DBUS.
There can be multiple servers running at any time. Each server can display applets in different places on the screen (e.g. in a sidebar or in a panel). In other words, the same applet can be displayed in different applications without requiring any modifications to the original applet. Accordingly, an applet server can easily display any applet without knowing or caring what language the applet was written in. Again, applets do not run in the same process as the applet server.
The Ten Second Component Overview
At this point, the only server is the aptly named server.py application that’s contained in my branch. server.py displays applets in toplevel windows. It runs a DBUS service and holds an array of GtkWindows and GtkSockets. (The toplevel windows are commonly referred to as “applet containers.”) Any application which would like to function as an applet server can do so by implementing similar DBUS code. Yes, it’s really that easy.
The AppletWrapper class implements all of the basic code necessary for an applet. It can be used to make any part of an app’s gui function as an applet. It handles the DBUS communication with the applet server and automagically takes care of all the nitty gritty XEmbed details. AppletWrapper is currently written in Python but I’m planning on reimplementing it in C.
In the layman’s terms: By using AppletWrapper any part of your app can gain toggleable applet status with about three extra lines of code. Nifty.
The Screenlets base class contains code for applets that need to implement custom drawing. It’s not absolutely necessary, but if you’re planning on writing a python applet you should probably subclass the Screenlets class. It supports theming and editable options (options that can be edited with a GUI) and will make your life simpler. Screenlets uses AppletWrapper for the magical DBUS and XEmbed ‘stuff’.
The session class is used by Screenlets to handle multiple instances. If you’re writing your own applet using AppletWrapper (or if you’re implementing your own equivalent to AppletWrapper) you can ignore it.
Other Important Notes:
There’s still some ugly and outdated legacy code from Screenlets in several places. In particular, I wouldn’t even try to understand the screenlets-manager.py file. It’s a coding nightmare and will be rewritten by the Universal Applet’s 0.1 release.
The server.py application (the name will change to something more original with the release) is the only currently the only applet server. There are plans to add support to Awn in the coming weeks.
There are still several features missing in Universal Applets that are present in the Screenlets. I’ve tried to focus on improving the stability and performance instead of adding new features. If someone wants to test the speed of my branch against screenlets’ trunk, I’d be interested in the results.