3.2. Functions

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:

3.2.1. 'q'

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 qqSomeConstructorOrStaticMethod. Non-static methods that take parameters of this type and whose names correspond to Haskell Prelude functions will also take a double "qq" prefix.

3.2.2. '_nf'

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 qSomeQtClass_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.

3.2.3. Destructors

QtHaskell destructors of the form qSomeQtClassName_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 qSomeQtClassName_deleteLater are available for all Qt class types based on QObject. These destructors are usually required for such class types.

3.2.4. Enumerated Types

QtHaskell functions for Qt enumerated type values and corresoponding flags type values have the formulae eSomeEnumeratedTypeValue and fSomeFlagsTypeValue 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)