Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added documentation

  • Loading branch information...
commit ccf4540958dea386089d8ad91e2b06473e7a115d 1 parent e1398c9
@mkottman authored
Showing with 208 additions and 43 deletions.
  1. +1 −0  LICENSE
  2. +0 −43 README
  3. +107 −0 README.md
  4. +100 −0 doc/USAGE.md
View
1  LICENSE
@@ -1,5 +1,6 @@
Copyright (c) 2007-2009 Mauro Iazzi
Copyright (c) 2008-2009 Peter K�mmel
+Copyright (c) 2010-2011 Michal Kottman
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
View
43 README
@@ -1,43 +0,0 @@
-
-lqt is an in-development Qt binding for Lua.
-
-You can find information about Qt at Trolltech
-(http://trolltech.org) and about Lua on its site
-http://lua.org
-
-This software is still in very early development
-and must not be used in production environment.
-In any case you use it at your own risk.
-
-The latest version can be found at the main Git
-repository http://repo.or.cz/w/lqt.git
-
-A Wiki and Bugtracker is here:
-http://code.google.com/p/lqt/
-
-The version on the KDE repository is less likely
-to be up to date with the Git one unless/until
-I find a clean way to push changes directly to
-svn. Pointers to tutorials and manuals are
-welcome.
-
-The BUILD file gives some information on how to
-build the bindings.
-
-lqt builds the bindings using the information
-found in the Qt headers. The generator itself
-does not link ti Qt at all and is under the
-MIT/BSD license included in the file named
-LICENSE. The generated files most likely fall
-under the same license as your Qt copy:
-http://trolltech.com/developer/knowledgebase/236
-http://trolltech.com/developer/task-tracker/index_html?id=213857&method=entry
-I am no lawyer, however, so contact Trolltech
-for more details on their license:
-
-
-You can contact the authors at
- * Mauro Iazzi <mauro.iazzi@gmail.com>
- * Peter K�mmel <syntheticpp@gmx.net>
-
-
View
107 README.md
@@ -0,0 +1,107 @@
+Overview
+========
+
+lqt is a [Lua](http://www.lua.org) binding to the [Qt framework](http://qt.nokia.com).
+It is an automated binding generated from the Qt headers, and covers almost
+all classes and methods from supported Qt modules.
+
+For more info, check the documentation, [mailing list](http://groups.google.com/group/lqt-bindings) or contact the authors:
+
+ * Michal Kottman michal.kottman@gmail.com
+ * Mauro Iazzi mauro.iazzi@gmail.com
+ * Peter Kümmel syntheticpp@gmx.net
+
+Features
+--------
+
+* automatically generated from Qt headers - remains up-to-date even with as Qt progresses
+* supported modules: QtCore, QtGui, QtNetwork, QtXml, QtXmlPatterns, QtWebKit, QtOpenGL, QtSql, QtSvg, QtUiTools
+* high API coverage - only a minimum of methods are not available
+* C++/Qt features available:
+ * method overloads
+ * virtual methods (including abstract methods)
+ * multiple inheritance
+ * you can store additional Lua values in userdata - they act like Lua tables
+ * several overloaded operators are supported
+ * chosen templated classes are available, like `QList<QString>`
+ * signal/slot mechanism - you can define custom slots in Lua
+ * `QObject` derived objects are automatically cast to correct type thanks to Qt metaobject system
+ * implicit conversion - i.e. write Lua strings where QString is expected, or numbers instead of QVariant
+* optional memory management - you can let the Lua GC destroy objects, or let Qt parent/child management do the work
+
+Building lqt
+------------
+
+Pre-compiled Windows binaries of lqt compiled against Qt 4.7 compatible
+with Lua for Windows [are available](https://github.com/downloads/mkottman/lqt/lqt_4.7_lfw_binaries.zip),
+on other systems you need:
+
+* Lua 5.1
+* [CMake](http://www.cmake.org/cmake/resources/software.html)
+* Qt and headers, on Ubuntu you need to install the `libqt4-dev` package
+
+You can get the latest source of lqt from https://github.com/mkottman/lqt .
+When you have the sources, create an out-of-source build directory
+(where the binaries will be built, I often use `build` or `/dev/shm`).
+Then, use CMake to generate the Makefile and run `make` as usual:
+
+ mkdir build; cd build
+ cmake ..
+ make -j4 # use parallel build with your number of cores/processors
+
+The generated Lua binding libraries are created in the `lib` directory,
+you can copy them to your `LUA_CPATH`.
+
+Usage
+-----
+
+A quick example of "Hello World!" button with signal/slot handling:
+
+ require 'qtcore'
+ require 'qtgui'
+
+ app = QApplication.new(select('#',...) + 1, {'lua', ...})
+
+ btn = QPushButton.new("Hello World!")
+ btn:__addmethod('quitApp()', function(self)
+ print("I'm about to close...")
+ self:close()
+ end)
+ btn:connect('2pressed()', btn, '1quitApp()')
+ btn:setWindowTitle("A great example!")
+ btn:resize(300,50)
+ btn:show()
+
+ app.exec()
+
+For more examples, check out the `test` folder and also the `doc`
+folder for documentation on detailed usage - memory management,
+signal/slot handling, virtual method overloading, etc.
+
+License
+-------
+
+Copyright (c) 2007-2009 Mauro Iazzi
+Copyright (c) 2008-2009 Peter Kümmel
+Copyright (c) 2010-2011 Michal Kottman
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
View
100 doc/USAGE.md
@@ -0,0 +1,100 @@
+Overview of lqt
+===============
+
+This document explains how to use lqt in Lua, how to load the libraries, how to use them, create instances and use advanced features.
+
+Loading the library
+-------------------
+
+The libraries are distributed as separate modules, that can be loaded by the `require` function. They are named by lowercasing the module name, i.e. `qtcore`, `qtgui`, `qtxml`, etc.:
+
+ require 'qtcore'
+
+Classes and creating instances
+------------------------------
+
+Classes are named the same as in Qt (i.e. `QPushButton`), and are registered in the global table. To create an instance, you can either "call" the class, or call the `new()` function. You can pass the arguments as parameters. The `new()` function is preferred, because you explicitly state the memory management type (more later), and the Class() type may change later.
+
+ a = QPushButton.new("Button A")
+ b = QPushButton("Button B") -- equivalent to previous
+
+Calling methods
+---------------
+
+Calling methods follows the Lua idioms - you pass the object as the first parameter, so you can use the colon:`btn:setVisible(true)`. For static methods, you can use the dot: `QApplication.exec()`.
+
+Mapping of types
+----------------
+
+Primitive C++ types, like `int`, `bool`, `double`, `const char *` are converted to corresponding Lua types. Every other class and struct is represented by userdata. One exception is QByteArray - it is mapped into Lua string, and you can pass Lua string anywhere QByteArray is accepted. You lose ability to call methods of the QByteArray, but you can do them in Lua anyway.
+
+Why can you pass Lua string where QString is expected? lqt uses the same principle as C++ - implicit constructors. Becase QString can be constructed from a QByteArray (which is Lua string), you can pass a Lua string wherever a QString is expected. This also means that you can pass number/boolean/string as QVariant parameter.
+
+Memory management
+-----------------
+
+Memory management with Lua and C++ is a complicated issue. For every bound class, lqt provides the `new(...)` and `delete(o)` methods. `new(...)` creates a new instance - userdata containing a boxed pointer to the instance, and `delete(o)` frees the memory and sets the boxed pointer to NULL.
+
+Mix in Lua garbage collector (GC). By default, lqt does not let the Lua GC free the created objects. However, you can do this:
+
+ local o = QObject.new()
+ o.__gc = o.delete -- take ownership of object
+
+This way, when Lua collects the userdata, it will also free the allocated object. lqt provides a shortcut for this - the `new_local()` function:
+
+ local o = QObject.new_local()
+
+Now, when `o` goes out of scope (and there is no other reference to it), the object will be freed. You have to be careful however - if Qt keeps a reference to an object, and there is no reference to it in Lua (even a simple `t[obj]=true`, the GC may collect it and free the memory, and then cause a segmentation fault when Qt accesses it.
+
+The Qt framework provides an alternative way - the parent/child mechanism. Every class derived from QObject has a constructor that takes an argument named `parent` (check the Qt documentation). The object then becomes a child of `parent`, and is freed whenever the parent gets freed. When using the parent/child system, you cannot use the Lua GC (because the object will be freed twice).
+
+Essentially you have 3 choices:
+* forget about memory management and use `new(...)` everywhere (not good for long-running apps)
+* use `new_local(...)` and keep references to objects while they are used in Qt
+* create a widget/parent object and make other objects it's children using `new(..., parent)`
+
+Additional Lua fields
+-----------------
+
+The userdata objects can also serve as traditional Lua tables (these are stored in the userdata's environment table):
+
+ local obj = QObject.new()
+ obj.message = "Hello from Lua!"
+
+lqt keeps references to objects keyed by their pointer (in a weak table).When you have a userdata and you keep a reference to it, and a method returns the same pointer as return value, or it is passed to your callback function, you get back the same userdata (along with it's Lua fields).
+
+Virtual methods
+---------------
+
+You can override a virtual method and implement abstract methods in Lua. To do that, you need to save them as an object field. Easier to show on code:
+
+ wnd = QMainWindow.new()
+ function wnd:resizeEvent(e)
+ print("I'm being resized!")
+ end
+ wnd:show()
+
+Signal/slot mechanism
+---------------------
+
+To see the signals and slots an object responds to, you can retrieve a list of them by using the `__methods()` method. It returns a table of strings, representing the signatures and types of Qt "methods" (= signals and slots) it supports.
+
+To connect signals and slots, use the standard `connect()` method, you just have to prepend '2' to the signal signature, and '1' to the slot signature. If you really want, you can use the following functions:
+
+ function SIGNAL(sig) return '2'..sig end
+ function SLOT(sig) return '1'..sig end
+
+To implement custom slots, you need to use the `__addmethod(obj, sig, func)` method to add a custom slot. You can implement it on any object you want, but it usually makes sense to implement it directly on the provider of the signal. It is used as follows:
+
+ local btn = QCheckButton.new("Press me!")
+ btn:__addmethod("mySlot(bool)", function(self, state)
+ print("My state is", state)
+ end)
+ btn:connect('2toggled(bool)', btn, '1mySlot(bool)')
+
+You have to be careful about the signature (Qt is picky, you have to be precise). Always check `__methods()` to see the correct signature: `table.foreachi(obj:__methods(), print)`. Also, lqt can only implement slots of known signature - they are compiled from the list of all signals, therefore you can create a slot for any signal signature present in Qt, but you cannot create new slots/signals (use pure Lua for that).
+
+The Qt API
+------------
+
+For reference on available classes and their methods, please refer to the [Qt documentation](http://doc.qt.nokia.com/). lqt provides essentially the same API, except that you do not need differentiate between pointers, references and values.
Please sign in to comment.
Something went wrong with that request. Please try again.