Personal tools

Grapefruit

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(update concerning release date and documentation)
(update which takes changes because of the first release into account)
Line 24: Line 24:
 
== Versions ==
 
== Versions ==
   
Grapefruit has undergone fundamental interface and implementation changes in late 2008 and early 2009. A version without these changes is available as the “classic” version. The classic version contains support for animated graphics, incrementally updating list signals and a restricted form of dynamic user interfaces (user interfaces whose widget structure may change).
+
There is a first official Grapefruit release which is release 0.0.0.0.
   
The current development version does not have these features at the moment. Graphics support is expected to come back later if someone finds the time to port the respective code to the new Grapefruit interface. List signal and dynamic UI support are intended to come back in a much more generalized form.
+
Grapefruit underwent fundamental interface and implementation changes before this release. A version from before these changes is available as the “classic” version. In contrast to the released version, the classic version contains support for animated graphics, incrementally updating list signals and a restricted form of dynamic user interfaces (user interfaces whose widget structure may change). These features are expected to come back in future releases.
   
A stable release of Grapefruit is expected to happen during the first half of February 2009.
+
== Installation ==
   
== Download ==
+
First, a note for GHC 6.8 users. If you get warnings of the form “Can’t find interface-file declaration for type constructor or class …” when compiling with GHC 6.8 then don’t panic. This seems to be because of a bug in the (non-official) type family support of GHC 6.8. However, it seems to be harmless.
   
The current version can be fetched from the [[Darcs|darcs]] repository at http://softbase.org/grapefruit/darcs/main. If you want to try out the classic version, please get it from the darcs repository at http://softbase.org/grapefruit/darcs/classic.
+
=== Released version ===
   
== Building ==
+
You need at least GHC 6.8.3 and Gtk2Hs 0.9.13 to build and use Grapefruit. GHC 6.8.2 can ''not'' be used because of [http://hackage.haskell.org/trac/ghc/ticket/1981 GHC bug #1981]. Grapefruit was tested with GHC 6.8.3 and Gtk2Hs 0.9.13 as well as with GHC 6.10.1 and a Gtk2Hs 0.10.0.
   
You need at least GHC 6.8.3 and Gtk2Hs 0.9.13 to build and use Grapefruit. GHC 6.8.2 can ''not'' be used because of [http://hackage.haskell.org/trac/ghc/ticket/1981 GHC bug #1981]. Gtk2Hs 0.9.12.1 might be okay but you would have to change the gtk dependency in grapefruit-ui-gtk/grapefruit-ui-gtk.cabal in order to use it. Grapefruit was tested with GHC 6.8.3 and Gtk2Hs 0.9.13 as well as GHC 6.10.1 and a pre-0.10.0 development version of Gtk2Hs.
+
Grapefruit is released on [[Hackage]]. If you do not have special requirements, you can install Grapefruit and its prerequisites as follows:
  +
# Install GHC 6.10.1 (see [http://www.haskell.org/ghc/download_ghc_6_10_1.html]).
  +
# Install cabal-install (see [http://ghcmutterings.wordpress.com/2008/11/10/bootstrapping-cabal-install/]).
  +
# Insert the line <code>documentation: True</code> into the cabal-install configuration file ($HOME/.cabal/config on UNIX-like systems).
  +
# Install Gtk2Hs&nbsp;0.10.0 (see [http://sourceforge.net/project/showfiles.php?group_id=49207&package_id=42440&release_id=659598]).
  +
# Install Grapefruit by entering <code>cabal update</code>, followed by <code>cabal install grapefruit-ui-gtk grapefruit-examples</code> on a command line.
   
In addition to Gtk2Hs, you will need a couple of other Haskell libraries. These are all available from [http://hackage.haskell.org/ Hackage]. Cabal will tell you what libraries it wants. Alternatively, you can have a look at the build dependency specifications in the files grapefruit-*/grapefruit-*.cabal.
+
=== Current development version ===
   
If you get warnings of the form “Can’t find interface-file declaration for type constructor or class …” when compiling grapefruit-ui or grapefruit-ui-gtk with GHC&nbsp;6.8.3 then don’t panic. This seems to be because of a bug in the (non-official) type family support of GHC&nbsp;6.8.3. However, it seems to be harmless.
+
The current development version can be fetched from the [[Darcs|darcs]] repository at http://softbase.org/grapefruit/darcs/main. You can build it by building the individual [[Cabal]] packages in the grapefruit-* directories. Note that grapefruit-graphics is currently defunct.
   
Grapefruit consists of the following packages, each residing inside an equally-named directory in the source tree:
+
=== Classic version ===
* grapefruit-frp
 
* grapefruit-records
 
* grapefruit-ui
 
* grapefruit-ui-gtk
 
* grapefruit-examples
 
You can use Cabal to build each single package.
 
   
There is also a Setup.lhs script in the root directory of the source tree which simplifies the building process. Alas, it only works with older Cabal versions so that it is not usable with the Cabal that comes with GHC&nbsp;6.10.1. For building the complete Grapefruit library (including examples) in place with this script, run the following command:
+
If you want to try out the classic version, please get it from the darcs repository at http://softbase.org/grapefruit/darcs/classic. You can build it by building the individual [[Cabal]] packages in the grapefruit-* directories. Alternatively, you can use the Setup.lhs script in the root directory to easily build all packages. You can run the following:
  +
;<code>runghc Setup.lhs clean</code>
  +
:cleans all packages
  +
;<code>runghc Setup.lhs up-to-install ''configure-options'' -- ''build-options'' -- ''install-options''</code>
  +
:configures, builds and installs all packages
  +
;<code>runghc Setup.lhs up-to-register ''configure-options'' -- ''build-options'' -- ''register-options''</code>
  +
:configures and builds all packages and registers all library packages (which are all except grapefruit-examples)
   
<blockquote><p><code>runghc Setup.lhs up-to-register ''configure-options'' -- ''build-options'' -- --inplace ''further-register-options''</code></p></blockquote>
+
The classic version does not work with GHC&nbsp;6.10.1 and the global Setup.lhs script does not work with newer Cabals.
   
If you rather want to install Grapefruit in some directory, use this command:
+
== Running the examples ==
   
<blockquote><p><code>runghc Setup.lhs up-to-install ''configure-options'' -- ''build-options'' -- ''install-options''</code></p></blockquote>
+
=== Released version and current development version ===
   
== Running the examples ==
+
You can run the examples by typing the following lines into GHCi:
   
The package grapefruit-examples of the classic versions provides an executable for each example. Since the current version is able to use different UI toolkits (at least in theory), it would not be wise to create executables since these would be fixed to one specific toolkit. Therefore, in the current version, grapefruit-example provides a toolkit-independent library. To run an example, start GHCi and type the following:
+
<blockquote><p><code>import Graphics.UI.Grapefruit.Circuit</code><br /><code>import Graphics.UI.Grapefruit.''UIBackend''</code><br /><code>import Examples.Grapefruit.''Example''</code><br /><code>run ''UIBackend'' mainCircuit</code></p></blockquote>
   
<blockquote><p><code>import Graphics.UI.Grapefruit.Circuit</code><br /><code>import Graphics.UI.Grapefruit.''YourToolkit''</code><br /><code>import Examples.Grapefruit.''YourExample''</code><br /><code>run ''YourToolkit'' mainCircuit</code></p></blockquote>
+
Replace <code>''Example''</code> with the name of the example to run and <code>''UIBackend''</code> with the name of the UI backend you want to use.
  +
At the moment, the only meaningful replacement for <code>''UIBackend''</code> is <code>GTK</code> and the only meaningful replacements for <code>''Example''</code> are <code>Simple</code> and <code>Switching</code>.
   
At the moment, the only meaningful replacement for <code>''YourToolkit''</code> is <code>GTK</code> and the only meaningful replacements for <code>''YourExample''</code> are <code>Simple</code> and <code>Switching</code>.
+
We do not provide ready-to-use executables since it is possible (at least in theory) to run the examples with different UI backends and an executable would be fixed to a specific backend.
  +
  +
=== Classic version ===
  +
  +
The package grapefruit-examples provides an executable for each example.
   
 
== Documentation ==
 
== Documentation ==
   
Documentation for the current version is currently being written. You can build HTML API documentation by issuing <code>runghc Setup.lhs haddock</code> inside the Grapefruit package directories.
+
=== Released version ===
  +
  +
For the following packages, complete documentation is available on [[Hackage]]:
  +
* [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/grapefruit-frp grapefruit-frp]
  +
* [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/grapefruit-records grapefruit-records]
  +
* [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/grapefruit-ui grapefruit-ui]
  +
* [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/grapefruit-examples grapefruit-examples]
  +
  +
For [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/grapefruit-ui-gtk grapefruit-ui-gtk], only the overiew page is available. The reason is that Hackage cannot build grapefruit-ui-gtk since Gtk2Hs is not installed on Hackage. However, if you have installed Grapefruit as described above, you have the documentation locally installed (under $HOME/.cabal/share/doc/ under UNIX-like systems).
  +
  +
=== Current development version ===
  +
  +
You can build the documentation by issuing <code>runghc Setup.lhs haddock</code> inside the Grapefruit package directories.
  +
  +
=== Classic version ===
  +
  +
There is only little documentation of the classic version and there are no plans to change this situation. So you will have to live with what is there. If you have questions, you may always ask the author of Grapefruit as listed in the *.cabal files.
   
There are no plans for providing complete API documentation for the classic version. You will have to live with what’s there. If you have questions, you may always ask the author of Grapefruit as listed in the *.cabal files.
+
To build the documentation, issue <code>runghc Setup.lhs haddock</code> inside the Grapefruit package directories.
   
 
== Publications and talks ==
 
== Publications and talks ==
Line 83: Line 83:
 
== Screenshots ==
 
== Screenshots ==
   
Following are some screenshots from the examples of the classic version:
+
Below are some screenshots from the examples of the classic version. The Simple example is also available in the released version (along with the Switching example, not mentioned here).
 
;Simple
 
;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.
 
: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.

Revision as of 11:54, 14 February 2009


Contents

1 About

Grapefruit is a library for Functional Reactive Programming (FRP) with a focus on user interfaces. FRP makes it possible to implement reactive and interactive systems in a declarative style. With Grapefruit, user interfaces are described as networks of communicating widgets and windows. Communication is done via different kinds of signals which describe temporal behavior.

2 Features

Grapefruit has the following important features:

  • a push-based FRP implementation where signals
    • can be memoized using ordinary variable bindings
    • can be merged without doubling of simultaneous events
    • cannot behave differently by starting them at different times
  • a record system which makes it possible that
    • input signals can be left out to get default behavior
    • output signals can be left out to ignore uninteresting data
    • output signals can be chosen and fetched by pattern matching
  • an abstract UI implementation which can work with different backends which in turn use different toolkits to provide different look and feel with one and the same application code

At the moment, the only supported UI toolkit is GTK+ (via Gtk2Hs). We plan to support Qt in the future, making use of the HQK project’s output.

3 Versions

There is a first official Grapefruit release which is release 0.0.0.0.

Grapefruit underwent fundamental interface and implementation changes before this release. A version from before these changes is available as the “classic” version. In contrast to the released version, the classic version contains support for animated graphics, incrementally updating list signals and a restricted form of dynamic user interfaces (user interfaces whose widget structure may change). These features are expected to come back in future releases.

4 Installation

First, a note for GHC 6.8 users. If you get warnings of the form “Can’t find interface-file declaration for type constructor or class …” when compiling with GHC 6.8 then don’t panic. This seems to be because of a bug in the (non-official) type family support of GHC 6.8. However, it seems to be harmless.

4.1 Released version

You need at least GHC 6.8.3 and Gtk2Hs 0.9.13 to build and use Grapefruit. GHC 6.8.2 can not be used because of GHC bug #1981. Grapefruit was tested with GHC 6.8.3 and Gtk2Hs 0.9.13 as well as with GHC 6.10.1 and a Gtk2Hs 0.10.0.

Grapefruit is released on Hackage. If you do not have special requirements, you can install Grapefruit and its prerequisites as follows:

  1. Install GHC 6.10.1 (see [1]).
  2. Install cabal-install (see [2]).
  3. Insert the line documentation: True into the cabal-install configuration file ($HOME/.cabal/config on UNIX-like systems).
  4. Install Gtk2Hs 0.10.0 (see [3]).
  5. Install Grapefruit by entering cabal update, followed by cabal install grapefruit-ui-gtk grapefruit-examples on a command line.

4.2 Current development version

The current development version can be fetched from the darcs repository at http://softbase.org/grapefruit/darcs/main. You can build it by building the individual Cabal packages in the grapefruit-* directories. Note that grapefruit-graphics is currently defunct.

4.3 Classic version

If you want to try out the classic version, please get it from the darcs repository at http://softbase.org/grapefruit/darcs/classic. You can build it by building the individual Cabal packages in the grapefruit-* directories. Alternatively, you can use the Setup.lhs script in the root directory to easily build all packages. You can run the following:

runghc Setup.lhs clean
cleans all packages
runghc Setup.lhs up-to-install configure-options -- build-options -- install-options
configures, builds and installs all packages
runghc Setup.lhs up-to-register configure-options -- build-options -- register-options
configures and builds all packages and registers all library packages (which are all except grapefruit-examples)

The classic version does not work with GHC 6.10.1 and the global Setup.lhs script does not work with newer Cabals.

5 Running the examples

5.1 Released version and current development version

You can run the examples by typing the following lines into GHCi:

import Graphics.UI.Grapefruit.Circuit
import Graphics.UI.Grapefruit.UIBackend
import Examples.Grapefruit.Example
run UIBackend mainCircuit

Replace Example with the name of the example to run and UIBackend with the name of the UI backend you want to use. At the moment, the only meaningful replacement for UIBackend is GTK and the only meaningful replacements for Example are Simple and Switching.

We do not provide ready-to-use executables since it is possible (at least in theory) to run the examples with different UI backends and an executable would be fixed to a specific backend.

5.2 Classic version

The package grapefruit-examples provides an executable for each example.

6 Documentation

6.1 Released version

For the following packages, complete documentation is available on Hackage:

For grapefruit-ui-gtk, only the overiew page is available. The reason is that Hackage cannot build grapefruit-ui-gtk since Gtk2Hs is not installed on Hackage. However, if you have installed Grapefruit as described above, you have the documentation locally installed (under $HOME/.cabal/share/doc/ under UNIX-like systems).

6.2 Current development version

You can build the documentation by issuing runghc Setup.lhs haddock inside the Grapefruit package directories.

6.3 Classic version

There is only little documentation of the classic version and there are no plans to change this situation. So you will have to live with what is there. If you have questions, you may always ask the author of Grapefruit as listed in the *.cabal files.

To build the documentation, issue runghc Setup.lhs haddock inside the Grapefruit package directories.

7 Publications and talks

The following publications and talks are related to Grapefruit:

8 Screenshots

Below are some screenshots from the examples of the classic version. The Simple example is also available in the released version (along with the Switching example, not mentioned here).

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.
Grapefruit-screenshot-Simple.png
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.
Grapefruit-screenshot-Codebreaker.png
CircuitingObjects
This example demonstrates Grapefruit’s support for animations.
Grapefruit-screenshot-CircuitingObjects.png