[Fudgets Home Page]

Fudgets User's Guide

This guide covers various practical details encountered when writing and using fudgets programs. It is a complement to the Tutorial and other material

Writing Fudgets Program

Fudgets programs are written in the lazy functional language Haskell using any text editor.

What to import

To use the stuff defined in the Fudgets Library you should import it. There are three modules you can import:
This interface contains all the stuff useful for normal application programming. The things you find here are the things listed in the Programmer's Index in the Reference Manual.

This interface exports almost everything defined in the library and thus reveals a lot of the undocumented, internal structure that we may want to change in the future. It is intended for the advanced user who perhaps wants to extend the library. This is what you see in the Full Index in the Reference Manual.

This interface exports some additional stuff, contributed by various people. We also put new, experimental stuff here, pending proper integration with the library.

Fudgets Library Naming Conventions


The fudget library uses suffixes to identify some common types of functions and values.

F identifies a fudget or a combinator returning a fudget. Examples:

SP Stream processor I/O operations and combinators. Examples:
  • putSP :: o -> SP i o -> SP i o
  • serCompSP :: SP b c -> SP a b -> SP a c
P Placers. Examples:
S Spacers. Examples:
D Drawing combinators. Examples:
  • blankD, rectD, filledRectD :: Size -> Drawing lbl leaf
  • hboxD, vboxD :: [Drawing lbl leaf] -> Drawing lbl leaf
K Fudget Kernels. (Not used by application programmers).

Dashed names

Often there is a standard version of a function, and a more general version with extra parameters. The name of the more general function is then obtained by appending a ' to the name of the standard function. Often these general functions have one extra parameter, which is a customiser. Examples:

Understanding Infix Plumbing Operators

There are a number of operators for serial and parallel composition of fudgets:
>+< >*< >==< >^^=< >=^^< >^=< >=^<
The two outermost character > and < in these names indicate that the result of the composition is a fudget. (They are supposed to look like the low and high level input and output pins of a fudget).

The characters in the middle mean:

+Tagged parallel composition of two fudgets.
*Untagged parallel composition of two fudgets.
=Serial composition of a fudget with something else

In serial compositions, the characters in the middle indicate what kind of operands are composed. One of the operands is always a fudget, represented by an = (two lines, suggesting the presence of both high and low level streams). The other operand can be a fudget (the operator is >==<) or:

^A function. It operates on one element in the high level stream at a time.
^^A stream processor. It operates on high level streams.
. A function or a stream processor that operates on low level streams. (Not used by application programmers.)

Data flow from right to left in serial compositions, so for example

>=^< :: F b c -> (a->b) -> F a c
is a serial composition of a fudget and a function where the function can be seen as a preprocessor.

Compiling Fudgets programs

Compiling Fudgets programs with ghc

Compiling Fudgets programs is very easy. The Fudgets library is distributed as a Cabal package called fudgets, and assuming it has been installed with cabal install, just compile your program like any other Haskell program.

Other Haskell compilers…

Compiling Fudgets programs with hbc

Compiling Fudgets programs is very easy. The automatic make command
hbcxmake Main
compiles the program whose main module is called Main and located in the file Main.hs. This simple command is sufficient also for large programs consisting of several modules.

If some of your modules import ContribFudgets, you have to add the -contrib flag to the command line:

hbcxmake -contrib Main

Note: The main module must be called Main, but the file containing it can be called anything with the extension .hs, not just Main.hs. (If the module ... where header is omitted from a module, its name automatically becomes Main.)

Running Fudgets programs

Starting Fudgets programs

Fudgets programs are started as any other program: by entering its name in a shell. If the program is called Main, you enter
to run it. You can also supply various flags and arguments. The command line syntax for programs compiled with nhc13 or ghc is
Main [ +RTS runtime flags -RTS] [ program flags and arguments ]
Other Haskell compilers…

The general command line syntax for Haskell programs compiled with hbc is

Main [ runtime flags ] [ - program flags ] [ arguments ]
where the square brackets [ ] indicate optional items. Notice the - preceeding the program flags.

The runtime flags are interpreted by the run-time system and allows you to set the heap size, switch on heap profiling, etc. See the compilers' manual pages for details. The program flags and arguments are available for the Haskell program to read. Flags interpreted by the fudgets library are listed below.

Command line switches and environment variables

Various parameters can be changed by using command line switches or environment variables. Global settings:

-look3d yes/noyesswitches between a slim 3D look and an older 3D look designed for monochrome displays
-ctt yes/noyesuse click-to-type input discipline
-versionnomakes the program print the version of the fudget library and exit
-cache yes/noyesuse font/color/gc cache to reduce communication with the X server
-fg colorblackdefault foreground color
-bg colorgreydefault background color of unused or static areas
-paper colorwhitedefault background in areas displaying text that can be changed by the program or the user
-font fontfixeddefault fixed font
-labelfont fontvariabledefault proportional font
-sep distance5the default distance (in pixels) that separates adjacent user interface elements
-string16bitnocauses text to be drawn with XDrawString16 instead of XDrawString, allowing characters with codes above 255 to be used with 16-bit fonts.
-dialogue-to-stdionosend all IO requests to stdout, expect IO responses on stdin

Flags that affect certain types of fudgets:

Input editors
-inputfg colorfgcolors used by fudgets that allow the user to edit a value
-inputbg colorpaper
-stringfg colorinputfgcolors used by stringF et al
-stringbg colorinputbg
-inputfont fontfontfont used by stringF et al
-editfg colorinputfgcolors used by editorF
-editbg colorinputbg
-selectfg colorinputbgcolors used for selected text in editorF
-selectbg colorinputfg
-undodepth numunlimitedlimit on the depth of the undo buffer in editorF
-buttonfg colorfgcolors for button labels
-buttonbg colorbg
-buttonfont fontlabelfontfont for text in button labels
-shine colorwhite or lightgreycolor of button edges
-shadow colorblack or grey30
-edgew width2 or 4default button edge width (in pixels)
-toggleoff colorbgcolor of the indicator in a toggle button
-toggleon colorfg
-menufont fontlabelfontfont for text in menu labels
-dispfg colorfgcolors used by displayF et al
-dispbg colorpaper
-lblfg colorfgcolors used by labelF et al
-lblbg colorbg
-cursor coloryellowcursor color used by graphicsF et al

The settings above can also be changed using environment variables. The value of a parameter called name is taken from

  1. the command line, if -name value is present, else
  2. the environment variable FUD_prog_name (where prog is the name of the program), if set, else
  3. the environment variable FUD_name, if set, else
  4. a builtin default (indicated in the tables above).
If -name is present on a command line without a value after, the value is taken to be yes.

Interacting with Fudgets Programs

Fudgets is designed create user interfaces with a familiar look and feel, so interacting with Fudgets programs shouldn't be different from interacting with other programs in the X Window system.

Stopping Fudgets Programs

Window managers usually add a button in the window title bar to close programs, so closing Fudgets programs shouldn't be any different from closing other programs in the X Window system.

Some old style X Windows applications (e.g. xfd, xfontsel and xmore) contain a Quit button and some old Fudgets programs might have a Quit button too.

When a program is started from a shell in a terminal window, Control-C can be use to stop it, like other programs.