
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 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, 
       - autodedecting 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 patchlevel 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 refering 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 explicitely 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 WidgetId 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)
 


 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<socketString>, which can be of the form

       *  <socketName>
          example: --S/tmp/wafe.1052-1
       *  <port>
          example: --S8853
       *  <hostName:port>
          example: --Smohegan:8853
     
     If the --S option is used, Wafe establishes during its
     initialization a socket communication determined by the
     <socketString> and connects its standard input and output to the
     created socket.

     a) If <socketString> is of the form <socketName>, 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 <socketString> is of the form <port>, 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 <socketString> is of the form <hostName:port>, a simple two
        phase communication protocol is used to establish the
        connection.
         
         - In the first phase the application program on host <hostName>
           binds the specified port (like a server), spawns Wafe (for
           example using remote shell) with the option --S<hostName:port>.  
           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 <port> 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 <widget> <resource> <noPixmap>' where noPixmap can be
     "None", "ParentRelative", or "Unspecified".



 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 <name> <parent> <resource value pairs>
         
      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      <XmCommandWidget>      <Child>
        XmSelectionBoxGetChild <XmSelectionBoxWidget> <Child>
        XmUpdateDisplay        <Widget>

     The following commands are newly supported for OSF/Motif 1.2:

        XmChangeColor          <Widget>        <backgroundColor>
        XmTextDisableRedisplay <XmTextWidget>
        XmTextEnableRedisplay  <XmTextWidget>
        XmScrollVisible        <XmScrolledWindow> <Widget> <leftMargin> <topMargin>

   + 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 <TclCommand>       (returns workProcID)
           removeWorkProc <workProcId>


   + 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 happend

     Supported Wafe command:

           hooksOfDisplay <Widget>

           returns widget ID of the Hook Object, which can
           be used for sV, gV, showRes etc. The specifyed 
           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!



  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 <Options>
        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 "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 serveral 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.

        Essentialy, 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



 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)

   + 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 (-F)

   + ctrl-n can be used for digest-like mails to skip to the next part
     of the mail starting with dashes.


 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 <pythonFunctionName> <arguments>
     pythonE <pythonStatement>
     pythonF <pythonFunction>

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


    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 <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@thyme.jpl.nasa.gov>)
            - 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, 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 <Your Name>
       help

    to listserv@wu-wien.ac.at. Postings should be sent to
    wafe@wu-wien.ac.at.


