addon.register

Registers a script-based addon

Usage

addon.register [-f] [-n] [-q] (<id:string>,<version:string>,<visible_name:string>,<description:string>,<minkvircverion:string>[,<iconid:string>])
{
<uninstall callback>
}

Description

Registers a script-based addon.

The registration process allows to show the addon in the script-addon manager dialog and provides a standard way for the user to manage and uninstall the addons. You simply register your addon BEFORE attempting to install it.

A script-based addon is a set of scripts, icons, translations and possibly other data files that add functionality to the KVIrc program. The script-based addons are often simply called scripts and we will adhere to that naming in certain parts of the documentation too.

Each script-based addon (a set of scripts) is identified by a UNIQUE <id>. Two addons with the same <id> can't co-exist in the same KVIrc installation (so be sure to choose a token unique enough to avoid collisions with others). The <id> itself is used only for identification purposes and the user will almost always see the <visible_name> instead, which can contain the $tr function that will handle the translation for it.

Each addon also has a <version> which is a string in the form x.y.z where x, y and z are numbers (yes.. that's the standard major-minor-patch level version numbering scheme). A <version> of 2.4.23 is greater than 2.4.3 even if 2.4.3 comes after when compared as a string. When an updated addon is installed over the same or previous version, the current version is first uninstalled. Installing a lower version over a greater one is not possible, unless the lower version one is uninstalled first.

<description> is another, possibly translated, string that will be presented to the user in the addon management dialog.

<minkvircversion> is the minimum KVIrc version required for the addon to run. If the version of the running KVIrc executable is lower than the requested one then the command will abort with an error. If you want to completely ignore the KVIrc versioning (don't do it), use 0.0.0 here. If you need fine tuning on git features you may also add the sources date tag at the end of the required version string (e.g 3.2.1.20060303).

<iconid> is the image identifier of the icon that will be displayed in the addon management dialog. If not specified, a default icon will be used.

The <uninstall_callback> is a snippet of code that should wipe out the addon from the system. It is ALWAYS a good practice to write a complete uninstallation procedure (think that YOU like to be able to completely uninstall a program that you don't use anymore). The <uninstall_callback> will be called by KVIrc when the addon uninstallation is requested, either explicitly by using the GUI or the command addon.uninstall, or implicitly by installing a newer version of the addon (upgrading).

If the user's security configuration doesn't allow your addon to be installed, or a higher version of an addon with the same name already exists, the command will fail with an error (aborting the installation process). If you don't want to fail with an error but handle it gracefully instead, you should use $addon.exists() to check if an addon with the same name and a greater version already exists. You can't gracefully handle security error conditions: your installation will be always aborted with an error in this case.

The addon can also define a configuration callback via addon.setconfigurecallback and a help callback via addon.sethelpcallback. The first will usually display a configuration dialog, the second will display some sort of addon documentation, usually in the help browser.

The registration process uninstalls any previous addon version by executing its uninstall callback routine. This is another reason that you should call addon.register BEFORE you attempt to install your addon. Failing to do this may result in the the old version uninstallation wiping out your newly installed files or code.

Switches

-f | --force

Registers the addon even if an addon with the same <id> and a higher version already exists. The usage of this flag is highly discouraged (i.e. use it only for debugging purposes on your own machine).

-n | --no-uninstall

Performs no uninstallation of existing versions of the addon: it simply replaces the registration entry with the new data. Again, only use this switch for debugging purposes and on your own machine.

-q | --quiet

Makes the command run quietly

Examples