In section 1.2 we saw a basic formula for the main qtHaskell functions. Chapter 2 described the functions for enabling callback functions in qtHaskell. A few other important points about qtHaskell functions are as follows:
QtHaskell functions that correspond to non-static members of a Qt class are not prefixed with the name of that class. This means that some of them (e.g. show, read) are the same as Haskell Prelude functions. To avoid the need for always qualifying either the qtHaskell function or the Prelude function, the qtHaskell function is prefixed with "q".
QtHaskell functions that correspond to any Qt constructors or
methods that take parameters of the type:
QRect, QLine, QPoint, QSize
are implemented to take parameters of the corresponding
Qth
classname type, i.e.:
Rect, Line, Point, Size
. A corresponding function that
takes parameters of the original type is retained and prefixed with "q".
A constructor or static method in this case will have a variant form
qq
SomeConstructorOrStaticMethod
.
Non-static methods that take parameters of this type
and whose names correspond to Haskell Prelude
functions will also take a double "qq" prefix.
QtHaskell uses native Haskell garbage collection to delete
objects corresponding to the Qt data classes automatically. Objects of some
of these class types such as QImage, QPixmap and QBitmap
are not copied internally by Qt when passed as parameters. These means they
usually cannot be deleted when they go out of scope in a Haskell function.
There are two options available to qtHaskell programmers in the above case (or in any case where a Qt data class type object is not to be deleted automatically). They can store a reference to the Qt data object in an IORef type in the Haskell environment, or if that is not convenient, they can construct the object with a "_nf" suffixed constructor.
All qtHaskell constructors for Qt data class types have an equivalent
"_nf" form, which, (as the suffix suggests), does not return a finalizer
function for the Haskell foreign pointer. In this case however the object
must be explicitly deleted with a call to the appropriate
q
SomeQtClass
_delete
function.
There are also some functions such as
qPixmapFromImage
and scale
, which
return new instances of Qt data types even though they are not
constructors. These functions also have a "_nf" form.
N.B. It is very rarely if ever safe to let objects of the
QPainter
class be automatically deleted, hence it is
recommended that the qPainter_nf
constructor be used at
all times for objects of this type.
QtHaskell destructors of the form
q
SomeQtClassName
_delete
are available for all Qt class types. As discussed in the previous section,
these should only be used with Qt data class types if the object is created
by a "_nf" suffixed constructor or method function.
QtHaskell destructors of the form
q
SomeQtClassName
_deleteLater
are available for all Qt class types based on QObject. These destructors are
usually required for such class types.
QtHaskell functions for Qt enumerated type values and corresoponding
flags type values have the formulae
e
SomeEnumeratedTypeValue
and
f
SomeFlagsTypeValue
respectively. There is no difference between the actual numerical value
associated with "e" and "f" functions with the same name but each can only
be used as parameters of the respective type, and only "f" prefixed flags
functions can be combined with the '+" operator.
Enumerated and flags types functions are not prefixed with the corresponding type name, hence the same functions can occur for more than one type. In this case any use of the function in question must be explicitly type qualified when passed as a parameter to any method function which has multiple parameter instances. E.g.
setAlignment tl (fAlignCenter::Alignment)