Index

Wafe - A Programming Environment for X Toolkit Based Applications

Table of contents:

The main ftp archives of Wafe are located at  

WHAT IS WAFE

Wafe (Widget[Athena]front end) is a package that implements a symbolic, string based interface based on Tcl to the X Toolkit, the Athena Widget Set (or the three-D version of the Athena Widget Set Xaw3d), the OSF/Motif Widget Set (versions 1.1 to 2.0) and various complementary widget classes and extension packages.

Using Wafe, one can develop applications with high level graphical user interfaces in the scripting language Tcl, or one can use Wafe mostly as a graphical front-end that provides an easy access to GUI programming for various programming languages.

The newest released version of Wafe is 1.0.19 (see Wafe distribution and patch releases).

Wafe and its Components

The Wafe ingredients formula reads as:
Wafe = Tcl + Xt + WidgetSets + Extensions
where Tcl is John Ousterhout's string based scripting language, Xt is the X Window Toolkit from the X Consortium, Widget sets are either the Athena or OSF/Motif Widget set with supplemental widgets, and extensions are the Xpm library (for providing colored picture labels or colored icons etc), or a drag and drop library, additional converters, memory management a.s.o..

The supplemental widgets supported by Wafe are

  • Kino widget class (embeddable and extensible HTML widget class)
  • Ghostview widget, for displaying postscript files,
  • the Layout Widget, for arranging widgets with TeX-like semantics using boxes and glue
  • Plotter widgets, for business graphics,
  • TVscreen (a widget class to view TV or Videos on a PC)
  • the Xbae widgets (require Motif), containing a widget for labeling purposes (XbaeCaption widget) and a spreadsheet like XbaeMatrix widget, and the
  • Mosaic's Hypertext widget (HTML), for providing hypertext functionality
  • the XmGraph widget (OSF/Motif versions only), for arbitrary, directed or undirected graphs,
  • the Motif Tree Widget (requires Motif), for arranging widgets in a tree structure
  • Eurobridge widget set, for multimedia applications,
  • Analog clock widget for OSF/Motif and Xaw R6 versions,
  • Most of the widget classes of the Free Widget Foundation (FWF; new in Wafe 1.0.17)
  • libWWW (WWW support library by the W3 consortium)
  • LDAP (Lightweight Directory Access Protocol )

Wafe supports a range of graphic formats such as XBM, XPM, GIF, JPEG and PNG. Whenever a widget supports a pixmap all of these graphic formats can be used (for example in the Athena Label or the OSF/Motif XmLabel widget class).

For programming larger projects Wafe supports various object oriented Tcl extensions such as MIT's OTcl (8.0b2) or itcl (version 1.5) .

For a full list of packages and the commands implemented through these packages consult the Wafe package list.

Application Areas for Wafe

Wafe can be used as
  1. a scripting language for the X Toolkit (Xt) from the X Consortium,

  2. a package for implementing GUI based front-ends for applications communicating via standard i/o,

  3. a library linkable from C and other languages to provide a string based interface to GUI functionality, which is relatively easy to use from any programming language.

When Wafe is used as a front-end a Wafe applicaton consits of two processes. When it is used scripting language or for embedding, certainly, only one process is needed for one application during execution time.

(1) Using Wafe as a Scripting Language

The simplest way to use Wafe is to use it as a scripting language. Simple applications can be written purely in Tcl (cite John Ousterhout) syntax. The Wafe package extends the basic Tcl command set various commands interfacing the the GUI functionality. Wafe proper is an extended Tcl interpreter: It sequentially reads and responds to Tcl commands. For example,
   Command my-button topLevel label "Wafe new World!" \
      callback {puts Goodbye; quit}
   realize   
instructs Wafe
  • to construct a "Command" widget (a push button in the Athena widget set) with the following properties:
    • The button is named "my-button",
    • it is placed it on the "topLevel" widget (the main Wafe window, which is automatically constructed by Wafe at startup),
    • it displays the string "Wafe new World!" ,
    • and it responds to user mouse clicks on that button by printing "Goodbye" to stdout before exiting the whole script (command "quit")
  • The "realize" command triggers actual creation of the window on the display: To allow synchronized creation of a collection of related widgets, widget-creation commands are accumulated internally until a "realize" is executed.

When the above script is executed, it appears like the following image on the screen

[wafe-mini]

Whereas the Wafe script above uses the Athean widget set (Xaw or Xaw3d) the script below implements the same functionality using the Motif Widget set instead:

   #!/usr/bin/X11/mofe --f
   XmPushButton c topLevel labelString "Wafe new World!" \
      activateCallback {puts Goodbye; quit}
   realize
When this script is executed it appears like (depending on the default settings for fonts, colors etc. on your installation):

[mofe-mini]

Currently, the full Wafe package is distributed with about 90 sample scripts, about half of it for the Athena Widget set and the other half for the OSF/Motif Widget set.

The sample scripts of the Wafe distribution based on the Athena widgets contain:

  • xy.tcl (a small animated line and bar plot example)
  • filesel (an implementation of an file selector widget in Wafe)
  • puzzle
  • xpm-test (setting shaped color pictures on Labels)
  • xyplot.tcl (sample plot using the plotter widget)

The sample scripts using the Motif widget Set (version 1.2) contain among other examples:

  • m-tetris (a sample implementation of the well known game)
  • m-graph-config (a sample application using the XmGraph widget and shaped pixmaps)
  • m-ghostview (sample application using the Ghostview widget to view a postscript file)
  • m-htmlEdit (an HTML editor using Mosaic's HTML widget)
  • m-matrix (a sample script using the optional Xbae Matrix widget)

The sample scripts using the Motif Widget Set (version 2.0) contain e.g.:

(2) Using Wafe as a Front-End

In addition to the described scripting facilities Wafe is equipped with built-in capabilities that make it realtively easy to use it as front-end for application programs in arbitray programming languages. When Wafe is used as a front-end, a Wafe application consists of two parts:
  1. a front-end (Wafe), and
  2. an application program which runs typically as a separate process.
The application program can be implemented in an arbitrary programming language and talks to the front-end via stdio. Since Wafe (the front-end) is based on a programming language (Tcl), an application program can dynamically submit requests to the front-end to build up the graphical user interface; the application can also down-load application specific procedures into the front-end, which can be executed with or without interaction with the application program. The Wafe distribution contains sample application programs in Perl, GAWK, Prolog, Python, Tcl, C and Ada talking to the same Wafe binary. Most of the following demo applications are implemented in Perl 4.0.36 (for versions of Wafe starting with 1.0.6, Perl 5.0 is supported as well):
  • xwafedesign: interactive design program for Wafe (Athena Widgets) applications
  • xwafeftp: FTP front-end
  • xwafemail: Mail user front-end with faces, using elm aliases
  • xwafenews: NNTP based newsreader, using elm aliases
  • xwafegopher: a very simple gopher interface
  • xdirtree: tree directory browser
  • xprojektor: white board program for the classroom
  • xbm: bitmap and pixmap viewer
  • xwafemc: multiple choice test answering program
  • xruptimes: rwho monitor like xnetload
  • xnetstats: network statistics; front-end for netstat -i <interval>
  • xvmstats: system statistics; front-end for vmstat -i <interval>
  • xiostats: io statistics; front-end for iostat -i <interval>
  • xwafeping: pings several machines an show up-status
  • xwafecf: a simple read only card-filer
  • xwafetel: a simple read only Oracle front-end for looking up telephone numbers
  • xwafeora: a more elaborated Oracle front-end with updates capable to model an entity type with distinct predicate defined subtypes, allowing multi valued attributes (it comes with sample applications "filing management" and "paper base") doing field completion and other funky stuff
  • primfakt.awk: primfakt program in GAWK using wafe
  • primfakt.prolog: primfakt program in Prolog using wafe
  • primfakt.perl: primfakt program in Perl using wafe
  • primfakt.py: primfakt program in Python using wafe
  • primfakt.c: primfakt program in C using wafe
  • primfakt.a: primfakt program in Ada using wafe
  • cprimfakt.c: native C implementation of primfakt (single process, without wafe)
  • xprimfakt.tcl: primfakt program in TCL using wafe (single process)
  • perlwafe: an example program calling wafe as a subprocess of the application program (normally, it is the other way round).

Information and sample screen shots from further applications using Wafe as a front-end can be obtained via WWW for the following items:

  • Wafe Gauge (a Wafe front-end for the SICStus Prolog profiler)
  • Syllog (IBM Research project, Knowledge Based System with DB/2 and Oracle interface, providing explanations of Queries, Form interface, etc.)
Note that these two applications are NOT included in the Wafe package.
REQUIREMENTS FOR APPLICATION PROGRAMS
In order to use Wafe in a two process setup, an application program must be able to write **LINEBUFFERED** (or unbuffered) to stdout (the application program must at least be able to flush the buffer) and to read from stdio. The application program determines the syntax in which Wafe talks back.
HOW WAFE CAN BE USED AS A FRONTEND

In general, all communication between the Wafe front end and the application program is done by sending ASCII text through stdin/stdout pipes connecting the two processes:

     +----------+    text Tcl commands    +----------+
     |          |   -------pipe-------->  |          |
     |   App    |                         |   Wafe   |
     |          |    text responses       |          |
     |          |   <------pipe--------   |          |
     +----------+                         +----------+
The application program does not need to link to any special Wafe libraries: It merely uses normal text I/O commands (such as 'printf()' in C or Perl) to send Tcl commands to Wafe. Some of these commands may create widgets and windows at program startup, and some will pop or hide windows and alter existing widgets as computation proceeds. Some of the widgets will have actions which result in (say) a user button- click action sending a text string to the stdout pipe and thence to the calling app, which may read them using normal text-input commands (such as 'scanf()' in C or 'while (<>) { ... }' in Perl).

The following Perl script shows how the basic mechanism works: The program writes Wafe commands starting with "%" to standard output. When Wafe receives these lines, it strips the leading "%" and interprets the remainder. The commands issued by the Perl script below create a box widget containing two push buttons (Athena "Command" widgets) named "PressMe" and "quit", and a text label (Athena Label widget). When "PressMe" is pushed it sends the string "gimme cookie" to the Perl script. The Perl script reads the output from the "echo" command in the while loop. When it receives "gimme cookie" it changes the contents of the label in the front-end.

 
#!/usr/local/bin/perl
$|=1; # set output line buffered
print 
     "%Box top topLevel\n"
    ."%Command PressMe top callback {echo gimme cookie}\n"
    ."%Label answer top label {} width 200 resize 0\n"
    ."%Command quit top callback {echo quit}\n"
    ."%realize\n";

while(<STDIN>) {
    chop;
    print "%sV answer label {click = " .$i++. "}\n" 
       if /^gimme cookie/;
    exit if /^quit/;
}
Realistic Wafe applications will of course normally have many more widgets, and many more cases for the 'while () {...}' loop to handle, but they will have the same general organization.

When the script above is called "mini.perl", it can be executed with the front-end using the command "wafe --p mini.perl".

However, Wafe supports an even more conveniant way of calling applications using Wafe as a front-end. Suppose you have an application program named "app". If we install a link like "ln -s wafe xapp" and execute "xapp ", the program "app" is spawned as a subprocess of wafe and connects its stdio channels to the front end. Alternatively the application program could be started by the command "wafe --p app".

In most example programs in the distribution the application program is run as a subprocess of Wafe, but one example (perlwafe) shows the opposite constellation where Wafe is run as a sub process of the application program. When Wafe is run as a sub process it is relatively easy for the application program to keep standard I/O connected to the terminal, which makes debugging easier.

Since Wafe 0.96, the distributed sample Perl programs using "wafe.pl " (that are all larger applications) can be started with Wafe on top (e.g "xwafemail" or "wafe --p wafemail") or alternatively with Perl on top by using the -P option ("wafemail -P"). The support library "wafe.pl" makes this is possible without changing the source code of the application program.

(3) Using Wafe for Embedding

Since Wafe can be easily linked with C programs, it can be used as well to provide GUI functionality for other interpretative languages by extending these languages by a few commands. In the Wafe distribution are sample implementations for embedding Wafe in interpretative languages included. These implementations provide a bidirectional interface from and to Wafe (e.g. Wafe calls Perl and Perl calls Wafe). These are

  • wafeperl (a version of Perl (Perl4 or Perl5) enhanced with Wafe commands),
  • wafepython (a version of Python enhanced with Wafe commands),
For further information about wafeperl or wafepython see README.wafeperl or for specific information about the dynamic extensions in Perl 5 see README.wafeperl5.

An example script for wafeperl included in the Wafe package is mp-edit (using Motif and Perl5 as a dynamic extension).

Summary of Wafe Highlights

General:
  • Relatively high level interface to widget application
  • A single Wafe binary can be used for multiple applications
  • No need to use C as development language for Xt-based applications
  • Various modes and types of operation of Wafe for a wide range of application scenarios are provided
  • Many widgets sets are supported (Athena, OSF/Motif, FWF, XmGraph, Plotter, HTML, Xbae, Motif Tree, Ghostview, Layout)
  • Additional non-widgetspecific libraries are supported (libwww, SSLeay, LDAP, etc).

When Wafe is used as a front-end:

  • Application program can be written in wide range of programming languages
  • Better separation between user interface and application program matters
  • Better refresh behavior when application program is busy
  • Click ahead
  • Easier migration from existing ASCII based programs or command line controlled utilities to X-window applications

Availability

Copyright

All of the Wafe sources are covered by the following copyright:
    # Copyright (C) 1992-96 by Gustaf Neumann, Stefan Nusser
    #
    #     Wirtschaftsuniversitaet Wien, 
    #     Abteilung fuer Wirtschaftsinformatik
    #     Augasse 2-6, 
    #     A-1090 Vienna, Austria
    #     neumann@wu-wien.ac.at, nusser@wu-wien.ac.at
    # 
    # Permission to use, copy, modify, and distribute this
    # software and its documentation for any purpose and without
    # fee is hereby granted, provided that the above copyright
    # notice appears in all copies and that both that copyright
    # notice and this permission notice appear in all supporting
    # documentation.  This software is provided "as is" without
    # expressed or implied warranty.
Every user is permitted to create derivative work to this program. However, all copies of the program and its derivative works must contain the above copyright notice. We would like to ask every user to supply a copy of any change, enhancement or derivative work to the email address:
neumann@wi-inf.uni-essen.de
Thank you in advance.

Note that Wafe copyright covers only the core system of Wafe. Wafe can be configured to use several other packages and libraries which might have different copyrights. Please check, whether the copyrights of the included packages are applicable in your situation.

Platforms

Wafe was developed originally on DECstations 5000/200 under Ultrix 4.2 using X11R5, and has been tested on a SparcStation 1+ under SunOS 4.1, RS6000/320 under AIX, on a HP 9000/720 under hpux 8.05 and under Linux 1.0. Wafe can be compiled under X11R4, X11R5 or X11R6.

Source Code Distribution

Wafe 1.0 can be obtained via anonymous ftp from

ftp.wu-wien.ac.at:pub/src/X11/wafe/wafe-1.0.tar.gz
(the ip address of the ftp server is 137.208.8.9).

References to the current patch levels, version numbering and some recent binaries of Wafe can be found in README.wafe-patches.

A few questions concerning mostly compilation problems are described in ftp.wu-wien.ac.at:pub/src/X11/wafe/INSTALL-FAQ.

Donations for statically bound binaries of the OSF/Motif version of Wafe (mofe) are accepted (please contact neumann@wu-wien.ac.at).

Additional packages

Useful packages not included in the Wafe distribution

Most application programs of the distribution that are using Wafe as a front-end are written in Perl. Perl 4.036 is needed to run these applications (starting with Wafe version 1.0.6 both Perl4 and Perl5 are supported).

More than 50% of the Wafe C-sources are generated by a Perl written C code generator. If a Wafe developer wants to modify Wafe, it is likely that the will need Perl to regenerate some code.

Two applications included in the Wafe distribution will need oraperl. Only user with an Oracle license might find wafeora and wafetel useful.

There are many more packages supported by Wafe. For a listing of these packages (with a short discription an a link to the source) consult the supplemental package list .

Further Readings

  1. Wafe Presentations:

  2. Widget set and toolkit handbooks:

    As stated above, Wafe is based on X11 and its standard Xlib and X Toolkit which are since many years part of the X11 core distribution. For developing Wafe applications, primarily the following Postscript manuals might be helpful. These manuals are from the unpacked X11R6 distribution from ftp.x.org or from one of its mirrors.

    Note that these manuals are written for the C programmer and that many of the details are not relevant to Wafe users. However, at the same time, these manuals are the primary source of the meaning of the library routines and the meaning of most of the technical concepts.

    • X Toolkit: This is the primary description for the general widget handling; it is independed from the widget set.

    • Xlib: Some lower level commands in Wafe, which are manipulating Windows rather than widgets, are based directly on the Xlib (such as bell, raiseWindow, ...)

    For versions of Wafe using the Athena Widget Set (or derivatives such as Xaw3d) the following documentaion might be useful:

    For users of Wafe versions based on the OSF/Motif Widget Set, please refer to the OSF/Motif Reference Manual and Programming Manual (e.g. from O'Reilly). Up to my knowledge, there is no freely available PostScript version of Motif manuals around. In case I am wrong, please contact me.

Mailing list

In order to subscribe to the Wafe mailing list, send a mail with the mail body
       subscribe Wafe <Your Name>
       help
to listserv@wu-wien.ac.at. Postings should be sent to wafe@wu-wien.ac.at.

Acknowledgements

The Wafe project would have been impossible without the availability of software in source form, in particular the following packages
  • X11R5 and X11R6 distributions from the X Consortium
  • Tcl (John Ousterhout)
  • Perl (Larry Wall)
  • XPM-Library (Arnaud Le Hors <lehors@sophia.inria.fr>)
  • dbug-Library (Fred Fish)
  • plotter widget set (Peter Klingebiel <klin@iat.uni-paderborn.de>)
  • XmGraph (Douglas Young)
  • Xaw3d (Kaleb Keithley <kaleb@x.org>)
  • rdd2 (Roger Reynolds <rogerr@netcom.com>)
  • oraperl (Kevin Stock <kstock@gouldfr.encore.fr)>
  • ftp.pl package (Alan R. Martello <al@ee.pitt.edu>)
  • chat2.pl package (Randal L. Schwartz <merlyn@ora.com>)
  • nntp.pl package (Randall S. Krebs)
  • XMosaic (Marc Andreessen, Eric Bina, former NCSA)
Only the most important packages are listed here.

Contributors:

Wafe was developed by Gustaf Neumann and Stefan Nusser and is now maintained by Gustaf Neumann.

The following people have contributed to Wafe

  • Anthony Baxter (anthony@aaii.oz.au)
  • Dov Grobgeld (dov@menora.weizmann.ac.il)
  • Fredj Dridi (dridi@nestroy.wi-inf.uni-essen.de)
  • Christian Holzbaur (christian@ai.univie.ac.at)
  • Werner Horn (werner@ai.univie.ac.at)
  • Natuki ITIMARU (itimaru@lang.ai.kyushu-u.ac.jp)
  • Eckhart Köppen (koeppen@nestroy.wi-inf.uni-essen.de)
  • Pierre Laplante (laplante@crim.ca)
  • Peter Ludemann (peter.ludemann@imi.kdsi.com)
  • Thomas Mohr (mohr@lts.sel.alcatel.de)
  • Jeff Prothero (jsp@betz.biostr.washington.edu)
  • Ernie Rael (ernie@maspar.com)
  • Wayne Scott (wscott@ichips.intel.com)
  • Peter Sylvester (peter.sylvester@edelweb.fr)
  • Jim Wight (J.K.Wight@newcastle.ac.uk)

Gustaf Neumann
neumann@wi-inf.uni-essen.de