QtLua and Qt Package Reference Manual

The package qt is available when you run the Lua interpreter using the qlua program. It provides a seamless interface between the lua interpreter and the Qt4 portable user interface libraries. Of course, a full understanding of this package qt requires a minimal familiarity with the Qt4 library.

Program qlua relies in fact on the QtLua C++ library which provides a Qt object that encapsulates a Lua interpreter. All properties, slots and signals declared by the C++ Qt objects are automatically exposed in the Lua interpreter. Signals can be connected to Lua functions.

The packages qtcore, qtgui, and qtuiloader provide bindings for the classes defined by the corresponding Qt libraries.

Program qlua

Program qlua is a compatible replacement for the standard interpreter program lua with several new capabilities:

  • New packages provide a rich interface with the Qt4 library: qt, qtwidget, qtuiloader.
  • The Lua interpreter runs in a dedicated thread. The main thread remains in charge of graphical interface and user interaction. Therefore all graphical interfaces remain active while the interpreter is running.
  • Console output can be captured and emitted as Qt signals.

Therefore one can program a complete integrated development environment including a graphical console.

Usage

Program qlua accepts the same command line options and arguments as the stand-alone Lua interpreter lua. It also accepts all the Qt command line options as well as a few specific options.

At any time, one can exit the interpreter using [CTRL-D].

Usage: qlua [options] [script <scriptargs>]
The lua options are:
  -e stat       execute string 'stat'
  -l name       require library 'name'
  -i            enter interactive mode after executing 'script'
  -v            show version information
  --            stop handling options
  -             execute stdin and stop handling options
The specific qlua options are:
  -ide          run the qlua integrated environment
  -onethread    run lua in the main thread
  -nographics   disable all the graphical capabilities
The most important Qt options are:
  -style s      set the application gui style 's'
  -session s    restore gui session 's'
  -display d    set the X display (default is $DISPLAY)
  -geometry g   set the main window size and position
  -title s      set the main window title to 's'
  ...           see the Qt documentation for more options

Option -nographics initializes the Qt library for a text-only application. This can be handy when executing scripts because it avoids unnecessary overhead.

Option -onethread runs the Lua interpreter in the main thread instead of starting a dedicated thread. As a consequence, while Lua is running, graphical operations are not handled, windows are not painted, timers are not honored, etc., unless the Lua program calls qt.doevents() frequently enough. This is not the normal mode of operation of qlua but this can be useful for debugging purposes.

Components

Program qlua is a Qt program composed of three objects working independently in separate threads.

  • The console manager manages the interactive session using input and output on a terminal or inside a shell window. It can capture all output to the stdout file descriptor and publish it as Qt signal for use in graphical interfaces. It also manages the user input with Lua code completion.
  • The QtLua engine runs the Lua code and provides the integration with the Qt environment.
  • The application manager runs in the main thread. It handles the graphical user interface events and all the notifications emitted by the console manager and the lua engine.

Running the Lua interpreter in a separate thread lets the main thread handle user interaction at all times. Windows are refreshed and user interfaces remain active while a Lua program is running.

At times the Lua code needs to act on objects living in another thread. Potential synchronization problems are avoided using the "thread hopping" technique which allows the execution of a Lua function in the target thread. When the function returns, the Lua thread resumes the normal execution of the Lua code. Thread hopping happens automatically when invoking a method defined by a Qt object. Thread hopping can also be performed manually using functions qt.qcall or qt.xqcall.

Package qt

When you run program qlua, the package qt is readily accessible using require('qt') because the libqtlua library installs a suitable loading function in the array package.preload['qt'].

Package qt essentially contains the metatables associated with Lua userdata values and a few useful functions. The QtLua API also provides a means to name an arbitrary Qt object and publish it inside the package qt.

Qt Variants

Values represented by the Qt class QVariant can be exposed to the Lua interpreter as userdata. Class QVariant defines in fact a container for a large number of standard Qt types with value semantics. In fact any type registered with the Qt macro Q_DECLARE_METATYPE can be represented by a Qt variant value.

Whenever a QVariant value is made accessible to the Lua interpreter (see luaQ_pushqt), the QtLua library ensures that there is a metatable associated with all objects of that type. Methods for each type can then be added to the class table qt.TypeName where TypeName represent the type name. If the class table contains a method named new, this method is used to construct new values of that type using the syntax qt.Typename(...).

The metatable defines the standard Lua hooks __eq to perform an equality test and __tostring to return a string representing the data. In addition, the following methods are predefined in all class tables:

qtdata:tostring()

Function qtdata:tostring() returns a Lua string representing the value contained in the Qt variant.

  • Qt variants of type QString are converted to Lua strings using the local multibyte encoding.
  • Qt variants that can be converted to type QByteArrayare also transformed into Lua strings.
  • Other types are represented using the type name followed by the hexadecimal representation of a pointer to the data.

qtdata:tonumber()

Function qtdata:tonumber() returns a Lua number representing the value contained in the Qt variant. The value nil is returned when the data type cannot be meaningfully converted to a numeric value.

qtdata:tobool()

Function qtdata:tobool() returns a boolean value associated with the value contained in the Qt variant. This is achieved by calling the Qt function QVariant::isNull. In the case of object pointers, this function can be used to determine if the object has been deleted or is currently allocated.

qtdata:type()

Function qtdata:type() returns a string naming the type of the value contained in the Qt variant. In the case of object pointers, this function returns a string of the form "ClassName*" where ClassName represents the object class. If the object has been deleted, this function returns nil.

qtdata:isa(typename)

Function qtdata:isa(typename) returns a boolean value indicating whether the Qt variant contains an object of type typename. In the case of object pointers, this function returns true if the object inherits the qt object class named typename.

Qt Objects

Critical Qt classes are subclasses of class QObject. Qt distinguishes some member functions of these classes, namely slots, signals and properties. Qt provides means to enumerate these slots, signals and properties at run time. Please refer to the Qt documentation on the Qt object model for more details.

Instances of these classes are known as Qt objects. Pointers to Qt objects can be exposed to the Lua interpeter because Qt variants can contain values of type QObjectPointer which is a guarded pointer to a Qt object.

Such values have a special treatment:

  • A distinct metatable is allocated for each Qt object class. These metatables are available in the qt package and follow the same inheritance pattern as the Qt object class hierarchy. Class qt.QObject sits at the top of this hierarchy.
  • Slots, signals and properties are automatically exposed to the Lua interpreter. This is achieved using the information collected by the Qt precompiler moc.

Memory management

Qt organizes the Qt objects hierarchically. An object can be an orphan or can be the child of another object. When a Qt object is deleted, all its descendants are deleted as well. When programming in C++, orphan objects must be deleted manually.

Two situations arise when a Qt object is exposed the Lua interpreter.

  • An exposed Qt object may be deleted by C++ code, either directly, or indirectly because one of its ascendant has been deleted. The Lua userdata representing the object becomes a "zombie". Zombies can be detected using method tobool().
  • An exposed Qt object may be deleted because the Lua garbage collector determines that the Lua program no longer needs this object. Whether this happens is determined when the object is exposed to the Lua interpreter. Such objects are said to be owned by Lua.

In general, orphan objects created from a Lua program are owned by Lua. Objects with a parent and orphan objects created from C++ code are not Lua owned and are not affected by the decisions of the Lua garbage collector.

Properties

Qt object properties are automatically available using the Lua indexation syntax

Examples:

widget.windowTitle="my window title"
return widget.windowTitle

Properties are always manipulated from the thread owning the Qt object. If the Lua interpreter runs in a different thread, a thread hopping operation is performed for the duration of the operation.

Property values are always represented as Qt variant objects.
QByteArray variants and numerical variants are automatically converted into Lua strings or Lua numbers when they are read. However QString variants are left unchanges since such strings can contain non ASCII characters. Conversely, Lua strings and Lua numbers are automatically converted into the desired type when a property is set.

Property values with enumerated types registered using the Qt macro Q_ENUMS are automatically converted into strings representing the enumerated names and conversely. Property values with flag types declared using the Qt macro Q_DECLARE_FLAGS and registered using Q_ENUMS are automatically converted into Lua string containing the relevant flag names separated by vertical bars.

Slots and Invokable Methods

Public and protected Qt slots can be called using the Lua method invokation syntax.

Examples:

widget:setEnabled(true)
widget:show()

Public and protected member functions whose c++ declaration is marked with the Qt macro Q_INVOKABLE can also be invoked using the standard Lua syntax.

When a member function has the same name as a property, the property takes precedence. When overloaded member functions are exposed in this fashion, the QtLua library makes a best effort to determine which function should be called. It first narrows the choices using the number of parameters. When several options remain, it chooses one on the basis of the types of the parameters. Member function arguments with default values are handled by considering implicit overloaded functions.

It is always possible to work around these rules by selecting a particular member function using its signature.

widget['setEnabled(bool)'](widget, true)

Member functions exposes in this way are always invoked from the thread owning the Qt object. If the Lua interpreter runs in a different thread, a thread hopping operation is performed for the duration of the operation.

A Lua string is automatically converted when a QByteArray or a QString argument is expected. A Lua number is automatically converted whenever a numerical type is expected. Return values with numerical types are converted into Lua numbers. Return values of type QByteArray are automatically converted into Lua strings. Return values of type QString are returned as string variants.

Inheritance ensures that all methods exposed by a class are also exposed by its subclasses. Methods exposed by the QObject class, such as deleteLater(), are inherited by all Qt object classes.

Named Children

All Qt objects can be given a name represented by property objectName. The named children of a Qt object can be accessed by name using the indexation syntax. However, when the name of a child conflicts with a property or an exposed method, the property or the exposed method has precedence. Named children are searched in the whole descendency tree using the Qt function qFindChild.

Signals

Lua programs can emit and receive Qt signals.

Emitting Signals

Lua programs can emit signals using the function call syntax. Consider for example the following c++ class:

class MyQObject : public QObject {
  Q_OBJECT
...
signals:
  void mysignal(QByteArray msg, int x=0);
...

Given an instance myqobject of this class, a Lua program can emit signal mysignal as follows 

myqobject:mysignal("mymessage") -- or
myqobject:mysignal("mymessage", 4)

Overloaded signals are resolved like method invokation. In particular, arguments with default values are handled by considering implicit overloaded functions. As for functions, it is always possible to work around these rules by selecting a particular signal using its signature.

myqobject['mysignal(QByteArray,int)'](self,"message",3)

Receiving Signals

Qt signals can be connected to Lua functions using qt.connect(...).

For instance, the clause

qt.connect(qobject,'mysignal(QByteArray)', 
   function(s) print("mysignal("..s..")") end)

ensures that the specified lua function is called whenever the signal with signature mysignal(QByteArray) is emitted. Arguments with string types are converted to Lua strings, and arguments numerical types are converted to Lua numbers.

Functions passed to qt.connect can of course be closures:

local table = some_lua_object()
qt.connect(qobject,'mysignal(QByteArray)',
   function(s) table:mysignalemitted(s) end)

When the signal occurs while the Lua interpreter is busy, the execution of the Lua function connected to the signal is delayed until the Lua interpreter becomes available, either because the execution of the current Lua code terminates or because function qt.doevents() is called.

Objects

qt.qApp

Expression qt.qApp refers to the application object which orchestrates the operation of the qlua program. This object is the sole instance of class QLuaApplication. A few exposed slots and properties are relevant for Lua programs.

qt.qApp:quit()

Function qt.qApp:quit() quits the qlua application.

qt.qApp:restart(bool)

Function qt.qApp:restart(bool) reinitializes and restarts the Lua interpreter. When the optional flag bool is true, the command line arguments passed to the program qlua are re-executed.

qt.qApp:about()

Function qt.qApp:about() displays an about box dialog displaying the contents of the property qt.qApp.aboutMessage.

qt.qApp.aboutMessage

Property qt.qApp.aboutMessage contains an HTML string that is displayed in the about box when function qt.qApp:about() is invoked.

qt.qApp:readSettings(key)

Reads the preference settings associated with string key.

qt.qApp:writeSettings(key,value)

Sets the preference settings associated with string key to value. Argument value should be a Lua value that can be converted into a QVariant.

qt.qApp:runsWithoutGraphics()

This function returns true if the qlua interpreter was launched with the option -nographics.

qt.qConsole

Expression qt.qConsole refers to the console object which handles console input and output for the qlua program. This object is the sole instance of class QLuaConsole. A few exposed slots, signals and properties are relevant for Lua programs.

qt.qConsole.captureOutput

When the boolean property qt.qConsole.captureOutput is set, all output to the stdout file descriptor is captured and reexpressed by emitting signal consoleOutput(QByteArray).

qt.qConsole.printCapturedOutput

When qt.qConsole.captureOutput is true, the boolean property qt.qConsole.printCapturedOutput determines whether the captured text is display on the console or not.

qt.qConsole:addToHistory(string)

Function call qt.qConsole:addToHistory(string) adds string to the history of recent console input. This works only when qlua is compiled with command line history support.

[QLuaConsole signal] consoleOutput(QByteArray)

When qt.qConsole.captureOutput is true, signal consoleOutput(QByteArray) is emitted whenever a string is output to the file descriptor stdout. Capturing this signal can be useful to program a graphical replacement for the console.

[QLuaConsole signal] ttyInput(QByteArray)

Signal ttyInput(QByteArray) is emitted whenever a new input line has been validated by the user on the console.

[QLuaConsole signal] ttyEndOfFile()

Signal ttyEndOfFile() is emitted whenever an end-of-file condition is detected on the console input. When this happens, qlua asks the user if he really wants to quit the application.

[QLuaConsole signal] ttyBreak()

Signal ttyBreak() is emitted whenever the interrupt key sequence, typically Ctrl+C or Ctrl+Break is typed on the input console. When this happens, qlua stops the execution of Lua programs and waits for new commands on the console.

qt.qEngine

Expression qt.qEngine refers to the Lua execution engine. This object is an instance of class QtLuaEngine. A few exposed slots, signals and properties are relevant for Lua programs. See the documentation of class QtLuaEngine in the QtLua API section for more information.

qt.qEngine.lastErrorMessage

Read-only property qt.qEngine.lastErrorMessage contains the last error message generated by the Lua interpreter.

qt.qEngine.lastErrorLocation

Read-only property qt.qEngine.lastErrorLocation contains a QStringList whose elements describe the program locations extracted from the stack when the last error message was recorded. When a location corresponds to a line in a file, the string has the format "@filename:linenumber".

qt.qEngine.printResults

Boolean property qt.qEngine.printResults indicates whether the Lua interpreter should print the results returned by the evaluation of interactive Lua expressions.

qt.qEngine.printErrors

Boolean property qt.qEngine.printErrors indicates whether the Lua interpreter should print the error messages caused by the evaluation of interactive Lua expressions.

Functions

qt.connect(qobject, signature, function, [direct] )

Expression qt.connect(qobject, signature, func) connects the signal signature from Qt object qobject to the Lua function func. Argument signature is a string containing the full signature (c++ prototype) of the signal. The function is invoked whenever the signal is emitted.

Example:

require 'qt'
timer = qt.QTimer()
timer.singleShot = true
qt.connect(timer,'timeout()', function() print("timeout") end)
timer:start(2000) -- wait for 2 seconds...

See section Receiving Signals for more details.

When the signal occurs while the Lua interpreter is busy, the execution of the Lua function connected to the signal is delayed until the Lua interpreter becomes available, either because the execution of the current Lua code terminates or because function qt.doevents() is called.

Setting the optional flag direct to true changes that when the Qt signal is emitted from the thread currently running a Lua program. It is then assumed that the signal is a consequence of the Lua program execution and the function is called synchronously.

Warning : Function func remains allocated as long as the connection exists. Memory can be leaked if function func is a closure that points to the signaling object because the garbage collector will find that the object is in use. Future versions of QtLua may address this weakness of the interface between the Lua garbage collector and the Qt static memory allocation. In the mean time, be careful to delete or disconnect connected objects as soon as you do not need them anymore.

qt.connect(qobject1, signature1, qobject2, signature2)

Expression qt.connect(qobject1, signature1, qobject2, signature2) connects signal signature1 from Qt object qobject1 to slot or signal signature2 of Qt object qobject2. This is similar to the Qt function QObject::connect(...).

qt.disconnect(qobject, signature, function)

Expression qt.disconnect(qobject, signature, func) disconnects the signal signature from Qt object qobject from the Lua function func. Arguments signature or function may be nil. All connections matching the non-nil arguments will then be disconnected.

qt.disconnect(qobject1, signature1, qobject2, signature2)

Expression qt.disconnect(qobject1, signature1, qobject2, signature2) connects signal signature1 from Qt object qobject1 from slot or signal signature2 of Qt object qobject2. Arguments signature1, qobject2, or signature2 may be nil. All connections matching the non-nil arguments will then be disconnected. This is similar to the Qt function QObject::disconnect(...).

qt.doevents([waitflag])

Function qt.doevents() processes all pending events and executes the functions associated with all queued signals. Calling this function periodically can be useful to ensure that queued signals are processed timely.

Calling this function is very important when you run qlua in single-threaded mode using option -onethread, as graphic output will not be displayed properly until qt.doevents() is called.

Setting flags waitflag to true causes the function to wait until at least one event is processed by the current thread. This can of course cause an infinite wait when there are no event source for the current thread.

qt.isa(arg, typename)

If the Lua value arg represents a Qt object or variant, expression qt.isa(arg,typename) returns a boolean indicating whether the Qt data is a subclass of type typename, as if arg:isa(typename) had been called. Otherwise it simply returns nil.

qt.pause()

Expression qt.pause() causes the interpreter to enter the mode Paused. When the interpreter pauses with qt.pause, all events are processed and all Lua functions associated with signals are executed whenever the signal occurs.

Note that calling qt.qEngine:stop(false) also causes the interpreter to enter the mode Paused. However, in that case, the Lua functions associated with signals are not executed.

qt.qcall(qobject, function, ... )

Expression qt.qcall(qobject, f, ...) executes function f from the thread owning the Qt object qobject. To achieve this, the current thread performs a rendez-vous with the object thread. The object thread takes ownership of the Lua data structures and invokes function f with the specified arguments. Meanwhile the original thread processes events and waits. When the function f returns, the original thread resumes the execution.

Like the standard Lua function pcall, this function returns multiple results. If an error occurs during the execution, this function returns false plus the error message. Otherwise it returns true plus the results returned by function f.

This function is the basis for the thread hopping mechanism that underlies the multi-thread operations in QtLua. Thread hopping happens automatically whenever one manipulates a slot or a property of a Qt object. It may occasionnally be useful to manually hop into an object thread in order to avoid the overhead of subsequent thread hopping operations: if the Lua interpreter is already running in the desired thread, the function f can be invoked directly without expensive synchronization.

Important : Thread hopping only works if the target thread runs an event loop, using QThread::exec() or QEventLoop::exec(). Execution of Lua program will stop if this is not the case.

Within program qlua, object qt.qApp is always owned by the main thread in charge of the user interaction, and object qt.qEngine is always owned by the auxilliary thread in charge of the evaluation of Lua expressions.

qt.require(modulename)

This function searches and loads the shared library modulename almost like the standard lua function require. However this function ensures that the shared library is loaded in a way maximally compatible with C++ code. Symbols defined by the shared library are defined in the global name space, that is, are available to resolve undefined symbols in other libraries. This is necessary for supporting the C++ RTTI features. This function also ensures that remains loaded when the Lua state is closed. This is necessary when the shared library defines classes whose instances outlive the Lua interpreter.

This function supports none of the advanced search methods implemented by the usual function require, other than searching a shared library along package.cpath.

qt.type(arg)

If the Lua value arg represents a Qt object or variant, expression qt.type(arg) returns a string containing the type of the Qt data as if arg:type() had been called. Otherwise it simply returns nil.

qt.xqcall(qobject, function, ..., errorhandler)

Expression qt.xqcall(qobject, f, ..., handler) is a thread hopping analogous to the standard \ Lua function xpcall.

Function f is invoked with the specified arguments by the thread owning the Qt object qobject. If the execution completes without error, xqcall returns true plus the results returned by f. If an error occurs during the execution, the error handling function handler is invoked on the error message in the Qt object thread. The xqcall function then returns false followed by the values returned by the error handler.

QtLua API

This section describes the QtLua API. Class QtLuaEngine and QtLuaLocker provides a Lua interpreter for use in any Qt application with capabilities comparable to those of the QtScript and additional support for multi-threaded execution. Additional functions with prefix luaQ provide the essential tools for manipulating Qt data in Lua functions written in C or C++.

Class QtLuaEngine

Class QtLuaEngine is a QObject subclass representing a Lua interpreter. This object can be used to add a Lua interpreter to any Qt application with capabilities comparable to those of the QtScript language and additional support for multi-threaded execution.

Instances of this class can be in one of three state:

  • State QtLuaEngine::Ready indicates that the interpreter is ready to accept new Lua commands.
  • State QtLuaEngine::Running indicates that the interpreter is currently executing a Lua program.
  • State QtLuaEngine::Paused indicates that the interpreter was suspended while executing a Lua program. One can then use the Lua debug library to investigage the Lua state.

Class QtLuaEngine provides member functions to submit Lua strings to the interpreter and to collect the evaluation results. If these functions are invoked from the thread owning the Lua engine object, the Lua code is executed right away. Otherwise a thread hopping operation ensures that the execution of a Lua program happens in the thread owning the Lua engine object.

Class QtLuaLocker provides means to directly access the Lua state lua_State* using the Lua API.

Constructor

QtLuaEngine::QtLuaEngine(QObject *parent = 0)

This is the constructor for class QtLuaEngine. Argument parent is the optional parent object.

Properties

[QtLuaEngine property, readonly] QtLuaEngine::State state

The read-only property state contains the state of the Lua engine.

State QtLuaEngine::Ready indicates that the interpreter is ready to accept new Lua commands.

State QtLuaEngine::Running indicates that the interpreter is currently executing a Lua program.

State QtLuaEngine::Paused indicates that the interpreter was suspended while executing a Lua program.

[QtLuaEngine property, readonly] bool ready

[QtLuaEngine property, readonly] bool running

[QtLuaEngine property, readonly] bool paused

The read-only properties ready, running, and paused are true if the Lua engine is in the corresponding state.

[QtLuaEngine property, readonly] QByteArray lastErrorMessage

The read-only property lastErrorMessage contains the text of the last error message produced by the Lua interpreter.

[QtLuaEngine property, readonly] QStringList lastErrorLocation

The read-only property lastErrorLocation contains a list of locations extracted from the stack when the last error message was recorded. When a location corresponds to a line in a file, this string has the format "@filename:linenumber".

[QtLuaEngine property] bool printResults

Boolean property printResults indicates whether the Lua interpreter should print the results returned by the evaluation of the strings passed to functions eval or evaluate. The default value is false.

[QtLuaEngine property] bool printErrors

Boolean property printErrors indicates whether the Lua interpreter should print error message caused by the evaluation of the strings passed to functions eval or evaluate and by signal function execution. The default value is true.

[QtLuaEngine property] bool pauseOnError

Boolean property pauseOnError indicates whether the interpreter should enter state Paused when an error occurs. Setting this to true implies that some code will call function resume otherwise the interpreter will remain in state Paused forever. The default is false.

[QtLuaEngine read-only property] bool runSignalHandlers

This property is true when the Lua interpreter honors the signal handler invokations immediately instead of queuing them for further processing.

Signals

[signal] void QtLuaEngine::stateChanged(int state)

Signal stateChanged is emitted whenever the interpreter state is changed.

[signal] void QtLuaEngine::errorMessage(QByteArray)

Signal errorMessage is emitted whenever an error message is captured by the error handler set by functions eval or evaluate.

Execution

[slot] bool QtLuaEngine::eval(QByteArray s, bool async = false)

[slot] bool QtLuaEngine::eval(QString s, bool async = false)

Function eval runs the Lua code contained in string s.

When function eval is invoked from the thread owning the Lua engine object, the Lua code is executed right away. Otherwise the execution of the Lua code is started in the thread owning the Lua engine object using thread hopping. Function eval returns immediately if flag async is true. Otherwise it processes Qt events and waits until the termination of the Lua code.

This function returns true if the evaluation was performed without error. It immediately returns false if the Lua engine was not in state ready or if flag async was true when calling the function from the engine thread.

[slot] QVariantList QtLuaEngine::evaluate(QByteArray s)

[slot] QVariantList QtLuaEngine::evaluate(QString s)

Function evaluate returns an empty QVariantList if called when the engine is not in ready state. Otherwise if evaluates Lua code s like function eval. If an error occurs during evaluation, function evaluate returns a list whose first element is QVariant(false) and whose second element is the error message. Otherwise is returns a list whose first element is QVariant(true) and whose remaining elements are the evaluation results.

[slot] bool QtLuaEngine::stop(bool nopause = false)

When the Lua engine is in state Running, function stop interrupts the execution of Lua code and returns true. If flag nopause is false, the Lua engine enters the state Paused when it stops. Otherwise it unwinds the stack as if an error had occurred and returns to state Ready. If the Lua engine is not in state Running or already in state Paused, this function does nothing and simply returns false.

[slot] bool QtLuaEngine::resume(bool nocontinue=false)

If argument nocontinue is false and the interpreter is in state Paused because function stop was called, the interpreter returns to state Running and resumes the execution of the Lua code interrupted by function stop. If the interpreter is in state Paused for another reason, it unwinds the stack, and returns to state Ready as if an error had occurred. Otherwise the function does nothing and returns false.

If argument nocontinue is true and the interpreter is in state Paused or Running, it unwinds the stack, and returns to state Ready if an error had occurred. Otherwise the function does nothing and returns false.

Miscellaneous

void QtLuaEngine::nameObject(QObject *obj, QString name = QString())

QObject* QtLuaEngine::namedObject(QString name)

QList<QObjectPointer> QtLuaEngine::allNamedObjects()

These functions can be used to make a Qt object accessible by name in package qt by Lua programs. Function nameObject sets the object's name and declare the object accessible in package qt. Function namedObject retrieved an accessible object by its name. Function allNamedObjects return all accessible objects. An accessible object is always accessed using its object name, even if one uses QObject::setObjectName to changed it after calling nameObject.

void QtLuaEngine::registerMetaObject(const QMetaObject *mo)

This function declare the Qt class identified by the metaclass mo to the QtLua system. This usually happens automatically when an object of that class is passed to QtLua for the first time. In rare case, it may be necessary to call this function to ensure that the types of slot and signal arguments are properly recognized as an object class.

Class QtLuaLocker

Class QtLuaLocker provides means to directly access the Lua state lua_State* using the Lua API. This class ensures that the current thread has exclusive access to the Lua state.

QtLuaLocker::QtLuaLocker(QtLuaEngine *engine)

Create a QtLuaLocker object and ensures that the current thread has exclusive access to the Lua state for the Lua interpreter engine. This constructor hangs until obtaining the lock

QtLuaLocker::QtLuaLocker(QtLuaEngine *engine, int timeOut)

Create a QtLuaLocker object and ensures that the current thread has exclusive access to the Lua state for the Lua interpreter engine. This constructor hangs at most for timeOut milliseconds. To know whether the lock was acquired, cast the QtLuaLocker as a lua_State* pointer.

lua_State* QtLuaLocker::operator lua_State*()

Returns a lua_State* pointer to access the state of the Lua interpreter using the Lua API. Since this is a cast operator, one can simply pass the QtLuaLocker object whenever a lua_State* is expected. This cast returns 0 when the constructor was unable to acquire the exclusive lock during the specified timeout.

bool QtLuaLocker::isReady()

Returns true if the locking operation was successful and the interpreter is in ready state. Note that locking and state are distinct concepts. It is possible to lock a running interpreter while it is waiting for other events. The eval and evaluate functions use this test to decide whether to run a command.

void QtLuaLocker::setRunning()

Sets the interpreter to state Running. The engine will return to state Ready after the destruction of the last QtLuaLocker object and the execution of the queue. Temporary releasing the lock with unlock() keeps the engine in state Running. */

This can be useful if you plan to call the Lua API functions lua_call or lua_pcall and expect the code to run for an extended period of time.

The luaQ functions

The luaQ functions complete the Lua API with facilities related to the QtLua interface. Some luaQ functions are only meaningful for C++ program. The following snipped ensure that all available functions are accessible in both C and C++.

 #include "qtluautils.h"
 #ifdef __cplusplus
 # include "qtluaengine.h"
 #endif

luaopen_qt

int luaopen_qt(lua_State *L)

Load the qt package into the interpreter. This is the function preloaded into package.preload['qt'].

luaQ_call

void luaQ_call(lua_State *L, int na, int nr, QObject *obj = 0)

Perform a Lua function call like lua_call but ensure that the function is executed in the thread owning object obj using thread hopping. Unlike function luaQ_pcall, this function relays Lua errors into the current thread. This is similar to calling

  if (luaQ_pcall(L,na,nr,0,obj)) 
    lua_error(L);

luaQ_checkqobject<TYPE>

TYPE* luaQ_checkqobject&lt;TYPE&gt;(lua_State *L, int index)

This function causes an error if the Lua value at position index in the stack does not represent a Qt object of class TYPE. Otherwise it returns a pointer to the object.

luaQ_checkqvariant<TYPE>

TYPE luaQ_checkqvariant&lt;TYPE&gt;(lua_State *L, int index)

This function causes an error if the Lua value at position index in the stack cannot be converted to Qt variant of actual type TYPE. Otherwise it returns a value of the requested type.

The C++ type TYPE must be known to the Qt meta type system. This can always be achieved using the macro Q_DECLARE_METATYPE.

luaQ_complete

int luaQ_complete(lua_State *L)

This function first pops a string from the top of the stack. The string could contain a symbol or several symbols separated with dots of periods. Function luaQ_complete then pushes a table containing potential completions for the last symbol in the string.

luaQ_connect

bool luaQ_connect(lua_State*L, QObject*o, const char *s, int fi)

Connects the signal with signature s from the Qt object o to the function at position fi in the stack. Returns true in case of success. Returns false if the specified signal was not found.

See also qt.connect(...)

luaQ_disconnect

bool luaQ_disconnect(lua_State*L, QObject*o, const char *s, int fi)

Disconnects the signal with signature s of Qt object o from the function located at index fi in the stack. When argument fi is zero, this function removes all connections from the specified signal to a Lua function. When argument s is null, this function removes all connections from the specified object to the specified function.

See also qt.disconnect(...).

luaQ_doevents

void luaQ_doevents(lua_State *L, bool wait = false)

Processe all pending events and execute the functions associated with all queued signals. Calling this function periodically can be useful to ensure that queued signals are processed timely.

See also qt.doevents().

luaQ_engine

QtLuaEngine *luaQ_engine(lua_State *L)

Returns a pointer to the current Lua engine.

luaQ_getfield

void luaQ_getfield(lua_State *L, int index, const char *name)

This function is similar to lua_getfield but never propagates errors causes by executing the metatable __index functions. When such an error occurs, this function simply returns nil.

luaQ_optqobject<TYPE>

TYPE* luaQ_optqobject&lt;TYPE&gt;(lua_State *L, int index, TYPE *d)

Returns the optional Qt object of type TYPE found at position index in the stack. If the position corresponds to an unspecified function argument, this function returns d. If the Lua value at this position is not a Qt object of the requested type, this function causes an error.

See also luaQ_checkqobject

luaQ_optqvariant<TYPE>

TYPE luaQ_optqvariant&lt;TYPE&gt;(lua_State *L, int index, TYPE d = TYPE())

Returns the optional Qt variant of actual type TYPE found at position index in the stack. If the position corresponds to an unspecified function argument, this function returns d. If the Lua value at this position cannot be converted to the requested type, this function causes an error.

See also luaQ_checkqvariant

luaQ_pause

void luaQ_pause(lua_State *L)

Causes the interpreter to enter the mode Paused. When the interpreter pauses with this function, all events are processed and all Lua functions associated with signals are executed whenever the signal occurs.

luaQ_pcall

int luaQ_pcall(lua_State *L, int na, int nr, int eh, QObject *obj = 0)

int luaQ_pcall(lua_State *L, int na, int nr, int eh, int oh)

Performs a Lua function call like lua_pcall but ensures that the function is executed in the thread owning the Qt object obj or the Qt object at position oh on the stack. Argument eh is an event handler that will be executed in the target thread if an error occurs during the execution of the function.

This function is the basis for all thread hopping operations in the QtLua interface.

luaQ_print

int luaQ_print(lua_State *L, int nr)

Prints the nr top elements of the stack without changing the stack in any respect.

luaQ_pushmeta

void luaQ_pushmeta(lua_State *L, int type)

Pushes the metatable associated with Qt variants of type type.

Argument type is an integer representing a QMetaType::Type, a QVariant::Type, or any type declared using the C++ macro Q_DECLARE_METATYPE The following expression can be used to push a metatable for type TYPE:

 luaQ_pushmeta(L, qMetaTypeId&lt;TYPE&gt;());

void luaQ_pushmeta(lua_State *L, const QMetaObject *mo)

void luaQ_pushmeta(lua_State *L, const QObject *o)

Pushes the metatable associated with Qt object o or with Qt objects whose class is represented by the metaobject mo. The following expression can be used to push a metatable for a Qt object class TYPE:

  luaQ_pushmeta(L, &TYPE::staticMetaObject);

luaQ_pushqt

void luaQ_pushqt(lua_State *L)

Pushes the table corresponding to the package qt.

void luaQ_pushqt(lua_State *L, const QVariant &var)

Pushes a representation of the Qt variant var onto the Lua stack. Numeric types are automatically converted to Lua numbers. String types are automatically converted to Lua strings.

void luaQ_pushqt(lua_State *L, QObject *obj, bool owned=false)

Pushes a representation of the Qt object obj onto the Lua stack. By default, objects are not owned by Lua and therefore are not automatically deleted by the Lua garbage collector. To make an object owned by Lua, the optional flag owned should be set to true when calling function luaQ_pushqt immediately after creating the C++ object.

luaQ_register

void luaQ_register(lua_State *L, const luaL_Reg *l, QObject *obj)

Registers C or C++ functins that must run in the thread of Qt object obj. This function is similar to luaL_register. It creates entries in the table located on top of the stack for the C or C++ functions specified by the array pointed by argument l. When a Lua program calls these functions, execution always happens in the thread associated with object obj using thread hopping.

As a special case, when obj is null, the declared functions are always invoked in the thread associated with their first argument which is assumed to be a Qt object.

luaQ_toqobject

QObject* luaQ_toqobject(lua_State *L, int i, const QMetaObject *m = 0)

Returns a pointer to the Qt object located at position i on the stack. It returns a null pointer if the specified position does not represent a Qt object or if its class does not inherit the class represented by the meta object m. When m is null, all Qt objects are accepted.

luaQ_toqvariant

QVariant luaQ_toqvariant(lua_State *L, int i, int type = 0)

Converts the Lua value at position i of the stack into a Qt variant of type type. When type is zero, the most appropriate Qt variant type is returned. When the conversion is not possible, the function returns a Qt variant of type QVariant::Invalid.

luaQ_traceback

int luaQ_traceback(lua_State *L)

int luaQ_tracebackskip(lua_State *L, int skip)

Augments the string located on top of the stack with lines representing the stack trace of the Lua interpreter. This is convenient in error handlers. The skip topmost function calls are skipped.