CHANGES for Wafe 1.0 (relative to 0.97): TABLE OF CONTENTS: o NEWER COMPONENTS o BUG FIXES AND IMPROVEMENTS o NEW FEATURES o NEW GENERAL FEATURES o BETTER SUPPORT FOR ATHENA WIDGET SET o SUPPORT FOR THE GHOSTVIEW WIDGET CLASS o BETTER OSF/MOTIF SUPPORT (version 1.1 and 1.2) o IMPROVED X TOOLKIT SUPPORT (X11R6) o BETTER SUPPORT FOR THE PLOTTER WIDGET SET o IMPROVED DEBUGGING FACILITIES o MORE TCL SAMPLE SCRIPTS o IMPROVEMENTS FOR PERL WRITTEN WAFE APPLICATIONS o SUPPORT FOR EMBEDDING WAFE IN PYTHON For newbies: Appendix 1 contains the summary "What is Wafe". ================================================================== RELEASE NOTES: Differences between Wafe version 0.97 and 1.0 o NEWER COMPONENTS - HTML widget from Mosaic 2.4 (instead of 2.2) - uses xpm 3.4 (instead of 3.2g) - HTML widget of Mosaic updated to work with xpm 3.4 o BUG FIXES AND CODE IMPROVEMENTS + Wafe's C generator produces now slightly smaller and faster C code. + Improved Imakefile and Installation - trying to avoid problems with XCOMM, - auto detecting of OSF/Motif version (only when MOTIF is defined) - new topLevel makefile (TOPMAKE) It can be used to build several variants of Wafe without modifying the Imakefile - The Imakefile is now better commented and contains more useful hints. Many thanks to Jim Wight for his suggestions! - Several #include files have been reconsidered to make Wafe easier portable on various systems based on Stephen Gildea's helpful guide "Writing Portable X Code". - Many file names have been changed in this patch level to comply with the X Consortium file name restrictions (only wafe/src and below). + Several fixes and improvements for the XmGraph widget: - All percent codes in XmGraph callbacks referring to widgets are now substituted by widget IDs - the following percent codes are implemented now: for: newArcCallback, newNodeCallback, arcMovedCallback, nodeMovedCallback, defaultActionCallback, selectNodeCallback, selectArcCallback, deselectCallback, selectSubgraphCallback %A list of selected arcs %N list of selected nodes %I widget ID of node or arc, which is manipulated for: arcMovedCallback %f old "from-Widget" %t old "to-Widget" %F new "from-Widget" %T new "to-Widget" - a few other fixes in connection with multiple reason codes in the XmGraph implementation + A small bug fix in the dbug package from Fred Fish was applied. The bug was triggered by the newly supported commands that allow Wafe to turn debugging on and off at arbitrary times. + Widgets (or objects) which are not children of rectangular objects are now explicitly created unmanaged. Creating these as managed could result in damaged contents of the widgets' instance record. User who had problems with printing from the plotter widgets might check whether these problems are solved after this fix. + The AtLabelAxis widget class (contained in the plotter widgets) did not change the labels on the displayed graph under certain conditions, when they were modified using AtLabelAxisAttachData. This was a bug in the Plotter widget set. + XawSimpleMenuGetActiveEntry returns now Widget-Id instead of widget name + Shells with a "popupCallback ... positionCursor 0" are now always positioned in a way that the whole menu is visible in the screen (relevant for popups close to the screen border) + A bug introduced in Wafe 0.97.p1 has been fixed (Motif version only). The percent code substitution for defaultActionCallback was broken in all widget classes except the XmGraphWidget class. Thanks to Jan Timm for pointing out the bug! o NEW GENERAL FEATURES + There is a new global Tcl variable WAFELIB pointing to the location of the Wafe library (usually /usr/lib/X11/wafe) + If a Tcl procedure with the name "onExit" is defined (without arguments) it will be executed whenever Wafe exits. + Enhanced connectivity options for frontend applications: The new version supports the command line option --S, which can be of the form * example: --S/tmp/wafe.1052-1 * example: --S8853 * example: --Smohegan:8853 If the --S option is used, Wafe establishes during its initialization a socket communication determined by the and connects its standard input and output to the created socket. a) If is of the form , first the application program is responsible to create a unique socket name. Then it calls Wafe with the --S option, passing the socket name to Wafe. Wafe creates the specified unix domain socket (like a server) and waits, until the client application program connects. Wafe will remove the named socket on exit. b) If is of the form , Wafe binds the specified port (like a server) and waits for the application program to connect on it. Note, that the specified port is blocked on the host for the whole Wafe session. c) If is of the form , a simple two phase communication protocol is used to establish the connection. - In the first phase the application program on host binds the specified port (like a server), spawns Wafe (for example using remote shell) with the option --S. Wafe will connect to the specified host and port. - In the second phase Wafe will obtain a new unique port, and establish itself as a sever listening on the new port. The Wafe will send the new obtained port number as a ASCII string to the application program over the primary socket. The application program reads the new port number form the primary socket and will connect to Wafe on the new port number and release the original port number such that another Wafe process can use as well. A sample implementation of an application program exploiting all three types of socket connections is provided in wafe/apps/lang/sock.pl + Some optimizations in pixmap (.xpm) file handling for changePixmap. Pixmaps are now cached and have to be released via 'changePixmap ' where noPixmap can be "None", "ParentRelative", or "Unspecified". o SUPPORT FOR THE GHOSTVIEW WIDGET CLASS When wafe (or mofe) is compiled with ghostview support, PostScript files an be displayed in a Wafe application. Ghostview is NOT shipped together with Wafe, only the code for embedding the widget (wafe/src/GsvGen.{spec,c,tex}) and an Imakefile (wafe/lib/ghostview/Imakefile); see wafe/INSTALL how to compile wafe with ghostview support (it is actually pretty easy). An OSF/Motif sample script using the ghostview widget can be found in wafe/src/tcl/m-ghostview o BETTER SUPPORT FOR ATHENA WIDGET SET + The new version has an output converter for Athena List widget for resource "list" (necessary for [gV somelist list]) + Support for Athena Repeater widget class: A Repeater widget is a subclass of the Athena Command widget class, which executes its callback repeatedly when the button is pressed. The most important additional resources are startCallback, stopCallback and various configurations for timeouts. Supported Wafe command to create a Repeater widget: Repeater See: wafe/src/tcl/repeater.tcl o BETTER OSF/MOTIF SUPPORT + New Commands For mofe (OSF/Motif version of Wafe): The following commands are newly supported for OSF/Motif 1.1: XmCommandGetChild XmSelectionBoxGetChild XmUpdateDisplay The following commands are newly supported for OSF/Motif 1.2: XmChangeColor XmTextDisableRedisplay XmTextEnableRedisplay XmScrollVisible + TearOff menues are supported for OSF/Motif 1.2 For an example look into wafe/src/m-htmlBrowse o IMPROVED X TOOLKIT SUPPORT + Support for Xt's Work Procedures: Work Procedures can be used to implement a simple form of background processing. Most application spend most of its time waiting for input. A Tcl Work Procedure can be registered which will be executed whenever Xt is idle. Unless the Tcl procedure returns 1, it will be restarted automatically when Xt is idle again. See Xt Intrinsics Manual for more details (XtAppAddWorkProc, XtWorkProc) Supported Wafe commands: addWorkProc (returns workProcID) removeWorkProc + Support for X11R6's hook objects: An application may register functions, which are triggered at particular control points in the Intrinsics. These functions are intended to provide notifications of "Xt events" such as widget creation, modification, destroyal etc. X11R6 provides a "Hook Object" with several resources for callbacks (createHook, changeHook, configureHook, geometryHook, destroyHook). In Wafe these resources can be set and read using the standard sV and gV functions. The following percent codes can be used in the callback procedures: %w name of the Widget modified, destroyed etc. %W widget ID of the Widget modified, destroyed etc. %t type of the notification describing what happened Supported Wafe command: hooksOfDisplay returns widget ID of the Hook Object, which can be used for sV, gV, showRes etc. The specified widget determines the display. In case you experience problems in X11R6 with this Wafe function, i have a bug fix for X11R6's Xt, which i submitted some time ago to the X Consortium. I am not sure how soon this (or another fix for the problem) will be publically available from the X Consortium. Another surprise with X11R6 was the following: Wafe compiled with X11R6 is smaller than Wafe compiled with X11R5! + New commands (only available under X11R5 or newer): fallbackResources where is used to determine the resource database (screen or display). The command "fallbackResources" is very similar to "mergeResources" with the only difference that in cases, where a matching resource entry is already available in the resource database, the provided value in fallbackResources is ignored. fallbackResources have the lowest priority. combineFileDatabase where filename is the name of a resource file, is used to determine the resource database (screen or display) and determines whether already loaded resource entries should be overwritten or not. o BETTER SUPPORT FOR THE PLOTTER WIDGET SET The new Wafe version supports now several percent codes for the clickCallback, motionCallback, dragCallback and slideCallback of the Plotter widget class. The returned values can be used to let the user click on bar graphs or to select ranges on axis etc. clickCallback, motionCallback: %x pixel position of the x coordinate %y pixel position of the y coordinate %a position in terms of 1st x axis %b position in terms of 1st y axis %c position in terms of 2nd x axis %d position in terms of 2nd y axis dragCallback, slideCallback: %x lower left x position in pixels of rect. area %y lower left y position in pixels of rect. area %a lower left position in terms of 1st x axis %b lower left position in terms of 1st y axis %c lower left position in terms of 2nd x axis %d lower left position in terms of 2nd y axis %X upper right x position in pixels of rect. area %Y upper right y position in pixels of rect. area %A upper right position in terms of 1st x axis %B upper right position in terms of 1st y axis %C upper right position in terms of 2nd x axis %D upper right position in terms of 2nd y axis o IMPROVED DEBUGGING FACILITIES + Two new commands are now available to change the debugging options during a Wafe session. The commands have the same names as the corresponding MACROS from the dbug library DBUG_PUSH DBUG_POP DBUG_PUSH accepts the same arguments as the --D command line option. For example the Wafe command DBUG_PUSH d:t turns on debug and trace messages; for details concerning the argument string (profiling, etc), consult the manual page in wafe/lib/dbug/dbug.man. o MORE TCL SAMPLE SCRIPTS ... for Athena Widgets: + Example for using Tcl's "trace var ..." facility to control widget resources (cool!) Using Tcl's trace facility it is possible to trigger Tcl commands, whenever these variables are updated (or read or deleted). This makes it for example possible, to define a global variable BACKGROUND, and whenever this variable is modified, the background resources of several widget can be updated See: wafe/src/tcl/repeater.tcl + Simple graphical debugger for Wafe (Tcl code) This is a small debugger for Wafe. It is very experimental and has probably many bugs. it is quite dangerous to try to debug the debugger with itself. However, i found already a bug with it in a 6000 line Wafe application (Tcl part), so other might like to share it, but don't expect that it puts you out of your socks. It was mostly implemented on one rainy Sunday afternoon. Essentially, this debugger supports - call level tracing on + Tcl procedures, + Wafe built-ins, and + global Tcl variables (on read, write, unset) - inspection of the current state of + Tcl procedures and + global Tcl variables The debugger can be called by the Tcl Command "wafeDebug" and should be loaded via autoload. The current version uses the Athena widget set, it should be quite easy to provide OSF/Motif support as well. + Several sample scripts for various types of menues using the Athena widget set menupul1.tcl demonstrating pulldown menu (actually drop-down :) menupul2.tcl demonstrating pulldown menu (without MenuButton) menupop.tcl demonstrating popup menu menucasc.tcl demonstrating cascading menues menuchk.tcl demonstrating checking menu + New in the distribution is a tiny sample program that illustrates how to use the X11R5 Athena's Tree widget class wafe/src/tree.tcl ... for OSF/Motif Widgets: + wafe/src/tcl/m-htmlBrowse: The appearance of wafe/src/tcl/m-htmlBrowse is now Motif Style Guide compliant. Additionally, the following features has been implemented -> m-htmlBrowse jumps on "back" operations to the correct scroll position (instead to the last used anchor). -> search in HTML documents -> scrolling via cursor, -> tear off menus -> reload -> accelerators -> busy watch + New sexy demo for the graph widget: wafe/src/tcl/m-graph-config o IMPROVEMENTS FOR PERL WRITTEN WAFE APPLICATIONS + cosmetical changes in various Perl written sample applications + Several code improvements for xwafemail and xwafenews (some to Tcl procedures rewritten to reduce number of braces needed) + Several improvements in xwafemail * xwafemail has a new "ReplyAll" and a "Update" button. "ReplayAll" puts all addressees of an received mail into the Cc: line for a reply mail, "Update" rewrites the mailbox and removes mail articles marked as to delete. * xwafemail supports now only fastmode (previously option -F) * Ctrl-n can be used for digest-like mails to skip to the next part of the mail starting with dashes. * Adding aliases: The key combination Ctrl-a can be used in received mails to popup a window to add an alias. * Completion of addresses: When a mail is being sent, the Tab key can be used in lines starting with To:, Cc: or Bcc: to expand aliases. Say, there is an alias "joe" defined as "someUser@someHost.someNet", typing joe and pressing the Tab key will expand the alias. In fact, any unique abbreviation of an nickname will be complete. + Several improvements in xwafenews: * Adding aliases: The key combination Ctrl-a can be used in the article window to popup a window to add an alias. * Completion of addresses: When an article is being forwarded, the Tab key can be used in the To: line to expand aliases (see above under xwafemail for more details) * Reduced memory consumption by avoiding to pass large Perl arrays as arguments * New command line option -e (economy mode): In economy mode xwafenews behaves differently in two respects: a) the nntp server is NOT asked, which newsgroups are available b) the newsrc file will never grow. If the newsrc file at startup has say 10 lines, it will stay in this size Background: Here at research we have about 15 thousand newsgroups (no typo), which are transferred during startup from the nntp server and compared against the 15 thousand entries in the .newsrc file. I am watching about 200 newsgroups (roughly 1 percent). In most situations, most of the time and storage is wasted. Here some statistics: option newsgroups memory (Perl) startup (reading groups) standard 15500 56MB 48sec -e 15500 27MB 29sec -e 500 6MB 4sec in my situation the improvement in memory consumption and time spent in preparing newsgroup information is roughly a factor of 10, when -e is used. Information about new newsgroups can be obtained from news.announce.newsgroups. If -e is used, and the option "all groups" is selected on a large newsgroups file, speed is worse than without -e, since xwafenews asks for each group separately which articles are available. o SUPPORT FOR EMBEDDING WAFE IN PYTHON Wafepython is an extension to Python allowing to build python applications with graphical user interfaces based on the OSF/Motif or Athena Widget set. Python is an interpreted, interactive, object-oriented programming language. It incorporates modules, exceptions, dynamic typing, very high level dynamic data types, and classes. Wafepython provides a bi-directional calling interface between Python and Wafe based on strings. Wafepython supports currently the following Python commands: wafe.cmd(string) evaluate string as Wafe command wafe.set(nameString,valueString) set the Tcl variable named in the first argument to the value in the second argument wafe.process_events() start the event processing loop of Wafe (should be the last command in the script) In addition, the following Wafe commands are created during initialization of Wafe to archive the Wafe-calls-Python interface: pythonS pythonE pythonF Four sample scripts (demo1 to demo4) are shipped with wafepython. The first two are for the Athena widget set, the latter are for OSF/Motif. The demo scripts are VERY similar to the scripts provided with wafeperl and do not exploit any sophisticated python functionality. ============================================================================= Appendix 1: WHAT IS WAFE - A CLOSER LOOK Wafe (Widget[Athena]front end) is a package that implements a symbolic interface to the Athena widgets (X11R5) and OSF/Motif. The Wafe ingredients formula reads as: Wafe = Tcl + Xt + WidgetSets + Extensions Wafe can be used for - implementing GUI based frontends - providing a scripting language for the X Toolkit - linkable, string based interface to GUI functionality, relatively easy to use from any programming language When Wafe is used as a frontend, a Wafe application consists of two parts: a front-end (Wafe) and 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) was developed using the extensible TCL shell (cite John Ousterhout), 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 without interaction with the application program. In opposite to the described two process frontend approach, Wafe applications can also be written purely in TCL, or Wafe could be linked to another application program/interpreter which could exploit it's user interface facilities. In the Wafe distribution are sample implementations for embedding Wafe in interpretative languages included, which provide a bidirectional interface from and to Wafe. These are - wafeperl (a version of Perl enhanced with Wafe commands), - wafepython (a version of Python enhanced with Wafe commands), When Wafe is used as a scripting language or for embedding, certainly, only one process is running during execution time. The 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: - xwafedesign: interactive design program for Wafe 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 - xvmstats: system statistics; front-end for vmstat -i - xiostats: io statistics; front-end for iostat -i - 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). HOW CAN WAFE BE USED AS A FRONTEND 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 spawn as a subprocess of wafe and connects its stdio channels with the front end. Lines written from the application program to stdout are read from Wafe. If the line starts with a certain character (such as %) Wafe tries to interpret the remainder of the line as Wafe command (in Tcl syntax). Alternatively the application program could be started by the command "wafe --p app". In most example programs of the distribution the application program is run as a subprocess of wafe, one example (perlwafe) shows the opposite constellation where the "link magic" is not needed. Since Wafe 0.96, the distributed sample Perl programs 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). This is possible without changing the source code of the application program. ADVANTAGES of Wafe - application program can be written in wide range of programming languages - better separation between user interface and application program matters - relatively high level interface to widget applications - single wafe binary for multiple applications - better refresh behavior when application program is busy - click ahead - no need to hack C code - easier migration from existing ascii based programs to X-window applications - various modes and types of operation of Wafe for a wide range of application provided - many widgets sets are supported (Athena, OSF/Motif, XmGraph, Plotter, HTML) 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. AVAILABILITY 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 X11R5 and X11R4. The preferred program-to-program communication is done via socketpair, support for PIPES and SYS V streams is included for systems without the socktepair system call. NECESSARY, BUT NOT INCLUDED Most application of the distribution are written in Perl. Perl 4.036 is needed to run these applications. Two applications will need oraperl. Only user with an Oracle license might find wafeora and wafetel useful. User might wish to compile wafe with the 3d Athena Widget library Xaw3d-0.6.tar.Z. Pointers to the source can be found in the INSTALL file. ACKNOWLEDGEMENT The Wafe project would have been impossible without the availability of software in source form such as - X11R5 distribution from the MIT - TCL and TK (John Ousterhout) - Perl (Larry Wall) - XPM-Library (Arnaud Le Hors ) - dbug-Library (Fred Fish) - plotter widget set (Peter Klingebiel ) - XmGraph (Douglas Young) - Xaw3d (Kaleb Keithley ) - rdd2 (Roger Reynolds ) - oraperl (Kevin Stock ) - ftp.pl package (Alan R. Martello ) - chat2.pl package (Randal L. Schwartz ) - nntp.pl package (Randall S. Krebs) - XMosaic (Marc Andreessen, NCSA) Only the most important packages are listed here. Please check, whether the copyrights of the included packages are applicable in your situation. # Copyright (C) 1992,93,94 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 mailing address neumann@wu-wien.ac.at Thank you in advance. Wafe 1.0 can be obtained via anonymous ftp from ftp.wu-wien.ac.at:pub/src/X11/wafe/wafe-1.0.tar.gz (for people without name server: the ip address is 137.208.3.4) Donations for statically bound binaries of the OSF/Motif version of Wafe (mofe) are accepted. MAILING LIST: In order to subscribe to the Wafe mailing list, send a mail with the mailbody subscribe Wafe help to listserv@wu-wien.ac.at. Postings should be sent to wafe@wu-wien.ac.at.