Module "qt"
===========

The SPL/Qt Module

This module provides a thin wrapper for the Qt toolkit.
It is using the SMOKE library from the kdebindings package.
 
manual SPL_Qt;
--------------

The SPL/Qt Module

This module provides a thin wrapper for the Qt toolkit.
It is using the SMOKE library from the kdebindings package.

All Qt classes are available via the qt namespace and can be instanciated
using the "new" keyword, like normal SPL objects:

	load "qt";

	var a = new qt.QApplication();
	var l = new qt.QLabel(undef);
	l.setText("Hello World!");
	a.setMainWidget(l);
	l.show();
	a.exec();

Qt objects can be used like normal SPL objects. However: Only the qt methods
are available from SPL. The object properties can't be accessed directly.

The qt.QApplication class has a non-standard constructor which does not take
any arguments. It is recommended to use this constructor for creating a
qt.QApplication instance.

Some data types can't be converted by this module. So some Qt methods might
be unaccesable thru this module.

This is a thin wrapper for the Qt C++ libraries. It is possible to produce
segmentation faults or other errors by using this module incorrectly.

This module does not allow you to straight-forward derive your own classes
from qt classes. However, this functionality might be added later.

All Qt Objects have a pseudo member-variable ".class" which contains the
name of the Qt class for this object.

The pseudo member-variable ".ptr" contains a text representation of the
memory address of Qt Object. This can be used e.g. for checking if two SPL
Qt Object handlers point to the same Qt Object.

Static methods can be called directly from the qt namespace without
instanciating the class. Enums behave like static methods without arguments
which do return the numeric value for the enum.

The complete Qt Reference Documentation can be found at:
http://doc.trolltech.com/

An SPL Virtual Machine which loaded the "qt" module is unable to dump its
state. So the SPL dump/restore feature doesn't work for SPL/Qt programs.
 

builtin qt_debug(mode);
-----------------------

Enable/disable debug output.

Call this function with an argument of '1' to enable the debug output and
with an argument of '0' to disable it.

The debug output is disabled per default.
 

builtin qt_kde();
-----------------

Check for kde libraries.

This function returns '1' if the kde APIs are available and '0' if only the
core Qt APIs can be used.
 

builtin qt_ui(ui_file);
-----------------------

Instanciates the widget described in the specified .ui file.
The new widget is returned.
 

builtin qt_child(parent, name, class, recursive);
-------------------------------------------------

This is a frontend to the Qt QObject::child() function. The difference is
that this function automatically casts the return value to the specified
class. Example given:

	var d = qt_ui("dialog.ui");
	var b = qt_child(d, "pushButton1", "QPushButton", 1);
	b.setText("Click Me!");
 

builtin qt_cast(object, type);
------------------------------

Cast a Qt Object. The new object handler is returned.
For QObjects this is a frontend to QObject::qt_cast().
 

builtin qt_destroy(object);
---------------------------

Destroy a QObject.

Usually QObjects are destroyed automatically when the last SPL variable
refering to it is destroyed and the QObjects has no parent objects.

(Destroying QApplication Objects is automatically delayed until all other
Qt Objects are destroyed.)

But sometimes it is neccessary to explicitely destroy a QObject, e.g. when
one want's to remove a Widget from a dialog.
 

builtin qt_delete(object);
--------------------------

Delete a Qt Object.

This function can be used to delete any Qt Object. It is recommended to
use qt_destroy() for QObject. This function should only be used for
deleting Qt Objects which are not QObjects.
 

builtin qt_autodelete(object);
------------------------------

Mark a Qt Object for autodeletion.

This maks an object for autodeletion. That means that the object will be
deleted automatically when the SPL handler is removed by the garbage
collector.

The object is returned by the function. So this function can be used like
a filter when instanciating a new object. Example Given:

	var background = qt_autodelete(new qt.QColor(200, 100, 100));
 

builtin qt_as(type, value);
---------------------------

Create a hint for the SPL/Qt type converter

The SPL/Qt module does its best to guess which version of a method should be
used. But sometimes it needs a hint to make the right decision.

E.g. there are two implementations of QMessageBox::question():

	int QMessageBox::question(QWidget *parent,
			const QString &caption,	const QString &text,
			int button0, int button1 = 0, int button2 = 0)
and

	int QMessageBox::question (QWidget *parent,
			const QString &caption, const QString &text,
			const QString &button0Text = QString::null,
			const QString &button1Text = QString::null,
			const QString &button2Text = QString::null,
			int defaultButtonNumber = 0,
			int escapeButtonNumber = -1)

To choose the first version one needs to use qt_as() for the integer
parameters so they not converted to strings:

	qt.QMessageBox.question(win, "Hey!", "Are you sure?",
			qt_as("int", 3), qt_as("int", 4));
 

builtin qt_connect(sender, signal, receiver, slot);
---------------------------------------------------

Connect a signal to a slot. This is a frontend to the QObject::connect
method. The SIGNAL() and SLOT() macros are not available in SPL. This
function simply expects the signal or slot as string. E.g.:

	qt_connect(mybutton, "clicked()", myapp, "quit()");
 

builtin qt_disconnect(sender, signal, receiver, slot);
------------------------------------------------------

Like qt_connect(), but for disconnecting a signal and a slot.
 

builtin qt_event_callback(object, callback, @eventtypes);
---------------------------------------------------------

Register an event callback in a Qt object.

The callback function will be passed the QEvent object as 1st parameter. The
callback must return true (non-zero) if the event has been comsumed and false
(zero) if the event should be passed to the other event handlers.

A list of event types may be passed as additional parameters. If no types
are specified, all events are passed thru the callback function.

Example given:

	function click_callback(e) {
		debug "Click: ${e.x()} / ${e.y()}";
		return 1;
	}

	qt_event_callback(widget_object, click_callback,
		qt.QEvent.MouseButtonPress(), qt.QEvent.MouseButtonDblClick());

Once a callback function is registered it stays active until the widget gets
destroyed. There is no function for unregistering an event callback.

This function can be used to connect an SPL closoure to a Qt widget. The Qt
C++ API does not have such a function because C++ has not closoures..

In some cases it is dangerous to copy to variables passed to an event
callback to a different context and use it after the callback has been
returned. So it is recommended to not do this.
 

builtin qt_signal_callback(object, signalspec, callback);
---------------------------------------------------------

Register a signal callback in a Qt object.
Example given:

	function printpos(x,y) {
		debug "New content position: $x / $y";
	}

	qt_signal_callback(my_scrollview, "contentsMoving(int,int)", printpos);

Once a callback function is registered it stays active until the widget gets
destroyed. There is no function for unregistering a signal callback.

This function can be used to connect an SPL closoure to a Qt widget. The Qt
C++ API does not have such a function because C++ has not closoures..

In some cases it is dangerous to copy to variables passed to a signal
callback to a different context and use it after the callback has been
returned. So it is recommended to not do this.
 

builtin qt_virtual_callback(object, method, callback);
------------------------------------------------------

Overload a virtual method in a Qt object. The method name is specified in
the SMOKE syntax (method names, optionally postfixed with '$', '#' and '?'
for scalar, QObject or other arguments).
 

builtin qt_info();
------------------

Return information about classes and methods.

This function returns a data structure describing all classes and methods
available thru this interface.
 

function qt_kdeinit(progname, desc, version);
---------------------------------------------

This function is a simple frontend to KCmdLineArgs::init(). It must be
executed before instanciating a KApplication object.
 

namespace qt
------------

All Qt classes are available via this namespace.
 

object QtEx
-----------

An instance of this object is thrown on internal errors of the Qt wrapper.
 

var QtEx.description;
~~~~~~~~~~~~~~~~~~~~~

A description text describing the error.
 
