Home < Software

HsQML

HsQML Logo

HsQML Logo

Latest release 0.2.0.3 (Changelog) (Release Announcement)

Overview

HsQML is a Haskell binding to Qt Quick, a cross-platform framework for creating graphical user interfaces. Qt Quick utilises a declarative language called QML in combination with JavaScript to allow you to create rich animated UIs using a range of components. HsQML then allows you to bind together front-end designs written in QML with back-end logic written in Haskell to create complete applications using the strengths of both.

HsQML is a mid-level binding which abstracts users away from lower level details such as resource management, while still exposing the imperative nature of the underlying library. It allows you to define custom QML classes with methods, properties, and signals, via which the Haskell and QML worlds can interact. Hence, QML designs can invoke methods which translate into Haskell function calls and receive signals fired asynchronously from Haskell.

Requirements

As of the current release, HsQML supports binding against Qt 4.7 or 4.8 using the older QDeclarative API. HsQML cannot currently be built against Qt 5.x owing to API changes in the library, but work is in progress to migrate over to this newer series of Qt releases. HsQML has been tested on the major desktop platforms supported by Qt: Linux, Windows, and MacOS.

In order to build HsQML, you will require the following:-

Installation

HsQML is provided as a Cabal package containing the necessary scripts and source code so that it can be easily distributed, built, and installed on multiple platforms. Given a correctly setup Haskell development environment, simply typing "cabal install hsqml" should install the latest version available in the Hackage repository along with any dependent libraries. You may need to set to your PATH environment variable so that Cabal can find the Qt libraries and tools.

Usage

Unfortunately, there is not a great deal of documentation available for HsQML at the moment. I enclose a small example program below to demonstrate basic usage. For more sophisticated applications, you should look at the API reference and the larger example program available on Hackage. I have also written a blog post on using signals with HsQML.

This simple program defines a QML class for the Haskell data type MainObject which exposes a single method called getMagicNumber(). The program uses the HsQML library's runEngineLoop function to start the Qt event loop and display a QML document stored in separate file. Crucially, one of the parameters supplied via the engine configuration is a QML instance to be used as the document's global context object. The members of this object will be accessible in the global namespace to any JavaScript code running on the QML side of the system.

The QML document given below should display a small red box containing some text. The text to be displayed will be taken from the result of calling the getMagicNumber() function. The Haskell function supplied when defining this function returns the number 42, and so when you run this example you should see a window appear which displays that number. The program will exit when you close the window.

Screenshot of Simple HsQML Example

Screenshot of Simple HsQML Example

Main.hs

{-# LANGUAGE DeriveDataTypeable #-}

import Graphics.QML
import Data.Typeable

main :: IO ()
main = do
    ctx <- newObject MainObject
    runEngineLoop defaultEngineConfig {
        initialURL = filePathToURI "main.qml",
        contextObject = Just $ anyObjRef ctx}

data MainObject = MainObject deriving Typeable

instance Object MainObject where
    classDef = defClass [
        defMethod "getMagicNumber" (
            (\_ -> return 42) :: ObjRef MainObject -> IO Int)]

main.qml

import Qt 4.7

Rectangle {
    id: root
    width: 100; height: 100
    color: "red"

    Text {
        id: myText
        color: "white"
        text: getMagicNumber();
        y: 30
        anchors.horizontalCenter: root.horizontalCenter
        font.pointSize: 24;
        font.bold: true
    }
}

Downloads & Source Code


Robin KAY <komadori@gekkou.co.uk>