Plugin class reference
[Functions export module]

Declaration  

#include <QtLua/Plugin>

namespace QtLua {
class Plugin;
};

This class is a member of the QtLua namespace.

Description  

This class allows easy development and loading of Qt plugins which can be manipulated from lua scripts.

These plugins must use the PluginInterface interface. It may have additional Qt plugin interfaces which can be queried with the Plugin::api function from C++ code.

These plugins may to contains Function objects which can be invoked from lua.

Function objects contained in plugin library must be registered on the Plugin object. This is done on Plugin creation by the PluginInterface::register_members function which must be implemented in the plugin to call the Function::register_ function for each member to register.

An internal plugin loader object is allocated and referenced by registered member Function objects to prevent plugin unloading until all registered members get collected, even if the associated Plugin object is destroyed.

The Plugin object may be exposed to lua as a read only table like userdata object which contains registered members; it also exposes the plugin name and description.

The Plugin object can also be used to just load the plugin and get a lua table containing all registered Function objects by using the Plugin::to_table function in C++ or the - operator in lua. In this case there is no need to expose or keep the Plugin object once the plugin has been loaded.

The QtLuaLib lua library provides a plugin() lua function which returns a Plugin userdata object for a given plugin file name. The platform dependent plugin file name extension will be appended automatically. The returned Plugin object may be converted directly to a lua table using the - lua operator.

See also PluginInterface class.

Example  

Here is the code of an example plugin. The header file implements the Qt plugin interface:

// code from examples/cpp/plugin/plugin.hh:6

#include <QObject>
#include <QtLua/PluginInterface>

class ExamplePlugin : public QObject, public QtLua::PluginInterface
{
Q_OBJECT
Q_INTERFACES(QtLua::PluginInterface)

public:

const QtLua::String & get_name() const;
const QtLua::String & get_description() const;
void register_members(QtLua::Plugin &plugin);
};

The plugin source file registers a Function object:

// code from examples/cpp/plugin/plugin.cc:3

#include <QtLua/Function>
#include <QtLua/Plugin>

#include "plugin.hh"

Q_EXPORT_PLUGIN2(example, ExamplePlugin)

const QtLua::String & ExamplePlugin::get_name() const
{
static const QtLua::String s("example");
return s;
}

const QtLua::String & ExamplePlugin::get_description() const
{
static const QtLua::String s("This is just an example plugin");
return s;
}

void ExamplePlugin::register_members(QtLua::Plugin &plugin)
{

static class : public QtLua::Function
{
QtLua::Value::List meta_call(QtLua::State &ls, const QtLua::Value::List &args)
{
return QtLua::Value(ls, "foo");
}

} foo;

foo.register_(plugin, "foo");
}

Here is a C++ example of plugin use:

// code from examples/cpp/plugin/plugin_load.cc:28

QtLua::State state;
state.openlib(QtLua::QtLuaLib);

// forge plugin filename
QtLua::String filename = QtLua::String("plugin") + QtLua::Plugin::get_plugin_ext();

// load the plugin as a QtLua::Plugin userdata value
state["plugin_userdata"] = QTLUA_REFNEW(QtLua::Plugin, filename);
// access the QtLua::Plugin object and call the QtLua::Function object
state.exec_statements("print(plugin_userdata.foo())");

// load the plugin and convert the QtLua::Plugin object to lua table
state["plugin_table"] = QtLua::Plugin(filename).to_table(state);
// access the lua table and call the QtLua::Function object
state.exec_statements("print(plugin_table.foo())");

Inheritance  

Members  

Inherited members  

Types  

Functions  

  • Plugin(const String &filename)
  • template interface * api() const
  • const String & get_name() const
  • Value to_table(State &ls) const

Static function  

Members detail  

Plugin(const String &filename)  

Load a new plugin

template <typename interface> interface * api() const  

Get instance of the requested interface type. Return 0 if no such interface is available in the plugin.

typedef Ref<const Plugin, Plugin> const_ptr  

Shortcut for Ref smart pointer class to Plugin type provided for convenience

const String & get_name() const  

Get plugin name

static const String & get_plugin_ext()  

Get platform dependent plugin file name suffix

typedef Ref<Plugin, Plugin> ptr  

Shortcut for Ref smart pointer class to Plugin type provided for convenience

Value to_table(State &ls) const  

Convert Plugin object to lua table

Valid XHTML 1.0 StrictGenerated by diaxen on Mon Aug 15 03:23:06 2011 using MkDoc