Plugin class reference
[Base module]


 
 

 
 


 
 

 
 

QHashProxyRo<plugin_map_t>

 
 

 
 


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 handled from lua scripts.

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

These plugins are designed to contain 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 from the PluginInterface::register_members function. This function must invoke the QTLUA_PLUGIN_FUNCTION_REGISTER macro for each Function to register.

An internal plugin loader object is allocated and referenced by the Plugin object so that the Qt plugin is unloaded when the object is garbage collected. Function objects invoke the RefobjBase::ref_delegate function on the Plugin object when registered. This ensure references to plugin functions will keep the plugin loeaded.

The Plugin object can be copied to a lua table containing all registered Function objects by using the Plugin::to_table function in C++ or the - operator in lua. When used that way, 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/Plugin>

class ExamplePlugin : public QObject, public QtLua::PluginInterface
{
Q_OBJECT
Q_INTERFACES(QtLua::PluginInterface)
#if QT_VERSION >= 0x050000
Q_PLUGIN_METADATA(IID "qtlua.ExamplePlugin")
#endif

public:

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"

#if QT_VERSION < 0x050000
Q_EXPORT_PLUGIN2(example, ExamplePlugin);
#endif

QTLUA_FUNCTION(foo, "The foo function", "No help available")
{
Q_UNUSED(args);
return QtLua::Value(ls, "result");
}

void ExamplePlugin::register_members(QtLua::Plugin &plugin)
{
QTLUA_PLUGIN_FUNCTION_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 and convert the QtLua::Plugin object to lua table
state["plugin_table"] = QTLUA_REFNEW(QtLua::Plugin, filename)->to_table(&state);
state.exec_statements("print(plugin_table.foo())");

// unload the plugin
state.exec_statements("plugin_table = nil");
state.gc_collect();

// reload the plugin as a QtLua::Plugin userdata value
state["plugin_userdata"] = QTLUA_REFNEW(QtLua::Plugin, filename);
state.exec_statements("print(plugin_userdata.foo())");

Members  

Inherited members  

Types  

Functions  

Static function  

Macro  

Members detail  

Plugin(const String &filename)  

Load a new plugin

~Plugin()  

No documentation available

#define QTLUA_PLUGIN_FUNCTION_REGISTER(plugin, name)  

This macro registers a Function object on a Plugin object. It must be used in the PluginInterface::register_members function

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

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 Sat Mar 30 15:29:54 2013 using MkDoc