Writing LiveWallpaper Plugins

Writing LiveWallpaper Plugins — Tutorial on writing LiveWallpaper plugins

Introduction

If you want to create your own wallpaper, you have to create a LiveWallpaper plugin. Each live wallpaper is realised as a plugin. This makes it easy to create new wallpapers or install several wallpapers on your system.

Locations

There are two locations to install your plugin. LiveWallpaper plugins can either be installed in the system path (/usr/lib/livewallpaper/plugins), or in a user's home directory (~/.livewallpaper/plugins). Each plugin resides in a subdirectory named after the plugin itself.


Required Files

Each plugin consists of the following files:

  • A .plugin file that holds some informations about the plugin.

  • A GSettings schema file

  • The plugin's binary files

You can also add the following files to your plugin:

  • An icon file that will be shown inside the configurator.

  • Some additional data files like texture images.

The .plugin File

This file is essential for a plugin because it holds some informations required by the plugin engine and the configurator. The .plugin file should look like the following example:

[Plugin]
Loader=python
Module=plugin-name
IAge=1
Name=Plugin Name
Description=Simple description of the plugin
Schema-id=net.launchpad.livewallpaper
Authors=Plugin Author Name <E-Mail Address>
Copyright=Copyright © year Copyright Holder
Website=http://website
License-type=gpl-3-0
License=This program comes with ABSOLUTELY NO WARRANTY; for details, visit <a href="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</a>

This example file contains every key that will be used by the configurator or the plugin engine. Not all keys supported by PeasEngine are used by LiveWallpaper. You don't have to specify all keys. For example if the plugin don't has its own website, you don't need to add the Website key.

Loader: This key is only required if you are not using c as programming language. At the moment only the python loader is supported.

Module: This is the plugin's name. It should be in lowercase and contain no spaces.

IAge: This is the plugin's interface age. This number changes if the WallpaperInterface changes. The current interface age is 1.

Name: The human-readable plugin name. This name will be shown to the user inside the configurator. So this is not exactly the same as Module.

Schema-id: Use a different schema id then the default one. This will be used by the configurator to find the schema of the plugin. By default the configurator uses net.launchpad.livewallpaper.plugins.plugin-name as schema id.

License-type: The name of a predefined license. Could be gpl-2-0, gpl-3-0, lgpl-2-1, lgpl-3-0, bsd mit-x11 or artistic. This key overrides the License key.

License: A link to the license or the license's summary or full text.

Programming

Creating a plugin is just creating a GObject which implements the LwWallpaperInterface.

The Wallpaper Interface

Each plugin has to implement the WallpaperInterface. The interface provides some entry points into the drawing process. A plugin doesn't has to implement a defined method. It is possible to only implement the methods required to show the wallpaper.

After the plugin gets constructed, the init_plugin method will be called.The plugin interface provides a own initialization method because inside the constructor of the GObject it is not possible to get the plugin's data dir from the plugin engine. A plugin can first get its data dir in this second initialization method.

There are two possible orders for the other method calls. If there is only one output area, the methods will be called in the following order:

It exists only one output area if only one physical screen is attached to the system or if the wallpaper should be drawn over all screens as one big wallpaper.

If there are more physical screens, the methods will be called in the following order:

The methods will always be called in one of these orders, so you can rely on the fact that each call to adjust_viewport will be followed by a call to restore_viewport.


Example Plugins

You can download the source of some well commented example plugins with this command:

bzr branch lp:~fyrmir/livewallpaper/example-plugins

You can browse the code online here.

The example plugins are written in every language that works with LiveWallpaper. At the moment this is c and python. It might be possible that not all features provided by the API are supported by python plugins.

Integration with a build system

The cmake build system

The LiveWallpaper project uses cmake as build system. So it also provides some cmake macros for easier plugin creation.

Finding LiveWallpaper is really easy because it provides a FindLivewallpaper.cmake file.

find_package(Livewallpaper REQUIRED)

For compiling and installing a plugin, there are the livewallpaper_plugin_*() and livewallpaper_plugin_install_data() macros. Here a simple example on how to use them.

include(LivewallpaperPlugin)

...

# for c plugins
livewallpaper_plugin_c(PLUGIN_NAME
                       SOURCES Source Files
                       GSCHEMA schema.xml
                       ICON icon.svg
)

# or for python plugins
livewallpaper_plugin_python(PLUGIN_NAME
                            SOURCES Source Files
                            GSCHEMA schema.xml
                            ICON icon.svg
)

...

livewallpaper_plugin_install_data(PLUGIN_NAME
                                  FILES Additional Files
)

livewallpaper_plugin_install_data(PLUGIN_NAME
                                  DIRECTORY Additional Directories
)

You can find a more detailed description inside the LivewallpaperPlugin.cmake file.


Other build systems

You just have to compile the plugin and install it in the right directory, so there are no further information on how to use other build systems here.

You can check if the LiveWallpaper headers and libraries are installed on your system by using pkg-config.