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:

Fudgets: 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.
AllFudgets: 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.
ContribFudgets: 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

Suffixes

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

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

buttonF :: Graphic lbl => lbl -> F Click Click
loopLeftF :: F (Either loop inp) (Either loop outp) -> F inp outp

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:

verticalP, horizontalP :: Placer
tableP :: Int -> Placer

S Spacers. Examples:

centerS, leftS, bottomS :: Spacer
marginS :: Int -> Spacer

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

Suffix	Meaning
`F`	identifies a fudget or a combinator returning a fudget. Examples: `buttonF :: Graphic lbl => lbl -> F Click Click` `loopLeftF :: F (Either loop inp) (Either loop outp) -> F inp outp`
`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: `verticalP, horizontalP :: Placer` `tableP :: Int -> Placer`
`S`	Spacers. Examples: `centerS, leftS, bottomS :: Spacer` `marginS :: Int -> Spacer`
`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:

buttonF :: Graphic lbl => lbl -> F Click Click
buttonF' :: Graphic lbl => Customiser ButtonF -> lbl -> F Click Click

verticalP, horizontalP :: Placer
horizontalP', verticalP' :: Distance -> Placer

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

`+`	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.)
..

`^`	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

Main

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:

Flag Default Meaning
-look3d yes/no yes switches between a slim 3D look and an older 3D look designed for monochrome displays
-ctt yes/no yes use click-to-type input discipline
-version no makes the program print the version of the fudget library and exit
-cache yes/no yes use font/color/gc cache to reduce communication with the X server
-fg color black default foreground color
-bg color grey default background color of unused or static areas
-paper color white default background in areas displaying text that can be changed by the program or the user
-font font fixed default fixed font
-labelfont font variable default proportional font
-sep distance 5 the default distance (in pixels) that separates adjacent user interface elements
-string16bit no causes text to be drawn with XDrawString16 instead of XDrawString, allowing characters with codes above 255 to be used with 16-bit fonts.
-dialogue-to-stdio no send all IO requests to stdout, expect IO responses on stdin

Flag	Default	Meaning
-look3d yes/no	yes	switches between a slim 3D look and an older 3D look designed for monochrome displays
-ctt yes/no	yes	use click-to-type input discipline
-version	no	makes the program print the version of the fudget library and exit
-cache yes/no	yes	use font/color/gc cache to reduce communication with the X server
-fg color	black	default foreground color
-bg color	grey	default background color of unused or static areas
-paper color	white	default background in areas displaying text that can be changed by the program or the user
-font font	fixed	default fixed font
-labelfont font	variable	default proportional font
-sep distance	5	the default distance (in pixels) that separates adjacent user interface elements
-string16bit	no	causes text to be drawn with `XDrawString16` instead of `XDrawString`, allowing characters with codes above 255 to be used with 16-bit fonts.
-dialogue-to-stdio	no	send all IO requests to stdout, expect IO responses on stdin

Flags that affect certain types of fudgets:

Flag Default Meaning
Input editors
-inputfg color fg colors used by fudgets that allow the user to edit a value
-inputbg color paper
-stringfg color inputfg colors used by stringF et al
-stringbg color inputbg
-inputfont font font font used by stringF et al
-editfg color inputfg colors used by editorF
-editbg color inputbg
-selectfg color inputbg colors used for selected text in editorF
-selectbg color inputfg
-undodepth num unlimited limit on the depth of the undo buffer in editorF
Buttons
-buttonfg color fg colors for button labels
-buttonbg color bg
-buttonfont font labelfont font for text in button labels
-shine color white or lightgrey color of button edges
-shadow color black or grey30
-edgew width 2 or 4 default button edge width (in pixels)
-toggleoff color bg color of the indicator in a toggle button
-toggleon color fg
Other
-menufont font labelfont font for text in menu labels
-dispfg color fg colors used by displayF et al
-dispbg color paper
-lblfg color fg colors used by labelF et al
-lblbg color bg
-cursor color yellow cursor color used by graphicsF et al

Flag	Default	Meaning
Input editors
-inputfg color	fg	colors used by fudgets that allow the user to edit a value
-inputbg color	paper
-stringfg color	inputfg	colors used by stringF et al
-stringbg color	inputbg
-inputfont font	font	font used by stringF et al
-editfg color	inputfg	colors used by editorF
-editbg color	inputbg
-selectfg color	inputbg	colors used for selected text in editorF
-selectbg color	inputfg
-undodepth num	unlimited	limit on the depth of the undo buffer in editorF
Buttons
-buttonfg color	fg	colors for button labels
-buttonbg color	bg
-buttonfont font	labelfont	font for text in button labels
-shine color	white or lightgrey	color of button edges
-shadow color	black or grey30
-edgew width	2 or 4	default button edge width (in pixels)
-toggleoff color	bg	color of the indicator in a toggle button
-toggleon color	fg
Other
-menufont font	labelfont	font for text in menu labels
-dispfg color	fg	colors used by displayF et al
-dispbg color	paper
-lblfg color	fg	colors used by labelF et al
-lblbg color	bg
-cursor color	yellow	cursor 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

the command line, if -name value is present, else
the environment variable FUD_prog_name (where prog is the name of the program), if set, else
the environment variable FUD_name, if set, else
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.