Grapefruit

About

Grapefruit is a library for creating graphical user interfaces and animated graphics in a declarative way. It contains an implementation of Functional Reactive Programming and a record system which can be useful in other areas than GUI and graphics programming.

Grapefruit is currently based on Gtk2Hs but implementations on top of other GUI libraries are planned for the future. By using different GUI libraries on different platforms, Grapefruit shall be able to adapt to local look and feel conventions.

Grapefruit makes it possible to implement graphical user interfaces by describing them as systems of interconnected components. Components can be visible components like widgets and windows but also invisible components which provide certain control functionality. Component systems can be built from components by using methods from the Arrow and ArrowLoop classes.

Components communicate via signals. A signal is either continuous or discrete. A continuous signal denotes a time-varying value. A discrete signal denotes a sequence of values assigned to discrete points in time and can therefore be used to model streams of events. Several functions allow the construction of signals in a purely functional manner.

Grapefruit has also support for list signals, special signals denoting time-varying lists where each element has a unique identity. An algebra for list signals provides operations like concatenation, filtering and sorting. The key point is that when the value of a list signal changes, the values of the list signals depending on it do not have to be recalculated completely but can be just updated incrementally.

User interfaces with a changing collection of widgets are also possible with Grapefruit. There is a special widget which takes a list signal of widgets as its input and always contains the elements of it as its child widgets.

Furthermore, it is possible to implement animations using graphic signals. These are implemented on top of OpenGL. So-called caching graphic signals are available to make use of OpenGL’s display lists.

With Grapefruit, user interface descriptions always cover the complete lifetime of the respective interface. No explicit event handler registrations and no explicit recalculations of values are necessary. This is in line with the declarative nature of Haskell because it stresses how the user interface operates instead of how this operation is achieved. Internally though, signals are implemented efficiently using the event dispatching and handling mechanism of the underlying GUI toolkit.

The roots of Grapefruit lie in systems like FranTk and wxFruit. Grapefruit tries to combine concepts of these systems with new ideas to become a system which maintains a reasonable balance between ease of use and efficiency, and is applicable to real world problems.

Status

As of October 2007, Grapefruit is still in an early stage. Lots of basic concepts are implemented but Grapefruit still lacks a wide variety of widgets, for example. However, adding new widgets shouldn’t be too difficult since Grapefruit provides good generic support for doing this.

Furthermore, work on formal specification and verification of GUI properties based on Grapefruit’s GUI programming interface and dependent types has just started. The proof assistant Coq will be used in this context.

Source code

The source code of Grapefruit resides inside a darcs repository under http://softbase.org/grapefruit/darcs/main/. To get a copy, you can use the command darcs get http://softbase.org/grapefruit/darcs/main.

Building

You need at least GHC 6.8.1 and Gtk2Hs 0.9.12.1 to build and use Grapefruit. Currently, Grapefruit is tested with GHC 6.8.2 and Gtk2Hs 0.9.12.1. For building the API documentation, you need Haddock 2.0.0.0.

Grapefruit consists of the following packages, each residing inside a equally-named directory in the source tree:

• grapefruit-frp
• grapefruit-records
• grapefruit-gui
• grapefruit-graphics
• grapefruit-examples

You can use Cabal to build each single package.

There is also a script Setup.lhs in the root directory of the source tree which simplifies the building process. For building Grapefruit in place, use the following command:

runghc Setup.lhs up-to-register configure-options -- build-options -- --inplace further-register-options

If you rather want to install Grapefruit in some directory, use this command:

runghc Setup.lhs up-to-install configure-options -- build-options -- install-options

For building the API documentation, you can issue this:

runghc Setup.lhs haddock

This will build the documentation for the different packages with hyperlinks to the Haskell Hierarchical Libraries documentation. It will also build an index and a contents page for the complete Grapefruit library. The documentation will be placed in the directory doc. The entry point to the documentation will be doc/grapefruit/index.html. For building the documentation, you first need to build the complete library and install it or register it in place.

Documentation

API documentation generated by Haddock is also on the web. You find it under http://softbase.org/grapefruit/doc/grapefruit/index.html. Note that the documentation might get a bit out of date since it is not automatically regenerated on every commit yet.

Publications and talks

• Wolfgang Jeltsch: Improving Push-based FRP. TFP 2008.
  • draft paper (to appear in the draft proceedings)

• Wolfgang Jeltsch: Funktionale GUI-Programmierung in Haskell mit Grapefruit. Haskell in Leipzig 2. July 10, 2007.
  • video
  • presentation

Screenshots

Following are some screenshots from example programs using Grapefruit:

Simple

Clicking on the button adds a star to the caption of the button. This doesn’t look very meaningful. However, Simple is actually a very important example since it demonstrates that feedbacks work—the output of the button is transformed and then used as the button’s input.

Codebreaker

This is a Mastermind™-like game. The Add button is enabled if and only if the input field contains a valid code and the display box is enabled if and only if the list of guesses does not contain the code chosen by the computer. These properties are described in a declarative way in the source code.

CircuitingObjects

This example demonstrates Grapefruit’s support for animations.