The KVIrc addon system

Writing KVIrc addons
Introduction

An addon is basically a set of KVS scripts, multimedia, documentation and accessory files that implement a KVIrc feature. It might be a simple automatic-away subsystem, a GUI newsticker or a complex file sharing service (commonly called "fserve"). Addons are sometimes called "scripts". In fact a KVIrc addon is usually made of more than one KVS script.

KVIrc has a builtin addon management system that allows the users to install, configure and uninstall features with a nice graphical interface. The management system allows the addons to have documentation integrated in the KVIrc help and to be translated in several languages.

Addon installation

The addons are usually shipped in compressed archives (such as tar.gz "tarballs" or zip files). Once uncompressed they should contain a KVS script file called "install.kvs". KVIrc will look for and execute this file when the user will ask for your addon to be installed. The install.kvs will usually contain the code for the registration of your addon and will include all the other necessary source files.

The minimal addon

The smallest addon that you can write is the one that does nothing. It just need to be writte in a file named install.kvs and contain code similar to the following:

    addon.register("myaddon", \
                        "1.0.0", \
                        "My First Addon", \
                        "An addon that is really cool but does simply nothing", \
                        "3.2.0.99.20051230")
    {
    }

The code above does nothing but registers the "myaddon" addon.

The first parameter is the internal addon id which can be used to identify your addon inside KVIrc. The id must be unique: two addons that share the same name cannot be installed. The second parameter is the addon version. It should be expressed in the classic format [major].[minor].[pathlevel] or something really similar (in fact KVIrc just expects the version to be a string composed of numbers separated by dots). The version is compared when an addon is installed and KVIrc complains if the user tries to downgrade an addon (that is to install a less recent version over a more recent one). The third parameter is the visible name of your addon: it will be displayed to the user in the addon management dialog. It can contain the $tr function so you can have it translated to several languages. The fourth parameter is a short description of the feature that the addon implements; it can contain the $tr() function too. The fifth parameter is the minimal KVIrc version required to run the addon. There is also a sixth parameter (the icon) and some switches that can be used to fiddle a little bit more :)

The callback instruction that follows the registration command is the uninstallation code. KVIrc will invoke it when the user will ask for your addon to be uninstalled. Don't assume that your addon will be never uninstalled: sooner or later it will be. For example, when upgrading an addon KVIrc will first uninstall the existing version and after that install the new one. The uninstallation process is a very important requisite for any program (in any programming language). In the example above there is nothing to uninstall (yet) so the callback code is empty, but if you continue reading we will soon fill it.

A typical addon layout

As stated above, the addons are usually shipped in a compressed archive. Once uncompressed, the archive will expand into a small directory tree containing the addon code and all the related files. In order to have uniformity I encourage you to use the following directory structure.

    addonId-version/
        install.kvs
        INSTALL
        src
                source1.kvs
                source2.kvs
                source3.kvs
                ...
        pics
                addonId_pic1.png
                addonId_pic2.png
                addonId_pic3.png
                ...
        audio
                addonId_audio1.png
                addonId_audio2.png
                addonId_audio3.png
                ...
        help
                en
                        index.html
                        hints.html
                        ...
                it
                        index.html
                        hints.html
                        ...
                ...
        locale
                addonId_it.mo
                addonId_ru.mo
                addonId_de.mo
                ...
        ...
                ...
                ...
                ...
                ...

The entries in bold are directories while the other are files. Please note that this is a general layout for a huge and rather complex addon: you might not need all of these directories. Remember: the minimal addon has only an install.kvs file. Anyway, a really cool addon will probably have all of them and maybe some more.

The toplevel directory should be named with your addonId and version. Try to use no spaces in the directory entries (this will make the things simplier for people that want to use your addon). The toplevel directory should contain your install.kvs script and a file with a small description and the basic installation instructions. This file can be named INSTALL or README.

Hint: Remember that your addon is going to be installed on different platforms (at least linux, macosx and windows based). The poor windows notepad has serious problems with reading text files that contain only linefeeds as line separators. Keep it in mind...

The main source directory for your addon should be named "src" and should contain the implementation of the feature(s) you're going to provide. These files should be executed by the means of the parse command (or include if you like the C/C++ style) from install.kvs.

The "pics" and "audio" (if relevant) directories should contain your multimedia files. It is a good idea to prefix the filenames with your addon id in order to avoid collisions with other addons. The install.kvs script should copy these files to the appropriate locations under the KVIrc local directory returned by $file.localdir().

The "help" directory should contain subdirectories for each language that your help files are written in. The languages dirs should be named with the language code also used for the translation files (like "en","it" etc...). Please note that english is the default language and KVIrc will fallback to the "en" subdirectory when no other language is found around... The help files (and subdirectories) should be copied to the "help" subdirectory of the KVIrc local directory returned by $file.localdir(). Since there will be many help files inside the language dirs, it is a good idea to either prefix your help files with your addon id or (better) to create a subdirectory named agains your addon inside the help language directory. For an english file this would lead to something like...

    file.copy index.html $file.localdir("help/en/myaddon")

The "locale" directory should contain the *.mo files for your tranlations. The localization process of a script is explained in this document. The *.mo files should be copied to the "locale" subdirectory of the KVIrc local directory returned by $file.localdir(). Your *.mo filenames should be prefixed by your addon id (again to avoid collisions).

The help and configuration callbacks

Each addon can have a help and a configuration callback. These are set respectively by addon.sethelpcallback and addon.setconfigurecallback.

The help callback will be invoked by KVIrc when the user will ask help for your addon (mainly from the addon management dialog, but not necessairly). It should call help.open with the name of your documentation index html file (it should be relative to the help language directory: help.open myaddon/index.html will automatically lookup the right language). If you provide no help callback, the buttons for requesting help will be simply disabled. (A good an relatively complex addon *should* have at least a minimal help file explaining the features).

The configuration callback will be invoked when the user will try to configure your addon from the addon management dialog. This callback is useful mainly for complexier graphical scripts that can show up a dialog that allows configuring all of the addon features. To use this callback you will probably need some object scripting.

The real addon work

The real addon work is done by the scripts contained in the src directory. They will likely add aliases (maybe in a nice namespace named agains your addon), register event handlers, create actions, timers, toolbars and object classes. You should install all of this stuff from your addon source files. Remember that your source files will NOT be parsed every time KVIrc starts up: your stuff must be registered in KVIrc and be able to startup itself, if needed. Remember that you must clean up everything in your uninstallation callback. This means that you must remove the aliases, unregister the event handlers, destroy the actions, kill the timers and the object classes you've created. Be a clean coder :)

Where to start

It is a good idea to start on the KVIrc web site. There are surely several addons to look at. Pick one that seems simple and analyze its layout and code (wow... the free software!). It will be easier to do than it was to explain it :D

Have fun! :)


Index, Language Overview
KVIrc 3.9.99 Documentation
Generated by root at Wed Oct 17 19:34:06 2007