# SPL Module Reference: qt

load "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;

builtin qt_debug(mode);
builtin qt_kde();
builtin qt_ui(ui_file);
builtin qt_child(parent, name, class, recursive);
builtin qt_cast(object, type);
builtin qt_destroy(object);
builtin qt_delete(object);
builtin qt_autodelete(object);
builtin qt_as(type, value);
builtin qt_connect(sender, signal, receiver, slot);
builtin qt_disconnect(sender, signal, receiver, slot);
builtin qt_event_callback(object, callback, @eventtypes);
builtin qt_signal_callback(object, signalspec, callback);
builtin qt_virtual_callback(object, method, callback);
builtin qt_info();

function qt_kdeinit(progname, desc, version);

namespace qt { }

object QtEx
{
var description;
}

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.

Generated by SPLDOC. | http://www.clifford.at/spl/