From c69a5ebf9818195e47f43df7c1294feb28b2ff07 Mon Sep 17 00:00:00 2001 From: nicholas-leonard Date: Fri, 28 Aug 2015 22:26:02 -0400 Subject: readthedocs --- README.md | 16 +- doc/index.md | 13 + doc/qt.md | 1375 +++++++++++++++++++++++ doc/qtcore.md | 436 ++++++++ doc/qtgui.md | 1173 ++++++++++++++++++++ doc/qtide.md | 406 +++++++ doc/qtsvg.md | 166 +++ doc/qtuiloader.md | 100 ++ doc/qtwidget.md | 2177 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 15 + packages/qt/doc/README.md | 1381 ----------------------- packages/qtcore/doc/README.md | 436 -------- packages/qtgui/doc/README.md | 1192 -------------------- packages/qtide/doc/README.md | 411 ------- packages/qtsvg/doc/README.md | 169 --- packages/qtuiloader/doc/README.md | 103 -- packages/qtwidget/doc/README.md | 2177 ------------------------------------- 17 files changed, 5869 insertions(+), 5877 deletions(-) create mode 100644 doc/index.md create mode 100644 doc/qt.md create mode 100644 doc/qtcore.md create mode 100644 doc/qtgui.md create mode 100644 doc/qtide.md create mode 100644 doc/qtsvg.md create mode 100644 doc/qtuiloader.md create mode 100644 doc/qtwidget.md create mode 100644 mkdocs.yml delete mode 100644 packages/qt/doc/README.md delete mode 100644 packages/qtcore/doc/README.md delete mode 100644 packages/qtgui/doc/README.md delete mode 100644 packages/qtide/doc/README.md delete mode 100644 packages/qtsvg/doc/README.md delete mode 100644 packages/qtuiloader/doc/README.md delete mode 100644 packages/qtwidget/doc/README.md diff --git a/README.md b/README.md index c54f294..6a69445 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -QtLua -- a Lua interface to QT +QtLua: a Lua interface to QT ============================== This package includes several useful sub-packages: - - [qt](packages/qt/doc/README.md): the global Qt system - - [qtcore](packages/qtcore/doc/README.md): Core interface - - [qtgui](packages/qtgui/doc/README.md): GUI - - [qtuiloader](packages/qtuiloader/doc/README.md): QT Designer UI files loader - - [qtide](packages/qtide/doc/README.md): QLua Integrated Development Environment (IDE) - - [qtsvg](packages/qtsvg/doc/README.md): Qt SVG support - - [qtwidget](packages/qtwidget/doc/README.md): widgets and events + - [qt](doc/qt.md): the global Qt system + - [qtcore](doc/qtcore.md): Core interface + - [qtgui](doc/qtgui.md): GUI + - [qtuiloader](doc/qtuiloader.md): QT Designer UI files loader + - [qtide](doc/qtide.md): QLua Integrated Development Environment (IDE) + - [qtsvg](doc/qtsvg.md): Qt SVG support + - [qtwidget](doc/qtwidget.md): widgets and events diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..981d706 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,13 @@ +# QtLua: a Lua interface to QT + +This package includes several useful sub-packages: + + - [qt](qt.md): the global Qt system + - [qtcore](qtcore.md): Core interface + - [qtgui](qtgui.md): GUI + - [qtuiloader](qtuiloader.md): QT Designer UI files loader + - [qtide](qtide.md): QLua Integrated Development Environment (IDE) + - [qtsvg](qtsvg.md): Qt SVG support + - [qtwidget](qtwidget.md): widgets and events + + diff --git a/doc/qt.md b/doc/qt.md new file mode 100644 index 0000000..8b14e9f --- /dev/null +++ b/doc/qt.md @@ -0,0 +1,1375 @@ + +# QtLua and Qt Package Reference Manual + +The package `qt` is available when you run the Lua +interpreter using the [qlua](#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](#qlua) relies in fact on +the [QtLua](#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](qtcore.md), [qtgui](qtgui.md), and [qtuiloader](qtuiloader.md) +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](#qt), [qtwidget](qtwidget.md), [qtuiloader](qtuiloader.md). + * 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](..:LuaManual#LuaStandalone). It also +accepts all the +[Qt command line options](http://doc.trolltech.com/4.4/qapplication.html#QApplication) +as well as a few specific options. + +At any time, one can exit the interpreter using `[CTRL-D]`. + +``` +Usage: qlua [options] [script ] +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()](#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](#qt.qconsole) 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](#qt.qengine) runs the Lua code and provides the integration with the Qt environment. + * The [application manager](#qt.qapp) 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"](#qt.qcall) 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](#qt.qcall) or [qt.xqcall](#qtxqcall). + + + +# 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](#QtLua) +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](http://doc.trolltech.com/4.4/qvariant.html) 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](http://doc.trolltech.com/4.4/qmetatype.html) can +be represented by a Qt variant value. + +Whenever a `QVariant` value is made accessible to the Lua +interpreter (see [luaQ_pushqt](#luaqpushqt)), 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 `QByteArray`are 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) ### +![](anchor:qt.isa) + +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](http://doc.trolltech.com/4.4/qobject.html). 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](http://doc.trolltech.com/4.4/object.html) 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](qtcore.md#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()](#qt.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: +```lua +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](#qt.qcall) 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](http://doc.trolltech.com/4.4/qobject.html) are +automatically converted into strings representing the enumerated names +and conversely. Property values with flag types declared using the Qt +macro [Q_DECLARE_FLAGS](http://doc.trolltech.com/4.4/qflags.htm) 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: +```lua +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. + +```lua +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](#qt.qcall) 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()](qtcore.md#qobjectdeletelater), are +inherited by all Qt object classes. + + +### Named Children ### + +All Qt objects can be given a name represented by property +[objectName](qtcore.md#qobjectobjectname). 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: +```c++ +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 + +```lua +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. + +```lua +myqobject['mysignal(QByteArray,int)'](self,"message",3) +``` + + +#### Receiving Signals #### + +Qt signals can be connected to Lua functions +using [qt.connect(...)](#qt.connect). + +For instance, the clause + +```lua +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: + +```lua +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()](#qt.doevents) is called. + + + +## Objects ## + + +### qt.qApp ### + +Expression `qt.qApp` refers to the application object +which orchestrates the operation of the [qlua](#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](#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](#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](#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](#qt.QtLuaEngine). +A few exposed slots, signals and properties are relevant for Lua programs. +See the documentation of class [QtLuaEngine](#qt.QtLuaEngine) +in the [QtLua](#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: +```lua +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](#qt.recevingsignals.dok) 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()](#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](qtcore.md#qobjectdeletelater) or +[disconnect](#qt.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(...)](http://doc.trolltech.com/4.4/qobject.html#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(...)](http://doc.trolltech.com/4.4/qobject.html#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)](#qt.isa) 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](..:LuaManual#pcallfarg), 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](#qlua), object [qt.qApp](#qt.qapp) is always +owned by the main thread in charge of the user interaction, and object +[qt.qEngine](#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()](#qt.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](..:LuaManual#xpcallferr). + +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](#qt.QtLuaEngine) and [QtLuaLocker](#qt.QtLuaLocker) provides +a Lua interpreter for use in any Qt application with capabilities +comparable to those of the +[QtScript](http://doc.trolltech.com/4.4/qtscript.html) and additional +support for multi-threaded execution. Additional functions with +prefix [luaQ](#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](http://doc.trolltech.com/4.4/qtscript.html) 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](#qt.qcall) operation +ensures that the execution of a Lua program happens +in the thread owning the Lua engine object. + +Class [QtLuaLocker](#qt.QtLuaLocker) provides means +to directly access the Lua state +[`lua_State*`](..:LuaManual#luaState) 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](#qt.qcall). 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 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](#qt.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*`](..:LuaManual#luaState) +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](..:LuaManual#luacall) +or [lua_pcall](..:LuaManual#luapcall) 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++. + +```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](..:LuaManual#luacall) +but ensure that the function is executed in the thread owning object `obj` +using [thread hopping](#qt.qcall). +Unlike function [luaQ_pcall](#luaqpcall), +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<TYPE>(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](#QObjects) of class `TYPE`. +Otherwise it returns a pointer to the object. + + +### luaQ_checkqvariant<TYPE> ### + +`TYPE luaQ_checkqvariant<TYPE>(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](#Qt.Qvariants) 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](http://doc.trolltech.com/4.4/qmetatype.html). + + +### 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(...)](#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(...)](#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()](#qt.doevents). + + +### luaQ_engine ### + +`QtLuaEngine *luaQ_engine(lua_State *L)` + +Returns a pointer to the current [Lua engine](#qt.QtLuaEngine). + + +### luaQ_getfield ### + +`void luaQ_getfield(lua_State *L, int index, const char *name)` + +This function is similar to [lua_getfield](..:LuaManual#luagetfield) +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<TYPE>(lua_State *L, int index, TYPE *d)` + +Returns the optional [Qt object](#QObjects) 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](#luaqcheckqobject) + + +### luaQ_optqvariant<TYPE> ### + +`TYPE luaQ_optqvariant<TYPE>(lua_State *L, int index, TYPE d = TYPE())` + +Returns the optional [Qt variant](#Qt.Qvariants) 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](#luaqcheckqvariant) + + +### 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](..:LuaManual#luapcall) 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](#qt.qcall) +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](http://doc.trolltech.com/4.4/qmetatype.html) +The following expression can be used to push +a metatable for type `TYPE`: +```c++ + luaQ_pushmeta(L, qMetaTypeId<TYPE>()); +``` + +`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](http://doc.trolltech.com/4.4/qmetaobject.html) +`mo`. The following expression can be used to push +a metatable for a Qt object class `TYPE`: + +```c++ + 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](#qt.QVariants) `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](#qt.QObjects) `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](..:LuaManual#luaLregister). +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](#qt.qcall). + +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](#QObjects) +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](#Qt.Qvariants) 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. + diff --git a/doc/qtcore.md b/doc/qtcore.md new file mode 100644 index 0000000..017b6f2 --- /dev/null +++ b/doc/qtcore.md @@ -0,0 +1,436 @@ + +# QtCore Bindings # + +The package `qtcore` +contains bindings for classes defined by the Qt module +[QtCore](http://doc.trolltech.com/4.4/qtcore.html). + +Besides the capabilites reported below, +all qt variants inherit a set +of [default methods](qt.md#qt.QVariants), +and all qt object classes inherit the capabilities from their +superclasses and automatically expose +[properties, slots and signals](qt.md#qt.QObjects). + + + +## qt.QByteArray ## + +Class `qt.QByteArray` represents Qt values of type +[QByteArray](http://doc.trolltech.com/4.4/qbytearray.html). +These values are special because lua strings +are automatically converted to QByteArray objects +when such objects are needed. + + +### qt.QByteArray(arg) ### + +Expression `qt.QByteArray(arg)` returns a new byte array object. +Argument `arg` may be a lua string or a table containing +the integer values of the successive bytes. + + +### qbytearray:totable() ### + +Expression `qbytearray:totable()` returns a table +containing the integer values of the bytes represented +by the bytearray. + + +## qt.QCoreApplication ## + +The Qt class +[QCoreApplication](http://doc.trolltech.com/4.4/qcoreapplication.html) +provides an event loop for console Qt applications and serves +as a base class for class [QApplication](qtgui.md#qapplication). + + +### qt.QCoreApplication() ### + +Returns the unique instance of class `QCoreApplication`.make i + + + +## qt.QLine, qt.QLineF ## + +Classes `qt.QLine` and `qt.QLineF` represent common Qt classes. +Please refer to the Qt documentation for classes +[QLine](http://doc.trolltech.com/4.4/qline.html) +and [QLineF](http://doc.trolltech.com/4.4/qlinef.html) +for details. + + +### qt.QLine(table), qt.QLineF(table) ### + + +Expression `qt.QLine(table)` or `qt.QLineF(table)` +constructs a new `qt.QLine` or `qt.QLineF` object +representing a segment whose endpoints coordinates +are given by fields `x1`, `y1`, `x2`, and `y2` +of table `table`. + + +### qline:totable() ### + +Expression `qline:totable()` returns a table whose fields +`x1`, `y1`, `x2`, and `y2` contain the coordinates of the +endpoints of the `qt.QLine` or `qt.QLineF` object `qline`. + + + +## qt.QObject ## + +Qt class +[QObject](http://doc.trolltech.com/4.4/qobject.html). +is the base class of all [Qt objects](qt.md#qt.QObjects). +All Qt object classes have separate metatables following the +same inheritance pattern as the corresponding Qt classes. +The metatable [qt.QObject](#qobject) sits at the top +of this hierarchy. + + +### qobject:children() ### + +Expression `qobject:children()` +returns a Qt value of class [qt.QVariantList](#qvariantlist) +containing all the children of object `qobject`. + + + +### qobject:deleteLater() ### + +Calling `qobject:deleteLater()` is the recommended way to delete +the Qt object `qobject`. The object is not deleted immediately. +The deletion occurs when the object thread is processing +interactive events. + + + +### qobject:dumpObjectInfo() ### + +Function `qobject:dumpObjectInfo` prints a human readable +description of the object `qobject`. +This function only works when Qt and QtLua are +compiled in debug mode. + + + +### qobject:dumpObjectTree() ### + +Function `qobject:dumpObjectTree` prints a human readable +description of the object hierarchy containing `qobject`. +This function only works when Qt and QtLua are +compiled in debug mode. + + + +### qobject.objectName ### + +Property `qobject.objectName` contains a string +representing the name of a Qt object `qobject`. +Named children of a Qt object can be accessed +by indexing the parent object. + +Consider for instance a variable `a` referring +to a Qt object that contains a child object named `"b"`. +The child object can be accessed using the Lua syntax `a.b`. +In case of name conflicts, property and methods have precedence +over named children. + + +### qobject:parent() ### + +Expression `qobject:parent()` returns the parent of object `qobject` +if such a parent exists. Otherwise it returns `nil`. + + +## qt.QPoint, qt.QPointF ## + + +Classes `qt.QPoint` and `qt.QPointF` represent common Qt classes. +Please refer to the Qt documentation for classes +[QPoint](http://doc.trolltech.com/4.4/qpoint.html) +and [QPointF](http://doc.trolltech.com/4.4/qpointf.html) +for details. + + +### qt.QPoint(table), qt.QPointF(table) ### + + +Expression `qt.QPoint(table)` or `qt.QPointF(table)` +returns a new `qt.QPoint` or `qt.QPointF` object +initialized with the contents of fields `x` and `y` +from table `table`. + + +### qpoint:totable() ### + +Expression `qpoint:totable()` returns a table whose fields `x` and `y` +contain the coordinates of the `qt.QPoint` or `qt.QPointF` object `qpoint`. + + + +## qt.QRect, qt.QRectF ## + + +Classes `qt.QRect` and `qt.QRectF` represent common Qt classes. +Please refer to the Qt documentation for classes +[QRect](http://doc.trolltech.com/4.4/qrect.html) +and [QRectF](http://doc.trolltech.com/4.4/qrectf.html) +for details. + + +### qt.QRect(table), qt.QRectF(table) ### + + +Expression `qt.QRect(table)` or `qt.QRectF(table)` +returns a new `qt.QRect` or `qt.QRectF` object +representing a rectangle whose origin is +specified by table fields `x` and `y` +and whose width and height are specified +by the table fields `width` and `height`. + + +### qrect:totable() ### + +Expression `qrect:totable()` returns a table +whose fields `x` and `y` contain the origin of the rectangle `qrect` +and whose fields `width` and `height` contain the width and +height of the rectangle. + + + +## qt.QSize, qt.QSizeF ## + + +Classes `qt.QSize` and `qt.QSizeF` represent common Qt classes. +Please refer to the Qt documentation for classes +[QSize](http://doc.trolltech.com/4.4/qsize.html) +and [QSizeF](http://doc.trolltech.com/4.4/qsizef.html) +for details. + +Example: +```lua +require 'qtwidget' +widget = qt.QWidget() +widget.size = qt.QSize{width=320,height=200} +widget:show() +``` + + +### qt.QSize(table), qt.QSizeF(table) ### + + +Expression `qt.QSize(table)` or `qt.QSizeF(table)` +returns a new `qt.QSize` or `qt.QSizeF` object +initialized with the contents of fields `width` and `height` +from table `table`. + + +### qsize:totable() ### + +Expression `qsize:totable()` returns a table whose +fields `width` and `height` are initialized with +the width and height of the size `qsize`. + + + +## qt.QString ## + +Class `qt.QString` represents Qt values of type +[QString](http://doc.trolltech.com/4.4/qstring.html). +These values are special because lua strings +are automatically converted to string objects +when such objects are needed. + + +### qt.QString(arg) ### + +Expression `qt.QString(arg)` returns a new string object. +Argument `arg` may be a lua string representing the string +in locale encoding or a table containing the unicode values +for the string characters. + + +### qstring:totable() ### + +Expression `qurl:totable()` returns a table +containing the integer values of the successive +unicode characters represented by the string. + + +## qt.QStringList ## + +Class `qt.QStringList` represents Qt values of type +[QStringList](http://doc.trolltech.com/4.4/qstringlist.html) +containing a list of Qt strings. + + +### qt.QStringList(table) ### + +Expression `qt.QStringList(table)` creates a new `QStringList` +initialized with the strings contained in +table `table` at positions `1` to `#table`. +When the argument `table` is omitted, +an empty string list is returned. + +Example +```lua +require 'qt' +a = qt.QStringList{"a","b","c"} +``` + + +### qstringlist:totable() ### + +Expression `qstringlist:totable()` returns a Lua table +containing the elements of `qstringlist` starting at position `1`. + +Example +```lua +require 'qt' +a = qt.QStringList{"a","b","c"} +return a:totable()[2] +``` + + + +## qt.QTimer ## + +Class `qt.QTimer` is a subclass of [qt.QObject](#qobject) +associated with Qt objects of class `QTimer`. +Please see the Qt documentation for class +[QTimer](http://doc.trolltech.com/4.4/qtimer.html) +for an explanation of the available +slots, signals and properties. + +Example: +```lua +require 'qt' +timer = qt.QTimer() +timer.singleShot = true +qt.connect(timer,'timeout()', function() print("timeout") end) +timer:start(2000) -- wait for 2 seconds... +``` + + + +### qt.QTimer(parent) ### + +Expression `qt.QTimer(parent)` returns a +new `QTimer` object created from the current thread. +Argument `parent` optionally specifies its parent. +Note that the parent object must belong to the current thread as well. +When argument `parent` is not specified, +the new timer is owned by the Lua interpreter +and will be deleted by the Lua garbage collector +when it is no longer referenced. + + + +## qt.QUrl ## + +Class `qt.QStringList` represents Qt values of type +[QUrl](http://doc.trolltech.com/4.4/qurl.html) +containing an URL. + + +### qt.QUrl(string) ### + +Expression `qt.QUrl(string)` returns a +QUrl object from string `string`. + + +### qurl:tostring() ### + +Expression `qurl:tostring()` returns a string +describing the QUrl object `qurl`. + +### qurl.fromlocalfile(s) ### + +Returns a file url associated with the file named s. + + +### qurl:tolocalfile() ### + +If the url describes a local file, +expression `qurl:tolocalfile()` returns a string +describing the local filename associated with the url. +Otherwise it returns nil. + + + +## qt.QVariantList ## + +Class `qt.QVariantList` represents Qt values of type +[QVariantList](http://doc.trolltech.com/4.4/qvariant.html#QVariantList-typedef) +containing a list of values represented by class +[QVariant](http://doc.trolltech.com/4.4/qvariant.html). + + +### qt.QVariantList(table) ### + +Expression `qt.QVariantList(table)` creates a new `QVariantList` +initialized with the strings contained in +table `table` at positions `1` to `#table`. +When the argument `table` is omitted, +an empty string list is returned. + +Example +```lua +require 'qt' +a = qt.QVariantList{"a",32} +``` + + +### qvariantlist:totable() ### + +Expression `qvariantlist:totable()` returns a Lua table +containing the elements of `qstringlist` starting at position `1`. + +Example +```lua +require 'qt' +a = qt.QVariantList{"a",2,3,4} +return a:totable()[2] +``` + + + +## qt.QVariantMap ## + +Class `qt.QVariantList` represents Qt values of type +[QVariantMap](http://doc.trolltech.com/4.4/qvariant.html#QVariantMap-typedef) +containing a dictionary of named values represented by class +[QVariant](http://doc.trolltech.com/4.4/qvariant.html). + + + +### qt.QVariantMap(table) ### + +Expression `qt.QVariantMap(table)` creates a new `QVariantMap` +initialized with the contents of the table `table`. +When the argument `table` is omitted, +an empty map is returned. + +Example +```lua +require 'qt' +a = qt.QVariantMap{a=23,b=45,c="foo"} +``` + + +### qvariantmap:totable() ### + +Expression `qvariantmap:totable()` returns a Lua table +containing the contents of the dictonary `qvariantmap`. + +Example +```lua +require 'qt' +a = qt.QVariantMap{a=23,b=45,c="foo"} +t = a:totable() +return t.c +``` + + diff --git a/doc/qtgui.md b/doc/qtgui.md new file mode 100644 index 0000000..9985c94 --- /dev/null +++ b/doc/qtgui.md @@ -0,0 +1,1173 @@ + +# QtGui Bindings # + +The package `qtgui` +contains bindings for classes defined by the Qt module +[QtGui](http://doc.trolltech.com/4.4/qtcore.html). + +Besides the capabilites reported below, all qt variants inherit a set +of [default methods](qt.md#qt.QVariants), and all qt object +classes inherit the capabilities from their superclasses and +automatically expose [[qt.md#qt.QObjects|properties, slots and +signals]]. + + + +## qt.QAction, qt.QtLuaAction ## + + +Qt class +[QAction](http://doc.trolltech.com/4.4/qaction.html) +is a sublass of [qt.QObject](qtcore.md#qt.qobject) +that represents actions associated with menu items +and toolbar icons. + + + +### qt.QAction([arg]) ### + +Expression `qt.QAction([arg])` returns a new `QAction` object. +The optional argument `arg` can be a qt object that +becomes the action parent or a table whose +members contain initial values for the action properties. +This table can also contain a function value +which is then connected to the signal `triggered(bool)` +of the qt action object. + +Example: +```lua +a === qt.QAction { text="Automatic Mode", + checkable === true, checked === false, + function(b) setAutoMode(b) end } +``` + +Unless a parent is specified, the action is owned +by the Lua interpreter and therefore is automatically +destroyed when the garbage collector determines that +it is no longer referenced. + +Actions are always created from the main thread using +the [thread hopping](qt.md#qt.qcall) mechanism. + + +### qaction:menu() ### + +Same as the C++ function `QAction::menu()`. + + +### qaction:setMenu() ### + + +Same as the C++ function `QAction::setMenu()`. + + +### qt.QtLuaAction([arg]) ### + +This constructor takes the same arguments as `qt.QAction` +but returns an instance of a convenient subclass +that enables or disables the action according +to the availability of the Lua engine. + +The action follows its property `enabled` +when the Lua engine is ready to invoke Lua +functions connected to Qt signals. +Otherwise the action is disabled regardless +of the value of property `enabled`. + + +### qtluaaction.autoDisable ### + +This property applies only to action objects of class `qt.QtLuaAction`. +It controls whether the action is automatically disabled +when the Lua engine is not available. +The default is `true`. + + + +## qt.QApplication ## + +Qt class [QApplication](http://doc.trolltech.com/4.4/qapplication.html) +manages the GUI application's control flow and main settings. This is a +subclass of [QCoreApplication](qtcore.md#qcoreapplication). + + +### qt.QApplication.changeOverrideCursor(qcursor) ### + +Changes the currently active application override cursor to cursor +without disturbing the cursor stack. This function has no +effect if `setOverrideCursor()` was not called. + + +### qt.QApplication.keyboardModifiers() ### + +Returns a string describing the currently depressed keyboard modifiers. + + +### qt.QApplication.mouseButtons() ### + +Returns a string describing the currently depressed mouse buttons. + + +### qt.QApplication.overrideCursor() ### + +Returns the active application override cursor. +This function returns `nil` if no application cursor +has been defined (i.e. the internal cursor stack is empty). + + +### qt.QApplication.restoreOverrideCursor() ### + +Undoes the last `setOverrideCursor()`. + + +### qt.QApplication.setOverrideCursor(qcursor) ### + +Sets the application override cursor to `qcursor`. +Application override cursors are intended for showing the user that +the application is in a special state, for example during an operation that might take some time. +Override cursors are stored on a stack. Function `setOverrideCursor()` pushes a cursor on the stack. +Function `restoreOverrideCursor()` pops the stack. + + + +## qt.QBrush ## + +Qt class +[QBrush](http://doc.trolltech.com/4.4/qbrush.html) +represents the painter settings that determine how shape +are filled and how text is rendered. Brushes are represented +by Qt variants of class `qt.QBrush`. + + + +### qt.QBrush(table) ### + + +Expression `qt.QBrush(table)` returns a brush whose settings +are determined by the fields of table `table`. +The following fields are recognized: + + * Field `color` contains a [qt.QColor](#qcolor) value representing the brush color. + * Field `texture` contains a [qt.QImage](#qimage) value representing the brush texture. + * Field `gradient` contains a [qt.QGradient](#qgradient) value representing a color gradient. + * Field `transform` contains a `qt.QTransform` value that defines a additional transformation applied to the brush before painting it into the current coordinate system. + * Field `style` contains the name of the [brush style](http://doc.trolltech.com/4.4/qt.html#BrushStyle-enum). The default brush style is `SolidPatter` when field `color` is defined, `TexturePattern` when field `texture` is defined, or one of the gradient styles when field `gradient` is defined. Otherwise the default style is `NoBrush` meaning that nothing is painted. + + + +### qbrush:totable() ### + +Expression `qbrush:totable()` returns a table describing the brush. +See the documentation of [qt.QBrush(table)](#qbrushfromtable) +for a description of the table fields. + + + +## qt.QColor ## + +Qt class +[QColor](http://doc.trolltech.com/4.4/qcolor.html) +represents colors for painting purposes. +Qt variant of class `qt.QColor` have a textual representation +of the form =="#RRGGBB" where letters `R`, `G`, or `B` are +hexadecimal digits representing the intensities of the +color components. + + + +### qt.QColor(...) ### + +There are several ways to construct a Qt variant of class `qt.QColor`. + +__`qt.QColor(r,g,b,[a])`__ + +Arguments `r`, `g`, `b`, and `a` are numbers in range `[0,1]` +representing the intensities of the red, green, blue, and alpha channels. +The default value for argument `a` is `1` for a fully opaque color. + +__ `qt.QColor(string)` __ + +Argument `string` is a string representing a color name. +All [SVG color names](http://www.w3.org/TR/SVG/types.html#ColorKeywords) +are recognized.Color names can have also the format `"#RGB"`, +`"#RRGGBB"`, `"#RRRGGGBBB"`, or =="#RRRRGGGGBBBB" +where letters `R`, `G`, or `B` represent hexadecimal +digits for each of the color component. + +__ `qt.QColor(table)` __ + +Argument `table` is a table whose fields `r`, `g`, `b` and `a` +contain numbers in range `[0,1]` representing the intensities +of the red, green, blue, and alpha channels. Such a table +is returned by function [qcolor:totable()](#qcolortotable). + + +### qcolor:totable() ### + + +Expression `qcolor:totable()` returns a table whose fields +`r`, `g`, `b` and `a` contain numbers in range `[0,1]` +representing the intensities of the red, green, blue, +and alpha channels. + + + +## qt.QColorDialog ## + +Qt class +[QColorDialog](http://doc.trolltech.com/4.4/qcolordialog.html) +implements a dialog for selecting colors. +The recommended way to use this class is the static function `getColor`. + + +### qt.QColorDialog.getColor([font],[parent]) ### + +Pops up a dialog for selecting a color. +Optional argument `color` is the initial color selection. +Argument `parent` is the parent widget. +This function returns `nil` if the no color was selected. +Otherwise it returns a qvariant of type [qt.QColor](#qcolor). + + +## qt.QCursor ## + +Qt class +[QCursor](http://doc.trolltech.com/4.4/qcursor.html) +provides a mouse cursor with an arbitrary shape. + + +### qt.QCursor(cursorshape) ### + +Returns a standard cursor. +Argument `cursorshape` is the name of a +[standard shape](http://doc.trolltech.com/4.4/qt.html#CursorShape-enum). + + +### qt.QCursor(image,[mask],[posx,[posy]) ### + +Constructs a cursor with the specified image, mask and hot spot. + + +### qcursor:hotSpot() ### + +Return a `qt.QPoint` with the cursor's hot spot coordinates. + + +### qcursor:mask() ### + +Return the cursor's mask. + + +### qcursor:pixmap() ### + +Return the cursor's pixmap. + + +### qcursor:shape() ### + +Return the name of the cursor's +[standard shape](http://doc.trolltech.com/4.4/qt.html#CursorShape-enum). + + +### qt.QCursor.pos() ### + +Returns a `QPoint` with the global coordinates of the mouse cursor. + + +### qt.QCursor.setPos(qpoint) ### + +Sets the global coordinates of the mouse cursor. + + +## qt.QDialog ## + +Qt class +[QDialog](http://doc.trolltech.com/4.4/qdialog.html) +is the base class of dialog windows. + + +### qt.QDialog([parent]) ### + +Expression `qt.QDialog(parent)` returns a new `QDialog` instance. +The optional argument `parent` specifies the widget parent. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + +### qdialog:result() ### + +Gets the dialog's result code as an integer. +This is usually `1` when the dialog has been accepted +and `0` when the dialog has been rejected. + + +### qdialog:setResult(integer) ### + +Sets the dialog's result code. +This is usually `1` when the dialog has been accepted +and `0` when the dialog has been rejected. + + + +## qt.QFileDialog ## + +Qt class +[QFileDialog](http://doc.trolltech.com/4.4/qfiledialog.html) +provides a dialog that allow users to select files or directories. +This is a subclass of [qt.QDialog](#qdialog). + + +### qt.QFileDialog.getExistingDirectory([p.[c,[d,[opt]]]]) ### + +This convenience function shows a file dialog +for selecting an existing directory. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QString` containing the selected directory name. + + +### qt.QFileDialog.getOpenFileName([p,[c,[d,[f,[s,[opt]]]]]]) ### + +This convenience function shows a file dialog +for selecting an existing file. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `f` contains the filters separated by double semicolons. + * Argument `s` contains the selected filter + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QString` containing the selected file name +and a `qt.QString` contaning the selected filter. + + +### qt.QFileDialog.getOpenFileNames([p,[c,[d,[f,[s,[opt]]]]]]) ### + +This convenience function shows a file dialog +for selecting multiple existing files. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `f` contains the filters separated by double semicolons. + * Argument `s` contains the selected filter + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QStringList` containing the file names +and a `qt.QString` contaning the selected filter. + + +### qt.QFileDialog.getSaveFileName([p,[c,[d,[f,[s,[opt]]]]]]) ### + +This convenience function shows a file dialog +for selecting a file name for saving data. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `f` contains the filters separated by double semicolons. + * Argument `s` contains the selected filter + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QString` containing the selected file name +and a `qt.QString` contaning the selected filter. + + +### qt.QFileDialog.new([parent.[caption,[dir,[filters]]]]) ### + +Function `qt.QFileDialog.new` returns a new file dialog object. + + * Argument `parent` is the parent widget + * Argument `caption` is the dialog caption. + * Argument `dir` is the initial directory shown in the dialog. + * Argument `filters` contains the filters separated by double semicolons. + +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + +### qfiledialog:directory() ### + +Returns a `qt.QString` containing the path of the selected directory. + + +### qfiledialog:nameFilters() ### + +Returns a `qt.QStringList` containing the name filters. + + +### qfiledialog:selectedFiles() ### + +Returns a `qt.QStringList` containing the selected files. + + +### qfiledialog:selectFile(fname) ### + +Select file `fname` in the file dialog. + + +### qfiledialog:selectNameFilter(filter) ### + +Select name filter `filter` in the file dialog. + + +### qfiledialog:setDirectory(dirname) ### + +Set the file dialog directory to `dirname`. + + +### qfiledialog:setNameFilters(filters) ### + +Set the file dialog name filters to `filters`. +Argument `filters` may be a `qt.QStringList` +or a string containing the filters separated by +two semicolons `";;"`. + + +### qfiledialog:setOption(option, bool) ### + +Sets the specified +[file dialog option](http://doc.trolltech.com/4.5/qfiledialog.html#Option-enum) +to the boolean value `bool`. Not available before Qt-4.5. + +### qfiledialog:testOption(option) ### + +Returns the value of the specified +[file dialog option](http://doc.trolltech.com/4.5/qfiledialog.html#Option-enum). +Not available before Qt-4.5. + + +## qt.QFont ## + +Qt class +[QFont](http://doc.trolltech.com/4.4/qfont.html) +represents the painter settings that determine the font(s) +used to display text. + + + +### qt.QFont(arg) ### + + +Expression `qt.QFont(arg)` returns a new font object. +Argument `arg` may be a string previously returned +by [qfont:tostring()](#qfonttostring) or +a table whose fields specify the desired font characteristics. +The following fields are recognized, listed in order of priority: + + * String field `family` may contain a comma separated list of the desired font families. + * Setting boolean field `sans` to `true` indicates a preference for sans serif font families such as "Helvetica". This is more portable than specifying a family. + * Setting boolean field `serif` to `true` indicates a preference for serif font families such as "Times". This is more portable than specifying a family. + * Setting boolean field `typewriter` to `true` indicates a preference for a fixed width font families such as "Courier". This is more portable than specifying a family. + * Numerical field `size` specify the desired size of the font. The default size is 10 points. + * Numerical fields `pixelSize` and `pointSize` also indicates the desired size of the font. Field `pixelSize` is an alias for `size`. Field `pointSize` includes a correction factor corresponding to the actual resolution of the target device. When both are precised, `pointSize` takes precedence. + * Numerical field `weight` defines the weight of the font. Weight 50 corresponds to a normal font and weight 75 corresponds to a bold font. + * Numerical field `stretch` is a percentage applied to the width of all characters. Value 100 corresponds to a normal width. Value 150 increases all width by 50 percent. + * Setting boolean field `bold` to `true` requests a bold font if the selected font family defines a bold variant. + * Setting boolean field `italic` to `true` requests and italic font if the selected font family defines an italic or oblique variant. + * Setting boolean field `fixedPitch` to `true` requests a fixed pitch font if the selected font family defines such a variant (rare). + * Setting boolean field `underline` to `true` draws a line below all the character at a font-specified position. + * Setting boolean field `overline` to `true` draws a line above all the character at a font-specified position. + * Setting boolean field `strikeOut` to `true` draws a line that crosses the character at a font-specified position. + +Example: +```lua +require 'qtwidget' +w=qtwidget.newwindow(300,300) +w:moveto(20,20) +w:setfont(qt.QFont{serif=true,size=12,italic=true}) +w:show("foo") +w:setfont(qt.QFont{serif=true,size=12,italic=true,underline=true}) +w:setcolor("blue") +w:show("bar") +``` + + + +### qfont:totable() ### + +Expression `qfont:totable()` returns a table +suitable for use with [qt.QFont(table)](#qfontfromtable). +All the supported fields are populated. + +Example: +```lua +require 'qtwidget' +f=qt.QFont{serif=true,size=12,bold=true} +for k,v in pairs(f:totable()) do print(k,v) end +``` + + +### qfont:tostring() ### + + +Expression `qfont:tostring()` returns a string +representation of the font settings that is +suitable for storing in configuration files for instance. +Use [qt.QFont(string)](#qfontfromtable) to +reconstruct the corresponding font object. + + +### qfont:info() ### + + +Expression `qfont:info()` returns a table describing +the actual font selected by the font matching algorithm +when one uses `qfont` to display text on the screen. +This table can be used as argument to +function [qt.QFont()](#qfontfromtable) +as it uses the same keys. +This is achieved using the Qt class +[QFontInfo](http://doc.trolltech.com/4.4/qfontinfo.html). +Fields `"underline"`, `"overline"`, `"strikeOut"`, and `"stretch"` +are copied verbatim from the `qfont` object. + + +## qt.QFontDialog ## + +Qt class +[QFontDialog](http://doc.trolltech.com/4.4/qfontdialog.html) +implements a dialog for selecting fonts. +The recommended way to use this class is the static function `getFont`. + + +### qt.QFontDialog.getFont([font],[parent, [caption]]) ### + +Pops up a dialog for selecting a font. +All arguments are optional. +Argument `font` is the initial font selection. +Argument `parent` is the parent widget. +Argument `caption` is the dialog window title. +This function returns `nil` if the no font was selected. +Otherwise it returns a qvariant of type [qt.QFont](#qfont). + + + +## qt.QGradient ## + +Qt class +[QGradient](http://doc.trolltech.com/4.4/qgradient.html) +represents a color gradient for use in [gradient brushes](#qbrush). +No specific Lua methods have been defined for this Qt variant class. + + + +## qt.QIcon ## + +Qt class +[QIcon](http://doc.trolltech.com/4.4/qimage.html) +provides scalable icons in different modes and states. + + +### qt.QIcon([arg]) ### + +Returns a new icon. +Argument `arg` can be a qt value of +type [qt.QImage](#qimage) +or [qt.QPixmap](#qpixmap). +Alternatively, argument `arg` may be a +file name that will be loaded on demand. + + + +## qt.QImage ## + +Qt class +[QImage](http://doc.trolltech.com/4.4/qimage.html) +represents a device independent off-screen image. +Such images are represented in Lua +as Qt variants of class `qt.QImage`. + + +### qt.QImage(...) ### + +There are several ways to construct a Qt variant of class `qt.QImage`. + +__ `qt.QImage(w,h,monoflag)` __ + +Returns a new image of width `w` and height `h`. +The image is bitonal when the optional boolean flag `monoflag` +is `true`. Otherwise the image is a 32 bits RGBA image. + +__ `qt.QImage(f,format)` __ + +Returns a new image obtained by reading the image file `f`. +Argument `f` can be a file name or a Lua file descriptor. +The [file format](#qimageformats) is determined +by the optional string `format` or by the file name extension. + + + +### qimage:depth() ### + +Expression `qimage:depth()` returns the depth of the image `qimage`. +A depth of 1 indicates a bitonal image. +A depth of 24 or 32 indicates a true color image. + + +### qimage:rect() ### + +Expression `qimage:rect()` returns a Qt variant of class +[qt.QRect](qtcore.md#qrect) representing the +boundaries of the image `qimage`. + + +### qimage:save(f,[format]) ### + +Expression `qimage:save(f,format)` saves the image data into file `f`. +Argument `f` can be a file name or a Lua file descriptor. +The [file format](#qimageformats) is determined by the +optional string `format` or by the file name extension. + + +### qimage:size() ### + +Expression `qimage:size()` returns a Qt variant of class +[qt.QSize](qtcore.md#qsize) representing the +size of the image `qimage`. + + +### qt.QImage.formats([string]) ### + + +Function `qt.QImage.formats` describes the +supported formats for reading or saving files. +The optional `string` argument must be a string +starting with letter `"r"` or `"w"` to indicate if +one is interested in the supported formats for reading or +writing image files. When this letter is followed by letter `"f"`, +the function returns a string suitable for selecting name +filters in a file dialog. Otherwise, the function +returns a `qt.QStringList` with the supported formats. + + + + +## qt.QKeySequence ## + +Qt class +[QKeySequence](http://doc.trolltech.com/4.4/qkeysequence.html) +encapsulates a key sequence as used by shortcuts. + + +### qt.QKeySequence(string) ### + +Returns a Qt value of class `qt.QKeySequence` +associated with the key combination described in string `string`. +Up to four key codes may be entered by separating +them with commas, e.g. `"Alt+V,Ctrl+Down,A,Shift+Home"`. + + +### qkeysequence:tostring() ### + +Returns a string describing the keys in the key sequence. + + + +## qt.QMainWindow ## + +Qt class +[QMainWindow](http://doc.trolltech.com/4.4/qmainwindow.html) +provides a main application window with menu, statusbar, toolbars +and dockable widgets. This is a subclass of [QWidget](#qwidget). + + +### qt.QMainWindow([parent]) ### + +Expression `qt.QMainWindow(parent)` returns a new `QMainWindow` instance. +The optional argument `parent` specifies the widget parent. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + +### qmainwindow:centralWidget() ### + +Expression `qmainwindow:centralWidget()` returns the +central widget managed by the main window. + + +### qmainwindow:menuBar() ### + +Returns the main window's menu bar. +This function creates and returns an empty menu bar +if the menu bar does not exist yet. + + +### qmainwindow:setCentralWidget(qwidget) ### + +Sets the widget `qwidget` to be the main window's central widget. +The main window takes ownership of the widget pointer and +deletes it at the appropriate time. + + +### qmainwindow:setMenuBar(qmenubar) ### + +Sets the menu bar for the main window to `qmenubar`. +The main window takes ownership of the menu bar and +deletes it at the appropriate time. + + +### qmainwindow:setStatusBar(qstatusbar) ### + +Sets the status bar for the main window to `qstatusbar`. +The main window takes ownership of the status bar and +deletes it at the appropriate time. + + +### qmainwindow:statusBar() ### + +Returns the main window's status bar. +This function creates and returns an empty status bar +if the status bar does not exist yet. + + + +## qt.QMenu ## + +Qt class +[QMenu](http://doc.trolltech.com/4.4/qmenu.html) +provides a menu widget for use in menu bars, +context menus, and other popup menus. +This is a subclass of [qt.QWidget](#qwidget). + +The most flexible way to populate a menu +consists of first creating [qt.QAction](#qaction) +objects for all the menu items. +These objects can then be inserted +into the menu using the method `addAction` defined by +the superclass [QWidget](#qwidget). + +Function `qmenu:addLuaAction` provides a more convenient way +to create menu items bound to specific lua functions. +See [qt.QMenuBar](#qmenubar) for an example. + + +### qmenu:addLuaAction([icon,]text[,keys[,statustip]][,function]) ### + +Creates a new [QtLuaAction](#qaction) owned by the menu +and appends it to the menu as a new menu item. +This function returns the newly created action. + + * Argument `icon` is an optional [qt.QIcon](#qicon) for the action. + * Argument `text` specifies the text for the menu item. + * Argument `keys` can be either a [qt.QKeySequence](#qkeysequence)specifying the menu item shortcut, or a string representing the shortcut key name. + * Argument `statustip` is an optional string that is displayed in the statusbar when the menu item is highlighted. +Finally argument `function` is a Lua function that is +connected to the action signal `triggered(bool)` and +therefore is called when the menu item is selected. + + +### qmenu:addMenu(newqmenu) ### + +Adds the menu `newqmenu` as a submenu of the menu `qmenu` +and returns the corresponding action object. + + +### qmenu:addMenu([icon,] text) ### + +Creates a new submenu with the specified `icon` and `text` +and adds it into the menu `qmenu`. This function returns +the new menu as an object of class `qt.QMenu`. + + +### qmenu:addSeparator() ### + +Adds a separator into the menu +and returns the corresponding action object. + + +### qmenu:clear() ### + +Removes all the menu items. +Actions owned by the menu and not shown +in any other widget are deleted. + + +### qmenu:exec([qpoint[, defaultqaction]]) ### + +Pops up the menu `qmenu` at position `qpoint` and returns +the action object corresponding to the selected menu item. +This function returns `nil` if no menu item was selected. +Argument `defaultqaction` specifies which action is located +below the mouse cursor when the menu is first shown. +Argument `qpoint` defaults to `qmenu.pos`. + +Note that actions added with `qmenu:addLuaAction` +are automatically disabled while Lua is running. +Therefore such actions cannot be used with +`qmenu:exec` because they would all be disabled. + + +### qmenu:insertMenu(beforeqaction, newqmenu) ### + +Inserts the menu `newqmenu` as a submenu into the menu `qmenu` +and returns the corresponding action object. +The submenu is inserted before action `beforeqaction` +or is appended when `beforeqaction` is null or invalid for this widget. + + +### qmenu:insertSeparator(beforeqaction) ### + +Inserts a new separator before action `beforeqaction` +and returns the corresponding action object. + + +### qmenu:menuAction() ### + +Returns the action associated with the menu `qmenu`. + + +## qt,QMenuBar ## + +Qt class +[QMenuBar](http://doc.trolltech.com/4.4/qmenu.html) +provides a horizontal menu bar for use in main windows. +This is a subclass of [qt.QWidget](#qwidget). + +Example: +```lua +w === qt.QMainWindow() +w:setCentralWidget(...) -- do something smart here +menubar === w:menuBar() +filemenu === menubar:addMenu("&File") +filemenu:addLuaAction("&Open", "Ctrl+O", function() doOpen(w) end) +filemenu:addLuaAction("&Close", "Ctrl+W", function() w:close() end) +editmenu === menubar:addMenu("&Edit") +editmenu:addLuaAction("&Cu&t", "Ctrl+X", function() doCut(w) end) +editmenu:addLuaAction("&Copy", "Ctrl+C", function() doCopy(w) end) +editmenu:addLuaAction("&Paste", "Ctrl+V", function() doPaste(w) end) +w:show() +``` + + +### qmenubar:addMenu(qmenu) ### + +Adds the menu `qmenu` as a menu of the menubar `qmenubar` +and returns the corresponding action object. + + +### qmenubar:addMenu([icon,] text) ### + +Creates a new menu with the specified `icon` and `text` +and adds it into the menubar `qmenubar`. This function returns +the new menu as an object of class `qt.QMenu`. + + +### qmenubar:clear() ### + +Removes all the menus and actions from the menu bar. +Actions owned by the menu and not shown +in any other widget are deleted. + + +### qmenubar:insertMenu(beforeqaction, qmenu) ### + +Inserts the menu `qmenu` into the menu bar `qmenubar` +and returns the corresponding action object. +The submenu is inserted before action `beforeqaction` +or is appended when `beforeqaction` is null or invalid for this widget. + + +### qmenubar:insertSeparator(beforeqaction) ### + +Inserts a new separator before action `beforeqaction` +and returns the corresponding action object. + + +## qt.QPainterPath ## + +Qt class +[QPainterPath](http://doc.trolltech.com/4.4/qpainterpath.html) +represents mathematical boundaries delimiting +regions that can be painted using [painter:fill](qtwidget.md#painterfill) +or delimited using [painter:stroke](qtwidget.md#painterstroke). +No specific Lua methods have been defined for this Qt variant class. + + + +## qt.QPixmap ## + +Qt class +[QPixmap](http://doc.trolltech.com/4.4/qpixmap.html) +represents a server-side image containing device-dependent data. +No specific Lua methods have been defined for this Qt variant class. + + + +## qt.QPen ## + +Qt class +[QPen](http://doc.trolltech.com/4.4/qpen.html) +represents the painter settings that determine how +lines are drawn. + + +### qt.QPen(table) ### + + +Expression `qt.QPen(table)` returns a pen whose settings +are determined by the fields of table `table`. +The following fields are recognized: + + * Field `style` specifies the name of the [pen style](http://doc.trolltech.com/4.4/qt.html#PenStyle-enum). The default style is `SolidLine`. + * Field `brush` contains a `qt.QBrush` value that defines the appearance of the painted areas. + * Field `color` contains a `qt.QColor` value for the brush color. Setting this field is equivalent to setting field `brush` with a solid brush of the specified color. Field `brush` has precedence over this field. + * Numerical field `width` contains the desired line width. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation on the painter. + * Setting boolean field `cosmetic` to `true` indicates that the pen width has a constant width regardless of the transformation on the painter. + * Field `style` specifies the name of the [pen style](http://doc.trolltech.com/4.4/qt.html#PenStyle-enum) which determines + * Field `joinStyle` specifies the name of the [pen join style](http://doc.trolltech.com/4.4/qt.html#PenJoinStyle-enum) which determines how lines meet with different angles. The default join style is `BevelJoin`. + * Field `capStyle` specifies the name of the [pen cap style](http://doc.trolltech.com/4.4/qt.html#PenCapStyle-enum) which determines how lines end are drawn. The default cap style is `SquareCap`. + * Numerical field `miterLimit` determines how far a [miter join](http://doc.trolltech.com/4.4/qpen.html#setMiterLimit) can extend from the join point. This is used to reduce artifacts between line joins where the lines are close to parallel. + + + +### qpen:totable() ### + +Expression `qpen:totable()` returns a table describing the pen. +See the documentation of [qt.QPen(table)](#qpenfromtable) +for a description of the table fields. + + + +## qt.QTransform ## + +Qt class +[QTransform](http://doc.trolltech.com/4.4/qtransform.html) +represents a 2D transformation of a coordinate system. +Transformation matrices are represented as Qt variants +of class `qt.QTransform`. + + +### qt.QTransform([table[,table]]) ### + + +Expression `qt.QTransform()` constructs an identity transformation matrix. + +Expression `qt.QTransform(table)` constructs a transformation matrix +whose matrix elements are initialized with the fields `m11`, `m12`, `m13`, +`m21`, `m22`, `m23`, `m31`, `m32`, and `m33` of table `table`. + +Expression `qt.QTransform(fquad,tquad)` constructs a transformation matrix +that maps the quad `fquad` to the quad `tquad`. +Both arguments `fquad` and `tquad` are table containing exactly four +[qt.QPointF](qtcore.md#qpoint) representing the four corners of the quad. + + +### qtransform:totable() ### + +Expression `qtransform:totable()` returns a table suitable +for use with expression [qt.QTransform(table)](#qtransformfromtable). + + +### qtransform:scaled(sx,sy) ### + +Function `qtransform:scaled` returns a new transformation matrix +representing a coordinate system whose axes have been +scaled by coefficient `sx` and `sy`. + + +### qtransform:translated(dx,dy) ### + +Function `qtransform:translated` returns a new transformation matrix +representing a coordinate system whose origin has been +translated by `dx` units along the X axis and `dy` units along the Y axis. + + + +### qtransform:sheared(cx,cy) ### + +Function `qtransform:sheared` returns a new transformation matrix +representing a coordinate system that has been sheared using coefficients +`cx` horizontally and `cy` vertically. + + + +### qtransform:rotated(angle,[axis,[unit]]) ### + +Function `qtransform:rotated` returns a new transformation matrix +representing a coordinate system rotated by `angle` units around the origin. +The optional string argument `axis` may be `XAxis`, `YAxis`, or `ZAxis` and +defaults to `ZAxis`. The optional string argument `unit` may +be `Degrees` or `Radians` +and default to `Degrees`. + + +### qtransform:inverted() ### + +Function `qtransform:inverted` returns +the inverse transform of its argument +or `nil` when it is not invertible. + + +### qtransform:map(...) ### + +Function `qtransform:map` applies +a transformation to its argument and returns +a new qvariant of the same type. +The argument can be a `QPoint`, `QPointF`, `QLine`, `QLineF`, +`QPolygon`, `QPolygonF`, `QRegion`, `QPainterPath`, +`QRect`, or `QRectF`. When the argument is a rectangle, +the function returns the bounding rectangle of the polygon +representing the transformed rectangle. +This function also take as argument to reals representing +the coordinates of a point and return two reals +representing the transformed coordinates. + + +## qt.QWidget ## + +Qt class +[QWidget](http://doc.trolltech.com/4.4/qwidget.html) +is the base class of all graphical interface components. +All widgets inherit class `qt.QWidget` and +its superclass [qt.QObject](qtcore.md#qobject). + + +### qt.QWidget([parent]) ### + +Expression `qt.QWidget(parent)` returns a new widget. +The optional argument `parent` specifies the widget parent. +New widgets are always created from the main thread using +the [thread hopping](qt.md#qt.qcall) mechanism. + +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + + +### qwidget:actions() ### + +Expression `qwidget:actions()` returns a +qt value of class [qt.QVariantList](qtcore.md#qvariantlist) +containing list of actions associated with this widget. + + +### qwidget:addAction(qaction) ### + +Appends action `qaction` to the +list of actions associated with this widget. + +Example: creating a context menu +```lua +action1 === qt.QtLuaAction{text="Checkme", checkable=true, + function(b) print("checked:", b) end} +action2 === qt.QtLuaAction{text="Pickme", + function() print("picked") end} +w:addAction(action1) +w:addAction(action2) +w.contextMenuPolicy='ActionsContextMenu' +``` + + +### qwidget:insertAction(beforeqaction, qaction) ### + +Insert action ==qaction== into the +list actions associated with this widget. +Argument ==beforeqaction== indicates at which position +to insert the action. If ==beforeqaction== is omitted +or invalid, the action is simply appended. + + +### qwidget:mapToGlobal(qpoint) ### + +Translates the widget coordinates `qpoint` to global screen coordinates. +Both argument `qpoint` and the return value are Qt value of class +[qt.QPoint](qtcore.md#qpoint). + + +### qwidget:mapFromGlobal(qpoint) ### + +Translates the global screen coordinates `qpoint` to widget coordinates. +Both argument `qpoint` and the return value are Qt value of class +[qt.QPoint](qtcore.md#qpoint). + + + +### qwidget:removeAction(qaction) ### + +Removes action `qaction` from the +list actions associated with this widget. + + + +### qwidget:render([pointer]) ### + +When called without argument, +this function draws the widget into an image +and returns the image. + +The optional argument `pointer` can be a +pointer to a `QPainter` or a `QPaintDevice` +where the widget should be rendered. +Such pointers can be obtained using functions +[painter:painter](qtwidget.md#painterpainter) or +[painter:device](qtwidget.md#painterdevice). +When such an argument is specified, +nothing is returned. + + +### qwidget:setAttribute(widgetattribute,[value]) ### + +Sets the specified +[widget attribute](http://doc.trolltech.com/4.4/qt.html#WidgetAttribute-enum) +to boolean value `value`. +Some of these flags are used internally by Qt. +Care is required. + + +### qwidget:setWindowFlag(windowflag,[value]) ### + +Sets the specified +[window flag](http://doc.trolltech.com/4.4/qt.html#WindowType-enum) +to boolean value `value`. +Flags indicating a window type +are handled as exclusive flags. +Setting these flags usually hides the window. +You need to do call `qwidget:show` again. + + +### qwidget:testAttribute(widgetattribute) ### + +Returns a boolean indicating the value of the specified +[widget attribute](http://doc.trolltech.com/4.4/qt.html#WidgetAttribute-enum). +Flags indicating a window type +are handled as exclusive flags. + + +### qwidget:testWindowFlag(windowflag) ### + +Returns a boolean indicating the value of the specified +[window flag](http://doc.trolltech.com/4.4/qt.html#WindowType-enum). +Flags indicating a window type +are handled as exclusive flags. + + +### qwidget:window() ### + +Expression `qwidget:window()` returns the window for widget `qwidget`, +that is the next ancestor that is (or could be) displayed +with a window frame. + +For instance the following code changes the +title of the window containing widget `qwidget`. + +```lua +qwidget:window().windowTitle "New Title" +``` + + + + diff --git a/doc/qtide.md b/doc/qtide.md new file mode 100644 index 0000000..b19b5b9 --- /dev/null +++ b/doc/qtide.md @@ -0,0 +1,406 @@ + +# QtIde Package Reference Manual # + +A package implementing +the QLua Integrated Development Environment (IDE), +including the text editor, the object inspector, +the help browser, and the lua graphical console. + +This package is not complete because +it is under heavy development. + + + +## Functions ## + + + +### qtide.editor([filename]) ### + +Called without argument, this function returns a +text editor object of class [QLuaEditor](#qluaeditor). +Otherwise it returns an editor for the file `filename`, +possibly creating a new editor window. +It pops a message box and returns `nil` if the +file `filename` does not exist or cannot be loaded. + +Open editors have object names of the form `editor`_n_ +and are accessible by name in the `qt` package. + + + +### qtide.doeditor(qluaeditor) ### + +This function executes the chunk of Lua code +corresponding to the text present in the editor `qluaeditor`. +This is the function called by the IDE when one selects +the menu entry "_Load Lua File_" from an editor +whose contents is not associated with a file +or has been modified (otherwise one can use the standard +Lua function `dofile`.) + + + +### qtide.browser([url]) ### + +This function opens a web browser for URL `url`. +The web browser is a widget of class [QLuaBrowser](#qluabrowser). +This is the function called by the IDE when one +requests the help index. + + + +### qtide.inspector(...) ### + +Not yet implemented + + + +### qtide.preferences() ### + +Not yet implemented + + + +### qtide.start([style]) ### + + +Starts the QLua Integrated Development Environment (IDE) +and ensure that the main window is visible. +This function is called implicitely when program `qlua` +is executed with option `-ide`. + +The optional argument `style` is a string +specifying the default IDE style. +When this argument is not specified +the last used style is assumed. +The recognized IDE styles are: + + * `"sdi"` for an IDE with multiple main windows, + * `"mdi"` for an IDE with subwindows in the style of Windows, + * `"tab"` groups all editors into a single tabbed window. + * `"tab2"` groups all editors and the console into a single tabbed window. + + + +### qtide.setup([style]) ### + + +This function is called by [qtide.start()](#qtidestart) +to setup the IDE style. You can call it directly if you +want to organize QLua editors and windows without creating +a graphic console. + + + +## Qt Classes ## + + +### qt.QLuaIde ### + +Object `qt.qLuaIde` represetns the global state of the IDE. +This is the unique instance of class `qt.QLuaIde` +which inherits [qt.QObject](qt.md#qobject). +Most of its capabilities are conveniently +accessible using the functions defined +by the [package ''qtide](#qtidefunctions). + + +#### qt.qLuaIde.editOnError #### + +When a Lua error occurs, this boolean property +specifies whether editors are automatically opened +on the location of the error. +This property is `false` by default +Function [qtide.start](#qtidestart) sets it to `true`. + + +#### qt.qLuaIde:windows() #### + +Returns a variant of type `qt.QObjectList` containing +all the main windows managed by the IDE. + + +#### qt.qLuaIde:windowNames() #### + +Returns a variant of type `qt.QStringList` containing +the names of all the main windows managed by the IDE. + + +#### qt.qLuaIde:activeWindow() #### + + +#### qt.qLuaIde:editor([fname]) #### + + +#### qt.qLuaIde:browser([url]) #### + + +#### qt.qLuaIde:inspector() #### + + +#### qt.qLuaIde:recentFiles() #### + +Returns a variant of type `qt.QStringList` containing +the file names appearing in the "Open Recent Files" menu. + + +#### qt.qLuaIde:addRecentFile(fname) #### + + +#### qt.qLuaIde:clearRecentFiles() #### + + +#### qt.qLuaIde:activateWidget(qwidget) #### + + +#### qt.qLuaIde:activateConsole() #### + + +#### qt.qLuaIde:messageBox(title,message,buttons,[defbutton,[icon]]) #### + + +#### qt.qLuaIde:hasAction(name) #### + + +#### qt.qLuaIde:stdAction(name) #### + + +#### [qt.QLuaIde signal] prefsRequested(qwidget) #### + +This signal is emitted when the "Preferences" menu is selected. + + +#### [qt.QLuaIde signal] helpRequested(qwidget) #### + +This signal is emitted when the "Help Index" menu is selected. + + + + +### qt.QLuaMainWindow ### + +This subclass of `QMainWindow` implements common +functionalities shared by all main windows defined +by the `qtide` package. + + +#### qluamainwindow:clearStatusMessage() #### + + +#### qluamainwindow:showStatusMessage(string,[timeout]) #### + + +#### qluamainwindow:hasAction(name) #### + + +#### qluamainwindow:stdAction(name) #### + + +#### qluamainwindow:doXXXX() #### + +Methods whose name start with `do` implement +the functions accessible from the menus and toolbar icons +in various subclasses of `qt.QLuaMainWindow`. + + + +### qt.QLuaEditor ### + +This subclass of [qt.QLuaMainWindow](#qluamainwindow) +implements the QLua editor windows using +an instance of [qt.QLuaTextEdit](#qluatextedit) +as its main widget. + + +#### qluaeditor:widget() #### + +Expression `qluaeditor:widget()` returns the +[qt.QLuaTextEdit](#qluatextedit) +object that underlies the editor window. + + +#### qluaeditor.fileName #### + +This property contains the name of the file being edited. + + +#### qluaeditor:readFile(string) #### + + +#### qluaeditor:writeFile(string) #### + + + +### qt.QLuaBrowser ### + +This subclass of [qt.QLuaMainWindow](#qluamainwindow) +implements the QLua web browser windows using the Qt WebKit interface. + + + +#### qluabrowser.url #### + +This property contains a qt variant +of type [qt.QUrl](qt.md#qurl) +representing the URL displayed by the browser. + + +#### qluabrowser.html #### + +This property contains a qt variant of type `QString` +representing the HTML text displayed by the browser. + + +### qt.QLuaSdiMain ### + +This subclass of [qt.QLuaMainWindow](#qluamainwindow) +implements the QLua console window. +Expression `qt.qLuaSdiMain` returns the single console +window when such a window exists. + + +#### qt.qLuaSdiMain:consoleWidget() #### + +Returns the object of class +[qt.QLuaTextEdit](#qluaconsolewidget) +implementing the part of the main console +where the user can edit and submit lua strings. + + +#### qt.qLuaSdiMain:editorWidget() #### + +Returns the object of class +[qt.QLuaTextEdit](#qluatextedit) +implementing the part of the main console +where the Lua output is shown. + + + +### qt.QLuaMdiMain ### + +This subclass of [qt.QLuaMainWindow](#qluamainwindow) +aggregates selected windows into a single main window +to implement the IDE styles. Expression `qt.qLuaMdiMain` +returns the single main window when such a window exists. + + +#### qt.qLuaMdiMain.tabMode #### + +The boolean property `qt.qLuaMdiMain.tabMode` +indicates whether the aggregated +windows are displayed using tabs or using a multiple document interface. + + +#### qt.qLuaMdiMain.clientClass #### + +The string property `qt.qLuaMdiMain.clientClass` +contains the name of a class. +All new main windows inheriting this class are then +managed by the single main window. + + +#### qt.qLuaMdiMain:adoptAll() #### + +Collects all main windows that are +subclasses of `qt.qLuaMdiMain.clientClass` +and aggregates them into the mdi main window. + + +#### qt.qLuaMdiMain:adopt(qwidget) #### + + +#### qt.qLuaMdiMain:activate(qwidget) #### + + +### qt.QLuaTextEdit ### + +Class `QLuaTextEdit` is a text editor widget derived +from `QPlainTextEdit` with support for line numbers, +find dialog, replace dialog, and printing. + + +#### qluatextedit.showLineNumbers #### + + +#### qluatextedit.autoComplete #### + + +#### qluatextedit.autoIndent #### + + +#### qluatextedit.autoHighlight #### + + +#### qluatextedit.autoMatch #### + + +#### qluatextedit.tabExpand #### + + +#### qluatextedit.tabSize #### + + +#### qluatextedit:setEditorMode(suffix) #### + + +#### qluatextedit:readFile(fname) #### + + +#### qluatextedit:writeFile(fname) #### + + +#### qluatextedit:showLine(lineno) #### + + +### qt.QLuaConsoleWidget ### + +Class `QLuaConsoleWidget` is a subclass of +[qt.QLuaTextEdit](#qluatextedit) +that captures and display the lua output. + + +#### qluaconsolewidget.printTimings #### + +Boolean property that indicates whether the console +displays the running time of each command. + + +#### qluaconsolewidget:addOutput(text,[format]) #### + +Adds `text` to the console window. +Argument `format` is a string specifying the text format. +Possible values are `"default"`, `"quote"`, and `"comment"`. + + +#### qluaconsolewidget:moveToEnd() #### + +Shows the bottom of the text displayed in the console window. + + +## Qt Objects ## + + +### qt.qLuaIde ### + +Expression `qt.qLuaIde` refers to the unique instance +of class [qt.QLuaIde](#qluaide). +This instance is created when package `qtide` is loaded. + + + +### qt.qLuaSdiMain ### + +Expression `qt.qLuaSdiMain` refers to the unique instance of +class [qt.QLuaSdiMain](#qluasdimain), +created by function [qtide.start()](#qtidestart). + + + +### qt.qLuaMdiMain ### + +Expression `qt.qLuaMdiMain` refers to the unique instance of +class [qt.QLuaMdiMain](#qluamdimain) created +by function [qtide.setup()](#qtidesetup). +There is no such object when the IDE runs in SDI mode. + diff --git a/doc/qtsvg.md b/doc/qtsvg.md new file mode 100644 index 0000000..288ae47 --- /dev/null +++ b/doc/qtsvg.md @@ -0,0 +1,166 @@ + +# QtSvg Bindings # + +The package `qtsvg` +contains bindings for classes defined by the Qt module +[QtSvg](http://doc.trolltech.com/4.4/qtsvg.html). + +Besides the capabilites reported below, +all qt variants inherit a set +of [default methods](qt.md#QVariants), +and all qt object classes inherit the capabilities from their +superclasses and automatically expose +[properties, slots and signals](qt.md#QObjects). + +You can also use the function +[qtwidget.newpdf](qtwidget.md#qtwidgetnewpdf), +defined in module `qtwidget`, +to easily generate SVG files. + + + +### qtsvg.loadsvg(filename) ### + + +Returns a Qt object of +class [qt.QSvgRenderer](#qsvgrenderer) +representing the SVG file `filename`. + + +### qtsvg.paintsvg(port,svg,...) ### + + +Draws a SVG image. + +Argument `port` must be a +[qt.QtLuaPainter](qtwidget.md#qtluapainter) or a +[qtwidget'' high level port descriptor](qtwidget.md#highlevel). +Argument `svg` can be the SVG filename or +an instance of class [qt.QSvgRenderer](#qsvgrenderer) +such as those returned by function [qtsvg.loadsvg](#qtsvg_loadsvg). +The remaining arguments are the same +as those for the C++ function `QSvgRenderer::render`. + + + +### qt.QSvgWidget ### + +Class +[QSvgWidget](http://doc.trolltech.com/4.4/qsvgwidget.html) +provides a widget that is used to display the contents +of Scalable Vector Graphics (SVG) files. + + +#### qt.QSvgWidget([filename],[parent]) #### + +Expression `qt.QSvgWidget(parent)` returns a +new widget for rendering SVG data. + +The optional argument `filename` specifies the name +of a file containing the SVG data. Without this argument, +you must use slot `qsvgwidget:load()` to load SVG data. + +The optional argument `parent` specifies the widget parent. +New widgets are always created from the main thread using +the [thread hopping](qt.md#qtqcall) mechanism. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + +#### qsvgwidget:renderer() #### + +Returns the [qt.QSvgRenderer](#qsvgrenderer) object +associated with this widget. + + + +### qt.QSvgRenderer ### + +Class +[QSvgRenderer](http://doc.trolltech.com/4.4/qsvgrenderer.html) +is used to draw the contents of SVG files onto paint devices. +You should use instead function +[qtsvg.paintsvg](#qtsvg_paintsvg) +to easily display SVG data. + + +#### qt.QSvgRenderer([filename],[parent]) #### + +Creates a new instance of class `QSvgRenderer`. + +The optional argument `filename` specifies the name +of a file containing the SVG data. Without this argument, +you must use slot `qsvgwidget:load()` to load SVG data. + +The optional argument `parent` specifies the widget parent. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + + +### qt.QtLuaSvgGenerator ### + +This is a thin wrapper around the Qt class +[QSvgGenerator](http://doc.trolltech.com/4.4/qsvggenerator.html). + +You should use instead function +[qtwidget.newpdf](qtwidget.md#qtwidgetnewpdf) +to easily generate SVG files. + + +#### qt.QtLuaSvgGenerator([filename],[parent]) #### + +Creates a new instance of class `QtLuaSvgGenerator`. + +When argument `filename` is present, the SVG data is written +into the specified file. Otherwise it is written into a memory +buffer accessible using the method +[qsvggenerator:data()](#qtluasvggeneratordata). + +The optional argument `parent` specifies the widget parent. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + +#### qtluasvggenerator:data() #### + + +Assuming the `qtluasvggenerator` was created without the `filename` argument, +this function returns a [qt.QByteArray](qtcore.md#qbytearray) +containing the generated SVG data. This data may be incomplete +until [painter:close()](qtwidget.md#painterclose) has +been closed on all painters operating on `qtluasvggenerator`. + + +#### qtluasvggenerator.description #### + +Starting with Qt-4.5, this string property defines +the contents of the `` tag of the SVG file. + + +#### qtluasvggenerator.title #### + +Starting with Qt-4.5, this string property defines +the contents of the `` tag of the SVG file. + +<a name="qtluasvggenerator.size"></a> +#### qtluasvggenerator.size #### + +This property contains a [qt.QSize](qtcore.md#qsize) +variant containing the size of the drawable area. +This information is shown in the `viewBox` attribute of the `<svg>` tag. + +<a name="qtluasvggenerator.resolution"></a> +#### qtluasvggenerator.resolution #### + +This integer property defines the resolution, in dots per inch, +of the coordinate system. +Together with `qtluasvggenerator.size`, this property determines +the contents of the `width` and `height` attributes of the `<svg>` tag. + diff --git a/doc/qtuiloader.md b/doc/qtuiloader.md new file mode 100644 index 0000000..9176cad --- /dev/null +++ b/doc/qtuiloader.md @@ -0,0 +1,100 @@ +<a name="qtuiloader.dok"></a> +# QtUiLoader Package Reference Manual # + +Package `qtuiloader` provides +functions for dynamically creating widgets +from the user interface files created by program +[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html). +This is achieved by providing bindings for the Qt class +[QUiLoader](http://doc.trolltech.com/4.4/quiloader.html). + + + +Directory `${`_TorchInstallDir=}/share/lua/5.1/qtuiloader= +contains a small demonstration of this package. +Use program +[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html) +to examine file `test.ui`. +Then load file `test.lua` into the +[qlua](qt.md#qlua) program. + +``` +$ cd /usr/local/share/lua/5.1/qtuiloader +$ /usr/local/bin/qlua +Lua 5.1 Copyright (C) 1994-2008 Lua.org, PUC-Rio +> dofile('test.lua') +``` + + +<a name="qtuiloader.functions"></a> +## Functions ## + +Package `qtuiloader` provides a few convenience functions. +Function [qtuiloader.loader](#qtuiloaderloader) returns a +preallocated instance of class [qt.QUiLoader](#quiloader). +Function [qtuiloader.load](#qtuiloaderload) uses +this preallocated loader to construct a widget using a +[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html) +user interface description. + + +<a name="qtuiloaderavailablewidgets"></a> +### qtuiloader.availableWidgets() ### +<a name="qtuiloader.availablewidgets"></a> + +Expression `qtuiloader.availableWidgets()` returns a +[qt.QStringList](qtcore.md#qstringlist) +containing the names of the supported widget classes. + + +<a name="qtuiloader.createWidget"></a> +### qtuiloader.createWidget(classname,[parent,[objectname]]) ### + +Creates a [widget](qtgui.md#qwidget) of class `classname`. +Argument `classname` can be any of the strings returned +by [`qtuiloader.availableWidgets()`](#qtuiloaderavailablewidgets). +The optional argument `parent` specifies the parent widget +and the optional argument `name` specifies the +[object name](qtcore.md#qobjectobjectname). + +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + +<a name="qtuiloaderload"></a> +### qtuiloader.load(filename,[parent]) ### +<a name="qtuiloader.load"></a> + +Expression `qtuiloader.load(filename,parent)` dynamically +constructs and returns the widget described by the +[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html) +file `filename`. + +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + +<a name="qtuiloaderloader"></a> +### qtuiloader.loader() ### +<a name="qtuiloader.loader"></a> + +Expression `qtuiloader.loader()` +returns a preallocated instance +of class [qt.QUiLoader](#quiloader). + + +<a name="qtuiloader.classes"></a> +## Classes ## + +<a name="quiloader"></a> +### qt.QUiLoader ### + +Class `qt.QUiLoader` provides bindings +for all the functions of the Qt class +[QUiLoader](http://doc.trolltech.com/4.4/quiloader.html). + +To be documented further... + + diff --git a/doc/qtwidget.md b/doc/qtwidget.md new file mode 100644 index 0000000..098cc72 --- /dev/null +++ b/doc/qtwidget.md @@ -0,0 +1,2177 @@ +<a name="qtwidget.dok"></a> +# QtWidget Package Reference Manual # + +Package `qtwidget` provides convenient way +to make drawings and capture user events. +In particular, class [QtLuaPainter](#qtluapainter) gives +the ability to draw simple graphics using well known +postscript-like operators. Graphic output can be sent to an +arbitrary widget, to a PS or PDF file, or to a printer. +Class [QtLuaListener](#qtlualistener) gives the +ability to listen to events on arbitrary widgets + +For instance, the convenient +function [qtwidget.newwindow](#qtwidgetnewwindow) +creates a main window and returns its descriptor. + +```lua +require 'qtwidget' +w=qtwidget.newwindow(400,300,"Some QWidget") +``` + +Drawing is easily achieved using Postscript-like operators. + +```lua +w:moveto(0,0); w:curveto(0,300,400,0,400,300); w:closepath() +w:setcolor("red"); w:fill(false) +w:setcolor("blue"); w:setlinewidth(5); w:stroke() +``` + +Text output is of course supported +using [show](#paintershow). + +```lua +w:moveto(90,40) +w:setcolor("black") +w:setfont(qt.QFont{serif=true,italic=true,size=20}) +w:show("The Quick Brown Fox...") +``` + +Alpha-transparency works as well. + +```lua +w:rectangle(50,50,300,200) +w:setcolor(1,1,0,.5) +w:fill() +``` + +Finally you can capture Qt events using the +[qt.connect](qt.md#qt.connect) function +on the predefined [qt.QtLuaListener](#qtlualistener) object, + +```lua +qt.connect(w.listener, + 'sigMousePress(int,int,QByteArray,QByteArray,QByteArray)', + function(...) print("MousePress",...) end ); +``` + + +and you can erase everything with + +```lua +w:showpage() +``` + +<a name="highlevel"></a> +## High Level Interface ## + +The following convenience functions +provide simple ways to perform graphic display +whose output is directed to a window on the screen, +to an image in memory, to a PostScript file, to a PDF file, or to a printer. +Each of these functions return a Lua table +that defines a number of useful fields and methods. +In particular, all the +[painting functions](#qtluapainterfunctions) +defined by class [qt.QtLuaPainter](#qtluapainter) +can be called directly using the +[Lua method syntax](..:LuaManual#FunctionCalls) +on these tables. + + + +<a name="qtwidgetnewwindow"></a> +### qtwidget.newwindow(w,h,[title]) ### +<a name="qtwidget.newwindow"></a> + +Expression `qtwidget.newwindow(w,h,title)` creates a +toplevel widget of class [qt.QWidget](qtgui.md#qwidget) +and a [qt.QtLuaPainter](#qtluapainter) object +operating on that widget. +Numerical arguments `w` and `h` specify the size of the widget. +String argument `title` specifies a window title. +The expression returns a Lua table that +serves as a drawing port descriptor. + +<a name="qtwidgetnewimage"></a> +### qtwidget.newimage(...) ### +<a name="qtwidget.newimage"></a> + +Function `qtwidget.newimage` creates an image in memory +that can be the target of drawing operations. +This function returns a Lua table that +serves as a drawing port descriptor. + +There are several ways to specify its arguments: + +__`qtwidget.newimage(w,h,[monoflag])`__ + +Creates an image of width `w` and height `h`. +When the optional argument `monoflag` is `true`, +a bitonal image is created. +Otherwise the image can contain arbitrary RGBA colors. + +__`qtwidget.newimage(filename,[format])`__ + +Creates an image by loading the contents of file `filename`. +The file format is defined by the optional string argument `format` +or derived from the file name extension. + +__`qtwidget.newimage(torchtensor)`__ + +Creates an image by extracting the contents of the specified +[torch.Tensor](..:torch:index#Tensor). +The valid tensor formats are described in the documentation for function +[qt.QImage.fromTensor](qt.md#qimagefromtensor). +This only works when both packages [torch](..:torch:index) +and [qttorch](qt.md) have been loaded. + + +<a name="qtwidgetnewps"></a> +### qtwidget.newps(w,h,filename) ### +<a name="qtwidget.newps"></a> + +Expression `qtwidget.newps(w,h,filename)` returns a Lua table that +serves as a drawing port descriptor. +Drawing operations will be output +into the PostScript file `filename`. +Arguments `w` and `h` represent the +initial size of the coordinate system. + +The output file contains incomplete data until +you delete the painter object or call +method [close](#qtwidgetclose). + +<a name="qtwidgetnewpdf"></a> +### qtwidget.newpdf(w,h,filename) ### +<a name="qtwidget.newpdf"></a> + +Expression `qtwidget.newpdf(w,h,filename)` returns a Lua table that +serves as a drawing port descriptor. +Drawing operations will be output +into the PDF file `filename`. +Arguments `w` and `h` represent the +initial size of the coordinate system. + +The output file contains invalid data until +you delete the painter object or call +method [close](#qtwidgetclose). + + +<a name="qtwidgetnewsvg"></a> +### qtwidget.newsvg(w,h,[filename]) ### +<a name="qtwidget.newsvg"></a> + +Expression `qtwidget.newsvg(w,h,filename)` returns a Lua table that +serves as a drawing port descriptor. +The optional argument `filename` contains the +name of the destination file for the SVG data. +Arguments `w` and `h` represent the +initial size of the coordinate system. + +The output contains invalid data until +you delete the painter object or call +method [close](#qtwidgetclose). +When argument `filename` is not specified, +the SVG data is written into an internal memory buffer +accessible using expression +[desc.svg:data()](qtsvg.md#qtluasvggeneratordata). + + +<a name="qtwidgetnewprint"></a> +### qtwidget.newprint(w,h,[printername]) ### +<a name="qtwidget.newprint"></a> + +Expression `qtwidget.newprint(w,h,printername)` +returns a Lua table that +serves as a drawing port descriptor. +Drawing operations will be output to printer `printername`. +When argument `printername` is omitted, +this function pops a print dialog that allows the user +to choose a printer and specify its settings. +Arguments `w` and `h` represent the +initial size of the coordinate system. + + + +<a name="qtpaintingfunctions"></a> +### Painting Functions. ### + +All the [painting functions](#qtluapainterfunctions) +defined by class [qt.QtLuaPainter](#qtluapainter) +can be called directly using the +[Lua method syntax](..:LuaManual#FunctionCalls) +on the table returned by the functions +[qtwidget.newwindow](#qtwidgetnewwindow), +[qtwidget.newimage](#qtwidgetnewimage), +[qtwidget.newps](#qtwidgetnewps), +[qtwidget.newpdf](#qtwidgetnewpdf), +[qtwidget.newsvg](#qtwidgetnewsvg), and +[qtwidget.newprint](#qtwidgetnewprint). + +These calls are simply forwarded to the underlying +[qt.QtLuaPainter](#qtluapainter) object. + + * [Link to the painting functions](#qtluapainterfunctions). + + +<a name="qtwidgetotherfunctions"></a> +### Other Functions and Fields. ### + +The following fields and functions are defined +on the descriptor tables returned by the functions +[qtwidget.newwindow](#qtwidgetnewwindow), +[qtwidget.newimage](#qtwidgetnewimage), +[qtwidget.newps](#qtwidgetnewps), +[qtwidget.newpdf](#qtwidgetnewpdf), and +[qtwidget.newprint](#qtwidgetnewprint). + + +<a name="descport"></a> +#### desc.port #### +<a name="qtwidget.desc.port"></a> + +Field `desc.port` contains the +[qt.QtLuaPainter](#qtluapainter) object +that is used to perform the drawings. + + +<a name="qtwidget.desc.widget"></a> +#### desc.widget #### + +Field `desc.widget` contains the +[qt.QWidget](qtgui.md#qwidget) object +that underlies drawing port descriptors created with +[qtwidget.newwindow](#qtwidgetnewwindow). + + +<a name="qtwidget.desc.listener"></a> +#### desc.listener #### + +Field `desc.widget` contains a +[qt.QtLuaListener](#qtlualistener) object. +that can be used to capture events on the widget created by +[qtwidget.newwindow](#qtwidgetnewwindow). + +<a name="qtwidget.desc.printer"></a> +#### desc.printer #### + +Field `desc.printer` contains the +[qt.QtLuaPrinter](#qtluaprinter) object +that underlies drawing port descriptors created with +[qtwidget.newps](#qtwidgetnewps), +[qtwidget.newpdf](#qtwidgetnewpdf), or +[qtwidget.newprint](#qtwidgetnewprint). + +<a name="qtwidget.desc.svg"></a> +#### desc.svg #### + +Field `desc.svg` contains the +[qt.QtLuaSvgGenerator](qtsvg.md#qtluasvggenerator) object +associated with drawing ports created with +[qtwidget.newsvg](#qtwidgetnewsvg). + + +<a name="qtwidget.desc.width"></a> +#### desc.width #### + +Field `desc.width` contains the width of the drawing surface. + +<a name="qtwidget.desc.height"></a> +#### desc.height #### + +Field `desc.height` contains the height of the drawing surface. + + +<a name="qtwidgetclose"></a> +#### desc:close() #### +<a name="qtwidget.desc.close"></a> + +Function `desc:close()` closes the [qt.QtLuaPainter](#qtluapainter). +In the case of a drawing port descriptor returned by function +[qtwidget.newwindow](#qtwidgetnewwindow), +this function also closes the [qt.QWidget](qtgui.md#qwidget) +and the windows disappears from the screen. + +<a name="qtwidget.desc.resize"></a> +#### desc:resize(w,h) #### + +Function `desc:resize(w,h)` is only available for +drawing port descriptor returned by function +[qtwidget.newwindow](#qtwidgetnewwindow). +It resizes the underlying widget. + + +<a name="qtwidget.desc.onResize"></a> +#### desc:onResize(f) #### + +Function `desc:onResize(f)` is only available for +drawing port descriptor returned by function +[qtwidget.newwindow](#qtwidgetnewwindow). +It ensures that +function `f(w,h)` gets called whenever the widget size changes. +The function argument indicate the new widget size. +Each call of `desc:onResize` replaces the previous callback function by `f`. +Calling it with argument `nil` removes the current callback. + + +<a name="qtwidget.desc.valid"></a> +#### desc:valid() #### + +Expression `desc:valid()` returns `false` if the +underlying drawing target is no longer valid, +for instance because the window has been closed. +Otherwise it returns `true`. + + +<a name="qtwidget.classes"></a> +## Classes ## + +<a name="qtlualistener"></a> +### qt.QtLuaListener ### + +Class `QtLuaListener` emits signals when its parent receives event messages. +This is convenient because the Lua program can define event handling functions +using the signal connection function [qt.connect](qt.md#qt.connect). + +<a name="qtlualistener"></a> +#### qt.QtLuaListener(qwidget) #### + +Expression `qt.QtLuaListener(qwidget)` returns a new `QtLuaListener` object +that relays the event messages received by widget `qwidget`. +This object is a child of `qwidget`. + +<a name="qtlualistener.sigClose"></a> +#### [QtLuaListener signal] sigClose() #### + +Signal `sigClose` is emitted when the underlying widget receives a +[QCloseEvent](http://doc.trolltech.com/4.4/qcloseevent.html). + +<a name="qtlualistener.sigResize"></a> +#### [QtLuaListener signal] sigResize(int,int) #### + +Signal `sigResize` is emitted whenever the underlying widget receives a +[QResizeEvent](http://doc.trolltech.com/4.4/qresizeevent.html) +because it has changed size. The two arguments are the new widget size. + + +<a name="qtlualistener.sigKeyPress"></a> +#### [QtLuaListener signal] sigKeyPress(QString,QByteArray,QByteArray) #### + +Signal `sigKeyPress` is emitted whenever the underlying widget receives a +[QKeyEvent](http://doc.trolltech.com/4.4/qkeyevent.html) +of type `QEvent::KeyPress` because a key was pressed on the keyboard. +The first argument is a string representing the text associated with the key. +The second argument is the +[key name](http://doc.trolltech.com/4.4/qt.html#Key-enum). +The third argument is a string containing the +[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) +separated by a vertical bar. + + +<a name="qtlualistener.sigKeyRelease"></a> +#### [QtLuaListener signal] sigKeyRelease(QString,QByteArray,QByteArray) #### + +Signal `sigKeyRelease` is emitted whenever the underlying widget receives a +[QKeyEvent](http://doc.trolltech.com/4.4/qkeyevent.html) +of type `QEvent::KeyRelease` because a key was released on the keyboard. +The first argument is a string representing the text associated with the key. +The second argument is the +[key name](http://doc.trolltech.com/4.4/qt.html#Key-enum). +The third argument is a string containing the +[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) +separated by a vertical bar. + + + +<a name="qtlualistener.sigMousePress"></a> +#### [QtLuaListener signal] sigMousePress(int,int,QByteArray,QByteArray,QByteArray) #### + +Signal `sigMousePress` is emitted whenever the underlying widget receives a +[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) +of type `QEvent::MouseButtonPress` because a mouse button was pressed. +The first two arguments are the +pixel coordinates of the mouse pointer when the button was clicked +The third argument is a string containing the +[button name](http://doc.trolltech.com/4.4/qt.html#MouseButton-enum). +The fourth argument is a string containing the +[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) +separated by a vertical bar. +The fifth argument is a string containing the names of all depressed buttons +separated by a vertical bar. + + + +<a name="qtlualistener.sigMouseRelease"></a> +#### [QtLuaListener signal] sigMouseRelease(int,int,QByteArray,QByteArray,QByteArray) #### + +Signal `sigMouseRelease` is emitted whenever the underlying widget receives a +[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) +of type `QEvent::MouseButtonRelease` because a mouse button was released. +The first two arguments are the +pixel coordinates of the mouse pointer when the button was released +The third argument is a string containing the +[button name](http://doc.trolltech.com/4.4/qt.html#MouseButton-enum). +The fourth argument is a string containing the +[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) +separated by a vertical bar. +The fifth argument is a string containing the names of all depressed buttons +separated by a vertical bar. + +<a name="qtlualistener.sigMouseDoubleClick"></a> +#### [QtLuaListener signal] sigMouseDoubleClick(int,int,QByteArray,QByteArray,QByteArray) #### + +Signal `sigMouseRelease` is emitted whenever the underlying widget receives a +[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) +of type `QEvent::MouseButtonDblClick` because a mouse button was double-clicked. +The first two arguments are the +pixel coordinates of the mouse pointer when the button was clicked +The third argument is a string containing the +[button name](http://doc.trolltech.com/4.4/qt.html#MouseButton-enum). +The fourth argument is a string containing the +[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) +separated by a vertical bar. +The fifth argument is a string containing the names of all depressed buttons +separated by a vertical bar. + +<a name="qtlualistener.sigMouseMove"></a> +#### [QtLuaListener signal] sigMouseMove(int,int,QByteArray,QByteArray) #### + +Signal `sigMouseRelease` is emitted whenever the underlying widget receives a +[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) +of type `QEvent::MouseMove` because the mouse was moved. +Such events occur only when a mouse button is pressed down, +unless the widget property `mouseTracking` has been set to `true`. +The first two arguments are the +pixel coordinates of the mouse pointer when the button was released +The third argument is a string containing the +[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) +separated by a vertical bar. +The fourth argument is a string containing the names of all depressed buttons +separated by a vertical bar. + + + +<a name="qtlualistener.sigEnter"></a> +#### [QtLuaListener signal] sigEnter(bool) #### + +Signal `sigEnter` is emitted whenever the underlying widget receives an +event of type +[QEvent::Enter](http://doc.trolltech.com/4.4/qevent.html) +or +[QEvent::Leave](http://doc.trolltech.com/4.4/qevent.html). +The boolean argument indicates whether the mouse pointer has just +entered or left the widget area. + +<a name="qtlualistener.sigFocus"></a> +#### [QtLuaListener signal] sigFocus(bool) #### + +Signal `sigEnter` is emitted whenever the underlying widget receives +a [QFocusEvent](http://doc.trolltech.com/4.4/qfocusevent.html). +The boolean argument indicates whether the widget has just gained +or just lost the keyboard focus. + +<a name="qtlualistener.sigShow"></a> +#### [QtLuaListener signal] sigShow(bool) #### + +Signal `sigEnter` is emitted whenever the underlying widget receives +a [QShowEvent](http://doc.trolltech.com/4.4/qshowevent.html) or a +a [QHideEvent](http://doc.trolltech.com/4.4/qhideevent.html). +The boolean argument indicates whether the widget has just been +shown or just been hidden. + + +<a name="qtlualistener.sigPaint"></a> +#### [QtLuaListener signal] sigPaint() #### + +Signal `sigEnter` is emitted whenever the underlying widget receives +a [QPaintEvent](http://doc.trolltech.com/4.4/qpaintevent.html). + +<a name="qtluapainter"></a> +### qt.QtLuaPainter ### + +Painting in Qt is usually achieved using class +[QPainter](http://doc.trolltech.com/4.4/qpainter.html). +Since this class is neither a subclass of +[QObject](http://doc.trolltech.com/4.4/qobject.html) +nor a value class suitable for storing into a Qt variant, +the QtLua class `QtLuaPainter` defines a Qt object that +exposes the painting capabilities of Qt in a more flexible way. + +Instances of class `QtLuaPainter` can target: + + * Any image stored in memory represented as a [qt.QImage](qtgui.md#qimage) or a [qt.QPixmap](qtgui.md#qpixmap). + * Any widget represented as a [qt.QWidget](qtgui.md#qwidget). + * Any `QPaintDevice` encapsulated in a Qt object class such as class [qt.QtLuaPrinter](#qtluaprinter). + +Class `QtLuaPainter` provides an automatic buffering +capability when it targets a widget. Drawing functions +paint onto an offline image. The class logic ensures +that the widget is automatically refreshed or updated +when appropriate. + +Despite these differences, the Qt documentation for the +[Qt paint system](http://doc.trolltech.com/4.4/paintsystem.html) +contains lots of useful information. In particular, the documentation for +class [QPainter](http://doc.trolltech.com/4.4/qpainter.html) +accurately describes how the painter settings affects drawing operations. + + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(...) #### + +Function `qt.QtLuaPainter` constructs a new `QtLuaPainter` instance. + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(qimage) #### + +Constructs a painter instance that targets an offscreen image. +The image is initialized with a copy of the +[qt.QImage](qtgui.md#qimage) +passed as argument. Painting operations do not modify the image +passed as argument. Instead a copy of the current image can be +accessed using expression [painter:image()](#paintergrab). + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(filename, [format]) #### + +Constructs a painter instance that targets an offscreen image +initialized by reading the image file `filename`. +The file format is determined by the optional string +`format` or by the file name extension. +Use expression [painter.image()](#paintergrab) to +obtain a copy of the offscreen image. + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(w,h,[monoflag]) #### + +Constructs a painter instance that targets an offscreen image +of width `w` and height `h`. The image is bitonal when +the optional boolean flag `monoflag` is `true`. Otherwise +the image is a 32 bits RGBA image. +Use expression [painter.image()](#paintergrab) to +obtain a copy of the offscreen image. + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(qpixmap) #### + +Constructs a painter instance that targets a +device-dependent pixmap in memory. +The pixmap is initialized with a copy of +the [qt.QPixmap](qtgui.md#qpixmap) passed as argument. +Use expression [painter:pixmap()](#painterpixmap). +to obtain a copy of the target pixmap. +Since Qt only supports painting a device-dependent `QPixmap` from +the main thread, one must use [qt.pcall](qt.md#qt.qcall) +to ensure that painting operations are performed from the main thread. +Otherwise Qt prints a lot of warnings and behaves erratically. + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(qwidget,[buffered]) #### + +Constructs a painter instance that targets the +specified [qt.QWidget](qtgui.md#qwidget). +The resulting painter is a child of `qwidget`. +The optional boolean argument `buffered` indicates +whether drawing should be performed in a offscreen buffer +or directly on the widget surface. The default is to +create a buffered painter. + +A buffered painter always draws onto an offscreen image +and ensures that the widget surface is automatically refreshed or +updated when needed. Since the painting functions target +a [qt.QImage](qtgui.md#qimage), +they can be called from any thread at any time. +This is the recommended mode of operation. + +An unbuffered painter directly draws onto the widget surface. +Unfortunately Qt4 only supports painting a widget from the paint event handler +[QObject::paintEvent](http://doc.trolltech.com/4.4/qwidget.html#paintEvent). +While this is happening in the main thread, +the Lua interpreter might be unavailable for painting because +the Lua thread is busy running another program. +Unbuffered widget painters are therefore difficult to use for painting; +they are mostly useful for grabbing the on-screen representation +of a widget using function [painter.image()](#paintergrab). + +<a name="qtluapainter"></a> +#### qt.QtLuaPainter(object) #### + +Constructs a painter instance that target the output +device represented by the instance `object` of a suitable Qt object class. +The class must implement an invokable method `device()` that returns +a pointer of type =QPaintDevice*=. +The class can also define an invokable method `printer()` +that returns a pointer of type `QPrinter*= and a signal =closing(QObject*)` +that indicates that the object is being destroyed. +Class [qt.QtLuaPrinter](#qtluaprinter) does all this. + + +<a name="qtluapainter.properties"></a> +#### QtLuaPainter Properties #### + +<a name="qtluapainterangleunit"></a> +##### painter.angleUnit ##### +<a name="qtluapainter.angleUnit"></a> + +This property contains a string defining how arguments +representing angles are interpreted in painter functions +such as [painter:rotate(angle)](#painterrotate). +The acceptable values are the strings `"Degrees"` and `"Radians"`. +The default unit is the degree. + + +<a name="qtluapainterbackground"></a> +##### painter.background ##### +<a name="qtluapainter.background"></a> + +This property contains the [qt.QBrush](qtgui.md#qbrush) +used to draw the spaces in stippled lines, the text background, +and the zero color of bitonal images. +The default background brush is an empty brush +meaning that these pixels are not painted at all. + +<a name="qtluapainterbrush"></a> +##### painter.brush ##### +<a name="qtluapainter.painter"></a> + +Property `painter.brush` contains a Qt variant of class +[qt.QBrush](qtgui.md#qbrush) representing the painter settings +that determine how function [painter:fill](#painterfill) +fills shapes and how function [painter:show](#painterfill) +draws text. + +<a name="qtluapainterclippath"></a> +##### painter.clippath ##### +<a name="qtluapainter.clippath"></a> + +Property `painter.clippath` contient a Qt variant of class +[qt.QPainterPath](qtgui.md#qpainterpath) +representing the boundary +of the current clipping region. Drawing operations +only modify pixels located within the clip region. +An empty path means that no clipping is performed. + +<a name="qtluapaintercompositionmode"></a> +##### painter.compositionMode ##### +<a name="qtluapainter.compositionMode"></a> + +The +[composition mode](http://doc.trolltech.com/4.4/qpainter.html#CompositionMode-enum) +defines how new drawings are merged with previous drawings in the image. +Composition modes are representing as a string containing the +name of the composition mode without the prefix `QPainter::`. +The default composition mode is `"SourceOver"`. + +Not all devices support complex alpha-blending composition modes. +In particular printers often support only the default composition mode. +When a composition mode is not supported, the Qt library prints a warning. + + +<a name="qtluapainterdepth"></a> +##### painter.depth ##### +<a name="qtluapainter.depth"></a> + +Expression `painter.depth` returns the color depth +of the target surface for drawings. +A depth of `1` indicates a bitonal surface. +A depth of `24` or `32` indicates a true color surface. + +<a name="qtluapainterfont"></a> +##### painter.font ##### +<a name="qtluapainter.font"></a> + +Property `painter.font` contient a Qt variant of class +[qt.QFont](qtgui.md#qfont) representing the font settings +used for drawing text. + +<a name="qtluapainterheight"></a> +##### painter.height ##### +<a name="qtluapainter.height"></a> + +Expression `painter.height` returns the height of +the drawing surface expressed in pixels. +The returned value +is not affected by the current transformation matrix. +It corresponds to the default coordinate system +set by [painter:initmatrix](#painterinitmatrix). + +<a name="qtluapaintermatrix"></a> +##### painter.matrix ##### +<a name="qtluapainter.matrix"></a> + +Property `painter.font` contient a Qt variant of class +[qt.QTransform](qtgui.md#qtransform) representing +how coordinates passed to the path construction functions +are transformed into device depending coordinates. + +<a name="qtluapainterpath"></a> +##### painter.path ##### +<a name="qtluapainter.path"></a> + +Property `painter.path` contient a Qt variant of class +[qt.QPainterPath](qtgui.md#qpainterpath) +representing the current path. +A path is a mathematical boundary delimiting regions in the plane. +The current path is used implicitely by functions +[painter:fill](#painterfill) +and [painter:stroke](#painterstroke). +The current path is modified by a rich collection +of path defining functions. + +<a name="qtluapainterpen"></a> +##### painter.pen ##### +<a name="qtluapainter.pen"></a> + +Property `painter.pen` contains a Qt variant of class +[qt.QPen](qtgui.md#qpen) representing the painter settings +that determine how function [painter:stroke](#painterfill) +draws shapes. + +<a name="qtluapainterpoint"></a> +##### painter.point ##### +<a name="qtluapainter.point"></a> + +Property `painter.point` contient a Qt variant of class +[qt.QPointF](qtcore.md#qpoint) representing the +coordinates of the current point. These coordinates +are used and updated implicitely by the majority +of the path construction functions. + + +<a name="qtluapainterrenderhints"></a> +##### painter.renderHints ##### +<a name="qtluapainter.renderHints"></a> + +[Rendering hints](http://doc.trolltech.com/4.4/qpainter.html#RenderHint-enum) +are flags controlling the quality of the drawing operations. +They are represented by a string containing the concatenation of +the names of the active rendering flags (without the prefix `QPainter::`) +separated with a vertical bar "`|`" symbolizing a boolean `or` operator. + + +<a name="qtluapainterstylesheet"></a> +##### painter.styleSheet ##### +<a name="qtluapainter.styleSheet"></a> + +This property contains a string containing a CSS style sheet +that is used when drawing rich text with +function [show](#paintershow). + + +<a name="qtluapainterwidth"></a> +##### painter.width ##### +<a name="qtluapainter.width"></a> + +Expression `painter.width` returns the width of +the drawing surface expressed in pixels. +The returned value +is not affected by the current transformation matrix. +It corresponds to the default coordinate system +set by [painter:initmatrix](#painterinitmatrix). + + +<a name="qtluapainterfunctions"></a> +#### QtLuaPainter Functions #### + +Class `QtLuaPainter` provides a broad array of +painting functions that closely resemble +the well-known PostScript operators. +Additional functions provide capabilities +that are unique to the Qt platform. + + +<a name="qtluapainter.arc"></a> +##### painter:arc(x,y,r,angle1,angle2) ##### + +Expression `painter:arc(x,y,r,angle1,angle2)` +appends an arc of a circle to the current path. +The arc is centered at coordinates `(x,y)` +with radius `r` and extends from angle `angle1` +to angle `angle2` in the trigonometric direction. + +If there is a current point, a line segment joins +the current point to the first endpoint of the arc. +The second endpoint becomes the new current point. + +Angles can be expressed in degrees or radians +according to the [current angle unit](#qtluapainterangleunit). +The default angle unit is the degree. + + +See also: PostScript operator `arc`. + +<a name="qtluapainter.arcn"></a> +##### painter:arcn(x,y,r,angle1,angle2) ##### + +Expression `painter:arcn(x,y,r,angle1,angle2)` +appends an arc of a circle to the current path. +The arc is centered at coordinates `(x,y)` +with radius `r` and extends from angle `angle1` +to angle `angle2` in the inverse trigonometric direction. + +If there is a current point, a line segment joins +the current point to the first endpoint of the arc. +The second endpoint becomes the new current point. + +Angles can be expressed in degrees or radians +according to the [current angle unit](#qtluapainterangleunit). +The default angle unit is the degree. + +See also: PostScript operator `arcn`. + +<a name="qtluapainter.arcto"></a> +##### painter:arcto(x1,y1,x2,y2,r) ##### + +Expression `painter:arcto(x1,y1,x2,y2,r)` +appends an arc of a circle to the current path +defined by the radius `r` and two tangent lines +extending from the current point `(x0,y0)` to `(x1,y1)` +and from `(x1,y1)` to `(x2,y2)`. + +When the current point is set, a line segment joins +the current point to the first endpoint of the arc. +The second endpoint becomes the new current point. + +See also: PostScript operators `arct` and `arcto`. + + +<a name="qtluapainter.charpath"></a> +##### painter:charpath(string) ##### + +Expression `painter:charpath(string)` +computes the path for the glyph outlines that would +result if string `string` was displayed +using [painter:show(string)](#paintershow). +This path is appended to the current path +and is therefore suitable for functions +[painter:stroke](#painterstroke) +or [painter:fill](#painterfill). + +After calling this function, the current point is left unset. + +See also: PostScript operators `charpath`. + +<a name="painterclip"></a> +##### painter:clip(optnewpath) ##### +<a name="qtluapainter.clip"></a> + +Function `painter:clip` intersects the +[current clip region](#qtluapainterclippath) +with the region described by the current path, +that is the region that would be painted by +[qtpainter.fill](#painterfill). +This intersection becomes the new clip region. + +The optional boolean `optnewpath` specifies +whether this function resets the current path +using [painter:newpath()](#painternewpath). +The default is to leave the current path unchanged. +The interior of the current path is determined using the +[winding rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule). +See function [painter:eoclip](#paintereoclip) for an alternative. + +This function cannot enlarge the clipping path. +The recommended approach is to call +[painter:gsave()](#paintergsave) +before reducing the clip region and +[painter:grestore()](#paintergrestore) +to restore the initial clip region. + +See also: PostScript operator `clip`. + + +<a name="painterclose"></a> +##### painter:close() ##### +<a name="qtluapainter.close"></a> + +Expression `painter:close()` detaches +the `QtLuaPainter` object from the underlying widget. +After doing this, you cannot draw anything. +Painters operating on a widget or a printer should +be closed before the underlying widget +or printer is destroyed. + + +<a name="qtluapainter.closepath"></a> +##### painter:closepath() ##### + +Expression `painter:closepath()` +closes the current subpath by appending a +straight line segment connecting the +current point to the subpath to its starting point. +This function does nothing if the current subpath +is already closed. + +Using function `painter:closepath` is better than specifying +the line segment using `painter:lineto` because it will +ensure that the line segments are joined using the +current pen `capStyle` and `joinStyle` attributes. + +After calling this function, +the current point is left unset. + +See also: PostScript operator `closepath`. + +<a name="qtluapainter.concat"></a> +##### painter:concat(qtransform) ##### + +Expression `painter:concat(qtransform)` +replaces the [current transformation matrix](#qtluapaintermatrix) +by the product of the current matrix +by the `QTransform` object `qtransform`. + +It is much easier to use functions +[painter:translate](#paintertranslate), +[painter:scale](#painterscale), or +[painter:rotate](#painterrotate). + +See also: PostScript operator `concat`. + +<a name="qtluapainter.currentangleunit"></a> +##### painter:currentangleunit() ##### + +Expression `painter:currentangleunit()` returns the +[current angle unit](#qtluapainterangleunit) +for angles in functions such as [painter:rotate](#painterrotate). +Possible values are strings `"Degrees"` and `"Radians"`. +The default angle unit are degrees. + + +<a name="qtluapainter.currentbackground"></a> +##### painter:currentbackground() ##### + +Expression `painter:currentbackground()` +returns a [qt.QBrush](qtgui.md#qbrush) +representing the [current background brush](#qtluapainterbackground) +used for displaying the backgrounds when painting +dashed line, text, or bitonal images. +The default is an empty brush. + + +<a name="qtluapainter.currentbrush"></a> +##### painter:currentbrush() ##### + +Expression `painter:currentbrush()` +returns a [qt.QBrush](qtgui.md#qbrush) +representing the [current brush](#qtluapainterbrush) +used for filling path with [painter:fill()](#painterfill). +The default is an empty brush. + + +<a name="qtluapainter.currentclip"></a> +##### painter:currentclip() ##### + +Expression `painter:currentclip()` +returns a [QPainterPath](qtgui.md#qpainterpath) +representing the [current clip region](#qtluapainterclippath). + +<a name="qtluapainter.currentcolor"></a> +##### painter:currentcolor() ##### + +Expression `painter:currentcolor()` +returns four numbers representing the +red, green, blue, and alpha components +of the color of the [current brush](qtgui.md#qbrush). +This numbers range from zero to one. + + +<a name="qtluapainter.currentdash"></a> +##### painter:currentdash() ##### + +Expression `painter:currentdash()` +returns the dash pattern and the dash offset +of the [current pen](#qtluapainterpen). + + +<a name="qtluapainter.currentfont"></a> +##### painter:currentfont() ##### + +Expression `painter:currentfont()` +returns a [QFont](qtgui.md#qfont) +describing the [current font](#qtluapainterfont) +for drawing text. + +<a name="qtluapainter.currentfontsize"></a> +##### painter:currentfontsize() ##### + +Expression `painter:currentfontsize()` +returns the size in points of the +[current font](#qtluapainterfont). + + +<a name="qtluapainter.currenthints"></a> +##### painter:currenthints() ##### + +Expression `painter:currenthints()` returns the +[current rendering hints](#qtluapainterrenderhints) +controlling the quality of the drawings. + + +<a name="qtluapainter.currentlinewidth"></a> +##### painter:currentlinewidth() ##### + +Expression `painter:currentlinewidth()` returns +the line width associated with the +[current pen](#qtluapainterpen). + +<a name="qtluapainter.currentmatrix"></a> +##### painter:currentmatrix() ##### + +Expression `painter:currentmatrix()` returns a Qt variant of class +[qt.QTransform](qtgui.md#qtransform) representing the +[current transformation matrix](#qtluapaintermatrix). + +<a name="qtluapainter.currentmode"></a> +##### painter:currentmode() ##### + +Expression `painter:currentmode()` returns a string representing the +[current composition mode](#qtluapaintercompositionmode). + + +<a name="qtluapainter.currentpath"></a> +##### painter:currentpath() ##### + +Expression `painter:currentpath()` returns a Qt variant of class +[qt.QPainterPath](qtgui.md#qpainterpath) representing the +[current path](#qtluapainterpath). + + +<a name="qtluapainter.currentpen"></a> +##### painter:currentpen() ##### + +Expression `painter:currentpath()` returns a Qt variant of class +[qt.QPen](qtgui.md#qpen) representing the +[current pen](#qtluapainterpen). + + +<a name="qtluapainter.currentpoint"></a> +##### painter:currentpoint() ##### + +Expression `painter:currentpoint()` returns two numbers +representing the coordinates of the +[current point](#qtluapainterpoint). + + +<a name="paintercurrentsize"></a> +##### painter:currentsize() ##### +<a name="qtluapainter.currentsize"></a> + +Expression `painter:currentsize()` returns two numbers +representing the width and height of the drawing are +expressed in pixels. The returned values +are not affected by the current transformation matrix. +They correspond to the default coordinate system +sets by [painter:initmatrix](#painterinitmatrix). + + +<a name="paintercurrentstylesheet"></a> +##### painter:currentstylesheet() ##### +<a name="qtluapainter.currentstylesheet"></a> + +Expression `painter:currentstylesheet()` returns the +the [current style sheet](#qtluapainterstylesheet) +used by function [show](#paintershow) for +displaying rich text. + + +<a name="paintercurveto"></a> +##### painter:curveto(x1,y1,x2,y2,x3,y3) ##### +<a name="qtluapainter.curveto"></a> + +Expression `painter:curveto(x1,y1,x2,y2,x3,y3)` +appends a section of a cubic Bezier curve to the current path. +The curve starts on the current point and ends in point `(x3,y3)` +using `(x1,y1)` and `(x2,y2)` as the Bezier control points. +The endpoint `(x3,y3)` then becomes the new current point. + +The behavior of this function is undefined +when the current point is not set + +See also: PostScript operator `curveto`. + + +<a name="painterdevice"></a> +##### painter:device() ##### +<a name="qtluapainter.device"></a> + +Expression `painter:device()` returns a pointer to the Qt +paint device underlying the painter. +Since the Qt class +[QPaintDevice](http://doc.trolltech.com/4.4/qpaintdevice.html) +is neither a Qt variant not a Qt object, this pointer +is represented by a Qt variant of type =QPaintDevice*=. +This is not very useful in Lua. + + +<a name="paintereoclip"></a> +##### painter:eoclip(optnewpath) ##### +<a name="qtluapainter.eoclip"></a> + +Function `painter:eoclip` is similar to function +[painter:clip](#painterclip). However the interior of the +current path is interpreted using the +[odd-even rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule) +instead of the winding rule. + + + +<a name="paintereofill"></a> +##### painter:eofill(optnewpath) ##### +<a name="qtluapainter.eofill"></a> + +Function `painter:eofill` is similar to function +[painter:fill](#painterfill). However the interior of the +current path is determined using the +[odd-even rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule) +instead of the winding rule. + +See also: PostScript operator `eofill`. + +<a name="painterfill"></a> +##### painter:fill(optnewpath) ##### +<a name="qtluapainter.fill"></a> + +Function `painter:fill` fills the interior of the +[current path](#qtluapainterpath) using +the [current brush](#qtluapainterbrush). + +The optional boolean `optnewpath` specifies +whether this function resets the current path +using [painter:newpath()](#painternewpath). +The default is to reset the current path. +The interior of the current path is determined using the +[winding rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule). +See function [painter:eofill](#paintereofill) for an alternative. + +See also: PostScript operator `fill`. + + +<a name="paintergbegin"></a> +##### painter:gbegin() ##### +<a name="qtluapainter.gbegin"></a> + +Functions [painter:gbegin](#paintergbegin) and +[painter:gend](#paintergend) can be used +to bracket code segments that perform drawings that +are meaningful as a whole. The actual display is +usually postponed until the last call to `painter:gend`. +This is useful for implementing smooth transitions +between successive drawings. + +<a name="paintergend"></a> +##### painter:gend([invalidate]) ##### +<a name="qtluapainter.gend"></a> + +Functions [painter:gbegin](#paintergbegin) and +[painter:gend](#paintergend) can be used +to bracket code segments that perform drawings that +are meaningful as a whole. The actual display is +usually postponed until the last call to `painter:gend`. +This is useful for implementing smooth transitions +between successive drawings. + +When the target device is a buffered widget, +setting flag `invalidate` to true +ensures that the whole widget will be refreshed. +This is useful after drawing directly into +the underlying `QPainter` object without +using the `QtLuaPainter` functions. + + +<a name="paintergrestore"></a> +##### painter:grestore() ##### +<a name="qtluapainter.grestore"></a> + +Expression `painter:grestore()` restores the painter settings +previously saved by a matching expression [painter:gsave()](#paintergsave). + +Functions [painter:gsave](#paintergsave) and +[painter:restore](#paintergrestore) should be used +to bracket code segments that perform some rendering +in order to ensure that the painter settings +remain unchanged. + + + +<a name="paintergsave"></a> +##### painter:gsave() ##### +<a name="qtluapainter.gsave"></a> + +Expression `painter:gsave()` records the painter settings +and pushes this information on top of a stack of painter settings. +Subsequent calls to [painter:grestore()](#paintergrestore) +can be used to restore the saved settings. + +Functions [painter:gsave](#paintergsave) and +[painter:restore](#paintergrestore) should be used +to bracket code segments that perform some rendering +in order to ensure that the painter settings +remain unchanged. + +<a name="paintergrab"></a> +##### painter:image() ##### +<a name="qtluapainter.image"></a> + +Expression `painter:image()` returns a Qt variant of class +[qt.QImage](qtgui.md#qimage) +representing the drawing surface. + +When the underlying surface is a widget without backing store, +this function grabs the widget image from the display. +When the painter operates on a device that cannot be represented +as an image, for instance a printer, +this function returns an empty image for which method +[tobool](qt.md#qt.tobool) returns `false`. + +Note that this function must be invoked without arguments. +Otherwise see the documentation for [painter:image(...)](#painterblit). + + +<a name="painterblit"></a> +##### painter:image(x,y,[w,h],image,[sx,sy,[sw,sh]]) ##### +<a name="qtluapainter.image"></a> + +Function `painter:image` paints a segment of image `image` +at position `(x,y)` in the current coordinate systems +with with `w` and height `h`. The source segment +is defined by the rectangle of size `(sw,sh)` +starting on point `(sx,sy)`. + +The default source width `sw` and height `sh` are the width and height of the +source image. The default source origin `(sx,sy)` is the origin `(0,0)`. +The default target width `w` and height `h` are +the source width `sw` and height `sh`. + +Argument `image` can be a Qt variant of +class [qt.QImage](qtgui.md#qimage) +or [qt.QPixmap](qtgui.md#qpixmap) +or a Qt object of class [qt.QtLuaPainter](#qtluapainter). +In the latter case, the function +[painter:image()](#paintergrab) without arguments +is used to obtain the source surface. + + * To blit an image `img` constructed with [qtwidget.newimage](#qtwidgetnewimage), you must specify the associated painter [img.port](#descport). + * To blit a [torch.Tensor](..:torch:index#Tensor), first create a [qt.QImage](qtgui.md#qimage) using the function [qt.QImage.fromTensor](qt.md#qimagefromtensor) from by package [qttorch](qt.md). + +Blit is of course affected by +the [current composition mode](#qtluapaintercompositionmode). + +Note that this function must be invoked with arguments. +Otherwise see the documentation for [painter:image()](#paintergrab). + +See also: PostScript operator `image`. + + +<a name="painterinitclip"></a> +##### painter:initclip() ##### +<a name="qtluapainter.initclip"></a> + +Expression `painter:initclip()` resets the +[current clip region](#qtluapainterclippath) +to the empty path. This effectively means +that clipping is disabled and therefore +that all surface pixels can be affected +by a subsequent drawing operation. + + +See also: PostScript operator `initclip`. + + +<a name="painterinitgraphics"></a> +##### painter:initgraphics() ##### +<a name="qtluapainter.initgraphics"></a> + +Expression `painter:initgraphics()` resets +all painter settings to their default values. +After calling this function: + + * The [current clip region](#qtluapainterclippath) is set as with [painter:initclip()](#painterinitclip). + * The [current transformation matrix](#qtluapaintermatrix) is set as with [painter:initmatrix()](#painterinitmatrix). + * The [current brush](#qtluapainterbrush) is a solid black brush with brush origin (0,0). + * The [current pen](#qtluapainterpen) is a solid black pen with line width `1`, flat caps, and miter joins. + * The [current background](#qtluapainterbackground) is an empty brush meaning that background pixels are not painted at all. + * The [current font](#qtluapainterfont) is a 10 points sans serif font. + * The [current path](#qtluapainterpath) is empty and the [current point](#qtluapainterpoint) is unset. + * The [current rendering hints](#qtluapainterrenderhints) are `"Antialiasing|TextAntialiasing"`. + * The [current composition mode](#qtluapaintercompositionmode) is `"SourceOver"`. + * The [current angle unit](#qtluapainterangleunit) is `"Degrees"`. + +See also: PostScript operator `initgraphics`. + + +<a name="painterinitmatrix"></a> +##### painter:initmatrix() ##### +<a name="qtluapainter.initmatrix"></a> + +Expression `painter:initmatrix()` resets the +[current transformation matrix](#qtluapaintermatrix) +to its default value. +The coordinate system has then its origin +in the upper left corner of the surface +with X coordinates ordered from left to right +and Y coordinates ordered from top to bottom. +Coordinates are expressed in device pixels +on most devices. + +See also: PostScript operator `initmatrix`. + +<a name="qtluapainter.lineto"></a> +##### painter:lineto(x,y) ##### + +Expression `painter:lineto(x,y)` appends +a line segment to the current path, +starting from the [current point](#qtluapainterpoint) +and ending at coordinates `(x,y)`. +The segment end point then becomes +the new current point. + +The behavior of this function is undefined +when the current point is not set + +See also: PostScript operator `lineto`. + + +<a name="qtluapainter.moveto"></a> +##### painter:moveto(x,y) ##### + +Expression `painter:moveto(x,y)` terminates the +last subpath of the current path and moves +the current point to coordinates `(x,y)`. + +See also: PostScript operator `moveto`. + + +##### painter:newpath() ##### +![](anchor:painternewpath) +<a name="qtluapainter.newpath"></a> + +Expression `painter:newpath()` terminates the last subpath. +After calling this function, the current point is left unset. + +See also: PostScript operator `newpath`. + +<a name="painterobject"></a> +##### painter:object() ##### +<a name="qtluapainter.object"></a> + +Expression `painter:object()` returns the Qt object +that represents the paint device if such an object exists. +Typical return values are instance of class +[qt.QWidget](qtgui.md#qwidget) or class +[qt.QtLuaPrinter](#qtluaprinter). + + +<a name="painterpainter"></a> +##### painter:painter() ##### +<a name="qtluapainter.painter"></a> + +Expression `painter:painter()` returns a pointer +to the underlying Qt painter. +Since the Qt class +[QPainter](http://doc.trolltech.com/4.4/qpainter.html) +is neither a Qt variant not a Qt object, this pointer +is represented by a Qt variant of type =QPainter*=. + + +<a name="painterpixmap"></a> +##### painter:pixmap() ##### +<a name="qtluapainter.pixmap"></a> + +Expression `painter:pixmap()` returns a Qt variant of class +[qt.QPixmap](qtgui.md#qpixmap) representing the drawing surface. + +When the underlying surface is a widget without backing store, +this function grabs the widget representation from the display. +When the painter operates on a device that cannot be represented +as a pixmap, for instance a printer, +this function returns an empty pixmap for which method +[tobool](qt.md#qt.tobool) returns `false`. + +<a name="qtluapainter.printer"></a> +##### painter:printer() ##### + +Expression `painter:printer()` returns a pointer +to the underlying Qt printer. +Since the Qt class +[QPrinter](http://doc.trolltech.com/4.4/qpainter.html) +is neither a Qt variant not a Qt object, this pointer +is represented by a Qt variant of type =QPrinter*=. + + + +<a name="qtluapainter.rcurveto"></a> +##### painter:rcurveto(x1,y1,x2,y2,x3,y3) ##### + +This is similar to calling function +[painter:curveto](#paintercurveto) +with the following arguments + +```lua +painter:curveto(x0+x1,y0+y1,x0+x2,y0+y2,x0+x3,y0+y3) +``` + +where `(x0,y0)` are the coordinates of the previous +current point. + +The behavior of this function is undefined +when the current point is not set. + +See also: PostScript operator `rcurveto`. + +<a name="qtluapainter.rect"></a> +##### painter:rect() ##### + +Expression `painter:rect()` returns a Qt variant +of class [=qt.QRect](qtcore.md#qrect) +representing the pixel coordinates of the drawing surface. +This does not depend on the transformation matrix +but corresponds to the default coordinate system +set by [painter:initmatrix()](#painterinitmatrix). + +The same information can be obtained more conveniently +using function [painter:currentsize()](#paintercurrentsize) +or properties [painter.width](#qtluapainterwidth) +and [painter.height](#qtluapainterheight). + + +<a name="qtluapainter.rectangle"></a> +##### painter:rectangle(x,y,w,h) ##### + +Expression `painter:rectangle(x,y,w,h)` +appends a rectangle to the current path. +The rectangle starts is defined by its origin `(x,y)`, +its width `w` and its height `h`. + +After calling this function, +the current point is left unset. + + + +<a name="qtluapainter.refresh"></a> +##### painter:refresh() ##### + +Expression `painter:refresh()` immediately +repaints the displayed image, +regardless of the nesting count of functions +[painter:gbegin()](#paintergbegin) and +[painter:gend()](#paintergend). + + + +<a name="qtluapainter.rlineto"></a> +##### painter:rlineto(rx,ry) ##### + +Expression `painter:lineto(x,y)` appends a line segment +to the current path, starting from the current point `(x0,y0)` +and ending at coordinates `(x0+x,y0+y)`. +The segment end point then becomes +the new current point. + +The behavior of this function is undefined +when the current point is not set + +See also: PostScript operator `rlineto`. + +<a name="qtluapainter.rmoveto"></a> +##### painter:rmoveto(rx,ry) ##### + +Expression `painter:moveto(x,y)` terminates the +last subpath of the current path and moves +the current point to coordinates `(x0+x,y0+y)` +where `(x0,y0)` are the coordinates of the previous +current point. + +The behavior of this function is undefined +when the current point is not set + +See also: PostScript operator `rmoveto`. + +<a name="painterrotate"></a> +##### painter:rotate(angle) ##### +<a name="qtluapainter.rotate"></a> + +Expression `painter:rotate(angle)` +rotates the axes of the coordinate system by `angle` angle units +in the trigonometric direction around the coordinate origin. +The position of the coordinate origin and the size of the coordinate units +are unaffected. + +Argument `angle` can be expressed in degrees or radians +according to the [current angle unit](#qtluapainterangleunit). +The default angle unit is the degree. + +See also: PostScript operator `rotate`. + +<a name="painterscale"></a> +##### painter:scale(sx,sy) ##### +<a name="qtluapainter.scale"></a> + +Expression `scale(sx,sy)` scales the units of the +coordinate space by a factor of `sx` horizontally and +`sy` vertically. The position of the coordinate origin and +the orientation of the axes are unaffected. + +See also: PostScript operator `scale`. + + +<a name="paintersetangleunit"></a> +##### painter:setangleunit(unit) ##### +<a name="qtluapainter.setangleunit"></a> + +Expression `painter:setangleunit(unit)` sets the +[angle unit](#qtluapainterangleunit) +for functions such as [painter:rotate](#painterrotate) +that require an angle as argument. + +Argument `unit` must be string `"Degrees"` +for expressing angles in degrees, +or `"Radians"` for expressing angles in radians. +The default angle unit is the degree. + + +<a name="qtluapainter.setbackground"></a> +##### painter:setbackground(brush) ##### + +Expression `painter:setbackground(brush)` sets the +[current background brush](#qtluapainterbackground). +Argument `brush` must be a Qt variant of type +[qt.QBrush](qtgui.md#qbrush). + +<a name="qtluapainter.setbrush"></a> +##### painter:setbrush(brush) ##### + +Expression `painter:setbrush(brush)` sets the +[current brush](#qtluapainterbrush). +Argument `brush` must be a Qt variant of type +[qt.QBrush](qtgui.md#qbrush). + +<a name="qtluapainter.setclip"></a> +##### painter:setclip(qpainterpath) ##### + +Expression `painter:setclip(qpainterpath)` sets the +[current clipping region](#qtluapainterclippath) +to be the interior of the specified path. +Argument `brush` must be a Qt variant of type +[qt.QPainterPath](qtgui.md#qpainterpath). + + +<a name="qtluapainter.setcolor"></a> +##### painter:setcolor(...) ##### + +Function `painter:setcolor` sets the color of both the +[current brush](#qtluapainterbrush) +and [current pen](#qtluapainterpen). + +There are several ways to specify a color: + +__`painter:setcolor(qcolor)`__ + +Argument `qcolor` is a Qt variant of +class [qt.QColor](qtgui.md#qcolor). + +__`painter:setcolor(string)`__ + +Argument `string` is a string representing a color name. +All [SVG color names](http://www.w3.org/TR/SVG/types.html#ColorKeywords) +are recognized.Color names can have also the format `"#RGB"`, +`"#RRGGBB"`, `"#RRRGGGBBB"`, or ="#RRRRGGGGBBBB" +where letters `R`, `G`, or `B` represent hexadecimal +digits for each of the color component. + +__`painter:setcolor(r,g,b,[a])`__ + +Arguments `r`, `g`, `b`, and `a` are numbers in range `[0,1]` +representing the intensities of the red, green, blue, and alpha channels. +The default value for argument `a` is `1` for a fully opaque color. + + +<a name="qtluapainter.setdash"></a> +##### painter:setdash([sizes,[offset]]) ##### + +Function `painter:setdash` changes the +style of the [current pen](#qtluapainterpen). + +When this function is called without argument, +or when argument `sizes` is `nil`, +this function sets the current pen style +to `"SolidLine"`. + +Otherwise argument `sizes` can be a single number or +a table containing a list of numbers. +The number or the list of numbers represent the length of successive +[dashes and blanks](http://doc.trolltech.com/4.4/qpen.html#setDashPattern) +along the drawn curve, expressed in units of the line width. +When the size of the sequence is odd, the last blank +is assumed to have the same size as the last dash. +The optional argument `offset` is a length +representing the starting position of the dash sequence. + + +<a name="qtluapainter.setfont"></a> +##### painter:setfont(qfont) ##### + +Expression `painter:setfont(qfont)` sets the +[current font](#qtluapainterfont). +Argument `font` must be a Qt variant of type +[qt.QFont](qtgui.md#qfont). + +<a name="qtluapainter.setfontsize"></a> +##### painter:setfontsize(size) ##### + +Expression `painter:setfontsize(size)` changes the size +of the [current font](#qtluapainterfont). +Argument `size` must be a positive number. + + +<a name="qtluapainter.sethints"></a> +##### painter:sethints(hints) ##### + +Expression `painter:sethints(hints)` sets the +[current rendering hints](#qtluapainterrenderhints). +Argument `hints` must be a string containing +a concatenation of the names of the active +[rendering flags](http://doc.trolltech.com/4.4/qpainter.html#RenderHint-enum) +separated with a vertical bar "`|`". + + +<a name="qtluapainter.setlinewidth"></a> +##### painter:setlinewidth(lw) ##### + +Expression `painter:setlinewidth(lw)` changes the line width +of the [current pen](#qtluapainterpen). +Argument `lw` must be a positive number. + +<a name="qtluapainter.setmatrix"></a> +##### painter:setmatrix(qtransform) ##### + +Expression `painter:setmatrix(qtransform)` sets the +[current transformation matrix](#qtluapaintermatrix). +Argument `qtransform` must be a Qt variant of type +[qt.QTransform](qtgui.md#qtransform). + + +<a name="qtluapainter.setmode"></a> +##### painter:setmode(compositionmode) ##### + +Expression `painter:setmode(compositionmode)` sets the +[current composition mode](#qtluapaintercompositionmode) +for subsequent drawing operations. +Argument `compositionmode` must be a string containing the name of a +[composition mode](http://doc.trolltech.com/4.4/qpainter.html#CompositionMode-enum). + + +<a name="qtluapainter.setpath"></a> +##### painter:setpath(qpainterpath) ##### + +Expression `painter:setpath(qpainterpath)` sets the +[current path](#qtluapainterpath). +Argument `qpainterpath` must be a Qt variant of type +[qt.QPainterPath](qtgui.md#qpainterpath). + + +<a name="qtluapainter.setpattern"></a> +##### painter:setpattern(pattern,[x,y]) ##### + +Expression `painter:setpattern(pattern,[x,y])` +creates a textured pattern brush. +This brush is used to set both the [current brush](#qtluapainterbrush) +and the brush of the [current pen](#qtluapainterpen). + +Argument `p` can be either a Qt variant +of type [qt.QImage](qtgui.md#qimage) or an object +equipped with a method `image` returning a suitable image. +Such objects include instances of [qt.QtLuaPainter](#qtluapainter) +as well as the return values of functions +[qtwidget.newwindow](#qtwidgetnewwindow) +or [qtwidget.newimage](#qtwidgetnewimage) + +The optional arguments `x` and `y` specify +the origin of the pattern in the source image. + + +<a name="qtluapainter.setpen"></a> +##### painter:setpen(qpen) ##### + +Expression `painter:setpen(qpen)` sets the +[current pen](#qtluapainterpen). +Argument `qpen` must be a Qt variant of type +[qt.QPen](qtgui.md#qpen). + + +<a name="qtluapainter.setpoint"></a> +##### painter:setpoint(x,y) ##### + +Expression `painter:setpoint(x,y)` sets the +[current point](#qtluapainterpen) coordinates to `(x,y)`. +Arguments `x` and `y` must be valid numbers. + + +<a name="qtluapainter.setstylesheet"></a> +##### painter:setstylesheet(s) ##### + +Expression `painter:setstylesheet(s)` sets the +the [current style sheet](#qtluapainterstylesheet) +used by function [show](#paintershow) for +displaying rich text. + + + +<a name="paintershow"></a> +##### painter:show(string,[x,y,w,h,textflags]) ##### +<a name="qtluapainter.show"></a> + +Function `painter:show` draws string `string` using +the [current font](#qtluapainterfont). + +When called with a single string argument `string`, +this function draws the specified text +starting from the [current point](#qtluapainterpoint). +After displaying each glyph, the current point is adjusted +with a displacement computed from the font's glyph-spacing information. +The behavior of this function is undefined +when the current point is not set. + +When called with more arguments, this function draws +the text `string` within the rectangle specified by +the origin `(x,y)`, the width `w`, and the heigth `h`. +Argument `textflags` is then a string composed by concatenating +a subset of the following keywords separated +by a vertical bar "`|`" symbolizing a `or` operator: +[AlignLeft](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignRight](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignTop](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignBottom](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignHCenter](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignVCenter](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignCenter](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), +[AlignJustify](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum). +[TextSingleLine](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), +[TextExpandTabs](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), +[TextShowMnemonic](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), +[TextWordWrap](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), +[RichText](http://doc.trolltech.com/4.4/richtext-html-subset.html). + +The flag `RichText` is directly implemented by the `QtLuaPainter` class. +It indicates that the text contains rich text data using the +[subset of HTML](http://doc.trolltech.com/4.4/richtext-html-subset.html) +supported by Qt and can be used in conjunction with alignment flags only. +Display is affected by +the [current font](#qtluapainterfont), +the [current brush color](#qtluapainterbrush), and +the [current style sheet](#qtluapainterstylesheet). +You can use the css `style` attribute in HTML tags +to specify more complicated formats. + +See also: PostScript operator `show`. + + +<a name="qtluapainter.showpage"></a> +##### painter:showpage() ##### + +Expression `painter:showpage()` +clears the current drawing +and paints the background all white. + +Things are a bit different when the painting device is a printer. +Function `painter:showpage` ensures that the next drawing operation +will first print the current page and initialize a new page. +Successive calls of `painter:showpage()` do not print multiple pages +unless some drawing operation is performed on each page. + +See also: PostScript operator `showpage`. + + +<a name="qtluapainter.size"></a> +##### painter:size() ##### + +Expression `painter:size()` returns a Qt variant +of class [qt.QSize](qtcore.md#qsize) +representing the size in pixels of the drawing surface. +This does not depend on the transformation matrix +but corresponds to the default coordinate system +set by [painter:initmatrix()](#painterinitmatrix). + +The same information can be obtained more conveniently +using function [painter:currentsize()](#paintercurrentsize) +or properties [painter.width](#qtluapainterwidth) +and [painter.height](#qtluapainterheight). + +<a name="qtluapainter.stringrect"></a> +##### painter:stringrect(string,[x,y,w,h,textflags]) ##### + +Function `painter:stringrect` returns a Qt variant of type +[qt.QRectF](qtcore.md#qrect) representing +the bounding box of the text that would be displayed +by calling function [painter:show](#paintershow) +with the same arguments. + + +<a name="qtluapainter.stringwidth"></a> +##### painter:stringwidth(string) ##### + +Fonction `painter:stringwidth` returns +two numbers representing the total displacement `(dx,dy)` +that would be applied to the [current point](#qtluapainterpoint) +by expression [show(string)](#paintershow). + +See also: PostScript operator `stringwidth`. + + +<a name="painterstroke"></a> +##### painter:stroke(optnewpath) ##### +<a name="qtluapainter.stroke"></a> + +Function `painter:stroke` draws the boundary of the +[current path](#qtluapainterpath) using +the [current pen](#qtluapainterpen). + +The optional boolean `optnewpath` specifies +whether this function resets the current path +using [painter:newpath()](#painternewpath). +The default is to reset the current path. + +See also: PostScript operator `stroke`. + +<a name="paintertranslate"></a> +##### painter:translate(dx,dy) ##### +<a name="qtluapainter.translate"></a> + +Expression `translate(dx,dy)` translates the coordinate +origin by `dx` units along the X axis and `dy` units +along the Y axis. The the size of the coordinate units and +the orientation of the axes are unaffected. + +See also: PostScript operator `translate`. + +<a name="qtluapainter.widget"></a> +##### painter:widget() ##### + +Expression `painter:widget()` returns the Qt object of class +[qt.QWidget](qtgui.md#qwidget) underlying the painter. +When the painter is not associated with a widget, +this expression returns `nil`. + + +<a name="qtluapainter.write"></a> +##### painter:write(f,[format]) ##### + +Expression `painter:write(f)` saves the image +associated with the painter into the file named `f`. +Argument `f` can be a file name or a Lua file descriptor. + +The image data is obtained using +function [painter:image()](#paintergrab). +The image format is determined by the +optional string argument `format` or +deduced from the file name extension. + + + +<a name="qtluaprinter"></a> +### qt.QtLuaPrinter ### + +Printing in Qt is usually achieved using class +[QPrinter](http://doc.trolltech.com/4.4/qprinter.html). +Since this class is neither a subclass of +[QObject](http://doc.trolltech.com/4.4/qobject.html) +nor a value class suitable for storing into a Qt variant, +the QtLua class `QtLuaPrinter` defines a Qt object that +acts as a thin wrapper for class `QPrinter`. + +Most usual +[printer settings](http://doc.trolltech.com/4.4/qprinter.html) +are exposed by class `qt.QtLuaPrinter` as properties. +Property [printer.paperSize](#printerpapersize) +can be used to specify the size of the drawing in pixels. +Printers can be selected using [printer.printerName](#printerprintername) +and PostScript and PDF files can be produced with +properties [printer.outputFileName](#printeroutputfilename) +and [printer.outputFormat](#printeroutputformat). +Alternatively, function `printer:setup()` pops a print dialog +that lets the user adjust these properties interactively. + + +<a name="qtluaprinternew"></a> +#### qt.QtLuaPrinter([mode]) #### +<a name="qtluaprinter"></a> + +Expression `qt.QtLuaPrinter(mode)` returns a +new instance of class `qt.QtLuaPrinter`. + +The optional argument `mode` is a string specifying +the resolution of the initial coordinate system. +The default value `ScreenResolution` replicates the screen resolution. +Value `HighResolution` initializes the coordinate +system with the resolution of the printer. + +Most printer properties should be set before +creating the [qt.QtLuaPainter](#qtluapainter) +that will peform the drawings. + + +<a name="qtluaprinter.abort"></a> +#### printer:abort() #### + +Expression `printer:abort()` aborts the current print run. +Returns `true` if the print run was successfully aborted. +Property [printer.printerState](#printerprinterstate) +will then be `"Aborted"`. +It is not always possible to abort a print job. + +<a name="qtluaprinter.collateCopies"></a> +#### printer.collateCopies #### + +Boolean property `printer.collateCopies` specifies +if collation is turned on when multiple copies is selected. + +<a name="qtluaprinter.colorMode"></a> +#### printer.colorMode #### + +Boolean property `printer.colorMode` is `true` +when one prints in color (the default) and `false` +when one prints in gray scale. + +<a name="qtluaprinter.creator"></a> +#### printer.creator #### + +Property `printer.creator` is a string containing +the name of the application producing the printout. +This information is passed to the print spooling system. + +<a name="qtluaprinter.docName"></a> +#### printer.docName #### + +Property `printer.creator` is a string containing +the name of the document being printed. +This information is passed to the print spooling system + +<a name="qtluaprinter.doubleSidedPrinting"></a> +#### printer.doubleSidedPrinting #### + +Boolean property `printer.doubleSidedPrinting` +indicates whether double sided printing is requested. + +<a name="qtluaprinter.fontEmbeddingEnabled"></a> +#### printer.fontEmbeddingEnabled #### + +Boolean property `printer.fontEmbeddingEnabled` indicates +whether the output data should embed a font description. +This is `true` by default. + + +<a name="qtluaprinter.fromPage"></a> +#### printer.fromPage #### + +Readonly numerical property `printer.fromPage` +contains the index of the first page to print. +Use function [printer:setFromTo](#printersetfromto) to change it. + +<a name="qtluaprinter.fullPage"></a> +#### printer.fullPage #### + +Setting boolean property `printer.fullPage` to `true` +enables support for painting over the entire page. +Otherwise painting is restricted to the printable area +reported by the device. + +<a name="qtluaprinter.landscape"></a> +#### printer.landscape #### + +Setting boolean property `printer.landscape` to `true` +sets the printout in landscape mode. +Otherwise printing happens in portrait mode. + + +<a name="qtluaprinter.newPage"></a> +#### printer:newPage() #### + +Expression `printer:newPage()` +tells the printer to eject the current page and +to continue printing on a new page. +Returns `true` if this was successful. + +<a name="qtluaprinter.numCopies"></a> +#### printer.numCopies #### + +Property `printer.numCopies` contains the number of copies to be printed. +The default value is 1. + +Qt handles the number of copies in a rather strange way: +the value you obtain by reading property `printer.numCopies` is not +the value you have set but reports the number of times you should +draw the document in order to achieve the desired effect. +On Windows, Mac OS X and X11 systems that support CUPS, +reading property `printer.numCopies` always return 1 because these systems +internally handle the number of copies. + +<a name="printeroutputfilename"></a> +#### printer.outputFileName #### +<a name="qtluaprinter.outputFileName"></a> + +Setting property `printer.outputFileName` to a nonempty +string indicates that printing should be redirected +to the specified file. + + +<a name="printeroutputformat"></a> +#### printer.outputFormat #### +<a name="qtluaprinter.outputFormat"></a> + +Property `printer.outputFormat` contains a string describing +the output format for this file or printer. +Recognized values are `"PdfFormat"`, `"PostScriptFormat"`, +and `"NativeFormat"`. + + +<a name="printerpagerect"></a> +#### printer.pageRect #### +<a name="qtluaprinter.pageRect"></a> + +Read-only property `painter.pageRect` contains +a [qt.QRect](qtcore.md#qrect) +describing the coordinates of the printable +area of a page. + +This rectangle is expressed in coordinates +starting from the top-left corner of the page +and with units specified according to +[=printer.resolution](#printerresolution). +This coordinate system is not related the +the drawing coordinate system. + + +<a name="printerpagesize"></a> +#### printer.pageSize #### +<a name="qtluaprinter.pageSize"></a> + +String property `printer.pageSize` contains the name of the paper format. +The recognized names are +`"A4"`, `"B5"`, `"Letter"`, `"Legal"`, `"Executive"`, +`"A0"`, `"A1"`, `"A2"`, `"A3"`, `"A5"`, `"A6"`, +`"A7"`, `"A8"`, `"A9"`, `"B0"`, `"B1"`, +`"B10"`, `"B2"`, `"B3"`, `"B4"`, `"B6"`, +`"B7"`, `"B8"`, `"B9"`, `"C5E"`, `"Comm10E"`, +`"DLE"`, `"Folio"`, `"Ledger"`, and `"Tabloid"`. + +When using Qt-4.4 or greater, +this property can also contain the value `"Custom"` +to indicate that the produced output must +describe an image whose size matches +exactly the specified paper size. +When using an earlier version of Qt, +setting this property to `"Custom"` does nothing. + + +<a name="printerpaperrect"></a> +#### printer.paperRect #### +<a name="qtluaprinter.paperRect"></a> + +Read-only property `painter.paperRect` contains +a [qt.QRect](qtcore.md#qrect) +describing the full size of the paper. + +This rectangle is expressed in coordinates +starting from the top-left corner of the page +and with units specified according to +[printer.resolution](#printerresolution). +This coordinate system is not related the +the drawing coordinate system. + +<a name="printerpapersize"></a> +#### printer.paperSize #### +<a name="qtluaprinter.paperSize"></a> + +Property `printer.paperSize` contains a +[qt.QSizeF](qtcore.md#qsize) +describing the desired size of the drawable area. + +When this property contains a valid size, +that is a size with positive width and height, +the painter initial coordinate system +is adjusted to display the specified drawable area +within the desired page size. + +Furthermore, with Qt-4.4. or greater, +when property [printer.pageSize](#printerpagesize) +is equal to `"Custom"`, property `printer.paperSize` +also specifies the size of the image described +by the output file. + +<a name="printerprinter"></a> +#### printer:printer() #### +<a name="qtluaprinter.printer"></a> + +Returns a pointer to the real `QPrinter` object +which is a subclass of `QPaintDevice`. + + +<a name="qtluaprinter.printProgram"></a> +#### printer.printProgram #### + +Setting string property `printer.printProgram` overrides +the name of the program used to submit the printout +to the spooling system. + + +<a name="printerprintername"></a> +#### printer.printerName #### +<a name="qtluaprinter.printerName"></a> + +String property `printer.printerName` +contains the name of the target printer. +This value is initially set to the name of the +default printer for your system. + + +<a name="printerprinterstate"></a> +#### printer.printerState #### +<a name="qtluaprinter.printerState"></a> + +Readonly string property `printer.printerState` +returs a string describing the state of the printer. +Possible values are `Idle`, `Active`, `Aborted` and `Error`. +That does not work on all systems. + + +<a name="printerresolution"></a> +#### printer.resolution #### +<a name="qtluaprinter.resolution"></a> + +Numerical property `printer.resolution` +contains the resolution of the printer. +This is initially set by the `mode` argument +of the constructor [qt.QtLuaPrinter(mode)](#qtluaprinternew). +The resolution affects the coordinate systems +for properties [printer.paperRect](#printerpaperrect) +and [printer.pageRect](#printerpagerect). +It only affects the drawing coordinate systems +when property [printer.papersize](#printerpapersize) +does not contain a valid size. + + +<a name="printersetfromto"></a> +#### printer:setFromTo(frompage,topage) #### +<a name="qtluaprinter.setFromTo"></a> + +Function `printer:setFromTo` +specifies the indices of the page range to print. +If both `frompage` and `topage` are zero (the default), +the whole document is printed. + +<a name="qtluaprinter.setup"></a> +#### printer:setup([parentwidget]) #### + +Expression `printer:setup()` displays a dialog +allowing the user to choose a printer +and select various print settings. +It returns `true` if the user presses the button "Print" +and `false` if the user cancels. + +<a name="qtluaprinter.toPage"></a> +#### printer.toPage #### + +Readonly numerical property `printer.toPage` +contains the index of the last page to print. +Use function [printer:setFromTo](#printersetfromto) to change it. + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..90d7612 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,15 @@ +site_name: qtlua +theme : simplex +repo_url : https://github.com/torch/qtlua +use_directory_urls : false +markdown_extensions: [extra] +docs_dir : doc +pages: +- [index.md, Home] +- [qt.md, Global Qt System] +- [qtcore.md, Core Interface] +- [qtgui.md, Graphical User Interface] +- [qtuiloader.md, Qt Designer UI Files Loader] +- [qtide.md, Integrated Development Environment] +- [qtsvg.md, SVG Support] +- [qtwidget.md, Widgets and Events] diff --git a/packages/qt/doc/README.md b/packages/qt/doc/README.md deleted file mode 100644 index 5439171..0000000 --- a/packages/qt/doc/README.md +++ /dev/null @@ -1,1381 +0,0 @@ -<a name="qtlua.overview.dok"/> -# QtLua and Qt Package Reference Manual # - -The package `qt` is available when you run the Lua -interpreter using the [qlua](#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](#qlua) relies in fact on -the [QtLua](#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](..:qtcore:index), -[qtgui](..:qtgui:index), and -[qtuiloader](..:qtuiloader:index) -provide bindings for the classes defined -by the corresponding Qt libraries. - -<a name="qlua"/> -# Program qlua # - -Program `qlua` is a compatible replacement for -the standard interpreter program `lua` -with several new capabilities: - - * New packages provides a rich interface with the Qt4 library: [qt](#qt), [qtwidget](..:qtwidget:index), [qttorch](..:qttorch:index), [qtuiloader](..:qtuiloader:index). - - * 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. - -<a name="qlua.usage"/> -## Usage ## - -Program `qlua` accepts the same command line options and arguments as the -stand-alone Lua interpreter [lua](..:LuaManual#LuaStandalone). It also -accepts all the -[Qt command line options](http://doc.trolltech.com/4.4/qapplication.html#QApplication) -as well as a few specific options. - -``` -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()](#qt.doevents) frequently enough. This is not the -normal mode of operation of `qlua` but this can be useful for -debugging purposes. - -<a name="qlua.components"/> -## Components ## - -Program `qlua` is a Qt program composed of three objects working -independently in separate threads. - - * The [console manager](#qt.qconsole) 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](#qt.qengine) runs the Lua code and provides the integration with the Qt environment. - - * The [application manager](#qt.qapp) 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"](#qt.qcall) 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](#qt.qcall) or [qt.xqcall](#qtxqcall). - - -<a name="qt"/> -# 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](#QtLua) -also provides a means to name an arbitrary Qt object and publish it -inside the package `qt`. - -<a name="qt.QVariants"/> -## Qt Variants ## - -Values represented by the Qt class -[QVariant](http://doc.trolltech.com/4.4/qvariant.html) 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](http://doc.trolltech.com/4.4/qmetatype.html) can -be represented by a Qt variant value. - -Whenever a `QVariant` value is made accessible to the Lua -interpreter (see [luaQ_pushqt](#luaqpushqt)), 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: - -<a name="qt.tostring"/> -### 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 `QByteArray`are also transformed into Lua strings. - * Other types are represented using the type name followed by the hexadecimal representation of a pointer to the data. - -<a name="qt.tonumber"/> -### 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. - -<a name="qt.tobool"/> -### 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. - - -<a name="qt.type"/> -### 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) ### -![](anchor:qt.isa) - -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`. - - -<a name="qt.QObjects"/> -## Qt Objects ## - -Critical Qt classes are subclasses of class -[QObject](http://doc.trolltech.com/4.4/qobject.html). 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](http://doc.trolltech.com/4.4/object.html) 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](..:qtcore:index#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`. - -<a name="qt.memorymanagement.dok"/> -### 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()](#qt.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. - - -<a name="qt.properties.dok"/> -### Properties ### - -Qt object properties are automatically available using the Lua -indexation syntax - -Examples: -```lua - 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](#qt.qcall) 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](http://doc.trolltech.com/4.4/qobject.html) are -automatically converted into strings representing the enumerated names -and conversely. Property values with flag types declared using the Qt -macro [Q_DECLARE_FLAGS](http://doc.trolltech.com/4.4/qflags.htm) and -registered using `Q_ENUMS` are automatically converted into Lua -string containing the relevant flag names separated by vertical bars. - - - -<a name="qt.slots.dok"/> -### Slots and Invokable Methods ### - -Public and protected Qt slots can be called using the Lua method -invokation syntax. - -Examples: -```lua - 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. - -```lua - 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](#qt.qcall) 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()](..:qtcore:index#qobjectdeletelater), are -inherited by all Qt object classes. - -<a name="qt.namedchildren.dok"/> -### Named Children ### - -All Qt objects can be given a name represented by property -[objectName](..:qtcore:index#qobjectobjectname). 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`. - - -<a name="qt.signals.dok"/> -### Signals ### - -Lua programs can emit and receive Qt signals. - -<a name="qt.emttingsignals.dok"/> -#### Emitting Signals #### - -Lua programs can emit signals using the function call syntax. -Consider for example the following c++ class: -```c++ -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 - -```lua - 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. - -```lua -myqobject['mysignal(QByteArray,int)'](self,"message",3) -``` - -<a name="qt.receivingsignals.dok"/> -#### Receiving Signals #### - -Qt signals can be connected to Lua functions -using [qt.connect(...)](#qt.connect). - -For instance, the clause - -```lua - 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: - -```lua - 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()](#qt.doevents) is called. - - -<a name="qt.qobjects.dok"/> -## Objects ## - -<a name="qt.qapp"/> -### qt.qApp ### - -Expression `qt.qApp` refers to the application object -which orchestrates the operation of the [qlua](#qlua) program. -This object is the sole instance of class `QLuaApplication`. -A few exposed slots and properties are relevant for Lua programs. - -<a name="qt.qapp.quit"/> -#### qt.qApp:quit() #### - -Function `qt.qApp:quit()` quits the `qlua` application. - -<a name="qt.qapp.restart"/> -#### 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](#qlua) are re-executed. - -<a name="qt.qapp.about"/> -#### qt.qApp:about() #### - -Function `qt.qApp:about()` displays an about box dialog displaying -the contents of the property `qt.qApp.aboutMessage`. - -<a name="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. - -<a name="qt.qapp.readsettings"/> -#### qt.qApp:readSettings(key) #### - -Reads the preference settings associated with string `key`. - -<a name="qt.qapp.writesettings"/> -#### 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`. - -<a name="qt.qapp.runswithoutgraphics"/> -#### qt.qApp:runsWithoutGraphics() #### - -This function returns `true` if the `qlua` interpreter -was launched with the option `-nographics`. - - -<a name="qt.qconsole"/> -### qt.qConsole ### - -Expression `qt.qConsole` refers to the console object -which handles console input and output for the [qlua](#qlua) program. -This object is the sole instance of class `QLuaConsole`. -A few exposed slots, signals and properties are relevant for Lua programs. - -<a name="qt.qconsole.captureoutput"/> -#### 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)`. - -<a name="qt.qconsole.printCapturedOutput"/> -#### 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. - -<a name="qt.qconsole.addToHistory"/> -#### qt.qConsole:addToHistory(string) #### - -Function call `qt.qConsole:addToHistory(string)` adds -`string` to the history of recent console input. -This works only when [qlua](#qlua) is compiled -with command line history support. - -<a name="qt.consoleOutput"/> -#### [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. - -<a name="qt.ttyInput"/> -#### [QLuaConsole signal] ttyInput(QByteArray) #### - -Signal `ttyInput(QByteArray)` is emitted whenever a new -input line has been validated by the user on the console. - -<a name="qt.ttyEndOfFile"/> -#### [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. - -<a name="qt.ttyBreak"/> -#### [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. - - -<a name="qt.qengine"/> -### qt.qEngine ### - -Expression `qt.qEngine` refers to the Lua execution engine. -This object is an instance of class [QtLuaEngine](#qt.QtLuaEngine). -A few exposed slots, signals and properties are relevant for Lua programs. -See the documentation of class [QtLuaEngine](#qt.QtLuaEngine) -in the [QtLua](#QtLua) API section for more information. - -<a name="qt.qengine.lastErrorMessage"/> -#### qt.qEngine.lastErrorMessage #### - -Read-only property `qt.qEngine.lastErrorMessage` contains the -last error message generated by the Lua interpreter. - -<a name="qt.qengine.lastErrorLocation"/> -#### 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"`. - -<a name="qt.qengine.printResults"/> -#### 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. - -<a name="qt.qengine.printErrors"/> -#### 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. - - -<a name="qt.functions.dok"/> -## Functions ## - -<a name="qt.connect"/> -### 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: -```lua -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](#qt.recevingsignals.dok) 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()](#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](..:qtcore:index#qobjectdeletelater) or -[disconnect](#qt.disconnect) connected objects as soon as you do not -need them anymore. - - -<a name="qt.connect"/> -### 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(...)](http://doc.trolltech.com/4.4/qobject.html#connect). - -<a name="qt.disconnect"/> -### 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. - - -<a name="qt.disconnect"/> -### 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(...)](http://doc.trolltech.com/4.4/qobject.html#disconnect). - - -<a name="qt.doevents"/> -### 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. - - -<a name="qt.isa"/> -### 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)](#qt.isa) had been called. -Otherwise it simply returns `nil`. - - -<a name="qt.pause"/> -### 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. - - -<a name="qt.qcall"/> -### 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](..:LuaManual#pcallfarg), 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](#qlua), object [qt.qApp](#qt.qapp) is always -owned by the main thread in charge of the user interaction, and object -[qt.qEngine](#qt.qengine) is always owned by the auxilliary thread in -charge of the evaluation of Lua expressions. - - -<a name="qt.require"/> -### 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`. - - -<a name="qt.type"/> -### 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()](#qt.type) had been called. Otherwise it simply -returns `nil`. - - -<a name="qt.xqcall"/> -### qt.xqcall(qobject, function, ..., errorhandler) ### - -Expression `qt.xqcall(qobject, f, ..., handler)` -is a thread hopping analogous to the standard \ -Lua function [xpcall](..:LuaManual#xpcallferr). - -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. - - -<a name="QtLua"/> -# QtLua API # - -This section describes the QtLua API. Class -[QtLuaEngine](#qt.QtLuaEngine) and [QtLuaLocker](#qt.QtLuaLocker) provides -a Lua interpreter for use in any Qt application with capabilities -comparable to those of the -[QtScript](http://doc.trolltech.com/4.4/qtscript.html) and additional -support for multi-threaded execution. Additional functions with -prefix [luaQ](#luaQ) provide the essential tools for manipulating Qt -data in Lua functions written in C or C++. - - -<a name="qt.QtLuaEngine"/> -## 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](http://doc.trolltech.com/4.4/qtscript.html) 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](#qt.qcall) operation -ensures that the execution of a Lua program happens -in the thread owning the Lua engine object. - -Class [QtLuaLocker](#qt.QtLuaLocker) provides means -to directly access the Lua state -[`lua_State*`](..:LuaManual#luaState) using -the Lua API. - - -<a name="qt.qtluaengine.constructor"/> -### Constructor ### - -`QtLuaEngine::QtLuaEngine(QObject *parent = 0)` - -This is the constructor for class `QtLuaEngine`. Argument -`parent` is the optional parent object. - -<a name="qt.qtluaengine.properties"/> -### 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. - - -<a name="qt.qtluaengine.signals"/> -### 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`. - - -<a name="qt.qtluaengine.execution"/> -### 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](#qt.qcall). 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. - - - -<a name="qt.QtLuaLocker"/> -## Class QtLuaLocker ## - -Class [QtLuaLocker](#qt.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*`](..:LuaManual#luaState) -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](..:LuaManual#luacall) -or [lua_pcall](..:LuaManual#luapcall) and expect -the code to run for an extended period of time. - - -<a name="luaQ"/> -## 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++. - -```c++ - #include "qtluautils.h" - #ifdef __cplusplus - # include "qtluaengine.h" - #endif -``` - -<a name="luaqluaopen_qt"/> -### luaopen_qt ### - -`int luaopen_qt(lua_State *L)` - -Load the `qt` package into the interpreter. -This is the function preloaded into `package.preload['qt']`. - - -<a name="luaqcall"/> -### luaQ_call ### - -`void luaQ_call(lua_State *L, int na, int nr, QObject *obj = 0)` - -Perform a Lua function call like [lua_call](..:LuaManual#luacall) -but ensure that the function is executed in the thread owning object `obj` -using [thread hopping](#qt.qcall). -Unlike function [luaQ_pcall](#luaqpcall), -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); -``` - -<a name="luaqcheckqobject"/> -### luaQ_checkqobject<TYPE> ### - -`TYPE* luaQ_checkqobject<TYPE>(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](#QObjects) of class `TYPE`. -Otherwise it returns a pointer to the object. - -<a name="luaqcheckqvariant"/> -### luaQ_checkqvariant<TYPE> ### - -`TYPE luaQ_checkqvariant<TYPE>(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](#Qt.Qvariants) 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](http://doc.trolltech.com/4.4/qmetatype.html). - -<a name="luaqcomplete"/> -### 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. - -<a name="luaqconnnect"/> -### 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(...)](#qt.connect) - - -<a name="luaqdisconnect"/> -### 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(...)](#qt.disconnect). - -<a name="luaqdoevents"/> -### 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()](#qt.doevents). - -<a name="luaqengine"/> -### luaQ_engine ### - -`QtLuaEngine *luaQ_engine(lua_State *L)` - -Returns a pointer to the current [Lua engine](#qt.QtLuaEngine). - -<a name="luaqgetfield"/> -### luaQ_getfield ### - -`void luaQ_getfield(lua_State *L, int index, const char *name)` - -This function is similar to [lua_getfield](..:LuaManual#luagetfield) -but never propagates errors causes by executing the metatable -`__index` functions. When such an error occurs, this function -simply returns `nil`. - - -<a name="luaqoptqobject"/> -### luaQ_optqobject<TYPE> ### - -`TYPE* luaQ_optqobject<TYPE>(lua_State *L, int index, TYPE *d)` - -Returns the optional [Qt object](#QObjects) 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](#luaqcheckqobject) - -<a name="luaqoptqvariant"/> -### luaQ_optqvariant<TYPE> ### - -`TYPE luaQ_optqvariant<TYPE>(lua_State *L, int index, TYPE d = TYPE())` - -Returns the optional [Qt variant](#Qt.Qvariants) 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](#luaqcheckqvariant) - -<a name="luaqpause"/> -### 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. - - -<a name="luaqpcall"/> -### 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](..:LuaManual#luapcall) 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](#qt.qcall) -operations in the QtLua interface. - - -<a name="luaqprint"/> -### 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. - - -<a name="luaqpushmeta"/> -### 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](http://doc.trolltech.com/4.4/qmetatype.html) -The following expression can be used to push -a metatable for type `TYPE`: -```c++ - luaQ_pushmeta(L, qMetaTypeId<TYPE>()); -``` - -`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](http://doc.trolltech.com/4.4/qmetaobject.html) -`mo`. The following expression can be used to push -a metatable for a Qt object class `TYPE`: - -```c++ - luaQ_pushmeta(L, &TYPE::staticMetaObject); -``` - - - -<a name="luaqpushqt"/> -### 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](#qt.QVariants) `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](#qt.QObjects) `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. - - -<a name="luaqregister"/> -### 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](..:LuaManual#luaLregister). -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](#qt.qcall). - -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. - - -<a name="luaqtoqobject"/> -### luaQ_toqobject ### - -`QObject* luaQ_toqobject(lua_State *L, int i, const QMetaObject *m = 0)` - -Returns a pointer to the [Qt object](#QObjects) -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. - - -<a name="luaqtoqvariant"/> -### 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](#Qt.Qvariants) 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`. - - -<a name="luaqtraceback"/> -### 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. - diff --git a/packages/qtcore/doc/README.md b/packages/qtcore/doc/README.md deleted file mode 100644 index 1915740..0000000 --- a/packages/qtcore/doc/README.md +++ /dev/null @@ -1,436 +0,0 @@ -<a name="qtcore.dok"/> -# QtCore Bindings # - -The package `qtcore` -contains bindings for classes defined by the Qt module -[QtCore](http://doc.trolltech.com/4.4/qtcore.html). - -Besides the capabilites reported below, -all qt variants inherit a set -of [default methods](..:qt:index#qt.QVariants), -and all qt object classes inherit the capabilities from their -superclasses and automatically expose -[properties, slots and signals](..:qt:index#qt.QObjects). - - -<a name="qbytearray"/> -## qt.QByteArray ## - -Class `qt.QByteArray` represents Qt values of type -[QByteArray](http://doc.trolltech.com/4.4/qbytearray.html). -These values are special because lua strings -are automatically converted to QByteArray objects -when such objects are needed. - -<a name="qbytearray"/> -### qt.QByteArray(arg) ### - -Expression `qt.QByteArray(arg)` returns a new byte array object. -Argument `arg` may be a lua string or a table containing -the integer values of the successive bytes. - -<a name="qbytearray.totable"/> -### qbytearray:totable() ### - -Expression `qbytearray:totable()` returns a table -containing the integer values of the bytes represented -by the bytearray. - -<a name="qcoreapplication"/> -## qt.QCoreApplication ## - -The Qt class -[QCoreApplication](http://doc.trolltech.com/4.4/qcoreapplication.html) -provides an event loop for console Qt applications and serves -as a base class for class [QApplication](..:qtgui:index#qapplication). - -<a name="qcoreapplication"/> -### qt.QCoreApplication() ### - -Returns the unique instance of class `QCoreApplication`.make i - - -<a name="qline"/> -## qt.QLine, qt.QLineF ## - -Classes `qt.QLine` and `qt.QLineF` represent common Qt classes. -Please refer to the Qt documentation for classes -[QLine](http://doc.trolltech.com/4.4/qline.html) -and [QLineF](http://doc.trolltech.com/4.4/qlinef.html) -for details. - -<a name="qline"/> -### qt.QLine(table), qt.QLineF(table) ### -<a name="qlineF"/> - -Expression `qt.QLine(table)` or `qt.QLineF(table)` -constructs a new `qt.QLine` or `qt.QLineF` object -representing a segment whose endpoints coordinates -are given by fields `x1`, `y1`, `x2`, and `y2` -of table `table`. - -<a name="qline.totable"/> -### qline:totable() ### - -Expression `qline:totable()` returns a table whose fields -`x1`, `y1`, `x2`, and `y2` contain the coordinates of the -endpoints of the `qt.QLine` or `qt.QLineF` object `qline`. - - -<a name="qobject"/> -## qt.QObject ## - -Qt class -[QObject](http://doc.trolltech.com/4.4/qobject.html). -is the base class of all [Qt objects](..:qt:index#qt.QObjects). -All Qt object classes have separate metatables following the -same inheritance pattern as the corresponding Qt classes. -The metatable [qt.QObject](#qobject) sits at the top -of this hierarchy. - -<a name="qobject.children"/> -### qobject:children() ### - -Expression `qobject:children()` -returns a Qt value of class [qt.QVariantList](#qvariantlist) -containing all the children of object `qobject`. - - -<a name="qobjectdeletelater"/> -### qobject:deleteLater() ### - -Calling `qobject:deleteLater()` is the recommended way to delete -the Qt object `qobject`. The object is not deleted immediately. -The deletion occurs when the object thread is processing -interactive events. - - -<a name="qobjectdumobjectinfo"/> -### qobject:dumpObjectInfo() ### - -Function `qobject:dumpObjectInfo` prints a human readable -description of the object `qobject`. -This function only works when Qt and QtLua are -compiled in debug mode. - - -<a name="qobjectdumobjecttree"/> -### qobject:dumpObjectTree() ### - -Function `qobject:dumpObjectTree` prints a human readable -description of the object hierarchy containing `qobject`. -This function only works when Qt and QtLua are -compiled in debug mode. - - -<a name="qobjectobjectname"/> -### qobject.objectName ### - -Property `qobject.objectName` contains a string -representing the name of a Qt object `qobject`. -Named children of a Qt object can be accessed -by indexing the parent object. - -Consider for instance a variable `a` referring -to a Qt object that contains a child object named `"b"`. -The child object can be accessed using the Lua syntax `a.b`. -In case of name conflicts, property and methods have precedence -over named children. - -<a name="qobjectparent"/> -### qobject:parent() ### - -Expression `qobject:parent()` returns the parent of object `qobject` -if such a parent exists. Otherwise it returns `nil`. - -<a name="qpoint"/> -## qt.QPoint, qt.QPointF ## -<a name="qpointf"/> - -Classes `qt.QPoint` and `qt.QPointF` represent common Qt classes. -Please refer to the Qt documentation for classes -[QPoint](http://doc.trolltech.com/4.4/qpoint.html) -and [QPointF](http://doc.trolltech.com/4.4/qpointf.html) -for details. - -<a name="qpoint"/> -### qt.QPoint(table), qt.QPointF(table) ### -<a name="qpointf"/> - -Expression `qt.QPoint(table)` or `qt.QPointF(table)` -returns a new `qt.QPoint` or `qt.QPointF` object -initialized with the contents of fields `x` and `y` -from table `table`. - -<a name="qpoint.totable"/> -### qpoint:totable() ### - -Expression `qpoint:totable()` returns a table whose fields `x` and `y` -contain the coordinates of the `qt.QPoint` or `qt.QPointF` object `qpoint`. - - -<a name="qrect"/> -## qt.QRect, qt.QRectF ## -<a name="qrectf"/> - -Classes `qt.QRect` and `qt.QRectF` represent common Qt classes. -Please refer to the Qt documentation for classes -[QRect](http://doc.trolltech.com/4.4/qrect.html) -and [QRectF](http://doc.trolltech.com/4.4/qrectf.html) -for details. - -<a name="qrect"/> -### qt.QRect(table), qt.QRectF(table) ### -<a name="qrectf"/> - -Expression `qt.QRect(table)` or `qt.QRectF(table)` -returns a new `qt.QRect` or `qt.QRectF` object -representing a rectangle whose origin is -specified by table fields `x` and `y` -and whose width and height are specified -by the table fields `width` and `height`. - -<a name="qrect.totable"/> -### qrect:totable() ### - -Expression `qrect:totable()` returns a table -whose fields `x` and `y` contain the origin of the rectangle `qrect` -and whose fields `width` and `height` contain the width and -height of the rectangle. - - -<a name="qsize"/> -## qt.QSize, qt.QSizeF ## -<a name="qsizef"/> - -Classes `qt.QSize` and `qt.QSizeF` represent common Qt classes. -Please refer to the Qt documentation for classes -[QSize](http://doc.trolltech.com/4.4/qsize.html) -and [QSizeF](http://doc.trolltech.com/4.4/qsizef.html) -for details. - -Example: -```lua - require 'qtwidget' - widget = qt.QWidget() - widget.size = qt.QSize{width=320,height=200} - widget:show() -``` - -<a name="qsize"/> -### qt.QSize(table), qt.QSizeF(table) ### -<a name="qsizef"/> - -Expression `qt.QSize(table)` or `qt.QSizeF(table)` -returns a new `qt.QSize` or `qt.QSizeF` object -initialized with the contents of fields `width` and `height` -from table `table`. - -<a name="qsize.totable"/> -### qsize:totable() ### - -Expression `qsize:totable()` returns a table whose -fields `width` and `height` are initialized with -the width and height of the size `qsize`. - - -<a name="qstring"/> -## qt.QString ## - -Class `qt.QString` represents Qt values of type -[QString](http://doc.trolltech.com/4.4/qstring.html). -These values are special because lua strings -are automatically converted to string objects -when such objects are needed. - -<a name="qstring"/> -### qt.QString(arg) ### - -Expression `qt.QString(arg)` returns a new string object. -Argument `arg` may be a lua string representing the string -in locale encoding or a table containing the unicode values -for the string characters. - -<a name="qstring.totable"/> -### qstring:totable() ### - -Expression `qurl:totable()` returns a table -containing the integer values of the successive -unicode characters represented by the string. - -<a name="qstringlist"/> -## qt.QStringList ## - -Class `qt.QStringList` represents Qt values of type -[QStringList](http://doc.trolltech.com/4.4/qstringlist.html) -containing a list of Qt strings. - -<a name="qstringlist"/> -### qt.QStringList(table) ### - -Expression `qt.QStringList(table)` creates a new `QStringList` -initialized with the strings contained in -table `table` at positions `1` to `#table`. -When the argument `table` is omitted, -an empty string list is returned. - -Example -```lua - require 'qt' - a = qt.QStringList{"a","b","c"} -``` - -<a name="qstringlist.totable"/> -### qstringlist:totable() ### - -Expression `qstringlist:totable()` returns a Lua table -containing the elements of `qstringlist` starting at position `1`. - -Example -```lua - require 'qt' - a = qt.QStringList{"a","b","c"} - return a:totable()[2] -``` - - -<a name="qtimer"/> -## qt.QTimer ## - -Class `qt.QTimer` is a subclass of [qt.QObject](#qobject) -associated with Qt objects of class `QTimer`. -Please see the Qt documentation for class -[QTimer](http://doc.trolltech.com/4.4/qtimer.html) -for an explanation of the available -slots, signals and properties. - -Example: -```lua -require 'qt' -timer = qt.QTimer() -timer.singleShot = true -qt.connect(timer,'timeout()', function() print("timeout") end) -timer:start(2000) -- wait for 2 seconds... -``` - - -<a name="qtimer"/> -### qt.QTimer(parent) ### - -Expression `qt.QTimer(parent)` returns a -new `QTimer` object created from the current thread. -Argument `parent` optionally specifies its parent. -Note that the parent object must belong to the current thread as well. -When argument `parent` is not specified, -the new timer is owned by the Lua interpreter -and will be deleted by the Lua garbage collector -when it is no longer referenced. - - -<a name="qurl"/> -## qt.QUrl ## - -Class `qt.QStringList` represents Qt values of type -[QUrl](http://doc.trolltech.com/4.4/qurl.html) -containing an URL. - -<a name="qurl"/> -### qt.QUrl(string) ### - -Expression `qt.QUrl(string)` returns a -QUrl object from string `string`. - -<a name="qurl.tostring"/> -### qurl:tostring() ### - -Expression `qurl:tostring()` returns a string -describing the QUrl object `qurl`. - -### qurl.fromlocalfile(s) ### - -Returns a file url associated with the file named s. - -<a name="qurl.tolocalfile"/> -### qurl:tolocalfile() ### - -If the url describes a local file, -expression `qurl:tolocalfile()` returns a string -describing the local filename associated with the url. -Otherwise it returns nil. - - -<a name="qvariantlist"/> -## qt.QVariantList ## - -Class `qt.QVariantList` represents Qt values of type -[QVariantList](http://doc.trolltech.com/4.4/qvariant.html#QVariantList-typedef) -containing a list of values represented by class -[QVariant](http://doc.trolltech.com/4.4/qvariant.html). - -<a name="qvariantlist"/> -### qt.QVariantList(table) ### - -Expression `qt.QVariantList(table)` creates a new `QVariantList` -initialized with the strings contained in -table `table` at positions `1` to `#table`. -When the argument `table` is omitted, -an empty string list is returned. - -Example -```lua - require 'qt' - a = qt.QVariantList{"a",32} -``` - -<a name="qvariantlist.totable"/> -### qvariantlist:totable() ### - -Expression `qvariantlist:totable()` returns a Lua table -containing the elements of `qstringlist` starting at position `1`. - -Example -```lua - require 'qt' - a = qt.QVariantList{"a",2,3,4} - return a:totable()[2] -``` - - -<a name="qvariantmap"/> -## qt.QVariantMap ## - -Class `qt.QVariantList` represents Qt values of type -[QVariantMap](http://doc.trolltech.com/4.4/qvariant.html#QVariantMap-typedef) -containing a dictionary of named values represented by class -[QVariant](http://doc.trolltech.com/4.4/qvariant.html). - - -<a name="qvariantmap"/> -### qt.QVariantMap(table) ### - -Expression `qt.QVariantMap(table)` creates a new `QVariantMap` -initialized with the contents of the table `table`. -When the argument `table` is omitted, -an empty map is returned. - -Example -```lua - require 'qt' - a = qt.QVariantMap{a=23,b=45,c="foo"} -``` - -<a name="qvariantmap.totable"/> -### qvariantmap:totable() ### - -Expression `qvariantmap:totable()` returns a Lua table -containing the contents of the dictonary `qvariantmap`. - -Example -```lua - require 'qt' - a = qt.QVariantMap{a=23,b=45,c="foo"} - t = a:totable() - return t.c -``` - - diff --git a/packages/qtgui/doc/README.md b/packages/qtgui/doc/README.md deleted file mode 100644 index 27feebd..0000000 --- a/packages/qtgui/doc/README.md +++ /dev/null @@ -1,1192 +0,0 @@ -<a name="qtgui.dok"/> -# QtGui Bindings # - -The package `qtgui` -contains bindings for classes defined by the Qt module -[QtGui](http://doc.trolltech.com/4.4/qtcore.html). - -Besides the capabilites reported below, all qt variants inherit a set -of [default methods](..:qt:index#qt.QVariants), and all qt object -classes inherit the capabilities from their superclasses and -automatically expose [[..:qt:index#qt.QObjects|properties, slots and -signals]]. - - -<a name="qaction"/> -## qt.QAction, qt.QtLuaAction ## -<a name="qtluaaction"/> - -Qt class -[QAction](http://doc.trolltech.com/4.4/qaction.html) -is a sublass of [qt.QObject](..:qtcore:index#qt.qobject) -that represents actions associated with menu items -and toolbar icons. - - -<a name="qaction"/> -### qt.QAction([arg]) ### - -Expression `qt.QAction([arg])` returns a new `QAction` object. -The optional argument `arg` can be a qt object that -becomes the action parent or a table whose -members contain initial values for the action properties. -This table can also contain a function value -which is then connected to the signal `triggered(bool)` -of the qt action object. - -Example: -```lua - a === qt.QAction { text="Automatic Mode", - checkable === true, checked === false, - function(b) setAutoMode(b) end } -``` - -Unless a parent is specified, the action is owned -by the Lua interpreter and therefore is automatically -destroyed when the garbage collector determines that -it is no longer referenced. - -Actions are always created from the main thread using -the [thread hopping](..:qt:index#qt.qcall) mechanism. - -<a name="qaction.menu"/> -### qaction:menu() ### - -Same as the C++ function `QAction::menu()`. - -<a name="qaction.setmenu"/> -### qaction:setMenu() ### - - -Same as the C++ function `QAction::setMenu()`. - -<a name="qtluaaction"/> -### qt.QtLuaAction([arg]) ### - -This constructor takes the same arguments as `qt.QAction` -but returns an instance of a convenient subclass -that enables or disables the action according -to the availability of the Lua engine. - -The action follows its property `enabled` -when the Lua engine is ready to invoke Lua -functions connected to Qt signals. -Otherwise the action is disabled regardless -of the value of property `enabled`. - -<a name="qtluaaction.autodisable"/> -### qtluaaction.autoDisable ### - -This property applies only to action objects of class `qt.QtLuaAction`. -It controls whether the action is automatically disabled -when the Lua engine is not available. -The default is `true`. - - -<a name="qapplication"/> -## qt.QApplication ## - -Qt class [QApplication](http://doc.trolltech.com/4.4/qapplication.html) -manages the GUI application's control flow and main settings. This is a -subclass of [QCoreApplication](..:qtcore:index#qcoreapplication). - -<a name="qapplication.changeOverrideCursor"/> -### qt.QApplication.changeOverrideCursor(qcursor) ### - -Changes the currently active application override cursor to cursor -without disturbing the cursor stack. This function has no -effect if `setOverrideCursor()` was not called. - -<a name="qapplication.keyboardModifiers"/> -### qt.QApplication.keyboardModifiers() ### - -Returns a string describing the currently depressed keyboard modifiers. - -<a name="qapplication.mouseButtons"/> -### qt.QApplication.mouseButtons() ### - -Returns a string describing the currently depressed mouse buttons. - -<a name="qapplication.overrideCursor"/> -### qt.QApplication.overrideCursor() ### - -Returns the active application override cursor. -This function returns `nil` if no application cursor -has been defined (i.e. the internal cursor stack is empty). - -<a name="qapplication.restoreOverrideCursor"/> -### qt.QApplication.restoreOverrideCursor() ### - -Undoes the last `setOverrideCursor()`. - -<a name="qapplication.setoverridecursor"/> -### qt.QApplication.setOverrideCursor(qcursor) ### - -Sets the application override cursor to `qcursor`. -Application override cursors are intended for showing the user that -the application is in a special state, for example during an operation that might take some time. -Override cursors are stored on a stack. Function `setOverrideCursor()` pushes a cursor on the stack. -Function `restoreOverrideCursor()` pops the stack. - - -<a name="qbrush"/> -## qt.QBrush ## - -Qt class -[QBrush](http://doc.trolltech.com/4.4/qbrush.html) -represents the painter settings that determine how shape -are filled and how text is rendered. Brushes are represented -by Qt variants of class `qt.QBrush`. - - -<a name="qbrush"/> -### qt.QBrush(table) ### -<a name="qbrushfromtable"/> - -Expression `qt.QBrush(table)` returns a brush whose settings -are determined by the fields of table `table`. -The following fields are recognized: - - * Field `color` contains a [qt.QColor](#qcolor) value representing the brush color. - - * Field `texture` contains a [qt.QImage](#qimage) value representing the brush texture. - - * Field `gradient` contains a [qt.QGradient](#qgradient) value representing a color gradient. - - * Field `transform` contains a `qt.QTransform` value that defines a additional transformation applied to the brush before painting it into the current coordinate system. - - * Field `style` contains the name of the [brush style](http://doc.trolltech.com/4.4/qt.html#BrushStyle-enum). The default brush style is `SolidPatter` when field `color` is defined, `TexturePattern` when field `texture` is defined, or one of the gradient styles when field `gradient` is defined. Otherwise the default style is `NoBrush` meaning that nothing is painted. - - -<a name="qbrush.totable"/> -### qbrush:totable() ### - -Expression `qbrush:totable()` returns a table describing the brush. -See the documentation of [qt.QBrush(table)](#qbrushfromtable) -for a description of the table fields. - - -<a name="qcolor"/> -## qt.QColor ## - -Qt class -[QColor](http://doc.trolltech.com/4.4/qcolor.html) -represents colors for painting purposes. -Qt variant of class `qt.QColor` have a textual representation -of the form =="#RRGGBB" where letters `R`, `G`, or `B` are -hexadecimal digits representing the intensities of the -color components. - - -<a name="qcolor"/> -### qt.QColor(...) ### - -There are several ways to construct a Qt variant of class `qt.QColor`. - -__`qt.QColor(r,g,b,[a])`__ - -Arguments `r`, `g`, `b`, and `a` are numbers in range `[0,1]` -representing the intensities of the red, green, blue, and alpha channels. -The default value for argument `a` is `1` for a fully opaque color. - -__ `qt.QColor(string)` __ - -Argument `string` is a string representing a color name. -All [SVG color names](http://www.w3.org/TR/SVG/types.html#ColorKeywords) -are recognized.Color names can have also the format `"#RGB"`, -`"#RRGGBB"`, `"#RRRGGGBBB"`, or =="#RRRRGGGGBBBB" -where letters `R`, `G`, or `B` represent hexadecimal -digits for each of the color component. - -__ `qt.QColor(table)` __ - -Argument `table` is a table whose fields `r`, `g`, `b` and `a` -contain numbers in range `[0,1]` representing the intensities -of the red, green, blue, and alpha channels. Such a table -is returned by function [qcolor:totable()](#qcolortotable). - -<a name="qcolor.totable"/> -### qcolor:totable() ### -<a name="qcolortotable"/> - -Expression `qcolor:totable()` returns a table whose fields -`r`, `g`, `b` and `a` contain numbers in range `[0,1]` -representing the intensities of the red, green, blue, -and alpha channels. - - -<a name="qcolordialog"/> -## qt.QColorDialog ## - -Qt class -[QColorDialog](http://doc.trolltech.com/4.4/qcolordialog.html) -implements a dialog for selecting colors. -The recommended way to use this class is the static function `getColor`. - -<a name="qcolordialog.getcolor"/> -### qt.QColorDialog.getColor([font],[parent]) ### - -Pops up a dialog for selecting a color. -Optional argument `color` is the initial color selection. -Argument `parent` is the parent widget. -This function returns `nil` if the no color was selected. -Otherwise it returns a qvariant of type [qt.QColor](#qcolor). - -<a name="qcursor"/> -## qt.QCursor ## - -Qt class -[QCursor](http://doc.trolltech.com/4.4/qcursor.html) -provides a mouse cursor with an arbitrary shape. - -<a name="qcursor"/> -### qt.QCursor(cursorshape) ### - -Returns a standard cursor. -Argument `cursorshape` is the name of a -[standard shape](http://doc.trolltech.com/4.4/qt.html#CursorShape-enum). - -<a name="qcursor"/> -### qt.QCursor(image,[mask],[posx,[posy]) ### - -Constructs a cursor with the specified image, mask and hot spot. - -<a name="qcursor.hotSpot"/> -### qcursor:hotSpot() ### - -Return a `qt.QPoint` with the cursor's hot spot coordinates. - -<a name="qcursor.mask"/> -### qcursor:mask() ### - -Return the cursor's mask. - -<a name="qcursor.pixmap"/> -### qcursor:pixmap() ### - -Return the cursor's pixmap. - -<a name="qcursor.shape"/> -### qcursor:shape() ### - -Return the name of the cursor's -[standard shape](http://doc.trolltech.com/4.4/qt.html#CursorShape-enum). - -<a name="qcursor.pos"/> -### qt.QCursor.pos() ### - -Returns a `QPoint` with the global coordinates of the mouse cursor. - -<a name="qcursor.setPos"/> -### qt.QCursor.setPos(qpoint) ### - -Sets the global coordinates of the mouse cursor. - -<a name="qdialog"/> -## qt.QDialog ## - -Qt class -[QDialog](http://doc.trolltech.com/4.4/qdialog.html) -is the base class of dialog windows. - -<a name="qdialog"/> -### qt.QDialog([parent]) ### - -Expression `qt.QDialog(parent)` returns a new `QDialog` instance. -The optional argument `parent` specifies the widget parent. -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - -<a name="qdialog.result"/> -### qdialog:result() ### - -Gets the dialog's result code as an integer. -This is usually `1` when the dialog has been accepted -and `0` when the dialog has been rejected. - -<a name="qdialog.setresult"/> -### qdialog:setResult(integer) ### - -Sets the dialog's result code. -This is usually `1` when the dialog has been accepted -and `0` when the dialog has been rejected. - - -<a name="qfiledialog"/> -## qt.QFileDialog ## - -Qt class -[QFileDialog](http://doc.trolltech.com/4.4/qfiledialog.html) -provides a dialog that allow users to select files or directories. -This is a subclass of [qt.QDialog](#qdialog). - -<a name="qfiledialog.getExistingDirectory"/> -### qt.QFileDialog.getExistingDirectory([p.[c,[d,[opt]]]]) ### - -This convenience function shows a file dialog -for selecting an existing directory. -Argument `p` is the parent widget. -Argument `c` is the dialog caption. -Argument `d` is the initial directory shown in the dialog. -Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). - -The function returns a `qt.QString` containing the selected directory name. - -<a name="qfiledialog.getOpenFileName"/> -### qt.QFileDialog.getOpenFileName([p,[c,[d,[f,[s,[opt]]]]]]) ### - -This convenience function shows a file dialog -for selecting an existing file. - * Argument `p` is the parent widget. - * Argument `c` is the dialog caption. - * Argument `d` is the initial directory shown in the dialog. - * Argument `f` contains the filters separated by double semicolons. - * Argument `s` contains the selected filter - * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). - -The function returns a `qt.QString` containing the selected file name -and a `qt.QString` contaning the selected filter. - -<a name="qfiledialog.getOpenFileNames"/> -### qt.QFileDialog.getOpenFileNames([p,[c,[d,[f,[s,[opt]]]]]]) ### - -This convenience function shows a file dialog -for selecting multiple existing files. - * Argument `p` is the parent widget. - * Argument `c` is the dialog caption. - * Argument `d` is the initial directory shown in the dialog. - * Argument `f` contains the filters separated by double semicolons. - * Argument `s` contains the selected filter - * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). - -The function returns a `qt.QStringList` containing the file names -and a `qt.QString` contaning the selected filter. - -<a name="qfiledialog.getsavefilename"/> -### qt.QFileDialog.getSaveFileName([p,[c,[d,[f,[s,[opt]]]]]]) ### - -This convenience function shows a file dialog -for selecting a file name for saving data. - * Argument `p` is the parent widget. - * Argument `c` is the dialog caption. - * Argument `d` is the initial directory shown in the dialog. - * Argument `f` contains the filters separated by double semicolons. - * Argument `s` contains the selected filter - * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). - -The function returns a `qt.QString` containing the selected file name -and a `qt.QString` contaning the selected filter. - -<a name="qfiledialog.new"/> -### qt.QFileDialog.new([parent.[caption,[dir,[filters]]]]) ### - -Function `qt.QFileDialog.new` returns a new file dialog object. - * Argument `parent` is the parent widget - * Argument `caption` is the dialog caption. - * Argument `dir` is the initial directory shown in the dialog. - * Argument `filters` contains the filters separated by double semicolons. - -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - -<a name="qfiledialog.directory"/> -### qfiledialog:directory() ### - -Returns a `qt.QString` containing the path of the selected directory. - -<a name="qfiledialog.nameFilters"/> -### qfiledialog:nameFilters() ### - -Returns a `qt.QStringList` containing the name filters. - -<a name="qfiledialog.selectedFiles"/> -### qfiledialog:selectedFiles() ### - -Returns a `qt.QStringList` containing the selected files. - -<a name="qfiledialog.selectFile"/> -### qfiledialog:selectFile(fname) ### - -Select file `fname` in the file dialog. - -<a name="qfiledialog.selectNameFilter"/> -### qfiledialog:selectNameFilter(filter) ### - -Select name filter `filter` in the file dialog. - -<a name="qfiledialog.setDirectory"/> -### qfiledialog:setDirectory(dirname) ### - -Set the file dialog directory to `dirname`. - -<a name="qfiledialog.setNameFilters"/> -### qfiledialog:setNameFilters(filters) ### - -Set the file dialog name filters to `filters`. -Argument `filters` may be a `qt.QStringList` -or a string containing the filters separated by -two semicolons `";;"`. - -<a name="qfiledialog.setOption"/> -### qfiledialog:setOption(option, bool) ### - -Sets the specified -[file dialog option](http://doc.trolltech.com/4.5/qfiledialog.html#Option-enum) -to the boolean value `bool`. Not available before Qt-4.5. - -### qfiledialog:testOption(option) ### - -Returns the value of the specified -[file dialog option](http://doc.trolltech.com/4.5/qfiledialog.html#Option-enum). -Not available before Qt-4.5. - -<a name="qfont"/> -## qt.QFont ## - -Qt class -[QFont](http://doc.trolltech.com/4.4/qfont.html) -represents the painter settings that determine the font(s) -used to display text. - - -<a name="qfont"/> -### qt.QFont(arg) ### -<a name="qfontfromtable"/> - -Expression `qt.QFont(arg)` returns a new font object. -Argument `arg` may be a string previously returned -by [qfont:tostring()](#qfonttostring) or -a table whose fields specify the desired font characteristics. -The following fields are recognized, listed in order of priority: - - * String field `family` may contain a comma separated list of the desired font families. - - * Setting boolean field `sans` to `true` indicates a preference for sans serif font families such as "Helvetica". This is more portable than specifying a family. - - * Setting boolean field `serif` to `true` indicates a preference for serif font families such as "Times". This is more portable than specifying a family. - - * Setting boolean field `typewriter` to `true` indicates a preference for a fixed width font families such as "Courier". This is more portable than specifying a family. - - * Numerical field `size` specify the desired size of the font. The default size is 10 points. - - * Numerical fields `pixelSize` and `pointSize` also indicates the desired size of the font. Field `pixelSize` is an alias for `size`. Field `pointSize` includes a correction factor corresponding to the actual resolution of the target device. When both are precised, `pointSize` takes precedence. - - * Numerical field `weight` defines the weight of the font. Weight 50 corresponds to a normal font and weight 75 corresponds to a bold font. - - * Numerical field `stretch` is a percentage applied to the width of all characters. Value 100 corresponds to a normal width. Value 150 increases all width by 50 percent. - - * Setting boolean field `bold` to `true` requests a bold font if the selected font family defines a bold variant. - - * Setting boolean field `italic` to `true` requests and italic font if the selected font family defines an italic or oblique variant. - - * Setting boolean field `fixedPitch` to `true` requests a fixed pitch font if the selected font family defines such a variant (rare). - - * Setting boolean field `underline` to `true` draws a line below all the character at a font-specified position. - - * Setting boolean field `overline` to `true` draws a line above all the character at a font-specified position. - - * Setting boolean field `strikeOut` to `true` draws a line that crosses the character at a font-specified position. - -Example: -```lua - require 'qtwidget' - w=qtwidget.newwindow(300,300) - w:moveto(20,20) - w:setfont(qt.QFont{serif=true,size=12,italic=true}) - w:show("foo") - w:setfont(qt.QFont{serif=true,size=12,italic=true,underline=true}) - w:setcolor("blue") - w:show("bar") -``` - - -<a name="qfont.totable"/> -### qfont:totable() ### - -Expression `qfont:totable()` returns a table -suitable for use with [qt.QFont(table)](#qfontfromtable). -All the supported fields are populated. - -Example: -```lua - require 'qtwidget' - f=qt.QFont{serif=true,size=12,bold=true} - for k,v in pairs(f:totable()) do print(k,v) end -``` - -<a name="qfonttostring"/> -### qfont:tostring() ### -<a name="qfont.tostring"/> - -Expression `qfont:tostring()` returns a string -representation of the font settings that is -suitable for storing in configuration files for instance. -Use [qt.QFont(string)](#qfontfromtable) to -reconstruct the corresponding font object. - -<a name="qfontinfo"/> -### qfont:info() ### -<a name="qfont.info"/> - -Expression `qfont:info()` returns a table describing -the actual font selected by the font matching algorithm -when one uses `qfont` to display text on the screen. -This table can be used as argument to -function [qt.QFont()](#qfontfromtable) -as it uses the same keys. -This is achieved using the Qt class -[QFontInfo](http://doc.trolltech.com/4.4/qfontinfo.html). -Fields `"underline"`, `"overline"`, `"strikeOut"`, and `"stretch"` -are copied verbatim from the `qfont` object. - -<a name="qfontdialog"/> -## qt.QFontDialog ## - -Qt class -[QFontDialog](http://doc.trolltech.com/4.4/qfontdialog.html) -implements a dialog for selecting fonts. -The recommended way to use this class is the static function `getFont`. - -<a name="qfontdialog.getfont"/> -### qt.QFontDialog.getFont([font],[parent, [caption]]) ### - -Pops up a dialog for selecting a font. -All arguments are optional. -Argument `font` is the initial font selection. -Argument `parent` is the parent widget. -Argument `caption` is the dialog window title. -This function returns `nil` if the no font was selected. -Otherwise it returns a qvariant of type [qt.QFont](#qfont). - - -<a name="qgradient"/> -## qt.QGradient ## - -Qt class -[QGradient](http://doc.trolltech.com/4.4/qgradient.html) -represents a color gradient for use in [gradient brushes](#qbrush). -No specific Lua methods have been defined for this Qt variant class. - - -<a name="qicon"/> -## qt.QIcon ## - -Qt class -[QIcon](http://doc.trolltech.com/4.4/qimage.html) -provides scalable icons in different modes and states. - -<a name="qicon"/> -### qt.QIcon([arg]) ### - -Returns a new icon. -Argument `arg` can be a qt value of -type [qt.QImage](#qimage) -or [qt.QPixmap](#qpixmap). -Alternatively, argument `arg` may be a -file name that will be loaded on demand. - - -<a name="qimage"/> -## qt.QImage ## - -Qt class -[QImage](http://doc.trolltech.com/4.4/qimage.html) -represents a device independent off-screen image. -Such images are represented in Lua -as Qt variants of class `qt.QImage`. - -<a name="qimage"/> -### qt.QImage(...) ### - -There are several ways to construct a Qt variant of class `qt.QImage`. - -__ `qt.QImage(w,h,monoflag)` __ - -Returns a new image of width `w` and height `h`. -The image is bitonal when the optional boolean flag `monoflag` -is `true`. Otherwise the image is a 32 bits RGBA image. - -__ `qt.QImage(f,format)` __ - -Returns a new image obtained by reading the image file `f`. -Argument `f` can be a file name or a Lua file descriptor. -The [file format](#qimageformats) is determined -by the optional string `format` or by the file name extension. - - -<a name="qimage.depth"/> -### qimage:depth() ### - -Expression `qimage:depth()` returns the depth of the image `qimage`. -A depth of 1 indicates a bitonal image. -A depth of 24 or 32 indicates a true color image. - -<a name="qimage.rect"/> -### qimage:rect() ### - -Expression `qimage:rect()` returns a Qt variant of class -[qt.QRect](..:qtcore:index#qrect) representing the -boundaries of the image `qimage`. - -<a name="qimage.save"/> -### qimage:save(f,[format]) ### - -Expression `qimage:save(f,format)` saves the image data into file `f`. -Argument `f` can be a file name or a Lua file descriptor. -The [file format](#qimageformats) is determined by the -optional string `format` or by the file name extension. - -<a name="qimage.size"/> -### qimage:size() ### - -Expression `qimage:size()` returns a Qt variant of class -[qt.QSize](..:qtcore:index#qsize) representing the -size of the image `qimage`. - -<a name="qimage.formats"/> -### qt.QImage.formats([string]) ### -<a name="qimageformats"/> - -Function `qt.QImage.formats` describes the -supported formats for reading or saving files. -The optional `string` argument must be a string -starting with letter `"r"` or `"w"` to indicate if -one is interested in the supported formats for reading or -writing image files. When this letter is followed by letter `"f"`, -the function returns a string suitable for selecting name -filters in a file dialog. Otherwise, the function -returns a `qt.QStringList` with the supported formats. - - - -<a name="qkeysequence"/> -## qt.QKeySequence ## - -Qt class -[QKeySequence](http://doc.trolltech.com/4.4/qkeysequence.html) -encapsulates a key sequence as used by shortcuts. - -<a name="qkeysequence"/> -### qt.QKeySequence(string) ### - -Returns a Qt value of class `qt.QKeySequence` -associated with the key combination described in string `string`. -Up to four key codes may be entered by separating -them with commas, e.g. `"Alt+V,Ctrl+Down,A,Shift+Home"`. - -<a name="qkeysequence.tostring"/> -### qkeysequence:tostring() ### - -Returns a string describing the keys in the key sequence. - - -<a name="qmainwindow"/> -## qt.QMainWindow ## - -Qt class -[QMainWindow](http://doc.trolltech.com/4.4/qmainwindow.html) -provides a main application window with menu, statusbar, toolbars -and dockable widgets. This is a subclass of [QWidget](#qwidget). - -<a name="qmainwindow"/> -### qt.QMainWindow([parent]) ### - -Expression `qt.QMainWindow(parent)` returns a new `QMainWindow` instance. -The optional argument `parent` specifies the widget parent. -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - -<a name="qmainwindow.centralWidget"/> -### qmainwindow:centralWidget() ### - -Expression `qmainwindow:centralWidget()` returns the -central widget managed by the main window. - -<a name="qmainwindow.menuBar"/> -### qmainwindow:menuBar() ### - -Returns the main window's menu bar. -This function creates and returns an empty menu bar -if the menu bar does not exist yet. - -<a name="qmainwindow.setcentralwidget"/> -### qmainwindow:setCentralWidget(qwidget) ### - -Sets the widget `qwidget` to be the main window's central widget. -The main window takes ownership of the widget pointer and -deletes it at the appropriate time. - -<a name="qmainwindow.setmenubar"/> -### qmainwindow:setMenuBar(qmenubar) ### - -Sets the menu bar for the main window to `qmenubar`. -The main window takes ownership of the menu bar and -deletes it at the appropriate time. - -<a name="qmainwindow.setstatusbar"/> -### qmainwindow:setStatusBar(qstatusbar) ### - -Sets the status bar for the main window to `qstatusbar`. -The main window takes ownership of the status bar and -deletes it at the appropriate time. - -<a name="qmainwindow.statusBar"/> -### qmainwindow:statusBar() ### - -Returns the main window's status bar. -This function creates and returns an empty status bar -if the status bar does not exist yet. - - -<a name="qmenu"/> -## qt.QMenu ## - -Qt class -[QMenu](http://doc.trolltech.com/4.4/qmenu.html) -provides a menu widget for use in menu bars, -context menus, and other popup menus. -This is a subclass of [qt.QWidget](#qwidget). - -The most flexible way to populate a menu -consists of first creating [qt.QAction](#qaction) -objects for all the menu items. -These objects can then be inserted -into the menu using the method `addAction` defined by -the superclass [QWidget](#qwidget). - -Function `qmenu:addLuaAction` provides a more convenient way -to create menu items bound to specific lua functions. -See [qt.QMenuBar](#qmenubar) for an example. - -<a name="qmenu.addLuaAction"/> -### qmenu:addLuaAction([icon,]text[,keys[,statustip]][,function]) ### - -Creates a new [QtLuaAction](#qaction) owned by the menu -and appends it to the menu as a new menu item. -This function returns the newly created action. - - * Argument `icon` is an optional [qt.QIcon](#qicon) for the action. - * Argument `text` specifies the text for the menu item. - * Argument `keys` can be either a [qt.QKeySequence](#qkeysequence)specifying the menu item shortcut, or a string representing the shortcut key name. - * Argument `statustip` is an optional string that is displayed in the statusbar when the menu item is highlighted. -Finally argument `function` is a Lua function that is -connected to the action signal `triggered(bool)` and -therefore is called when the menu item is selected. - -<a name="qmenu.addMenu"/> -### qmenu:addMenu(newqmenu) ### - -Adds the menu `newqmenu` as a submenu of the menu `qmenu` -and returns the corresponding action object. - -<a name="qmenu.addMenu"/> -### qmenu:addMenu([icon,] text) ### - -Creates a new submenu with the specified `icon` and `text` -and adds it into the menu `qmenu`. This function returns -the new menu as an object of class `qt.QMenu`. - -<a name="qmenu.addSeparator"/> -### qmenu:addSeparator() ### - -Adds a separator into the menu -and returns the corresponding action object. - -<a name="qmenu.clear"/> -### qmenu:clear() ### - -Removes all the menu items. -Actions owned by the menu and not shown -in any other widget are deleted. - -<a name="qmenu.exec"/> -### qmenu:exec([qpoint[, defaultqaction]]) ### - -Pops up the menu `qmenu` at position `qpoint` and returns -the action object corresponding to the selected menu item. -This function returns `nil` if no menu item was selected. -Argument `defaultqaction` specifies which action is located -below the mouse cursor when the menu is first shown. -Argument `qpoint` defaults to `qmenu.pos`. - -Note that actions added with `qmenu:addLuaAction` -are automatically disabled while Lua is running. -Therefore such actions cannot be used with -`qmenu:exec` because they would all be disabled. - -<a name="qmenu.insertMenu"/> -### qmenu:insertMenu(beforeqaction, newqmenu) ### - -Inserts the menu `newqmenu` as a submenu into the menu `qmenu` -and returns the corresponding action object. -The submenu is inserted before action `beforeqaction` -or is appended when `beforeqaction` is null or invalid for this widget. - -<a name="qmenu.insertSeparator"/> -### qmenu:insertSeparator(beforeqaction) ### - -Inserts a new separator before action `beforeqaction` -and returns the corresponding action object. - -<a name="qmenu.menuAction"/> -### qmenu:menuAction() ### - -Returns the action associated with the menu `qmenu`. - -<a name="qmenubar"/> -## qt,QMenuBar ## - -Qt class -[QMenuBar](http://doc.trolltech.com/4.4/qmenu.html) -provides a horizontal menu bar for use in main windows. -This is a subclass of [qt.QWidget](#qwidget). - -Example: -```lua - w === qt.QMainWindow() - w:setCentralWidget(...) -- do something smart here - menubar === w:menuBar() - filemenu === menubar:addMenu("&File") - filemenu:addLuaAction("&Open", "Ctrl+O", function() doOpen(w) end) - filemenu:addLuaAction("&Close", "Ctrl+W", function() w:close() end) - editmenu === menubar:addMenu("&Edit") - editmenu:addLuaAction("&Cu&t", "Ctrl+X", function() doCut(w) end) - editmenu:addLuaAction("&Copy", "Ctrl+C", function() doCopy(w) end) - editmenu:addLuaAction("&Paste", "Ctrl+V", function() doPaste(w) end) - w:show() -``` - -<a name="qmenubar.addMenu"/> -### qmenubar:addMenu(qmenu) ### - -Adds the menu `qmenu` as a menu of the menubar `qmenubar` -and returns the corresponding action object. - -<a name="qmenubar.addMenu"/> -### qmenubar:addMenu([icon,] text) ### - -Creates a new menu with the specified `icon` and `text` -and adds it into the menubar `qmenubar`. This function returns -the new menu as an object of class `qt.QMenu`. - -<a name="qmenubar.clear"/> -### qmenubar:clear() ### - -Removes all the menus and actions from the menu bar. -Actions owned by the menu and not shown -in any other widget are deleted. - -<a name="qmenubar.insertMenu"/> -### qmenubar:insertMenu(beforeqaction, qmenu) ### - -Inserts the menu `qmenu` into the menu bar `qmenubar` -and returns the corresponding action object. -The submenu is inserted before action `beforeqaction` -or is appended when `beforeqaction` is null or invalid for this widget. - -<a name="qmenubar.insertSeparator"/> -### qmenubar:insertSeparator(beforeqaction) ### - -Inserts a new separator before action `beforeqaction` -and returns the corresponding action object. - -<a name="qpainterpath"/> -## qt.QPainterPath ## - -Qt class -[QPainterPath](http://doc.trolltech.com/4.4/qpainterpath.html) -represents mathematical boundaries delimiting -regions that can be painted using [painter:fill](..:qtwidget:index#painterfill) -or delimited using [painter:stroke](..:qtwidget:index#painterstroke). -No specific Lua methods have been defined for this Qt variant class. - - -<a name="qpixmap"/> -## qt.QPixmap ## - -Qt class -[QPixmap](http://doc.trolltech.com/4.4/qpixmap.html) -represents a server-side image containing device-dependent data. -No specific Lua methods have been defined for this Qt variant class. - - -<a name="qpen"/> -## qt.QPen ## - -Qt class -[QPen](http://doc.trolltech.com/4.4/qpen.html) -represents the painter settings that determine how -lines are drawn. - -<a name="qpen"/> -### qt.QPen(table) ### -<a name="qpenfromtable"/> - -Expression `qt.QPen(table)` returns a pen whose settings -are determined by the fields of table `table`. -The following fields are recognized: - - * Field `style` specifies the name of the [pen style](http://doc.trolltech.com/4.4/qt.html#PenStyle-enum). The default style is `SolidLine`. - - * Field `brush` contains a `qt.QBrush` value that defines the appearance of the painted areas. - - * Field `color` contains a `qt.QColor` value for the brush color. Setting this field is equivalent to setting field `brush` with a solid brush of the specified color. Field `brush` has precedence over this field. - - * Numerical field `width` contains the desired line width. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation on the painter. - - * Setting boolean field `cosmetic` to `true` indicates that the pen width has a constant width regardless of the transformation on the painter. - - * Field `style` specifies the name of the [pen style](http://doc.trolltech.com/4.4/qt.html#PenStyle-enum) which determines - - * Field `joinStyle` specifies the name of the [pen join style](http://doc.trolltech.com/4.4/qt.html#PenJoinStyle-enum) which determines how lines meet with different angles. The default join style is `BevelJoin`. - - * Field `capStyle` specifies the name of the [pen cap style](http://doc.trolltech.com/4.4/qt.html#PenCapStyle-enum) which determines how lines end are drawn. The default cap style is `SquareCap`. - - * Numerical field `miterLimit` determines how far a [miter join](http://doc.trolltech.com/4.4/qpen.html#setMiterLimit) can extend from the join point. This is used to reduce artifacts between line joins where the lines are close to parallel. - - -<a name="qpen.totable"/> -### qpen:totable() ### - -Expression `qpen:totable()` returns a table describing the pen. -See the documentation of [qt.QPen(table)](#qpenfromtable) -for a description of the table fields. - - -<a name="qtransform"/> -## qt.QTransform ## - -Qt class -[QTransform](http://doc.trolltech.com/4.4/qtransform.html) -represents a 2D transformation of a coordinate system. -Transformation matrices are represented as Qt variants -of class `qt.QTransform`. - -<a name="qtransform"/> -### qt.QTransform([table[,table]]) ### -<a name="qtransformfromtable"/> - -Expression `qt.QTransform()` constructs an identity transformation matrix. - -Expression `qt.QTransform(table)` constructs a transformation matrix -whose matrix elements are initialized with the fields `m11`, `m12`, `m13`, -`m21`, `m22`, `m23`, `m31`, `m32`, and `m33` of table `table`. - -Expression `qt.QTransform(fquad,tquad)` constructs a transformation matrix -that maps the quad `fquad` to the quad `tquad`. -Both arguments `fquad` and `tquad` are table containing exactly four -[qt.QPointF](..:qtcore:index#qpoint) representing the four corners of the quad. - -<a name="qtransform.totable"/> -### qtransform:totable() ### - -Expression `qtransform:totable()` returns a table suitable -for use with expression [qt.QTransform(table)](#qtransformfromtable). - -<a name="qtransform.scaled"/> -### qtransform:scaled(sx,sy) ### - -Function `qtransform:scaled` returns a new transformation matrix -representing a coordinate system whose axes have been -scaled by coefficient `sx` and `sy`. - -<a name="qtransform.translated"/> -### qtransform:translated(dx,dy) ### - -Function `qtransform:translated` returns a new transformation matrix -representing a coordinate system whose origin has been -translated by `dx` units along the X axis and `dy` units along the Y axis. - - -<a name="qtransform.sheared"/> -### qtransform:sheared(cx,cy) ### - -Function `qtransform:sheared` returns a new transformation matrix -representing a coordinate system that has been sheared using coefficients -`cx` horizontally and `cy` vertically. - - -<a name="qtransform.rotated"/> -### qtransform:rotated(angle,[axis,[unit]]) ### - -Function `qtransform:rotated` returns a new transformation matrix -representing a coordinate system rotated by `angle` units around the origin. -The optional string argument `axis` may be `XAxis`, `YAxis`, or `ZAxis` and -defaults to `ZAxis`. The optional string argument `unit` may -be `Degrees` or `Radians` -and default to `Degrees`. - -<a name="qtransform.inverted"/> -### qtransform:inverted() ### - -Function `qtransform:inverted` returns -the inverse transform of its argument -or `nil` when it is not invertible. - -<a name="qtransform.map"/> -### qtransform:map(...) ### - -Function `qtransform:map` applies -a transformation to its argument and returns -a new qvariant of the same type. -The argument can be a `QPoint`, `QPointF`, `QLine`, `QLineF`, -`QPolygon`, `QPolygonF`, `QRegion`, `QPainterPath`, -`QRect`, or `QRectF`. When the argument is a rectangle, -the function returns the bounding rectangle of the polygon -representing the transformed rectangle. -This function also take as argument to reals representing -the coordinates of a point and return two reals -representing the transformed coordinates. - -<a name="qwidget"/> -## qt.QWidget ## - -Qt class -[QWidget](http://doc.trolltech.com/4.4/qwidget.html) -is the base class of all graphical interface components. -All widgets inherit class `qt.QWidget` and -its superclass [qt.QObject](..:qtcore:index#qobject). - -<a name="qwidget"/> -### qt.QWidget([parent]) ### - -Expression `qt.QWidget(parent)` returns a new widget. -The optional argument `parent` specifies the widget parent. -New widgets are always created from the main thread using -the [thread hopping](..:qt:index#qt.qcall) mechanism. - -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - - -<a name="qwidget.actions"/> -### qwidget:actions() ### - -Expression `qwidget:actions()` returns a -qt value of class [qt.QVariantList](..:qtcore:index#qvariantlist) -containing list of actions associated with this widget. - -<a name="qwidget.addAction"/> -### qwidget:addAction(qaction) ### - -Appends action `qaction` to the -list of actions associated with this widget. - -Example: creating a context menu -```lua - action1 === qt.QtLuaAction{text="Checkme", checkable=true, - function(b) print("checked:", b) end} - action2 === qt.QtLuaAction{text="Pickme", - function() print("picked") end} - w:addAction(action1) - w:addAction(action2) - w.contextMenuPolicy='ActionsContextMenu' -``` - -<a name="qwidget.insertAction"/> -### qwidget:insertAction(beforeqaction, qaction) ### - -Insert action ==qaction== into the -list actions associated with this widget. -Argument ==beforeqaction== indicates at which position -to insert the action. If ==beforeqaction== is omitted -or invalid, the action is simply appended. - -<a name="qwidget.mapToGlobal"/> -### qwidget:mapToGlobal(qpoint) ### - -Translates the widget coordinates `qpoint` to global screen coordinates. -Both argument `qpoint` and the return value are Qt value of class -[qt.QPoint](..:qtcore:index#qpoint). - -<a name="qwidget.mapFromGlobal"/> -### qwidget:mapFromGlobal(qpoint) ### - -Translates the global screen coordinates `qpoint` to widget coordinates. -Both argument `qpoint` and the return value are Qt value of class -[qt.QPoint](..:qtcore:index#qpoint). - - -<a name="qwidget.removeAction"/> -### qwidget:removeAction(qaction) ### - -Removes action `qaction` from the -list actions associated with this widget. - - -<a name="qwidget.render"/> -### qwidget:render([pointer]) ### - -When called without argument, -this function draws the widget into an image -and returns the image. - -The optional argument `pointer` can be a -pointer to a `QPainter` or a `QPaintDevice` -where the widget should be rendered. -Such pointers can be obtained using functions -[painter:painter](..:qtwidget:index#painterpainter) or -[painter:device](..:qtwidget:index#painterdevice). -When such an argument is specified, -nothing is returned. - -<a name="qwidget.setAttribute"/> -### qwidget:setAttribute(widgetattribute,[value]) ### - -Sets the specified -[widget attribute](http://doc.trolltech.com/4.4/qt.html#WidgetAttribute-enum) -to boolean value `value`. -Some of these flags are used internally by Qt. -Care is required. - -<a name="qwidget.setWindowFlag"/> -### qwidget:setWindowFlag(windowflag,[value]) ### - -Sets the specified -[window flag](http://doc.trolltech.com/4.4/qt.html#WindowType-enum) -to boolean value `value`. -Flags indicating a window type -are handled as exclusive flags. -Setting these flags usually hides the window. -You need to do call `qwidget:show` again. - -<a name="qwidget.testAttribute"/> -### qwidget:testAttribute(widgetattribute) ### - -Returns a boolean indicating the value of the specified -[widget attribute](http://doc.trolltech.com/4.4/qt.html#WidgetAttribute-enum). -Flags indicating a window type -are handled as exclusive flags. - -<a name="qwidget.testWindowFlag"/> -### qwidget:testWindowFlag(windowflag) ### - -Returns a boolean indicating the value of the specified -[window flag](http://doc.trolltech.com/4.4/qt.html#WindowType-enum). -Flags indicating a window type -are handled as exclusive flags. - -<a name="qwidget.window"/> -### qwidget:window() ### - -Expression `qwidget:window()` returns the window for widget `qwidget`, -that is the next ancestor that is (or could be) displayed -with a window frame. - -For instance the following code changes the -title of the window containing widget `qwidget`. -```lua - qwidget:window().windowTitle "New Title" -``` - - - - diff --git a/packages/qtide/doc/README.md b/packages/qtide/doc/README.md deleted file mode 100644 index cb97755..0000000 --- a/packages/qtide/doc/README.md +++ /dev/null @@ -1,411 +0,0 @@ -<a name="qtide.dok"/> -# QtIde Package Reference Manual # - -A package implementing -the QLua Integrated Development Environment (IDE), -including the text editor, the object inspector, -the help browser, and the lua graphical console. - -This package is not complete because -it is under heavy development. - - -<a name="qtide.functions."/> -## Functions ## -<a name="qtidefunctions"/> - -<a name="qtide.editor"/> -### qtide.editor([filename]) ### - -Called without argument, this function returns a -text editor object of class [QLuaEditor](#qluaeditor). -Otherwise it returns an editor for the file `filename`, -possibly creating a new editor window. -It pops a message box and returns `nil` if the -file `filename` does not exist or cannot be loaded. - -Open editors have object names of the form `editor`_n_ -and are accessible by name in the `qt` package. - - -<a name="qtide.doeditor"/> -### qtide.doeditor(qluaeditor) ### - -This function executes the chunk of Lua code -corresponding to the text present in the editor `qluaeditor`. -This is the function called by the IDE when one selects -the menu entry "_Load Lua File_" from an editor -whose contents is not associated with a file -or has been modified (otherwise one can use the standard -Lua function `dofile`.) - - -<a name="qtide.browser"/> -### qtide.browser([url]) ### - -This function opens a web browser for URL `url`. -The web browser is a widget of class [QLuaBrowser](#qluabrowser). -This is the function called by the IDE when one -requests the help index. - - -<a name="qtide.inspector"/> -### qtide.inspector(...) ### - -Not yet implemented - - -<a name="qtide.preferences"/> -### qtide.preferences() ### - -Not yet implemented - - -<a name="qtide.start"/> -### qtide.start([style]) ### -<a name="qtidestart"/> - -Starts the QLua Integrated Development Environment (IDE) -and ensure that the main window is visible. -This function is called implicitely when program `qlua` -is executed with option `-ide`. - -The optional argument `style` is a string -specifying the default IDE style. -When this argument is not specified -the last used style is assumed. -The recognized IDE styles are: - - * `"sdi"` for an IDE with multiple main windows, - * `"mdi"` for an IDE with subwindows in the style of Windows, - * `"tab"` groups all editors into a single tabbed window. - * `"tab2"` groups all editors and the console into a single tabbed window. - - -<a name="qtide.setup"/> -### qtide.setup([style]) ### -<a name="qtidesetup"/> - -This function is called by [qtide.start()](#qtidestart) -to setup the IDE style. You can call it directly if you -want to organize QLua editors and windows without creating -a graphic console. - - -<a name="qtclasses"/> -## Qt Classes ## - -<a name="qluaide"/> -### qt.QLuaIde ### - -Object `qt.qLuaIde` represetns the global state of the IDE. -This is the unique instance of class `qt.QLuaIde` -which inherits [qt.QObject](..:qt:index#qobject). -Most of its capabilities are conveniently -accessible using the functions defined -by the [package ''qtide](#qtidefunctions). - -<a name="qluaide.editOnError"/> -#### qt.qLuaIde.editOnError #### - -When a Lua error occurs, this boolean property -specifies whether editors are automatically opened -on the location of the error. -This property is `false` by default -Function [qtide.start](#qtidestart) sets it to `true`. - -<a name="qluaide.windows"/> -#### qt.qLuaIde:windows() #### - -Returns a variant of type `qt.QObjectList` containing -all the main windows managed by the IDE. - -<a name="qluaide.windowNames"/> -#### qt.qLuaIde:windowNames() #### - -Returns a variant of type `qt.QStringList` containing -the names of all the main windows managed by the IDE. - -<a name="qluaide.activeWindow"/> -#### qt.qLuaIde:activeWindow() #### - -<a name="qluaide.editor"/> -#### qt.qLuaIde:editor([fname]) #### - -<a name="qluaide.browser"/> -#### qt.qLuaIde:browser([url]) #### - -<a name="qluaide.inspector"/> -#### qt.qLuaIde:inspector() #### - -<a name="qluaide.recentFiles"/> -#### qt.qLuaIde:recentFiles() #### - -Returns a variant of type `qt.QStringList` containing -the file names appearing in the "Open Recent Files" menu. - -<a name="qluaide.addRecentFile"/> -#### qt.qLuaIde:addRecentFile(fname) #### - -<a name="qluaide.clearRecentFiles"/> -#### qt.qLuaIde:clearRecentFiles() #### - -<a name="qluaide.activateWidget"/> -#### qt.qLuaIde:activateWidget(qwidget) #### - -<a name="qluaide.activateConsole"/> -#### qt.qLuaIde:activateConsole() #### - -<a name="qluaide.messageBox"/> -#### qt.qLuaIde:messageBox(title,message,buttons,[defbutton,[icon]]) #### - -<a name="qluaide.hasAction"/> -#### qt.qLuaIde:hasAction(name) #### - -<a name="qluaide.stdAction"/> -#### qt.qLuaIde:stdAction(name) #### - -<a name="qluaide.prefsRequested"/> -#### [qt.QLuaIde signal] prefsRequested(qwidget) #### - -This signal is emitted when the "Preferences" menu is selected. - -<a name="qluaide.helpRequested"/> -#### [qt.QLuaIde signal] helpRequested(qwidget) #### - -This signal is emitted when the "Help Index" menu is selected. - - - -<a name="qluamainwindow"/> -### qt.QLuaMainWindow ### - -This subclass of `QMainWindow` implements common -functionalities shared by all main windows defined -by the `qtide` package. - -<a name="qluamainwindow.clearStatusMessage"/> -#### qluamainwindow:clearStatusMessage() #### - -<a name="qluamainwindow.showStatusMessage"/> -#### qluamainwindow:showStatusMessage(string,[timeout]) #### - -<a name="qluamainwindow.hasAction"/> -#### qluamainwindow:hasAction(name) #### - -<a name="qluamainwindow.stdAction"/> -#### qluamainwindow:stdAction(name) #### - -<a name="qluamainwindow.doXXXX"/> -#### qluamainwindow:doXXXX() #### - -Methods whose name start with `do` implement -the functions accessible from the menus and toolbar icons -in various subclasses of `qt.QLuaMainWindow`. - - -<a name="qluaeditor"/> -### qt.QLuaEditor ### - -This subclass of [qt.QLuaMainWindow](#qluamainwindow) -implements the QLua editor windows using -an instance of [qt.QLuaTextEdit](#qluatextedit) -as its main widget. - -<a name="qluaeditor.widget"/> -#### qluaeditor:widget() #### - -Expression `qluaeditor:widget()` returns the -[qt.QLuaTextEdit](#qluatextedit) -object that underlies the editor window. - -<a name="qluaeditor.fileName"/> -#### qluaeditor.fileName #### - -This property contains the name of the file being edited. - -<a name="qluaeditor.readFile"/> -#### qluaeditor:readFile(string) #### - -<a name="qluaeditor.writeFile"/> -#### qluaeditor:writeFile(string) #### - - -<a name="qluabrowser"/> -### qt.QLuaBrowser ### - -This subclass of [qt.QLuaMainWindow](#qluamainwindow) -implements the QLua web browser windows using the Qt WebKit interface. - - -<a name="qluabrowser.url"/> -#### qluabrowser.url #### - -This property contains a qt variant -of type [qt.QUrl](..:qt:index#qurl) -representing the URL displayed by the browser. - -<a name="qluabrowser.html"/> -#### qluabrowser.html #### - -This property contains a qt variant of type `QString` -representing the HTML text displayed by the browser. - - - - -<a name="qluasdimain"/> -### qt.QLuaSdiMain ### - -This subclass of [qt.QLuaMainWindow](#qluamainwindow) -implements the QLua console window. -Expression `qt.qLuaSdiMain` returns the single console -window when such a window exists. - -<a name="qluasdimain.consoleWidget"/> -#### qt.qLuaSdiMain:consoleWidget() #### - -Returns the object of class -[qt.QLuaTextEdit](#qluaconsolewidget) -implementing the part of the main console -where the user can edit and submit lua strings. - -<a name="qluasdimain.editorWidget"/> -#### qt.qLuaSdiMain:editorWidget() #### - -Returns the object of class -[qt.QLuaTextEdit](#qluatextedit) -implementing the part of the main console -where the Lua output is shown. - - -<a name="qluamdimain"/> -### qt.QLuaMdiMain ### - -This subclass of [qt.QLuaMainWindow](#qluamainwindow) -aggregates selected windows into a single main window -to implement the IDE styles. Expression `qt.qLuaMdiMain` -returns the single main window when such a window exists. - -<a name="qluamdimain.tabMode"/> -#### qt.qLuaMdiMain.tabMode #### - -The boolean property `qt.qLuaMdiMain.tabMode` -indicates whether the aggregated -windows are displayed using tabs or using a multiple document interface. - -<a name="qluamdimain.clientClass"/> -#### qt.qLuaMdiMain.clientClass #### - -The string property `qt.qLuaMdiMain.clientClass` -contains the name of a class. -All new main windows inheriting this class are then -managed by the single main window. - -<a name="qluamdimain.adoptAll"/> -#### qt.qLuaMdiMain:adoptAll() #### - -Collects all main windows that are -subclasses of `qt.qLuaMdiMain.clientClass` -and aggregates them into the mdi main window. - -<a name="qluamdimain.adopt"/> -#### qt.qLuaMdiMain:adopt(qwidget) #### - -<a name="qluamdimain.activate"/> -#### qt.qLuaMdiMain:activate(qwidget) #### - -<a name="qluatextedit"/> -### qt.QLuaTextEdit ### - -Class `QLuaTextEdit` is a text editor widget derived -from `QPlainTextEdit` with support for line numbers, -find dialog, replace dialog, and printing. - -<a name="qluatextedit.showLineNumbers"/> -#### qluatextedit.showLineNumbers #### - -<a name="qluatextedit.autoComplete"/> -#### qluatextedit.autoComplete #### - -<a name="qluatextedit.autoIndent"/> -#### qluatextedit.autoIndent #### - -<a name="qluatextedit.autoHighlight"/> -#### qluatextedit.autoHighlight #### - -<a name="qluatextedit.autoMatch"/> -#### qluatextedit.autoMatch #### - -<a name="qluatextedit.tabExpand"/> -#### qluatextedit.tabExpand #### - -<a name="qluatextedit.tabSize"/> -#### qluatextedit.tabSize #### - -<a name="qluatextedit.setEditorMode"/> -#### qluatextedit:setEditorMode(suffix) #### - -<a name="qluatextedit.readFile"/> -#### qluatextedit:readFile(fname) #### - -<a name="qluatextedit.writeFile"/> -#### qluatextedit:writeFile(fname) #### - -<a name="qluatextedit.showLine"/> -#### qluatextedit:showLine(lineno) #### - -<a name="qluaconsolewidget"/> -### qt.QLuaConsoleWidget ### - -Class `QLuaConsoleWidget` is a subclass of -[qt.QLuaTextEdit](#qluatextedit) -that captures and display the lua output. - -<a name="qluaconsolewidget.printTimings"/> -#### qluaconsolewidget.printTimings #### - -Boolean property that indicates whether the console -displays the running time of each command. - -<a name="qluaconsolewidget.addOutput"/> -#### qluaconsolewidget:addOutput(text,[format]) #### - -Adds `text` to the console window. -Argument `format` is a string specifying the text format. -Possible values are `"default"`, `"quote"`, and `"comment"`. - -<a name="qluaconsolewidget.moveToEnd"/> -#### qluaconsolewidget:moveToEnd() #### - -Shows the bottom of the text displayed in the console window. - - - -<a name="qtobjects"/> -## Qt Objects ## - -<a name="qtqluaide"/> -### qt.qLuaIde ### - -Expression `qt.qLuaIde` refers to the unique instance -of class [qt.QLuaIde](#qluaide). -This instance is created when package `qtide` is loaded. - - -<a name="qtqluasdimain"/> -### qt.qLuaSdiMain ### - -Expression `qt.qLuaSdiMain` refers to the unique instance of -class [qt.QLuaSdiMain](#qluasdimain), -created by function [qtide.start()](#qtidestart). - - -<a name="qtqluamdimain"/> -### qt.qLuaMdiMain ### - -Expression `qt.qLuaMdiMain` refers to the unique instance of -class [qt.QLuaMdiMain](#qluamdimain) created -by function [qtide.setup()](#qtidesetup). -There is no such object when the IDE runs in SDI mode. - diff --git a/packages/qtsvg/doc/README.md b/packages/qtsvg/doc/README.md deleted file mode 100644 index 2d0cfc7..0000000 --- a/packages/qtsvg/doc/README.md +++ /dev/null @@ -1,169 +0,0 @@ -<a name="qtsvg.dok"/> -# QtSvg Bindings # - -The package `qtsvg` -contains bindings for classes defined by the Qt module -[QtSvg](http://doc.trolltech.com/4.4/qtsvg.html). - -Besides the capabilites reported below, -all qt variants inherit a set -of [default methods](..:qt:index#QVariants), -and all qt object classes inherit the capabilities from their -superclasses and automatically expose -[properties, slots and signals](..:qt:index#QObjects). - -You can also use the function -[qtwidget.newpdf](..:qtwidget:index#qtwidgetnewpdf), -defined in module `qtwidget`, -to easily generate SVG files. - - -<a name="qtsvg_loadsvg"/> -### qtsvg.loadsvg(filename) ### -<a name="qtsvg.loadsvg"/> - -Returns a Qt object of -class [qt.QSvgRenderer](#qsvgrenderer) -representing the SVG file `filename`. - - -<a name="qtsvg_paintsvg"/> -### qtsvg.paintsvg(port,svg,...) ### -<a name="qtsvg.paintsvg"/> - -Draws a SVG image. - -Argument `port` must be a -[qt.QtLuaPainter](..:qtwidget:index#qtluapainter) or a -[qtwidget'' high level port descriptor](..:qtwidget:index#highlevel). -Argument `svg` can be the SVG filename or -an instance of class [qt.QSvgRenderer](#qsvgrenderer) -such as those returned by function [qtsvg.loadsvg](#qtsvg_loadsvg). -The remaining arguments are the same -as those for the C++ function `QSvgRenderer::render`. - - -<a name="qsvgwidget"/> -### qt.QSvgWidget ### - -Class -[QSvgWidget](http://doc.trolltech.com/4.4/qsvgwidget.html) -provides a widget that is used to display the contents -of Scalable Vector Graphics (SVG) files. - -<a name="qsvgwidget"/> -#### qt.QSvgWidget([filename],[parent]) #### - -Expression `qt.QSvgWidget(parent)` returns a -new widget for rendering SVG data. - -The optional argument `filename` specifies the name -of a file containing the SVG data. Without this argument, -you must use slot `qsvgwidget:load()` to load SVG data. - -The optional argument `parent` specifies the widget parent. -New widgets are always created from the main thread using -the [thread hopping](..:qt:index#qtqcall) mechanism. -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - -<a name="qsvgwidget.renderer"/> -#### qsvgwidget:renderer() #### - -Returns the [qt.QSvgRenderer](#qsvgrenderer) object -associated with this widget. - - -<a name="qsvgrenderer"/> -### qt.QSvgRenderer ### - -Class -[QSvgRenderer](http://doc.trolltech.com/4.4/qsvgrenderer.html) -is used to draw the contents of SVG files onto paint devices. -You should use instead function -[qtsvg.paintsvg](#qtsvg_paintsvg) -to easily display SVG data. - -<a name="qsvgrenderer"/> -#### qt.QSvgRenderer([filename],[parent]) #### - -Creates a new instance of class `QSvgRenderer`. - -The optional argument `filename` specifies the name -of a file containing the SVG data. Without this argument, -you must use slot `qsvgwidget:load()` to load SVG data. - -The optional argument `parent` specifies the widget parent. -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - - -<a name="qtluasvggenerator"/> -### qt.QtLuaSvgGenerator ### - -This is a thin wrapper around the Qt class -[QSvgGenerator](http://doc.trolltech.com/4.4/qsvggenerator.html). - -You should use instead function -[qtwidget.newpdf](..:qtwidget:index#qtwidgetnewpdf) -to easily generate SVG files. - -<a name="qtluasvggenerator"/> -#### qt.QtLuaSvgGenerator([filename],[parent]) #### - -Creates a new instance of class `QtLuaSvgGenerator`. - -When argument `filename` is present, the SVG data is written -into the specified file. Otherwise it is written into a memory -buffer accessible using the method -[qsvggenerator:data()](#qtluasvggeneratordata). - -The optional argument `parent` specifies the widget parent. -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - -<a name="qtluasvggeneratordata"/> -#### qtluasvggenerator:data() #### -<a name="qtluasvggenerator.data"/> - -Assuming the `qtluasvggenerator` was created without the `filename` argument, -this function returns a [qt.QByteArray](..:qtcore:index#qbytearray) -containing the generated SVG data. This data may be incomplete -until [painter:close()](..:qtwidget:index#painterclose) has -been closed on all painters operating on `qtluasvggenerator`. - -<a name="qtluasvggenerator.description"/> -#### qtluasvggenerator.description #### - -Starting with Qt-4.5, this string property defines -the contents of the `<desc>` tag of the SVG file. - -<a name="qtluasvggenerator.title"/> -#### qtluasvggenerator.title #### - -Starting with Qt-4.5, this string property defines -the contents of the `<title>` tag of the SVG file. - -<a name="qtluasvggenerator.size"/> -#### qtluasvggenerator.size #### - -This property contains a [qt.QSize](..:qtcore:index#qsize) -variant containing the size of the drawable area. -This information is shown in the `viewBox` attribute of the `<svg>` tag. - -<a name="qtluasvggenerator.resolution"/> -#### qtluasvggenerator.resolution #### - -This integer property defines the resolution, in dots per inch, -of the coordinate system. -Together with `qtluasvggenerator.size`, this property determines -the contents of the `width` and `height` attributes of the `<svg>` tag. - - - diff --git a/packages/qtuiloader/doc/README.md b/packages/qtuiloader/doc/README.md deleted file mode 100644 index f25432b..0000000 --- a/packages/qtuiloader/doc/README.md +++ /dev/null @@ -1,103 +0,0 @@ -<a name="qtuiloader.dok"/> -# QtUiLoader Package Reference Manual # - -Package `qtuiloader` provides -functions for dynamically creating widgets -from the user interface files created by program -[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html). -This is achieved by providing bindings for the Qt class -[QUiLoader](http://doc.trolltech.com/4.4/quiloader.html). - - - -Directory `${`_TorchInstallDir=}/share/lua/5.1/qtuiloader= -contains a small demonstration of this package. -Use program -[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html) -to examine file `test.ui`. -Then load file `test.lua` into the -[qlua](..:qt:index#qlua) program. - -``` - $ cd /usr/local/share/lua/5.1/qtuiloader - $ /usr/local/bin/qlua - Lua 5.1 Copyright (C) 1994-2008 Lua.org, PUC-Rio - > dofile('test.lua') -``` - - -<a name="qtuiloader.functions"/> -## Functions ## - -Package `qtuiloader` provides a few convenience functions. -Function [qtuiloader.loader](#qtuiloaderloader) returns a -preallocated instance of class [qt.QUiLoader](#quiloader). -Function [qtuiloader.load](#qtuiloaderload) uses -this preallocated loader to construct a widget using a -[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html) -user interface description. - - -<a name="qtuiloaderavailablewidgets"/> -### qtuiloader.availableWidgets() ### -<a name="qtuiloader.availablewidgets"/> - -Expression `qtuiloader.availableWidgets()` returns a -[qt.QStringList](..:qtcore:index#qstringlist) -containing the names of the supported widget classes. - - -<a name="qtuiloader.createWidget"/> -### qtuiloader.createWidget(classname,[parent,[objectname]]) ### - -Creates a [widget](..:qtgui:index#qwidget) of class `classname`. -Argument `classname` can be any of the strings returned -by [`qtuiloader.availableWidgets()`](#qtuiloaderavailablewidgets). -The optional argument `parent` specifies the parent widget -and the optional argument `name` specifies the -[object name](..:qtcore:index#qobjectobjectname). - -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - - - -<a name="qtuiloaderload"/> -### qtuiloader.load(filename,[parent]) ### -<a name="qtuiloader.load"/> - -Expression `qtuiloader.load(filename,parent)` dynamically -constructs and returns the widget described by the -[Qt Designer](http://doc.trolltech.com/4.4/designer-manual.html) -file `filename`. - -When argument `parent` is `nil` or not specified, -the new widget is owned by the Lua interpreter -and is automatically destroyed when the garbage collector -determines that it is no longer referenced. - - -<a name="qtuiloaderloader"/> -### qtuiloader.loader() ### -<a name="qtuiloader.loader"/> - -Expression `qtuiloader.loader()` -returns a preallocated instance -of class [qt.QUiLoader](#quiloader). - - -<a name="qtuiloader.classes"/> -## Classes ## - -<a name="quiloader"/> -### qt.QUiLoader ### - -Class `qt.QUiLoader` provides bindings -for all the functions of the Qt class -[QUiLoader](http://doc.trolltech.com/4.4/quiloader.html). - -To be documented further... - - diff --git a/packages/qtwidget/doc/README.md b/packages/qtwidget/doc/README.md deleted file mode 100644 index d0231f3..0000000 --- a/packages/qtwidget/doc/README.md +++ /dev/null @@ -1,2177 +0,0 @@ -<a name="qtwidget.dok"/> -# QtWidget Package Reference Manual # - -Package `qtwidget` provides convenient way -to make drawings and capture user events. -In particular, class [QtLuaPainter](#qtluapainter) gives -the ability draw simple graphics using well known -postscript-like operators. Graphic output can be sent to an -arbitrary widget, to a PS or PDF file, or to a printer. -Class [QtLuaListener](#qtlualistener) gives the -ability to listen to events on arbitrary widgets - -For instance, the convenient -function [qtwidget.newwindow](#qtwidgetnewwindow) -creates a main window and returns its descriptor. - -```lua - require 'qtwidget' - w=qtwidget.newwindow(400,300,"Some QWidget") -``` - -Drawing is easily achieved using Postscript-like operators. - -```lua - w:moveto(0,0); w:curveto(0,300,400,0,400,300); w:closepath() - w:setcolor("red"); w:fill(false) - w:setcolor("blue"); w:setlinewidth(5); w:stroke() -``` - -Text output is of course supported -using [show](#paintershow). - -```lua - w:moveto(90,40) - w:setcolor("black") - w:setfont(qt.QFont{serif=true,italic=true,size=20}) - w:show("The Quick Brown Fox...") -``` - -Alpha-transparency works as well. - -```lua - w:rectangle(50,50,300,200) - w:setcolor(1,1,0,.5) - w:fill() -``` - -Finally you can capture Qt events using the -[qt.connect](..:qt:index#qt.connect) function -on the predefined [qt.QtLuaListener](#qtlualistener) object, - -```lua - qt.connect(w.listener, - 'sigMousePress(int,int,QByteArray,QByteArray,QByteArray)', - function(...) print("MousePress",...) end ); -``` - - -and you can erase everything with - -```lua - w:showpage() -``` - -<a name="highlevel"/> -## High Level Interface ## - -The following convenience functions -provide simple ways to perform graphic display -whose output is directed to a window on the screen, -to an image in memory, to a PostScript file, to a PDF file, or to a printer. -Each of these functions return a Lua table -that defines a number of useful fields and methods. -In particular, all the -[painting functions](#qtluapainterfunctions) -defined by class [qt.QtLuaPainter](#qtluapainter) -can be called directly using the -[Lua method syntax](..:LuaManual#FunctionCalls) -on these tables. - - - -<a name="qtwidgetnewwindow"/> -### qtwidget.newwindow(w,h,[title]) ### -<a name="qtwidget.newwindow"/> - -Expression `qtwidget.newwindow(w,h,title)` creates a -toplevel widget of class [qt.QWidget](..:qtgui:index#qwidget) -and a [qt.QtLuaPainter](#qtluapainter) object -operating on that widget. -Numerical arguments `w` and `h` specify the size of the widget. -String argument `title` specifies a window title. -The expression returns a Lua table that -serves as a drawing port descriptor. - -<a name="qtwidgetnewimage"/> -### qtwidget.newimage(...) ### -<a name="qtwidget.newimage"/> - -Function `qtwidget.newimage` creates an image in memory -that can be the target of drawing operations. -This function returns a Lua table that -serves as a drawing port descriptor. - -There are several ways to specify its arguments: - -__`qtwidget.newimage(w,h,[monoflag])`__ - -Creates an image of width `w` and height `h`. -When the optional argument `monoflag` is `true`, -a bitonal image is created. -Otherwise the image can contain arbitrary RGBA colors. - -__`qtwidget.newimage(filename,[format])`__ - -Creates an image by loading the contents of file `filename`. -The file format is defined by the optional string argument `format` -or derived from the file name extension. - -__`qtwidget.newimage(torchtensor)`__ - -Creates an image by extracting the contents of the specified -[torch.Tensor](..:torch:index#Tensor). -The valid tensor formats are described in the documentation for function -[qt.QImage.fromTensor](..:qttorch:index#qimagefromtensor). -This only works when both packages [torch](..:torch:index) -and [qttorch](..:qttorch:index) have been loaded. - - -<a name="qtwidgetnewps"/> -### qtwidget.newps(w,h,filename) ### -<a name="qtwidget.newps"/> - -Expression `qtwidget.newps(w,h,filename)` returns a Lua table that -serves as a drawing port descriptor. -Drawing operations will be output -into the PostScript file `filename`. -Arguments `w` and `h` represent the -initial size of the coordinate system. - -The output file contains incomplete data until -you delete the painter object or call -method [close](#qtwidgetclose). - -<a name="qtwidgetnewpdf"/> -### qtwidget.newpdf(w,h,filename) ### -<a name="qtwidget.newpdf"/> - -Expression `qtwidget.newpdf(w,h,filename)` returns a Lua table that -serves as a drawing port descriptor. -Drawing operations will be output -into the PDF file `filename`. -Arguments `w` and `h` represent the -initial size of the coordinate system. - -The output file contains invalid data until -you delete the painter object or call -method [close](#qtwidgetclose). - - -<a name="qtwidgetnewsvg"/> -### qtwidget.newsvg(w,h,[filename]) ### -<a name="qtwidget.newsvg"/> - -Expression `qtwidget.newsvg(w,h,filename)` returns a Lua table that -serves as a drawing port descriptor. -The optional argument `filename` contains the -name of the destination file for the SVG data. -Arguments `w` and `h` represent the -initial size of the coordinate system. - -The output contains invalid data until -you delete the painter object or call -method [close](#qtwidgetclose). -When argument `filename` is not specified, -the SVG data is written into an internal memory buffer -accessible using expression -[desc.svg:data()](..:qtsvg:index#qtluasvggeneratordata). - - -<a name="qtwidgetnewprint"/> -### qtwidget.newprint(w,h,[printername]) ### -<a name="qtwidget.newprint"/> - -Expression `qtwidget.newprint(w,h,printername)` -returns a Lua table that -serves as a drawing port descriptor. -Drawing operations will be output to printer `printername`. -When argument `printername` is omitted, -this function pops a print dialog that allows the user -to choose a printer and specify its settings. -Arguments `w` and `h` represent the -initial size of the coordinate system. - - - -<a name="qtpaintingfunctions"/> -### Painting Functions. ### - -All the [painting functions](#qtluapainterfunctions) -defined by class [qt.QtLuaPainter](#qtluapainter) -can be called directly using the -[Lua method syntax](..:LuaManual#FunctionCalls) -on the table returned by the functions -[qtwidget.newwindow](#qtwidgetnewwindow), -[qtwidget.newimage](#qtwidgetnewimage), -[qtwidget.newps](#qtwidgetnewps), -[qtwidget.newpdf](#qtwidgetnewpdf), -[qtwidget.newsvg](#qtwidgetnewsvg), and -[qtwidget.newprint](#qtwidgetnewprint). - -These calls are simply forwarded to the underlying -[qt.QtLuaPainter](#qtluapainter) object. - - * [Link to the painting functions](#qtluapainterfunctions). - - -<a name="qtwidgetotherfunctions"/> -### Other Functions and Fields. ### - -The following fields and functions are defined -on the descriptor tables returned by the functions -[qtwidget.newwindow](#qtwidgetnewwindow), -[qtwidget.newimage](#qtwidgetnewimage), -[qtwidget.newps](#qtwidgetnewps), -[qtwidget.newpdf](#qtwidgetnewpdf), and -[qtwidget.newprint](#qtwidgetnewprint). - - -<a name="descport"/> -#### desc.port #### -<a name="qtwidget.desc.port"/> - -Field `desc.port` contains the -[qt.QtLuaPainter](#qtluapainter) object -that is used to perform the drawings. - - -<a name="qtwidget.desc.widget"/> -#### desc.widget #### - -Field `desc.widget` contains the -[qt.QWidget](..:qtgui:index#qwidget) object -that underlies drawing port descriptors created with -[qtwidget.newwindow](#qtwidgetnewwindow). - - -<a name="qtwidget.desc.listener"/> -#### desc.listener #### - -Field `desc.widget` contains a -[qt.QtLuaListener](#qtlualistener) object. -that can be used to capture events on the widget created by -[qtwidget.newwindow](#qtwidgetnewwindow). - -<a name="qtwidget.desc.printer"/> -#### desc.printer #### - -Field `desc.printer` contains the -[qt.QtLuaPrinter](#qtluaprinter) object -that underlies drawing port descriptors created with -[qtwidget.newps](#qtwidgetnewps), -[qtwidget.newpdf](#qtwidgetnewpdf), or -[qtwidget.newprint](#qtwidgetnewprint). - -<a name="qtwidget.desc.svg"/> -#### desc.svg #### - -Field `desc.svg` contains the -[qt.QtLuaSvgGenerator](..:qtsvg:index#qtluasvggenerator) object -associated with drawing ports created with -[qtwidget.newsvg](#qtwidgetnewsvg). - - -<a name="qtwidget.desc.width"/> -#### desc.width #### - -Field `desc.width` contains the width of the drawing surface. - -<a name="qtwidget.desc.height"/> -#### desc.height #### - -Field `desc.height` contains the height of the drawing surface. - - -<a name="qtwidgetclose"/> -#### desc:close() #### -<a name="qtwidget.desc.close"/> - -Function `desc:close()` closes the [qt.QtLuaPainter](#qtluapainter). -In the case of a drawing port descriptor returned by function -[qtwidget.newwindow](#qtwidgetnewwindow), -this function also closes the [qt.QWidget](..:qtgui:index#qwidget) -and the windows disappears from the screen. - -<a name="qtwidget.desc.resize"/> -#### desc:resize(w,h) #### - -Function `desc:resize(w,h)` is only available for -drawing port descriptor returned by function -[qtwidget.newwindow](#qtwidgetnewwindow). -It resizes the underlying widget. - - -<a name="qtwidget.desc.onResize"/> -#### desc:onResize(f) #### - -Function `desc:onResize(f)` is only available for -drawing port descriptor returned by function -[qtwidget.newwindow](#qtwidgetnewwindow). -It ensures that -function `f(w,h)` gets called whenever the widget size changes. -The function argument indicate the new widget size. -Each call of `desc:onResize` replaces the previous callback function by `f`. -Calling it with argument `nil` removes the current callback. - - -<a name="qtwidget.desc.valid"/> -#### desc:valid() #### - -Expression `desc:valid()` returns `false` if the -underlying drawing target is no longer valid, -for instance because the window has been closed. -Otherwise it returns `true`. - - -<a name="qtwidget.classes"/> -## Classes ## - -<a name="qtlualistener"/> -### qt.QtLuaListener ### - -Class `QtLuaListener` emits signals when its parent receives event messages. -This is convenient because the Lua program can define event handling functions -using the signal connection function [qt.connect](..:qt:index#qt.connect). - -<a name="qtlualistener"/> -#### qt.QtLuaListener(qwidget) #### - -Expression `qt.QtLuaListener(qwidget)` returns a new `QtLuaListener` object -that relays the event messages received by widget `qwidget`. -This object is a child of `qwidget`. - -<a name="qtlualistener.sigClose"/> -#### [QtLuaListener signal] sigClose() #### - -Signal `sigClose` is emitted when the underlying widget receives a -[QCloseEvent](http://doc.trolltech.com/4.4/qcloseevent.html). - -<a name="qtlualistener.sigResize"/> -#### [QtLuaListener signal] sigResize(int,int) #### - -Signal `sigResize` is emitted whenever the underlying widget receives a -[QResizeEvent](http://doc.trolltech.com/4.4/qresizeevent.html) -because it has changed size. The two arguments are the new widget size. - - -<a name="qtlualistener.sigKeyPress"/> -#### [QtLuaListener signal] sigKeyPress(QString,QByteArray,QByteArray) #### - -Signal `sigKeyPress` is emitted whenever the underlying widget receives a -[QKeyEvent](http://doc.trolltech.com/4.4/qkeyevent.html) -of type `QEvent::KeyPress` because a key was pressed on the keyboard. -The first argument is a string representing the text associated with the key. -The second argument is the -[key name](http://doc.trolltech.com/4.4/qt.html#Key-enum). -The third argument is a string containing the -[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) -separated by a vertical bar. - - -<a name="qtlualistener.sigKeyRelease"/> -#### [QtLuaListener signal] sigKeyRelease(QString,QByteArray,QByteArray) #### - -Signal `sigKeyRelease` is emitted whenever the underlying widget receives a -[QKeyEvent](http://doc.trolltech.com/4.4/qkeyevent.html) -of type `QEvent::KeyRelease` because a key was released on the keyboard. -The first argument is a string representing the text associated with the key. -The second argument is the -[key name](http://doc.trolltech.com/4.4/qt.html#Key-enum). -The third argument is a string containing the -[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) -separated by a vertical bar. - - - -<a name="qtlualistener.sigMousePress"/> -#### [QtLuaListener signal] sigMousePress(int,int,QByteArray,QByteArray,QByteArray) #### - -Signal `sigMousePress` is emitted whenever the underlying widget receives a -[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) -of type `QEvent::MouseButtonPress` because a mouse button was pressed. -The first two arguments are the -pixel coordinates of the mouse pointer when the button was clicked -The third argument is a string containing the -[button name](http://doc.trolltech.com/4.4/qt.html#MouseButton-enum). -The fourth argument is a string containing the -[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) -separated by a vertical bar. -The fifth argument is a string containing the names of all depressed buttons -separated by a vertical bar. - - - -<a name="qtlualistener.sigMouseRelease"/> -#### [QtLuaListener signal] sigMouseRelease(int,int,QByteArray,QByteArray,QByteArray) #### - -Signal `sigMouseRelease` is emitted whenever the underlying widget receives a -[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) -of type `QEvent::MouseButtonRelease` because a mouse button was released. -The first two arguments are the -pixel coordinates of the mouse pointer when the button was released -The third argument is a string containing the -[button name](http://doc.trolltech.com/4.4/qt.html#MouseButton-enum). -The fourth argument is a string containing the -[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) -separated by a vertical bar. -The fifth argument is a string containing the names of all depressed buttons -separated by a vertical bar. - -<a name="qtlualistener.sigMouseDoubleClick"/> -#### [QtLuaListener signal] sigMouseDoubleClick(int,int,QByteArray,QByteArray,QByteArray) #### - -Signal `sigMouseRelease` is emitted whenever the underlying widget receives a -[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) -of type `QEvent::MouseButtonDblClick` because a mouse button was double-clicked. -The first two arguments are the -pixel coordinates of the mouse pointer when the button was clicked -The third argument is a string containing the -[button name](http://doc.trolltech.com/4.4/qt.html#MouseButton-enum). -The fourth argument is a string containing the -[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) -separated by a vertical bar. -The fifth argument is a string containing the names of all depressed buttons -separated by a vertical bar. - -<a name="qtlualistener.sigMouseMove"/> -#### [QtLuaListener signal] sigMouseMove(int,int,QByteArray,QByteArray) #### - -Signal `sigMouseRelease` is emitted whenever the underlying widget receives a -[QMouseEvent](http://doc.trolltech.com/4.4/qmouseevent.html) -of type `QEvent::MouseMove` because the mouse was moved. -Such events occur only when a mouse button is pressed down, -unless the widget property `mouseTracking` has been set to `true`. -The first two arguments are the -pixel coordinates of the mouse pointer when the button was released -The third argument is a string containing the -[keyboard modifier names](http://doc.trolltech.com/4.4/qt.html#KeyboardModifier-enum) -separated by a vertical bar. -The fourth argument is a string containing the names of all depressed buttons -separated by a vertical bar. - - - -<a name="qtlualistener.sigEnter"/> -#### [QtLuaListener signal] sigEnter(bool) #### - -Signal `sigEnter` is emitted whenever the underlying widget receives an -event of type -[QEvent::Enter](http://doc.trolltech.com/4.4/qevent.html) -or -[QEvent::Leave](http://doc.trolltech.com/4.4/qevent.html). -The boolean argument indicates whether the mouse pointer has just -entered or left the widget area. - -<a name="qtlualistener.sigFocus"/> -#### [QtLuaListener signal] sigFocus(bool) #### - -Signal `sigEnter` is emitted whenever the underlying widget receives -a [QFocusEvent](http://doc.trolltech.com/4.4/qfocusevent.html). -The boolean argument indicates whether the widget has just gained -or just lost the keyboard focus. - -<a name="qtlualistener.sigShow"/> -#### [QtLuaListener signal] sigShow(bool) #### - -Signal `sigEnter` is emitted whenever the underlying widget receives -a [QShowEvent](http://doc.trolltech.com/4.4/qshowevent.html) or a -a [QHideEvent](http://doc.trolltech.com/4.4/qhideevent.html). -The boolean argument indicates whether the widget has just been -shown or just been hidden. - - -<a name="qtlualistener.sigPaint"/> -#### [QtLuaListener signal] sigPaint() #### - -Signal `sigEnter` is emitted whenever the underlying widget receives -a [QPaintEvent](http://doc.trolltech.com/4.4/qpaintevent.html). - -<a name="qtluapainter"/> -### qt.QtLuaPainter ### - -Painting in Qt is usually achieved using class -[QPainter](http://doc.trolltech.com/4.4/qpainter.html). -Since this class is neither a subclass of -[QObject](http://doc.trolltech.com/4.4/qobject.html) -nor a value class suitable for storing into a Qt variant, -the QtLua class `QtLuaPainter` defines a Qt object that -exposes the painting capabilities of Qt in a more flexible way. - -Instances of class `QtLuaPainter` can target: - * Any image stored in memory represented as a [qt.QImage](..:qtgui:index#qimage) or a [qt.QPixmap](..:qtgui:index#qpixmap). - * Any widget represented as a [qt.QWidget](..:qtgui:index#qwidget). - * Any `QPaintDevice` encapsulated in a Qt object class such as class [qt.QtLuaPrinter](#qtluaprinter). - -Class `QtLuaPainter` provides an automatic buffering -capability when it targets a widget. Drawing functions -paint onto an offline image. The class logic ensures -that the widget is automatically refreshed or updated -when appropriate. - -Despite these differences, the Qt documentation for the -[Qt paint system](http://doc.trolltech.com/4.4/paintsystem.html) -contains lots of useful information. In particular, the documentation for -class [QPainter](http://doc.trolltech.com/4.4/qpainter.html) -accurately describes how the painter settings affects drawing operations. - - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(...) #### - -Function `qt.QtLuaPainter` constructs a new `QtLuaPainter` instance. - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(qimage) #### - -Constructs a painter instance that targets an offscreen image. -The image is initialized with a copy of the -[qt.QImage](..:qtgui:index#qimage) -passed as argument. Painting operations do not modify the image -passed as argument. Instead a copy of the current image can be -accessed using expression [painter:image()](#paintergrab). - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(filename, [format]) #### - -Constructs a painter instance that targets an offscreen image -initialized by reading the image file `filename`. -The file format is determined by the optional string -`format` or by the file name extension. -Use expression [painter.image()](#paintergrab) to -obtain a copy of the offscreen image. - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(w,h,[monoflag]) #### - -Constructs a painter instance that targets an offscreen image -of width `w` and height `h`. The image is bitonal when -the optional boolean flag `monoflag` is `true`. Otherwise -the image is a 32 bits RGBA image. -Use expression [painter.image()](#paintergrab) to -obtain a copy of the offscreen image. - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(qpixmap) #### - -Constructs a painter instance that targets a -device-dependent pixmap in memory. -The pixmap is initialized with a copy of -the [qt.QPixmap](..:qtgui:index#qpixmap) passed as argument. -Use expression [painter:pixmap()](#painterpixmap). -to obtain a copy of the target pixmap. -Since Qt only supports painting a device-dependent `QPixmap` from -the main thread, one must use [qt.pcall](..:qt:index#qt.qcall) -to ensure that painting operations are performed from the main thread. -Otherwise Qt prints a lot of warnings and behaves erratically. - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(qwidget,[buffered]) #### - -Constructs a painter instance that targets the -specified [qt.QWidget](..:qtgui:index#qwidget). -The resulting painter is a child of `qwidget`. -The optional boolean argument `buffered` indicates -whether drawing should be performed in a offscreen buffer -or directly on the widget surface. The default is to -create a buffered painter. - -A buffered painter always draws onto an offscreen image -and ensures that the widget surface is automatically refreshed or -updated when needed. Since the painting functions target -a [qt.QImage](..:qtgui:index#qimage), -they can be called from any thread at any time. -This is the recommended mode of operation. - -An unbuffered painter directly draws onto the widget surface. -Unfortunately Qt4 only supports painting a widget from the paint event handler -[QObject::paintEvent](http://doc.trolltech.com/4.4/qwidget.html#paintEvent). -While this is happening in the main thread, -the Lua interpreter might be unavailable for painting because -the Lua thread is busy running another program. -Unbuffered widget painters are therefore difficult to use for painting; -they are mostly useful for grabbing the on-screen representation -of a widget using function [painter.image()](#paintergrab). - -<a name="qtluapainter"/> -#### qt.QtLuaPainter(object) #### - -Constructs a painter instance that target the output -device represented by the instance `object` of a suitable Qt object class. -The class must implement an invokable method `device()` that returns -a pointer of type =QPaintDevice*=. -The class can also define an invokable method `printer()` -that returns a pointer of type `QPrinter*= and a signal =closing(QObject*)` -that indicates that the object is being destroyed. -Class [qt.QtLuaPrinter](#qtluaprinter) does all this. - - -<a name="qtluapainter.properties"/> -#### QtLuaPainter Properties #### - -<a name="qtluapainterangleunit"/> -##### painter.angleUnit ##### -<a name="qtluapainter.angleUnit"/> - -This property contains a string defining how arguments -representing angles are interpreted in painter functions -such as [painter:rotate(angle)](#painterrotate). -The acceptable values are the strings `"Degrees"` and `"Radians"`. -The default unit is the degree. - - -<a name="qtluapainterbackground"/> -##### painter.background ##### -<a name="qtluapainter.background"/> - -This property contains the [qt.QBrush](..:qtgui:index#qbrush) -used to draw the spaces in stippled lines, the text background, -and the zero color of bitonal images. -The default background brush is an empty brush -meaning that these pixels are not painted at all. - -<a name="qtluapainterbrush"/> -##### painter.brush ##### -<a name="qtluapainter.painter"/> - -Property `painter.brush` contains a Qt variant of class -[qt.QBrush](..:qtgui:index#qbrush) representing the painter settings -that determine how function [painter:fill](#painterfill) -fills shapes and how function [painter:show](#painterfill) -draws text. - -<a name="qtluapainterclippath"/> -##### painter.clippath ##### -<a name="qtluapainter.clippath"/> - -Property `painter.clippath` contient a Qt variant of class -[qt.QPainterPath](..:qtgui:index#qpainterpath) -representing the boundary -of the current clipping region. Drawing operations -only modify pixels located within the clip region. -An empty path means that no clipping is performed. - -<a name="qtluapaintercompositionmode"/> -##### painter.compositionMode ##### -<a name="qtluapainter.compositionMode"/> - -The -[composition mode](http://doc.trolltech.com/4.4/qpainter.html#CompositionMode-enum) -defines how new drawings are merged with previous drawings in the image. -Composition modes are representing as a string containing the -name of the composition mode without the prefix `QPainter::`. -The default composition mode is `"SourceOver"`. - -Not all devices support complex alpha-blending composition modes. -In particular printers often support only the default composition mode. -When a composition mode is not supported, the Qt library prints a warning. - - -<a name="qtluapainterdepth"/> -##### painter.depth ##### -<a name="qtluapainter.depth"/> - -Expression `painter.depth` returns the color depth -of the target surface for drawings. -A depth of `1` indicates a bitonal surface. -A depth of `24` or `32` indicates a true color surface. - -<a name="qtluapainterfont"/> -##### painter.font ##### -<a name="qtluapainter.font"/> - -Property `painter.font` contient a Qt variant of class -[qt.QFont](..:qtgui:index#qfont) representing the font settings -used for drawing text. - -<a name="qtluapainterheight"/> -##### painter.height ##### -<a name="qtluapainter.height"/> - -Expression `painter.height` returns the height of -the drawing surface expressed in pixels. -The returned value -is not affected by the current transformation matrix. -It corresponds to the default coordinate system -set by [painter:initmatrix](#painterinitmatrix). - -<a name="qtluapaintermatrix"/> -##### painter.matrix ##### -<a name="qtluapainter.matrix"/> - -Property `painter.font` contient a Qt variant of class -[qt.QTransform](..:qtgui:index#qtransform) representing -how coordinates passed to the path construction functions -are transformed into device depending coordinates. - -<a name="qtluapainterpath"/> -##### painter.path ##### -<a name="qtluapainter.path"/> - -Property `painter.path` contient a Qt variant of class -[qt.QPainterPath](..:qtgui:index#qpainterpath) -representing the current path. -A path is a mathematical boundary delimiting regions in the plane. -The current path is used implicitely by functions -[painter:fill](#painterfill) -and [painter:stroke](#painterstroke). -The current path is modified by a rich collection -of path defining functions. - -<a name="qtluapainterpen"/> -##### painter.pen ##### -<a name="qtluapainter.pen"/> - -Property `painter.pen` contains a Qt variant of class -[qt.QPen](..:qtgui:index#qpen) representing the painter settings -that determine how function [painter:stroke](#painterfill) -draws shapes. - -<a name="qtluapainterpoint"/> -##### painter.point ##### -<a name="qtluapainter.point"/> - -Property `painter.point` contient a Qt variant of class -[qt.QPointF](..:qtcore:index#qpoint) representing the -coordinates of the current point. These coordinates -are used and updated implicitely by the majority -of the path construction functions. - - -<a name="qtluapainterrenderhints"/> -##### painter.renderHints ##### -<a name="qtluapainter.renderHints"/> - -[Rendering hints](http://doc.trolltech.com/4.4/qpainter.html#RenderHint-enum) -are flags controlling the quality of the drawing operations. -They are represented by a string containing the concatenation of -the names of the active rendering flags (without the prefix `QPainter::`) -separated with a vertical bar "`|`" symbolizing a boolean `or` operator. - - -<a name="qtluapainterstylesheet"/> -##### painter.styleSheet ##### -<a name="qtluapainter.styleSheet"/> - -This property contains a string containing a CSS style sheet -that is used when drawing rich text with -function [show](#paintershow). - - -<a name="qtluapainterwidth"/> -##### painter.width ##### -<a name="qtluapainter.width"/> - -Expression `painter.width` returns the width of -the drawing surface expressed in pixels. -The returned value -is not affected by the current transformation matrix. -It corresponds to the default coordinate system -set by [painter:initmatrix](#painterinitmatrix). - - -<a name="qtluapainterfunctions"/> -#### QtLuaPainter Functions #### - -Class `QtLuaPainter` provides a broad array of -painting functions that closely resemble -the well-known PostScript operators. -Additional functions provide capabilities -that are unique to the Qt platform. - - -<a name="qtluapainter.arc"/> -##### painter:arc(x,y,r,angle1,angle2) ##### - -Expression `painter:arc(x,y,r,angle1,angle2)` -appends an arc of a circle to the current path. -The arc is centered at coordinates `(x,y)` -with radius `r` and extends from angle `angle1` -to angle `angle2` in the trigonometric direction. - -If there is a current point, a line segment joins -the current point to the first endpoint of the arc. -The second endpoint becomes the new current point. - -Angles can be expressed in degrees or radians -according to the [current angle unit](#qtluapainterangleunit). -The default angle unit is the degree. - - -See also: PostScript operator `arc`. - -<a name="qtluapainter.arcn"/> -##### painter:arcn(x,y,r,angle1,angle2) ##### - -Expression `painter:arcn(x,y,r,angle1,angle2)` -appends an arc of a circle to the current path. -The arc is centered at coordinates `(x,y)` -with radius `r` and extends from angle `angle1` -to angle `angle2` in the inverse trigonometric direction. - -If there is a current point, a line segment joins -the current point to the first endpoint of the arc. -The second endpoint becomes the new current point. - -Angles can be expressed in degrees or radians -according to the [current angle unit](#qtluapainterangleunit). -The default angle unit is the degree. - -See also: PostScript operator `arcn`. - -<a name="qtluapainter.arcto"/> -##### painter:arcto(x1,y1,x2,y2,r) ##### - -Expression `painter:arcto(x1,y1,x2,y2,r)` -appends an arc of a circle to the current path -defined by the radius `r` and two tangent lines -extending from the current point `(x0,y0)` to `(x1,y1)` -and from `(x1,y1)` to `(x2,y2)`. - -When the current point is set, a line segment joins -the current point to the first endpoint of the arc. -The second endpoint becomes the new current point. - -See also: PostScript operators `arct` and `arcto`. - - -<a name="qtluapainter.charpath"/> -##### painter:charpath(string) ##### - -Expression `painter:charpath(string)` -computes the path for the glyph outlines that would -result if string `string` was displayed -using [painter:show(string)](#paintershow). -This path is appended to the current path -and is therefore suitable for functions -[painter:stroke](#painterstroke) -or [painter:fill](#painterfill). - -After calling this function, the current point is left unset. - -See also: PostScript operators `charpath`. - -<a name="painterclip"/> -##### painter:clip(optnewpath) ##### -<a name="qtluapainter.clip"/> - -Function `painter:clip` intersects the -[current clip region](#qtluapainterclippath) -with the region described by the current path, -that is the region that would be painted by -[qtpainter.fill](#painterfill). -This intersection becomes the new clip region. - -The optional boolean `optnewpath` specifies -whether this function resets the current path -using [painter:newpath()](#painternewpath). -The default is to leave the current path unchanged. -The interior of the current path is determined using the -[winding rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule). -See function [painter:eoclip](#paintereoclip) for an alternative. - -This function cannot enlarge the clipping path. -The recommended approach is to call -[painter:gsave()](#paintergsave) -before reducing the clip region and -[painter:grestore()](#paintergrestore) -to restore the initial clip region. - -See also: PostScript operator `clip`. - - -<a name="painterclose"/> -##### painter:close() ##### -<a name="qtluapainter.close"/> - -Expression `painter:close()` detaches -the `QtLuaPainter` object from the underlying widget. -After doing this, you cannot draw anything. -Painters operating on a widget or a printer should -be closed before the underlying widget -or printer is destroyed. - - -<a name="qtluapainter.closepath"/> -##### painter:closepath() ##### - -Expression `painter:closepath()` -closes the current subpath by appending a -straight line segment connecting the -current point to the subpath to its starting point. -This function does nothing if the current subpath -is already closed. - -Using function `painter:closepath` is better than specifying -the line segment using `painter:lineto` because it will -ensure that the line segments are joined using the -current pen `capStyle` and `joinStyle` attributes. - -After calling this function, -the current point is left unset. - -See also: PostScript operator `closepath`. - -<a name="qtluapainter.concat"/> -##### painter:concat(qtransform) ##### - -Expression `painter:concat(qtransform)` -replaces the [current transformation matrix](#qtluapaintermatrix) -by the product of the current matrix -by the `QTransform` object `qtransform`. - -It is much easier to use functions -[painter:translate](#paintertranslate), -[painter:scale](#painterscale), or -[painter:rotate](#painterrotate). - -See also: PostScript operator `concat`. - -<a name="qtluapainter.currentangleunit"/> -##### painter:currentangleunit() ##### - -Expression `painter:currentangleunit()` returns the -[current angle unit](#qtluapainterangleunit) -for angles in functions such as [painter:rotate](#painterrotate). -Possible values are strings `"Degrees"` and `"Radians"`. -The default angle unit are degrees. - - -<a name="qtluapainter.currentbackground"/> -##### painter:currentbackground() ##### - -Expression `painter:currentbackground()` -returns a [qt.QBrush](..:qtgui:index#qbrush) -representing the [current background brush](#qtluapainterbackground) -used for displaying the backgrounds when painting -dashed line, text, or bitonal images. -The default is an empty brush. - - -<a name="qtluapainter.currentbrush"/> -##### painter:currentbrush() ##### - -Expression `painter:currentbrush()` -returns a [qt.QBrush](..:qtgui:index#qbrush) -representing the [current brush](#qtluapainterbrush) -used for filling path with [painter:fill()](#painterfill). -The default is an empty brush. - - -<a name="qtluapainter.currentclip"/> -##### painter:currentclip() ##### - -Expression `painter:currentclip()` -returns a [QPainterPath](..:qtgui:index#qpainterpath) -representing the [current clip region](#qtluapainterclippath). - -<a name="qtluapainter.currentcolor"/> -##### painter:currentcolor() ##### - -Expression `painter:currentcolor()` -returns four numbers representing the -red, green, blue, and alpha components -of the color of the [current brush](..:qtgui:index#qbrush). -This numbers range from zero to one. - - -<a name="qtluapainter.currentdash"/> -##### painter:currentdash() ##### - -Expression `painter:currentdash()` -returns the dash pattern and the dash offset -of the [current pen](#qtluapainterpen). - - -<a name="qtluapainter.currentfont"/> -##### painter:currentfont() ##### - -Expression `painter:currentfont()` -returns a [QFont](..:qtgui:index#qfont) -describing the [current font](#qtluapainterfont) -for drawing text. - -<a name="qtluapainter.currentfontsize"/> -##### painter:currentfontsize() ##### - -Expression `painter:currentfontsize()` -returns the size in points of the -[current font](#qtluapainterfont). - - -<a name="qtluapainter.currenthints"/> -##### painter:currenthints() ##### - -Expression `painter:currenthints()` returns the -[current rendering hints](#qtluapainterrenderhints) -controlling the quality of the drawings. - - -<a name="qtluapainter.currentlinewidth"/> -##### painter:currentlinewidth() ##### - -Expression `painter:currentlinewidth()` returns -the line width associated with the -[current pen](#qtluapainterpen). - -<a name="qtluapainter.currentmatrix"/> -##### painter:currentmatrix() ##### - -Expression `painter:currentmatrix()` returns a Qt variant of class -[qt.QTransform](..:qtgui:index#qtransform) representing the -[current transformation matrix](#qtluapaintermatrix). - -<a name="qtluapainter.currentmode"/> -##### painter:currentmode() ##### - -Expression `painter:currentmode()` returns a string representing the -[current composition mode](#qtluapaintercompositionmode). - - -<a name="qtluapainter.currentpath"/> -##### painter:currentpath() ##### - -Expression `painter:currentpath()` returns a Qt variant of class -[qt.QPainterPath](..:qtgui:index#qpainterpath) representing the -[current path](#qtluapainterpath). - - -<a name="qtluapainter.currentpen"/> -##### painter:currentpen() ##### - -Expression `painter:currentpath()` returns a Qt variant of class -[qt.QPen](..:qtgui:index#qpen) representing the -[current pen](#qtluapainterpen). - - -<a name="qtluapainter.currentpoint"/> -##### painter:currentpoint() ##### - -Expression `painter:currentpoint()` returns two numbers -representing the coordinates of the -[current point](#qtluapainterpoint). - - -<a name="paintercurrentsize"/> -##### painter:currentsize() ##### -<a name="qtluapainter.currentsize"/> - -Expression `painter:currentsize()` returns two numbers -representing the width and height of the drawing are -expressed in pixels. The returned values -are not affected by the current transformation matrix. -They correspond to the default coordinate system -sets by [painter:initmatrix](#painterinitmatrix). - - -<a name="paintercurrentstylesheet"/> -##### painter:currentstylesheet() ##### -<a name="qtluapainter.currentstylesheet"/> - -Expression `painter:currentstylesheet()` returns the -the [current style sheet](#qtluapainterstylesheet) -used by function [show](#paintershow) for -displaying rich text. - - -<a name="paintercurveto"/> -##### painter:curveto(x1,y1,x2,y2,x3,y3) ##### -<a name="qtluapainter.curveto"/> - -Expression `painter:curveto(x1,y1,x2,y2,x3,y3)` -appends a section of a cubic Bezier curve to the current path. -The curve starts on the current point and ends in point `(x3,y3)` -using `(x1,y1)` and `(x2,y2)` as the Bezier control points. -The endpoint `(x3,y3)` then becomes the new current point. - -The behavior of this function is undefined -when the current point is not set - -See also: PostScript operator `curveto`. - - -<a name="painterdevice"/> -##### painter:device() ##### -<a name="qtluapainter.device"/> - -Expression `painter:device()` returns a pointer to the Qt -paint device underlying the painter. -Since the Qt class -[QPaintDevice](http://doc.trolltech.com/4.4/qpaintdevice.html) -is neither a Qt variant not a Qt object, this pointer -is represented by a Qt variant of type =QPaintDevice*=. -This is not very useful in Lua. - - -<a name="paintereoclip"/> -##### painter:eoclip(optnewpath) ##### -<a name="qtluapainter.eoclip"/> - -Function `painter:eoclip` is similar to function -[painter:clip](#painterclip). However the interior of the -current path is interpreted using the -[odd-even rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule) -instead of the winding rule. - - - -<a name="paintereofill"/> -##### painter:eofill(optnewpath) ##### -<a name="qtluapainter.eofill"/> - -Function `painter:eofill` is similar to function -[painter:fill](#painterfill). However the interior of the -current path is determined using the -[odd-even rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule) -instead of the winding rule. - -See also: PostScript operator `eofill`. - -<a name="painterfill"/> -##### painter:fill(optnewpath) ##### -<a name="qtluapainter.fill"/> - -Function `painter:fill` fills the interior of the -[current path](#qtluapainterpath) using -the [current brush](#qtluapainterbrush). - -The optional boolean `optnewpath` specifies -whether this function resets the current path -using [painter:newpath()](#painternewpath). -The default is to reset the current path. -The interior of the current path is determined using the -[winding rule](http://doc.trolltech.com/4.4/qpainterpath.html#setFillRule). -See function [painter:eofill](#paintereofill) for an alternative. - -See also: PostScript operator `fill`. - - -<a name="paintergbegin"/> -##### painter:gbegin() ##### -<a name="qtluapainter.gbegin"/> - -Functions [painter:gbegin](#paintergbegin) and -[painter:gend](#paintergend) can be used -to bracket code segments that perform drawings that -are meaningful as a whole. The actual display is -usually postponed until the last call to `painter:gend`. -This is useful for implementing smooth transitions -between successive drawings. - -<a name="paintergend"/> -##### painter:gend([invalidate]) ##### -<a name="qtluapainter.gend"/> - -Functions [painter:gbegin](#paintergbegin) and -[painter:gend](#paintergend) can be used -to bracket code segments that perform drawings that -are meaningful as a whole. The actual display is -usually postponed until the last call to `painter:gend`. -This is useful for implementing smooth transitions -between successive drawings. - -When the target device is a buffered widget, -setting flag `invalidate` to true -ensures that the whole widget will be refreshed. -This is useful after drawing directly into -the underlying `QPainter` object without -using the `QtLuaPainter` functions. - - -<a name="paintergrestore"/> -##### painter:grestore() ##### -<a name="qtluapainter.grestore"/> - -Expression `painter:grestore()` restores the painter settings -previously saved by a matching expression [painter:gsave()](#paintergsave). - -Functions [painter:gsave](#paintergsave) and -[painter:restore](#paintergrestore) should be used -to bracket code segments that perform some rendering -in order to ensure that the painter settings -remain unchanged. - - - -<a name="paintergsave"/> -##### painter:gsave() ##### -<a name="qtluapainter.gsave"/> - -Expression `painter:gsave()` records the painter settings -and pushes this information on top of a stack of painter settings. -Subsequent calls to [painter:grestore()](#paintergrestore) -can be used to restore the saved settings. - -Functions [painter:gsave](#paintergsave) and -[painter:restore](#paintergrestore) should be used -to bracket code segments that perform some rendering -in order to ensure that the painter settings -remain unchanged. - -<a name="paintergrab"/> -##### painter:image() ##### -<a name="qtluapainter.image"/> - -Expression `painter:image()` returns a Qt variant of class -[qt.QImage](..:qtgui:index#qimage) -representing the drawing surface. - -When the underlying surface is a widget without backing store, -this function grabs the widget image from the display. -When the painter operates on a device that cannot be represented -as an image, for instance a printer, -this function returns an empty image for which method -[tobool](..:qt:index#qt.tobool) returns `false`. - -Note that this function must be invoked without arguments. -Otherwise see the documentation for [painter:image(...)](#painterblit). - - -<a name="painterblit"/> -##### painter:image(x,y,[w,h],image,[sx,sy,[sw,sh]]) ##### -<a name="qtluapainter.image"/> - -Function `painter:image` paints a segment of image `image` -at position `(x,y)` in the current coordinate systems -with with `w` and height `h`. The source segment -is defined by the rectangle of size `(sw,sh)` -starting on point `(sx,sy)`. - -The default source width `sw` and height `sh` are the width and height of the -source image. The default source origin `(sx,sy)` is the origin `(0,0)`. -The default target width `w` and height `h` are -the source width `sw` and height `sh`. - -Argument `image` can be a Qt variant of -class [qt.QImage](..:qtgui:index#qimage) -or [qt.QPixmap](..:qtgui:index#qpixmap) -or a Qt object of class [qt.QtLuaPainter](#qtluapainter). -In the latter case, the function -[painter:image()](#paintergrab) without arguments -is used to obtain the source surface. - - * To blit an image `img` constructed with [qtwidget.newimage](#qtwidgetnewimage), you must specify the associated painter [img.port](#descport). - - * To blit a [torch.Tensor](..:torch:index#Tensor), first create a [qt.QImage](..:qtgui:index#qimage) using the function [qt.QImage.fromTensor](..:qttorch:index#qimagefromtensor) from by package [qttorch](..:qttorch:index). - -Blit is of course affected by -the [current composition mode](#qtluapaintercompositionmode). - -Note that this function must be invoked with arguments. -Otherwise see the documentation for [painter:image()](#paintergrab). - -See also: PostScript operator `image`. - - -<a name="painterinitclip"/> -##### painter:initclip() ##### -<a name="qtluapainter.initclip"/> - -Expression `painter:initclip()` resets the -[current clip region](#qtluapainterclippath) -to the empty path. This effectively means -that clipping is disabled and therefore -that all surface pixels can be affected -by a subsequent drawing operation. - - -See also: PostScript operator `initclip`. - - -<a name="painterinitgraphics"/> -##### painter:initgraphics() ##### -<a name="qtluapainter.initgraphics"/> - -Expression `painter:initgraphics()` resets -all painter settings to their default values. -After calling this function: - - * The [current clip region](#qtluapainterclippath) is set as with [painter:initclip()](#painterinitclip). - * The [current transformation matrix](#qtluapaintermatrix) is set as with [painter:initmatrix()](#painterinitmatrix). - * The [current brush](#qtluapainterbrush) is a solid black brush with brush origin (0,0). - * The [current pen](#qtluapainterpen) is a solid black pen with line width `1`, flat caps, and miter joins. - * The [current background](#qtluapainterbackground) is an empty brush meaning that background pixels are not painted at all. - * The [current font](#qtluapainterfont) is a 10 points sans serif font. - * The [current path](#qtluapainterpath) is empty and the [current point](#qtluapainterpoint) is unset. - * The [current rendering hints](#qtluapainterrenderhints) are `"Antialiasing|TextAntialiasing"`. - * The [current composition mode](#qtluapaintercompositionmode) is `"SourceOver"`. - * The [current angle unit](#qtluapainterangleunit) is `"Degrees"`. - -See also: PostScript operator `initgraphics`. - - -<a name="painterinitmatrix"/> -##### painter:initmatrix() ##### -<a name="qtluapainter.initmatrix"/> - -Expression `painter:initmatrix()` resets the -[current transformation matrix](#qtluapaintermatrix) -to its default value. -The coordinate system has then its origin -in the upper left corner of the surface -with X coordinates ordered from left to right -and Y coordinates ordered from top to bottom. -Coordinates are expressed in device pixels -on most devices. - -See also: PostScript operator `initmatrix`. - -<a name="qtluapainter.lineto"/> -##### painter:lineto(x,y) ##### - -Expression `painter:lineto(x,y)` appends -a line segment to the current path, -starting from the [current point](#qtluapainterpoint) -and ending at coordinates `(x,y)`. -The segment end point then becomes -the new current point. - -The behavior of this function is undefined -when the current point is not set - -See also: PostScript operator `lineto`. - - -<a name="qtluapainter.moveto"/> -##### painter:moveto(x,y) ##### - -Expression `painter:moveto(x,y)` terminates the -last subpath of the current path and moves -the current point to coordinates `(x,y)`. - -See also: PostScript operator `moveto`. - - -##### painter:newpath() ##### -![](anchor:painternewpath) -<a name="qtluapainter.newpath"/> - -Expression `painter:newpath()` terminates the last subpath. -After calling this function, the current point is left unset. - -See also: PostScript operator `newpath`. - -<a name="painterobject"/> -##### painter:object() ##### -<a name="qtluapainter.object"/> - -Expression `painter:object()` returns the Qt object -that represents the paint device if such an object exists. -Typical return values are instance of class -[qt.QWidget](..:qtgui:index#qwidget) or class -[qt.QtLuaPrinter](#qtluaprinter). - - -<a name="painterpainter"/> -##### painter:painter() ##### -<a name="qtluapainter.painter"/> - -Expression `painter:painter()` returns a pointer -to the underlying Qt painter. -Since the Qt class -[QPainter](http://doc.trolltech.com/4.4/qpainter.html) -is neither a Qt variant not a Qt object, this pointer -is represented by a Qt variant of type =QPainter*=. - - -<a name="painterpixmap"/> -##### painter:pixmap() ##### -<a name="qtluapainter.pixmap"/> - -Expression `painter:pixmap()` returns a Qt variant of class -[qt.QPixmap](..:qtgui:index#qpixmap) representing the drawing surface. - -When the underlying surface is a widget without backing store, -this function grabs the widget representation from the display. -When the painter operates on a device that cannot be represented -as a pixmap, for instance a printer, -this function returns an empty pixmap for which method -[tobool](..:qt:index#qt.tobool) returns `false`. - -<a name="qtluapainter.printer"/> -##### painter:printer() ##### - -Expression `painter:printer()` returns a pointer -to the underlying Qt printer. -Since the Qt class -[QPrinter](http://doc.trolltech.com/4.4/qpainter.html) -is neither a Qt variant not a Qt object, this pointer -is represented by a Qt variant of type =QPrinter*=. - - - -<a name="qtluapainter.rcurveto"/> -##### painter:rcurveto(x1,y1,x2,y2,x3,y3) ##### - -This is similar to calling function -[painter:curveto](#paintercurveto) -with the following arguments - -```lua - painter:curveto(x0+x1,y0+y1,x0+x2,y0+y2,x0+x3,y0+y3) -``` - -where `(x0,y0)` are the coordinates of the previous -current point. - -The behavior of this function is undefined -when the current point is not set. - -See also: PostScript operator `rcurveto`. - -<a name="qtluapainter.rect"/> -##### painter:rect() ##### - -Expression `painter:rect()` returns a Qt variant -of class [=qt.QRect](..:qtcore:index#qrect) -representing the pixel coordinates of the drawing surface. -This does not depend on the transformation matrix -but corresponds to the default coordinate system -set by [painter:initmatrix()](#painterinitmatrix). - -The same information can be obtained more conveniently -using function [painter:currentsize()](#paintercurrentsize) -or properties [painter.width](#qtluapainterwidth) -and [painter.height](#qtluapainterheight). - - -<a name="qtluapainter.rectangle"/> -##### painter:rectangle(x,y,w,h) ##### - -Expression `painter:rectangle(x,y,w,h)` -appends a rectangle to the current path. -The rectangle starts is defined by its origin `(x,y)`, -its width `w` and its height `h`. - -After calling this function, -the current point is left unset. - - - -<a name="qtluapainter.refresh"/> -##### painter:refresh() ##### - -Expression `painter:refresh()` immediately -repaints the displayed image, -regardless of the nesting count of functions -[painter:gbegin()](#paintergbegin) and -[painter:gend()](#paintergend). - - - -<a name="qtluapainter.rlineto"/> -##### painter:rlineto(rx,ry) ##### - -Expression `painter:lineto(x,y)` appends a line segment -to the current path, starting from the current point `(x0,y0)` -and ending at coordinates `(x0+x,y0+y)`. -The segment end point then becomes -the new current point. - -The behavior of this function is undefined -when the current point is not set - -See also: PostScript operator `rlineto`. - -<a name="qtluapainter.rmoveto"/> -##### painter:rmoveto(rx,ry) ##### - -Expression `painter:moveto(x,y)` terminates the -last subpath of the current path and moves -the current point to coordinates `(x0+x,y0+y)` -where `(x0,y0)` are the coordinates of the previous -current point. - -The behavior of this function is undefined -when the current point is not set - -See also: PostScript operator `rmoveto`. - -<a name="painterrotate"/> -##### painter:rotate(angle) ##### -<a name="qtluapainter.rotate"/> - -Expression `painter:rotate(angle)` -rotates the axes of the coordinate system by `angle` angle units -in the trigonometric direction around the coordinate origin. -The position of the coordinate origin and the size of the coordinate units -are unaffected. - -Argument `angle` can be expressed in degrees or radians -according to the [current angle unit](#qtluapainterangleunit). -The default angle unit is the degree. - -See also: PostScript operator `rotate`. - -<a name="painterscale"/> -##### painter:scale(sx,sy) ##### -<a name="qtluapainter.scale"/> - -Expression `scale(sx,sy)` scales the units of the -coordinate space by a factor of `sx` horizontally and -`sy` vertically. The position of the coordinate origin and -the orientation of the axes are unaffected. - -See also: PostScript operator `scale`. - - -<a name="paintersetangleunit"/> -##### painter:setangleunit(unit) ##### -<a name="qtluapainter.setangleunit"/> - -Expression `painter:setangleunit(unit)` sets the -[angle unit](#qtluapainterangleunit) -for functions such as [painter:rotate](#painterrotate) -that require an angle as argument. - -Argument `unit` must be string `"Degrees"` -for expressing angles in degrees, -or `"Radians"` for expressing angles in radians. -The default angle unit is the degree. - - -<a name="qtluapainter.setbackground"/> -##### painter:setbackground(brush) ##### - -Expression `painter:setbackground(brush)` sets the -[current background brush](#qtluapainterbackground). -Argument `brush` must be a Qt variant of type -[qt.QBrush](..:qtgui:index#qbrush). - -<a name="qtluapainter.setbrush"/> -##### painter:setbrush(brush) ##### - -Expression `painter:setbrush(brush)` sets the -[current brush](#qtluapainterbrush). -Argument `brush` must be a Qt variant of type -[qt.QBrush](..:qtgui:index#qbrush). - -<a name="qtluapainter.setclip"/> -##### painter:setclip(qpainterpath) ##### - -Expression `painter:setclip(qpainterpath)` sets the -[current clipping region](#qtluapainterclippath) -to be the interior of the specified path. -Argument `brush` must be a Qt variant of type -[qt.QPainterPath](..:qtgui:index#qpainterpath). - - -<a name="qtluapainter.setcolor"/> -##### painter:setcolor(...) ##### - -Function `painter:setcolor` sets the color of both the -[current brush](#qtluapainterbrush) -and [current pen](#qtluapainterpen). - -There are several ways to specify a color: - -__`painter:setcolor(qcolor)`__ - -Argument `qcolor` is a Qt variant of -class [qt.QColor](..:qtgui:index#qcolor). - -__`painter:setcolor(string)`__ - -Argument `string` is a string representing a color name. -All [SVG color names](http://www.w3.org/TR/SVG/types.html#ColorKeywords) -are recognized.Color names can have also the format `"#RGB"`, -`"#RRGGBB"`, `"#RRRGGGBBB"`, or ="#RRRRGGGGBBBB" -where letters `R`, `G`, or `B` represent hexadecimal -digits for each of the color component. - -__`painter:setcolor(r,g,b,[a])`__ - -Arguments `r`, `g`, `b`, and `a` are numbers in range `[0,1]` -representing the intensities of the red, green, blue, and alpha channels. -The default value for argument `a` is `1` for a fully opaque color. - - -<a name="qtluapainter.setdash"/> -##### painter:setdash([sizes,[offset]]) ##### - -Function `painter:setdash` changes the -style of the [current pen](#qtluapainterpen). - -When this function is called without argument, -or when argument `sizes` is `nil`, -this function sets the current pen style -to `"SolidLine"`. - -Otherwise argument `sizes` can be a single number or -a table containing a list of numbers. -The number or the list of numbers represent the length of successive -[dashes and blanks](http://doc.trolltech.com/4.4/qpen.html#setDashPattern) -along the drawn curve, expressed in units of the line width. -When the size of the sequence is odd, the last blank -is assumed to have the same size as the last dash. -The optional argument `offset` is a length -representing the starting position of the dash sequence. - - -<a name="qtluapainter.setfont"/> -##### painter:setfont(qfont) ##### - -Expression `painter:setfont(qfont)` sets the -[current font](#qtluapainterfont). -Argument `font` must be a Qt variant of type -[qt.QFont](..:qtgui:index#qfont). - -<a name="qtluapainter.setfontsize"/> -##### painter:setfontsize(size) ##### - -Expression `painter:setfontsize(size)` changes the size -of the [current font](#qtluapainterfont). -Argument `size` must be a positive number. - - -<a name="qtluapainter.sethints"/> -##### painter:sethints(hints) ##### - -Expression `painter:sethints(hints)` sets the -[current rendering hints](#qtluapainterrenderhints). -Argument `hints` must be a string containing -a concatenation of the names of the active -[rendering flags](http://doc.trolltech.com/4.4/qpainter.html#RenderHint-enum) -separated with a vertical bar "`|`". - - -<a name="qtluapainter.setlinewidth"/> -##### painter:setlinewidth(lw) ##### - -Expression `painter:setlinewidth(lw)` changes the line width -of the [current pen](#qtluapainterpen). -Argument `lw` must be a positive number. - -<a name="qtluapainter.setmatrix"/> -##### painter:setmatrix(qtransform) ##### - -Expression `painter:setmatrix(qtransform)` sets the -[current transformation matrix](#qtluapaintermatrix). -Argument `qtransform` must be a Qt variant of type -[qt.QTransform](..:qtgui:index#qtransform). - - -<a name="qtluapainter.setmode"/> -##### painter:setmode(compositionmode) ##### - -Expression `painter:setmode(compositionmode)` sets the -[current composition mode](#qtluapaintercompositionmode) -for subsequent drawing operations. -Argument `compositionmode` must be a string containing the name of a -[composition mode](http://doc.trolltech.com/4.4/qpainter.html#CompositionMode-enum). - - -<a name="qtluapainter.setpath"/> -##### painter:setpath(qpainterpath) ##### - -Expression `painter:setpath(qpainterpath)` sets the -[current path](#qtluapainterpath). -Argument `qpainterpath` must be a Qt variant of type -[qt.QPainterPath](..:qtgui:index#qpainterpath). - - -<a name="qtluapainter.setpattern"/> -##### painter:setpattern(pattern,[x,y]) ##### - -Expression `painter:setpattern(pattern,[x,y])` -creates a textured pattern brush. -This brush is used to set both the [current brush](#qtluapainterbrush) -and the brush of the [current pen](#qtluapainterpen). - -Argument `p` can be either a Qt variant -of type [qt.QImage](..:qtgui:index#qimage) or an object -equipped with a method `image` returning a suitable image. -Such objects include instances of [qt.QtLuaPainter](#qtluapainter) -as well as the return values of functions -[qtwidget.newwindow](#qtwidgetnewwindow) -or [qtwidget.newimage](#qtwidgetnewimage) - -The optional arguments `x` and `y` specify -the origin of the pattern in the source image. - - -<a name="qtluapainter.setpen"/> -##### painter:setpen(qpen) ##### - -Expression `painter:setpen(qpen)` sets the -[current pen](#qtluapainterpen). -Argument `qpen` must be a Qt variant of type -[qt.QPen](..:qtgui:index#qpen). - - -<a name="qtluapainter.setpoint"/> -##### painter:setpoint(x,y) ##### - -Expression `painter:setpoint(x,y)` sets the -[current point](#qtluapainterpen) coordinates to `(x,y)`. -Arguments `x` and `y` must be valid numbers. - - -<a name="qtluapainter.setstylesheet"/> -##### painter:setstylesheet(s) ##### - -Expression `painter:setstylesheet(s)` sets the -the [current style sheet](#qtluapainterstylesheet) -used by function [show](#paintershow) for -displaying rich text. - - - -<a name="paintershow"/> -##### painter:show(string,[x,y,w,h,textflags]) ##### -<a name="qtluapainter.show"/> - -Function `painter:show` draws string `string` using -the [current font](#qtluapainterfont). - -When called with a single string argument `string`, -this function draws the specified text -starting from the [current point](#qtluapainterpoint). -After displaying each glyph, the current point is adjusted -with a displacement computed from the font's glyph-spacing information. -The behavior of this function is undefined -when the current point is not set. - -When called with more arguments, this function draws -the text `string` within the rectangle specified by -the origin `(x,y)`, the width `w`, and the heigth `h`. -Argument `textflags` is then a string composed by concatenating -a subset of the following keywords separated -by a vertical bar "`|`" symbolizing a `or` operator: -[AlignLeft](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignRight](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignTop](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignBottom](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignHCenter](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignVCenter](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignCenter](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum), -[AlignJustify](http://doc.trolltech.com/4.4/qt.html#AlignmentFlag-enum). -[TextSingleLine](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), -[TextExpandTabs](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), -[TextShowMnemonic](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), -[TextWordWrap](http://doc.trolltech.com/4.4/qt.html#TextFlag-enum), -[RichText](http://doc.trolltech.com/4.4/richtext-html-subset.html). - -The flag `RichText` is directly implemented by the `QtLuaPainter` class. -It indicates that the text contains rich text data using the -[subset of HTML](http://doc.trolltech.com/4.4/richtext-html-subset.html) -supported by Qt and can be used in conjunction with alignment flags only. -Display is affected by -the [current font](#qtluapainterfont), -the [current brush color](#qtluapainterbrush), and -the [current style sheet](#qtluapainterstylesheet). -You can use the css `style` attribute in HTML tags -to specify more complicated formats. - -See also: PostScript operator `show`. - - -<a name="qtluapainter.showpage"/> -##### painter:showpage() ##### - -Expression `painter:showpage()` -clears the current drawing -and paints the background all white. - -Things are a bit different when the painting device is a printer. -Function `painter:showpage` ensures that the next drawing operation -will first print the current page and initialize a new page. -Successive calls of `painter:showpage()` do not print multiple pages -unless some drawing operation is performed on each page. - -See also: PostScript operator `showpage`. - - -<a name="qtluapainter.size"/> -##### painter:size() ##### - -Expression `painter:size()` returns a Qt variant -of class [qt.QSize](..:qtcore:index#qsize) -representing the size in pixels of the drawing surface. -This does not depend on the transformation matrix -but corresponds to the default coordinate system -set by [painter:initmatrix()](#painterinitmatrix). - -The same information can be obtained more conveniently -using function [painter:currentsize()](#paintercurrentsize) -or properties [painter.width](#qtluapainterwidth) -and [painter.height](#qtluapainterheight). - -<a name="qtluapainter.stringrect"/> -##### painter:stringrect(string,[x,y,w,h,textflags]) ##### - -Function `painter:stringrect` returns a Qt variant of type -[qt.QRectF](..:qtcore:index#qrect) representing -the bounding box of the text that would be displayed -by calling function [painter:show](#paintershow) -with the same arguments. - - -<a name="qtluapainter.stringwidth"/> -##### painter:stringwidth(string) ##### - -Fonction `painter:stringwidth` returns -two numbers representing the total displacement `(dx,dy)` -that would be applied to the [current point](#qtluapainterpoint) -by expression [show(string)](#paintershow). - -See also: PostScript operator `stringwidth`. - - -<a name="painterstroke"/> -##### painter:stroke(optnewpath) ##### -<a name="qtluapainter.stroke"/> - -Function `painter:stroke` draws the boundary of the -[current path](#qtluapainterpath) using -the [current pen](#qtluapainterpen). - -The optional boolean `optnewpath` specifies -whether this function resets the current path -using [painter:newpath()](#painternewpath). -The default is to reset the current path. - -See also: PostScript operator `stroke`. - -<a name="paintertranslate"/> -##### painter:translate(dx,dy) ##### -<a name="qtluapainter.translate"/> - -Expression `translate(dx,dy)` translates the coordinate -origin by `dx` units along the X axis and `dy` units -along the Y axis. The the size of the coordinate units and -the orientation of the axes are unaffected. - -See also: PostScript operator `translate`. - -<a name="qtluapainter.widget"/> -##### painter:widget() ##### - -Expression `painter:widget()` returns the Qt object of class -[qt.QWidget](..:qtgui:index#qwidget) underlying the painter. -When the painter is not associated with a widget, -this expression returns `nil`. - - -<a name="qtluapainter.write"/> -##### painter:write(f,[format]) ##### - -Expression `painter:write(f)` saves the image -associated with the painter into the file named `f`. -Argument `f` can be a file name or a Lua file descriptor. - -The image data is obtained using -function [painter:image()](#paintergrab). -The image format is determined by the -optional string argument `format` or -deduced from the file name extension. - - - -<a name="qtluaprinter"/> -### qt.QtLuaPrinter ### - -Printing in Qt is usually achieved using class -[QPrinter](http://doc.trolltech.com/4.4/qprinter.html). -Since this class is neither a subclass of -[QObject](http://doc.trolltech.com/4.4/qobject.html) -nor a value class suitable for storing into a Qt variant, -the QtLua class `QtLuaPrinter` defines a Qt object that -acts as a thin wrapper for class `QPrinter`. - -Most usual -[printer settings](http://doc.trolltech.com/4.4/qprinter.html) -are exposed by class `qt.QtLuaPrinter` as properties. -Property [printer.paperSize](#printerpapersize) -can be used to specify the size of the drawing in pixels. -Printers can be selected using [printer.printerName](#printerprintername) -and PostScript and PDF files can be produced with -properties [printer.outputFileName](#printeroutputfilename) -and [printer.outputFormat](#printeroutputformat). -Alternatively, function `printer:setup()` pops a print dialog -that lets the user adjust these properties interactively. - - -<a name="qtluaprinternew"/> -#### qt.QtLuaPrinter([mode]) #### -<a name="qtluaprinter"/> - -Expression `qt.QtLuaPrinter(mode)` returns a -new instance of class `qt.QtLuaPrinter`. - -The optional argument `mode` is a string specifying -the resolution of the initial coordinate system. -The default value `ScreenResolution` replicates the screen resolution. -Value `HighResolution` initializes the coordinate -system with the resolution of the printer. - -Most printer properties should be set before -creating the [qt.QtLuaPainter](#qtluapainter) -that will peform the drawings. - - -<a name="qtluaprinter.abort"/> -#### printer:abort() #### - -Expression `printer:abort()` aborts the current print run. -Returns `true` if the print run was successfully aborted. -Property [printer.printerState](#printerprinterstate) -will then be `"Aborted"`. -It is not always possible to abort a print job. - -<a name="qtluaprinter.collateCopies"/> -#### printer.collateCopies #### - -Boolean property `printer.collateCopies` specifies -if collation is turned on when multiple copies is selected. - -<a name="qtluaprinter.colorMode"/> -#### printer.colorMode #### - -Boolean property `printer.colorMode` is `true` -when one prints in color (the default) and `false` -when one prints in gray scale. - -<a name="qtluaprinter.creator"/> -#### printer.creator #### - -Property `printer.creator` is a string containing -the name of the application producing the printout. -This information is passed to the print spooling system. - -<a name="qtluaprinter.docName"/> -#### printer.docName #### - -Property `printer.creator` is a string containing -the name of the document being printed. -This information is passed to the print spooling system - -<a name="qtluaprinter.doubleSidedPrinting"/> -#### printer.doubleSidedPrinting #### - -Boolean property `printer.doubleSidedPrinting` -indicates whether double sided printing is requested. - -<a name="qtluaprinter.fontEmbeddingEnabled"/> -#### printer.fontEmbeddingEnabled #### - -Boolean property `printer.fontEmbeddingEnabled` indicates -whether the output data should embed a font description. -This is `true` by default. - - -<a name="qtluaprinter.fromPage"/> -#### printer.fromPage #### - -Readonly numerical property `printer.fromPage` -contains the index of the first page to print. -Use function [printer:setFromTo](#printersetfromto) to change it. - -<a name="qtluaprinter.fullPage"/> -#### printer.fullPage #### - -Setting boolean property `printer.fullPage` to `true` -enables support for painting over the entire page. -Otherwise painting is restricted to the printable area -reported by the device. - -<a name="qtluaprinter.landscape"/> -#### printer.landscape #### - -Setting boolean property `printer.landscape` to `true` -sets the printout in landscape mode. -Otherwise printing happens in portrait mode. - - -<a name="qtluaprinter.newPage"/> -#### printer:newPage() #### - -Expression `printer:newPage()` -tells the printer to eject the current page and -to continue printing on a new page. -Returns `true` if this was successful. - -<a name="qtluaprinter.numCopies"/> -#### printer.numCopies #### - -Property `printer.numCopies` contains the number of copies to be printed. -The default value is 1. - -Qt handles the number of copies in a rather strange way: -the value you obtain by reading property `printer.numCopies` is not -the value you have set but reports the number of times you should -draw the document in order to achieve the desired effect. -On Windows, Mac OS X and X11 systems that support CUPS, -reading property `printer.numCopies` always return 1 because these systems -internally handle the number of copies. - -<a name="printeroutputfilename"/> -#### printer.outputFileName #### -<a name="qtluaprinter.outputFileName"/> - -Setting property `printer.outputFileName` to a nonempty -string indicates that printing should be redirected -to the specified file. - - -<a name="printeroutputformat"/> -#### printer.outputFormat #### -<a name="qtluaprinter.outputFormat"/> - -Property `printer.outputFormat` contains a string describing -the output format for this file or printer. -Recognized values are `"PdfFormat"`, `"PostScriptFormat"`, -and `"NativeFormat"`. - - -<a name="printerpagerect"/> -#### printer.pageRect #### -<a name="qtluaprinter.pageRect"/> - -Read-only property `painter.pageRect` contains -a [qt.QRect](..:qtcore:index#qrect) -describing the coordinates of the printable -area of a page. - -This rectangle is expressed in coordinates -starting from the top-left corner of the page -and with units specified according to -[=printer.resolution](#printerresolution). -This coordinate system is not related the -the drawing coordinate system. - - -<a name="printerpagesize"/> -#### printer.pageSize #### -<a name="qtluaprinter.pageSize"/> - -String property `printer.pageSize` contains the name of the paper format. -The recognized names are -`"A4"`, `"B5"`, `"Letter"`, `"Legal"`, `"Executive"`, -`"A0"`, `"A1"`, `"A2"`, `"A3"`, `"A5"`, `"A6"`, -`"A7"`, `"A8"`, `"A9"`, `"B0"`, `"B1"`, -`"B10"`, `"B2"`, `"B3"`, `"B4"`, `"B6"`, -`"B7"`, `"B8"`, `"B9"`, `"C5E"`, `"Comm10E"`, -`"DLE"`, `"Folio"`, `"Ledger"`, and `"Tabloid"`. - -When using Qt-4.4 or greater, -this property can also contain the value `"Custom"` -to indicate that the produced output must -describe an image whose size matches -exactly the specified paper size. -When using an earlier version of Qt, -setting this property to `"Custom"` does nothing. - - -<a name="printerpaperrect"/> -#### printer.paperRect #### -<a name="qtluaprinter.paperRect"/> - -Read-only property `painter.paperRect` contains -a [qt.QRect](..:qtcore:index#qrect) -describing the full size of the paper. - -This rectangle is expressed in coordinates -starting from the top-left corner of the page -and with units specified according to -[printer.resolution](#printerresolution). -This coordinate system is not related the -the drawing coordinate system. - -<a name="printerpapersize"/> -#### printer.paperSize #### -<a name="qtluaprinter.paperSize"/> - -Property `printer.paperSize` contains a -[qt.QSizeF](..:qtcore:index#qsize) -describing the desired size of the drawable area. - -When this property contains a valid size, -that is a size with positive width and height, -the painter initial coordinate system -is adjusted to display the specified drawable area -within the desired page size. - -Furthermore, with Qt-4.4. or greater, -when property [printer.pageSize](#printerpagesize) -is equal to `"Custom"`, property `printer.paperSize` -also specifies the size of the image described -by the output file. - -<a name="printerprinter"/> -#### printer:printer() #### -<a name="qtluaprinter.printer"/> - -Returns a pointer to the real `QPrinter` object -which is a subclass of `QPaintDevice`. - - -<a name="qtluaprinter.printProgram"/> -#### printer.printProgram #### - -Setting string property `printer.printProgram` overrides -the name of the program used to submit the printout -to the spooling system. - - -<a name="printerprintername"/> -#### printer.printerName #### -<a name="qtluaprinter.printerName"/> - -String property `printer.printerName` -contains the name of the target printer. -This value is initially set to the name of the -default printer for your system. - - -<a name="printerprinterstate"/> -#### printer.printerState #### -<a name="qtluaprinter.printerState"/> - -Readonly string property `printer.printerState` -returs a string describing the state of the printer. -Possible values are `Idle`, `Active`, `Aborted` and `Error`. -That does not work on all systems. - - -<a name="printerresolution"/> -#### printer.resolution #### -<a name="qtluaprinter.resolution"/> - -Numerical property `printer.resolution` -contains the resolution of the printer. -This is initially set by the `mode` argument -of the constructor [qt.QtLuaPrinter(mode)](#qtluaprinternew). -The resolution affects the coordinate systems -for properties [printer.paperRect](#printerpaperrect) -and [printer.pageRect](#printerpagerect). -It only affects the drawing coordinate systems -when property [printer.papersize](#printerpapersize) -does not contain a valid size. - - -<a name="printersetfromto"/> -#### printer:setFromTo(frompage,topage) #### -<a name="qtluaprinter.setFromTo"/> - -Function `printer:setFromTo` -specifies the indices of the page range to print. -If both `frompage` and `topage` are zero (the default), -the whole document is printed. - -<a name="qtluaprinter.setup"/> -#### printer:setup([parentwidget]) #### - -Expression `printer:setup()` displays a dialog -allowing the user to choose a printer -and select various print settings. -It returns `true` if the user presses the button "Print" -and `false` if the user cancels. - -<a name="qtluaprinter.toPage"/> -#### printer.toPage #### - -Readonly numerical property `printer.toPage` -contains the index of the last page to print. -Use function [printer:setFromTo](#printersetfromto) to change it. - -- cgit v1.2.3