# Loadable modules

KVIrc modules model

Starting from version 2.0.0, KVIrc included support for external plugins: parts of code that can be loaded at runtime. The support was optional and the main KVIrc functionality was indipendant of that support. In version 3.0.0 the "modularity" has becomed one of the primary KVIrc features. The pieces of external code are now named "modules". The module support has been rewritten completly to extend the available features and remove some "basic" problems that were present in 2.0.0. This caused the old "plugins" to be binary incompatible with the new KVIrc executable; anyway, most old "plugins" have been rewritten as "modules" and included in the 3.0.0 distribution. Some of the basic KVIrc features are based on modules now; for example, the help browser is now in an external library called libkvihelp.so. This allows to keep the basic KVIrc executable smaller and faster (in some phases). Module loading is now "transparent" to the user. There are no "load" and "unload" commands: the modules are automatically loaded when the "core" requests them and unloaded after some (configurable) time of inactivity.

## Module naming convention

Every KVIrc module must have an "unique" name: the name is a single token, made only of lowercase letters , digits and underscores. The real object file (library) is named "libkvi<name>.so". This convention allows KVIrc to load modules when they are referenced by name in the scripting code (the reference in the code is case insensitive and remapped always to the lowercase version).

## What a module can do

Basically, a module exports parts of the scripting language features. For example, the module "about" exports the "aboutkvirc" command, that shows the dialog that lists the KVIrc staff people. The dialog will be effectively activated only few times (maybe only once) by a single user: including it in a separate module allows keeping rarely used code out of the KVIrc executable and saving some memory. To activate the dialog you only need to execute the command:

    about.aboutkvirc

That's all. KVIrc will load the necessary module, run the "aboutkvirc" command, wait until the module is not used anymore and then unload it.

## Transparent loading and unloading

Any command that has the form <name>.<command> is assumed to be a module reference. KVIrc tries to locate the module named <name>, load it (if not already in memory) and execute the <command>. After the command execution KVIrc waits some user defined interval of time (typically 2-3 minutes) and then check the module state: if the module has not been referenced again, it is unloaded, otherwise it is kept in memory for another period of time. To prevent accidentaly unloading a module that has some windows or dialogs open, a module can lock itself in memory. For example, the 'help' module lock itself when a help browser window is open and unlocks itself when the last help browser window is closed.
A module can export functions as well: the function names follow exactly the same rule as the commands: $<name>.<function> is assumed to be a reference to the <function> exported by module named <name>.

## Forced loading and unloading

All the modules export a "load" and a "unload" command.

    about.load

The example above will do nothing more than loading the "about" module into the core memory.

    about.unload

The example above will forcibly unload the module from the core memory; even if it is still locked.
Please note that this can be dangerous in some situations...so better check the KVIrc behaviour twice before making public any script that uses this command.

Main index, Miscelaneous documentation index

KVirc 3.0.0 documentation
Generated by root at Thu Apr 29 12:41:05 2004