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
- 30 members inherited from QHashProxyRo<plugin_map_t>
Types
Private type
- struct Loader
Functions
Private function
- virtual void completion_patch(String &path, String &entry, int &offset)
Static function
- static const String & get_plugin_ext()
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
This destructor is declared in QtLua/qtluaplugin.hh source file, line 103.
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)This variable is declared in QtLua/qtluaplugin.hh source file, line 137.
This member access is private.
plugin_map_t _map
This variable is declared in QtLua/qtluaplugin.hh source file, line 136.
This member access is private.
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.
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.
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
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