[Fudgets Home Page] [Document under
construction]

Fudgets User's Guide

This is perhaps not a complete user's guide, but rather a complement to the Tutorial and other material. It covers various practical details encountered when writing and using fudgets programs.

Contents


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.

SuffixMeaning
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 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: hbcxmake calls the Haskell compiler hbc. To compile with ghc or nhc13 instead, use the commands ghcxmake or nhc13xmake.

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 ommited 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 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 command line syntax for programs compiled with nhc13 or ghc is

Main [ +RTS runtime flags -RTS] [ program flags and arguments ]
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:

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

Flags that affect certain types of fudgets:

FlagDefaultMeaning
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
Buttons
-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
Other
-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

...

Stopping Fudgets Programs

...
[Fudgets Home Page]
4 Oct 2016 18:46 Thomas Hallgren