Plugin class reference
[Base module]

Declaration  

#include <QtLua/Plugin>

namespace QtLua {
class Plugin;
};

This class is a member of the QtLua namespace.

This class is declared in QtLua/qtluaplugin.hh source file, line 94.

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  

Private type  

Functions  

Private function  

Static function  

Private fields  

Macro  

Members detail  

Plugin(const String &filename)  

This constructor is declared in QtLua/qtluaplugin.hh source file, line 101.

Load a new plugin

~Plugin()  

This destructor is declared in QtLua/qtluaplugin.hh source file, line 103.

#define QTLUA_PLUGIN_FUNCTION_REGISTER(plugin, name)  

This macro is declared in QtLua/qtluaplugin.hh source file, line 117.

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

This macro expands to:

(new QtLua_Function_##name)->register_(plugin, #name)

Ref<Plugin::Loader> _loader  

This variable is declared in QtLua/qtluaplugin.hh source file, line 137.

This member access is private.

This variable is declared in QtLua/qtluaplugin.hh source file, line 136.

This member access is private.

template <typename interface> interface * api() const  

This template function is declared in QtLua/qtluaplugin.hh source file, line 111.

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

virtual void completion_patch(String &path, String &entry, int &offset)  

This virtual function is declared in QtLua/qtluaplugin.hh source file, line 134.

This member access is private.

This virtual function overrides the completion_patch virtual function defined in the QHashProxyRo base class.

Documentation inherited from base class:

This function may be reimplemented to further modify completion result on console line when completed to a UserData value. This is usefull to append a dot or a pair of brackets access operator to the userdata value name for instance.

Parameters list:

  • path: Completion result tables path to userdata value.
  • entry: Completion result userdata name. May append to this string directly.
  • offset: Cursor offset. May be decreased to place cursor between inserted brackets for instance.

typedef Ref<const Plugin, Plugin> const_ptr  

This typedef is declared in QTLUA_REFTYPE function like macro expansion, line 3 in QtLua/qtluaplugin.hh source file, line 98.

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

static const String & get_plugin_ext()  

This function is declared in QtLua/qtluaplugin.hh source file, line 114.

Get platform dependent plugin file name suffix

typedef Ref<Plugin, Plugin> ptr  

This typedef is declared in QTLUA_REFTYPE function like macro expansion, line 5 in QtLua/qtluaplugin.hh source file, line 98.

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

Value to_table(State *ls) const  

This function is declared in QtLua/qtluaplugin.hh source file, line 106.

Convert Plugin object to lua table

Valid XHTML 1.0 StrictGenerated by diaxen on Sat Mar 30 16:23:03 2013 using MkDoc