Chapter 1. Introduction

Noatun supports plugins on a very deep level, and a rich API allows large amount of control of the entire application. This documentation will serve as the reference and guide for writing plugins.

The author of this document will be very helpful if you have questions regarding the development of your plugin. Feel free to email him.

Docbook source for this document is available, as well as HTML.

Before continuing to read this documentation, it is recommended that you use kdoc to generate documentation headers for $KDEDIR/include/noatun/*.h. However, this is not required, since you can read the headers directly. The API reference is also available online.

Getting Started

All plugins derive from class Plugin (plugin.h), and may inherit from one or more other classes.

Tip

Many Noatun plugins inherit from two or three class, we have used as many four. The noatun API makes this perfectly safe to do, and we suggest it.

The following code segment will allow the plugin to be loaded and unloaded by noatun, it, however won't do much.

class MyPlugin : public Plugin
{
public:
	MyPlugin();
};

extern "C"
{
	Plugin *create_plugin()
	{
		return new MyPlugin;
	}
}

MyPlugin::MyPlugin()
{
}

Warning

Returning Plugin *, versus an inheriting type, from create_plugin is important. Although, in this case it will not make a difference, using multiple inheritance will mangle the types.

Note

The NOATUNPLUGINC and NOATUNPLUGIND constructs that annoyed us all in previous versions are no longer required as of KDE 2.2 (Noatun 1.2). They do nothing.

Now all that is required is creating a .plugin file (referred to as "spec" files), compiling, and installing. It is highly suggested that you use the autoconf and automake files of an existent plugin. This has the tenancy of increasing the usage of a plugin greatly, as well as assisting in development, and being good, all around.

Spec files use the familiar KConfig format (in fact, that is how they are internally read). Following is an example, from the Milk Chocolate user interface.

Filename=libmilkchocolate
Author=Charles Samuels
Site=http://noatun.kde.org/plugins/milkchocolate/
Email=charles AT kde.org
Type=userinterface
License=Artistic
Name=Milk-Chocolate
Name[fr]=Chocolat de Lait
Comment=Noatun's simple GUI
Comment[no]=Noatuns enkel grensesnitt

Filename is the .la file, without the .la extension. My email address has been changed to prevent me from getting spam. Name and Comment also respond to internationalization tags, such as the above. Type may any one of the following:

userinterface
playlist
visualization
other

The Type field has no effect other than load order. Playlists are loaded first, followed by user-interfaces. The order is undefined past this point. Playlists are loaded first to satisfy any dependencies.

You know what's nice? napp is nice. It's a global pointer to the NoatunApp type, and that class will give you ways of getting the playlist, the equalizer, the effects chain, and all the other features Noatun has.

If you need to store song-specific information, you should use the Playlist property functions. This will allow that information be stored between sessions.