QtLua project home



The QtLua library aims to make Qt4/Qt5 applications scriptable using the Lua scripting language. It is an alternative to the QtScript module.

QtLua does not generate or use generated binding code for Qt. Instead it provides useful C++ wrapper classes to make C++ and lua objects accessible from both lua and C++. It takes advantages of the Qt meta object system to expose QObject members to lua scripts.

QtLua is not designed to develop an application in pure Lua but rather to extend a Qt C++ application using Lua as scripting language.


  • Basic features:

    • The Lua stack-based C API is not exposed, only C++ objects like QtLua::State and QtLua::Value are manipulated from C++ code.

    • Lua values can be accessed from C++ with almost the same straightforward syntax as in Lua thanks to C++ operators overloading.

    • C++ objects can be exposed to Lua as userdata values by inheriting from the QtLua::UserData class. All Lua meta operations can be redefined by overriding virtual functions, including iteration over userdata objects from Lua.

    • The QtLua::Ref smart pointer class enables reference tracking of QtLua::UserData based objects and can make these C++ objects garbage collectable.

    • The QtLua::Iterator wrapper class enables use of usual C++ iterators to traverse Lua table like values. Lua iterators can also be used to traverse QtLua::UserData based C++ objects from Lua script. Qt template containers can be accessed directly from Lua by using one of the available container proxy classes.

    • The QtLua::Function class can be sub-classed to easily define C++ function objects callable from Lua. The QtLua::Plugin class allows writing of Qt plugins which may contains QtLua::Function objects.

    • Lua coroutines are supported and can be used to control parallel jobs from Lua scripts in a Qt application.

  • QObject related features:

    • Qt QObject wrapping enables creation and manipulation of QObject objects from Lua.

    • QObject properties, enumerations, slots and children objects can be accessed from Lua. Qt Signals can be connected directly to Lua functions.

    • A qt Lua library is available and contains functions to create QObject and manage signal/slot connections from Lua.

    • QObject based user classes can be registered in the QtLua meta objects list. This allows instantiating user classes and accessing enum values from Lua scripts and .ui files directly.

    • User defined Qt types can be registered along with user defined conversion functions. This allows QtLua to perform transparent conversion between Qt user types and Lua values when calling Qt slots or accessing QObject properties.

  • Qt Widgets and user interface features:

    • The qtLua_uic tool can be used compile Qt .ui user interface files to Lua scripts. Some Qt functions are also wrapped to enable loading of .ui files directly from Lua.

    • The Qt QtLua::Console widget is a console widget with history and Lua table completion capabilities. The qtLua tool is based on this widget and provides a Lua based shell for experimentation.

    • The qt Lua library wraps some important user interface functions which are not directly available through the Qt meta object system.

  • Qt Model/view related features:

    • The QtLua::UserItemModel class enables development of hierarchical C++ data structures editable from both Lua script and Qt view widgets.

    • The QtLua::TableTreeModel and QtLua::TableGridModel classes can be used to expose Lua tables to Qt views.

    • The QtLua::LuaModel class enables implementation of a Qt model in pure Lua.

    • The QtLua::ItemViewDialog class provides a generic dialog for model data displaying and editing. It can be used with various views and has customizable edit buttons.

    • The qt Lua library contains some functions to allow instantiating MVC related models and dialogs from Lua.

QtLua 2.0 has been tested with Lua versions 5.0, 5.1 and 5.2 and with Qt versions 4.8 and 5.0.


Releases can be downloaded here.

The project is hosted at https://savannah.nongnu.org/projects/libqtlua.

Source code can be retrieved using subversion: svn co svn://svn.savannah.nongnu.org/libqtlua/trunk/libqtlua


The QtLua library comes with many examples and detailed documentation.

The user manual is available here.

Library internal details documentation is available here.


The libqtlua-list mailing list is available for discussing QtLua.

The QtLua library has been developed by Alexandre Becoulet. You can contact the author at: alexandre.becoulet (at) free.fr. Don't forget to include the "qtlua" string somewhere in your message to avoid being filtered.

Valid XHTML 1.0 StrictGenerated by diaxen on Sat Mar 30 16:25:06 2013 using MkDoc