
CHANGES for Wafe 0.97 (relative to 0.96):

TABLE OF CONTENTS:

 o NEWER COMPONENTS
 o BUG FIXES
 o NEW FEATURES
 o BETTER OSF/MOTIF SUPPORT
 o BETTER PERL SUPPORT
 o MORE TCL SAMPLE SCRIPTS


 Highlights:

  *  Support for Motif 1.2 Drag and Drop
  *  Support for TCL libraries
  *  Support for implementing widgets in Wafe
  *  New naming conventions (script for smoothing 
     transition from older versions available) 
  *  Hypertext support via the Mosaic 2.2 HTML widget

For newbies: Appendix 1 contains the summary "What is Wafe".

==================================================================
RELEASE NOTES:

 o NEWER COMPONENTS

   - based on tcl 7.3 (instead of 7.0)
   - HTML widget from Mosaic 2.2 (instead of 2.0pre4)


 o SPEEDUPS

   + manageChild and unmanageChild

     Are now implemented using a single Xt call.
     All widgets noted in the argument list have to have the same
     parent widget



 o BUG FIXES

  +  Two fixes in the implementation of the Plotter Widget set 
       - for logarithmic scale axis
       - fixing an initialized variable for sub-ticks
         when autoScale is false

  +  Some fixes for the implementation of the XmGraph widget 
     (arc deletion caused troubles)

  +  A fix for Wafe on DECstations, which avoids aborts for callbacks
     provided in the widget creation command for the Athena List or
     ScrollBar widgets

  +  Now the Tcl variable FILESEARCHPATH is used to locate pixmaps 
     in 'changePixmap' as well; Previously it was only used by 
     the StringToBitmap converter, StringToPixmap converter 
     and to locate .xbm, .xpm or .gif files in HTML texts.

  +  Error messages for invalid widget names:
     Wafe rejects now widget names starting with digits 
     or '-' or '.' or '*'

  +  Updated sample scripts, library files and Perl-written 
     Wafe applications

  +  Wafe's action and callback procedures are now executed
     explicitly as global procedures, seeing only global variables.



 o NEW FEATURES

   + Support for Tcl libraries 
     (available via auto loading)
         
        Commonly used Tcl idioms, convenience procedures,
        configuration files etc. can be loaded dynamically
        from the Wafe Tcl library only by referencing library
        procedures in the source file; the new naming conventions 
        (see Appendix 4) resolved a name clash between the 
        Tcl command "list" and the command to create an Athena
        list widget were a prerequisite for Tcl libraries.


   + Support for widget classes implemented in Wafe

        New widget classes can be created in Tcl. Typical
        usages are 

          - specialized composite widget classes 
            (eg. a file selector widget class), or

          - specially reconfigured predefined widget classes
            (eg. a password entry widget class which is
            implemented using the Athena text widget class)

        The following example Classes based on the Athena
        widget set are distributed together with Wafe:
           
            PwdEntry
            WarningDialog 
            InformationDialog 
            QuestionDialog
            MessageDialog 
            FileSelection 


   + Alternative ways to reference widgets in Wafe applications
         
        Previous versions of Wafe used solely names and 
        widget paths consisting of names, "*" and "." to reference
        widgets in the applications widget tree. 

        Now, additionally 
          - widget IDs (truly unique identifiers) and
          - widget paths starting with an widget ID 
            followed by widget names, "*" and "." can be used
            (anchored widget paths)

        Several Wafe built in commands have been changed to
        return widget IDs instead of widget names to avoid
        ambiguities which were possible in older versions.
        affected commands are:

	   [gV ... children] 
           [popupChildren ...] 
	   XmFileSelectionBoxGetChild 
           XmMessageBoxGetChild
 
        Each widget creation command returns now a unique 
        widget id.
       

   + New General Commands:

	waitForVariable <tclVarName>

	    This command can be used to "wait" in a Tcl command
            until a Tcl-variable is set (eg. from a callback or
            action routine). "waitForVariable" is commonly used
            for synchronization tasks (delaying or suspending). 

            In a sequence
                cmd1; waitForVariable x; cmd2
            Wafe suspends until the Tcl variable x is set (via
            callback procedures, actions or handlers). When
            x is set, cmd2 is executed.

            In a first step, waitForVariable unsets the
            specified GLOBAL Tcl variable and enters a new event
            loop. This "inner" event loop will be left, when the
            specified variable is set.  The return value of
            waitForVariable is the value of the specified
            variable.

            The sample wafe script 2nd-level.tcl illustrates the
            usage of waitForVariable.


	processPendingEvents

            The command processPendingEvents can be used within
            in a Tcl procedure to process all pending events and
            to continue later in the same point in the procedure;
            for example, this can be useful for refreshing the
            screen while computing heavily in Tcl. Another
            application area for this command is wafeperl/
            mofeperl where the use can force screen refresh
            etc. while computing in Perl. Note, that also
            callback or actions procedure might be triggered by
            this command, which might issue arbitrary Wafe
            commands.


        getApplicationResource <baseWidget> <resourceName> <resourceClass>
            
            This command can be used to obtain values from the
            Xt's resource database. On success the return value
            is the resource value, on failure, an empty string
            is returned. 

            Example: 
               the following resources are used for myApp

                  myApp*printCmd: mp | lpr -pPs

               myApp issuses the following command:

                  set cmd [getApplicationResource topLevel \
                         specificPrintCmd printCmd]
            
               cmd will be set to "mp | lpr -pPs"


        fontHeight Widget fontResource 

            returns the height of a font in pixels. The font is
            taken is taken from the given fontResource of the
            given widget.


        nameToWidget <widgetRef> <widgetPath>

            this command is the Tcl binding for XtNameToWidget
            and can be used to search for a widget specified in 
            "widgetPath" in the widget tree under "widgetRef".
            If the command succeeds, the widget ID is returned,
            otherwise 0.


        window <widgetRef>

            returns the window id of the specified widget

     
        popupChildren Widget

            this command is similar to [gV Widget children] of a
            composite widget, but it returns the list of popup
            Shells (eg: TransientShells) which are created as
            children of the given widget. Popup shells are not
            required to be children of composite widgets. If a
            widget has no popup children an empty list is
            returned.


        alias newCommand oldCommand

            can be used to register an alternate name
            (newCommand) for an existing command (oldCommand).


        addInput <fileno> <read|write|except|none> <TclVariable> <TclCommand>

            This command can be used to add an additional input
            handler or exception handler. If used with "read" as
            2nd argument, each time when data is ready the data
            is read and APPENDED to the specified TclVariable.
            and TclCommand is executed. addInput returns an
            inputId (see below)

            Note that the amount of data read might depend on
            the buffering of the operating system. If only the
            newly read data should be kept in the TclVariable,
            TclCommand should set it empty after processing its
            contents.

            If fileno corresponds to an open file, a busy loop
            is likely to occur. See wafe/src/tcl/addInput.tcl
            for an example.

	    As shipped, 16 additional input handlers can be
            added by the application program. Increasing this
            number needs recompilation.


       removeInput <inputId>

            removes an input added by addInput. inputId is
            returned from addInput.


       fileno <string identifying file> <read|write>

            The function fileno returns for the file opened by
            using tcl's open command the file descriptor.  For
            pipes the file descriptor might be different for
            reading or writing


       installAccelerators <destinationWidget> <sourceWidget>
       installAllAccelerators <destinationWidget> <sourceWidget>
       
            These commands can be used to bind events occurring
            in one widget (destinationWidget) to actions
            occurring in another widget (sourceWidget). For this
            purpose an translations table (a resource named
            'accelerators') has to be installed (via sV) in the
            sourceWidget before installAccelerators (or
            installAllAccelerators) is issued.

            installAccelerator installs the accelerators from
            sourceWidget to targetWidget.  installAllAccelerator
            installs all accelerators from sourceWidget and its
            descendants targetWidget
       
            Note: Earlier versions of Wafe used a version of
            installAccelerators with three arguments (where the
            last argument was the acceleration table). The new
            version conforms now exactly to the Xt manuals. The
            accelerators can be conveniently specifies using
            resource mechanisms (mergeResources or defaults
            files).

            If your applications need backward compatibility,
            add the following script to Wafe's tcllib:

                rename InstallAccelerators newInstallAccelerators
                proc installAccelerators {source dest accelerators} {
	           sV $source accelerators $accelerators
	           newInstallAccelerators $dest $source
                }


   + Removed obsolete Commands:

      asciiTextAppend Widget Text

            This command can be easily implemented by the
            following Tcl procedure:

            proc asciiTextAppend {widget text} {
               sV $widget string [gV $widget string]$text
            }

      simple
           this command could be used to create widgets of the
           Athena class Simple, which is primarily intended to
           be used for subclassing.



   +  Built-in support for shells popping up centered over the
      cursor. 

        callback <SomeShell> popupCallback positionCursor 0

      defines that <SomeShell> will pop up centered over the cursor,
      while

        callback <SomeShell> popupCallback positionCursor 10

      defines that <SomeShell> will pop up with an offset -10/-10
      from the actual cursor position (old behavior)


   +  New Percent codes in actions and callbacks:

        %W  is substituted by Widget IDs in actions and 
            callback procedures


   +  More percent code substitution in action procedures:

         %S for "state" in Key, Button or Motion events 
         %p for Message-actions 

      example:

        setWMProtocols topLevel WM_DELETE_WINDOW
        action topLevel override {<Message>WM_PROTOCOLS: \
            exec(puts stderr {the protocol is <%p>!})}

      %p will be replaced by the string name of the window manager
      protocol (eg. WM_DELETE_WINDOW).

      For an example usage in a wafe script see: 
          wafe/tcl/m-wm-message


   +  Updated Imakefile to produce libraries that make 
      compilation of c programs accessing directly wafe
      components easier (eg.: wafeperl and mofeperl)


 o BETTER OSF/MOTIF SUPPORT

   + Support for OSF/Motif 1.2 Drag and Drop
     (needs Motif 1.2 to compile, Motif 1.2 features
     will only be used when MOTIF12 was specified in
     the Imakefile); 

     For more details, see Appendix 2: 
     "Motif 1.2 Drag-and-Drop"


   + If mofe is compiled with the -DMOTIF_EDITRES flag
     X11R5's editres protocoll can be used to view
     the widget tree of all mofe applications and
     to change resources using editres.

     The flag -DMOTIF_EDITRES is set in the Imakefile.
     Note that it could only be used with a X11R5 toolkit.
     If mofe is compiled with an older toolkit this
     flag should be removed. The Imakefile shipped with
     Wafe has this flag defined.


   + More output converter for OSF/Motif data types (eg. for
     textPosition,  verticalPosition and horizontalPosition, etc).


   + New Commands For mofe (OSF/Motif version of Wafe):

     The following commands are for Drag and Drop support 
     of Motif 1.2:

        XmDragStart
        XmDropSiteRegister
        XmDropSiteUpdate
        XmDropSiteUnregister
        XmDropSiteStartUpdate
        XmDropSiteEndUpdate
        XmDropTransferStart


   + Secondary resources are now evaluated by Wafe (e.g. Motif's
     VendorShell widget class will have now more resources available
     from Wafe; example: "deleteResponse" for wm interactions) (many
     thanks to Gabe Beged-Dov for this suggestion)




 o BETTER PERL SUPPORT

   + cosmetical changes in various Perl written sample 
     applications

   + Faster startup of Perl written Wafe applications:

     Since the support functions for the Athena Text widget have
     been moved from wafe.config to wafe's tcllib, a shorter startup
     file will be read, startup time will be improved.

   + wafeperl is distributed together with Wafe

     wafeperl allows to build a Perl binary with Wafe support


 o MORE TCL SAMPLE SCRIPTS

   ...  for Athena Widgets:

        2nd-level.tcl   
            sample script for 2nd level event loops and 
            waitForVariable

        accelerator.tcl  
            sample script using accelerators

        htmlForms.tcl   
            sample script to demonstrate
            how to htmlForms could be used in wafe

        menu.tcl        
            pull down menus in wafe


   ... for OSF/Motif Widgets:

        m-dnd-simple     
            simple Motif 1.2 drag and drop example

        m-dnd-slider     
            a slightly more sophisticated Motif 1.2 
            drag and drop example

        m-event          
            an event tester for mofe demonstrating
            percent codes in actions

        m-htmlForm
            show usage of html forms under OSF/MOTIF

        m-wm-message
            example for decoding wm-messages 


   ... for Athena Widgets and OSF/Motif Widgets:

        htmlBrowse
            The new version of the HTML widget supports option
            menus, selection lists, one of many toggles, etc.

            In order to step through the example set of html
            forms issue the following commands:

                 1) cd wafe/src/tcl
                 2) ./htmlBrowse html/example-1.html

            The command (2) can be used to examine 12 examples
            by clicking on the hypertext links at the bottom
            of the forms.  These examples are straight from
            ncsa, the text might not always be appropriate.

            The example usage above assumes that you are using
            the Athena version (wafe). If you want to use the
            OSF/Motif version of Wafe (mofe) instead, one can
            issue

                 2) ../mofe --f ./htmlBrowse html/example-1.html

            Currently the Athena of the HTML widget does not
            support multiple selections in a selection list,
            since the the Athena List widget supports only
            single selections.


        tailf 
            implementation of something like the unix command
            "tail -f" in wafe. This script can be executed by
            wafe and by mofe.
                                     

 o TCL LIBRARY FILES

    XawText.tcl     
            support functions for the Athena Text widget

            The following support function for the Athena Text
            widget class have been added to the wafe library:
  
               XawTextRead, XawTextBackSpace, XawTextDelLine,
               XawTextGetChar, XawTextGetCurrentLine, XawTextGetColumn,
               XawTextGotoColumn, XawTextSetCurrentLine, 
               XawTextCopyCurrentLineToNext, XawTextNewlineAndIndent,
               XawTextSmartCloseBrace, XawTextSmartBackSpace
     
            Many of these functions were defined in wafe.config
            in earlier Wafe distributions. The commands above
            have several bugs fixed relative to its
            predecessors. (Thanks again to Dov Grobgeld for his
            input).


    showRes.tcl
            can be using for development/debugging to display
            resources of a given widget. Try 
	       "wafe --e 'Command c topLevel;showRes c;quit'"
            to see the resources of a Command widget

     wafeWidget.tcl 
            library support to create new widgets classes in Wafe

     widget.tcl       
            uniform interface for generic widget related 
            commands; (see Appendix 3)

     Dialogs.tcl 
            sample Dialog Widget classes for Wafe
            (InformationDialog, MessageDialog, QuestionDialog, 
            WarningDialog)

     FileSelection.tcl
            sample FileSelectionWidget class for Wafe

     PwdEntry.tcl
            sample password entry widget class for Wafe


=============================================================================
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.  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 languages
    
    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 (for example,
    wafeperl is a version of Perl enhanced with Wafe commands). 
    In both cases, only one process is needed during execution time.

    The distribution contains sample application programs in
    Perl, GAWK, Prolog, 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.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 TCL
    command.  The standard TCL shell has been extended with new
    commands exploiting the X Toolkit, the Athena widget set,
    the OSF/Motif widget set and the XPM library to build up
    user interfaces with the window system named X.

    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.

    ADVANTAGES of Wafe

      -  application program can be written in wide range of 
         programming languages
      -  relatively high level interface to widget applications
      -  single wafe binary for multiple applications
      -  better refresh behavior when application program is busy
      -  click ahead
      -  better separation between user interface and
         application program matters 
      -  no need to hack C code
      -  easier migration from existing ascii based programs to
         X-window applications



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


    PRERELEASE

    The current distribution is a prerelease (version 0.97). The
    final version (whatever final means) will be posted after we
    got some feedback/suggestions from the network.


    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 0.97 can be obtained via anonymous ftp from

            ftp.wu-wien.ac.at:pub/src/X11/wafe/wafe-0.97.tar.gz

    (for people without name server: the ip address is 137.208.3.4)
    A split up version is available from the same directory.

    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.


======================================================================
Appendix 2:

 Motif 1.2 Drag-and-Drop:
 ========================

 Generally speaking, drag-and-drop allows to pick up some
 information on the screen, move it around, and let it drop into
 another place. Source and target might be in the same application
 or a different one. The following features are only available,
 when Wafe is compiled with Motif 1.2. For older Motif versions or
 the Athena version of Wafe, please use rdd-style drag and drop,
 which is supported by Wafe as well.

 Motif 1.2 supports special 
   - drag-over-effects (the cursor and its color can vary depending 
     on whether it is located over an valid or invalid drop site),
   - drag-under-effects (the widget under the cursor can change its 
     appearance when the drag cursor is within its scope), and
   - drop-effects (successful or unsuccessful drags are visualized)

 In addition to the usual DRAG_COPY operation (an information is
 grabbed on one place and copied to another one) Motif 1.2
 drag-and-drop supports DRAG_MOVE (like DRAG_COPY, but the source
 information is removed) and DRAG_LINK (currently not supported
 from the Wafe interface (since not to well documented))

 The following commands are available in Wafe (mofe) when it is
 compiled with Motif 1.2:

    XmDragStart
    XmDropSiteRegister
    XmDropSiteUpdate
    XmDropSiteUnregister
    XmDropSiteStartUpdate
    XmDropSiteEndUpdate
    XmDropTransferStart

 Motif drag-and-drop creates the following widget/objects
 dynamically there is no need to create these `by hand':

    XmDropSiteManager
    XmDragContext
    XmDropTransfer

 The sample scripts

    m-dnd-simple
    m-dnd-slider

 demonstrate some of the above features. In addition theses scripts
 start with a short documentation (much more compact then the 60(!) 
 pages in the Motif 1.2 programmers guide) how Motif 1.2 Drag and
 Drop can be used.


======================================================================
 Appendix 3:

 widget.tcl
 ==========

 Since the Wafe functionality follows closely the Xt functionality,
 there are a variety of commands that have various argument patters
 originated from c-argument passing and sometime complicated names.
 
 For example for the abstract concept "widget", we can query its
 name, its class, its resource names, its children, its pop-up
 children, whether it exists, and so on. In once case we have to use
 [gV ...] to get the answer, in most cases the result is returned as
 a result of a function, in one case in a variable (Wafe is
 following the Xt argument conventions). I have to admit, it is not
 easy to remember all names, especially if you are a infrequent Wafe
 user.

 In Tcl there is the neat idea of a major and minor command, where
 the major command names an abstract object and the minor command an
 operation. For example for the abstract object string there is a
 [string length ...], [string match ..], [string trim ....]  etc.,
 and and if you don't remember the right command, use "string -help"
 and you get in the error message the list of valid minor
 commands. Other examples are [file MINOR ...] or [info MINOR ...].

 The library widget.tcl implements a similar major/minor approach
 using "widget" as major command. The library defines the following
 commands ($w is always a widget reference, i.e. a widget path or a
 widget-Id):
 
 [widget name $w]   ...... returns name of widget $w if it exists, 
                           "" otherwise

 [widget id $w]     ...... returns the widget ID of $w if it exists, 
                           0 otherwise

 [widget exists $w] ...... returns non-zero if $w exists, 
                           0 otherwise

 [widget class $w]  ...... returns the class of $w, if $w 
                           exists, an error otherwise

 [widget resourceNames $w] returns the list of resource names of $w, if $w 
                           exists, an error otherwise
                           
 [widget path $w]   ...... returns the widget path $w (up to
                           the topLevel) if it exists, 
                           an error otherwise
                           
 [widget parent $w] ...... returns the widget ID of the parent of $w if
                           $w exists, an error otherwise
                           
 [widget children $w] .... returns the list of children of $w in form of 
                           widget IDs if $w exists, an error otherwise
                           
 [widget popupChildren $w] returns the list of pop-up children of $w as widget 
                           IDs if $w exists, an error otherwise
                           
 [widget allChildren $w]   returns the list of children and pop-up children
                           of $w if $w exists, an error otherwise

 [widget names $refs]  ... returns a list of widget names derived from 
                           the provided list of widget references

 [widget ids $refs] ...... returns a list of widget IDs derived form the
                           provided list of widget references


 The major command "widget" is implemented in Tcl and will be loaded via
 auto-load. 
========================================================================== 

 Appendix 4:

 New Naming Conventions (NNC)

 Most of the native command names of wafe/mofe have been changed
 relative to the previous version to solve the name clash
 problem between Tcl's list command and Wafe's command to
 generate a list widget.

 I have to decided not to use the proposed ":" approach to leave
 the use of other Tcl extensions (such as [incr tcl] which uses
 ":" as well to separate class names) open for future
 enhancements.

 Here are the new naming rules:

     1) All widget creation commands
        - start with a capital letter
        - are identical with the widgetClass of the created widget
        - the widgetClass is the value returned by [getClass ...]
          (as a consequence the former Athena asciiText is now called Text)

     2) All widget set specific commands 
        are prefixed with the same prefix 
         - Xaw for Athena widget specific commands,
         - Xm for OSF/Motif specific widgets and commands,
         - At for Plotter widgets and commands

    3) All toolkit and xlib commands have naming conventions
       like all previous wafe releases: 
       - leading X, Xt, XtApp, XtVa prefixes are stripped, 
       - the first character is lowercased

 Background:
 a)  many commands names contain c programming conventions,
     which are meaningless for Wafe user:

        * XtAppAddTimeOut vs. XtAddTimeOut
          Wafe's addTimeOut is implemented using the recommended
          XtAppAddTimeOut, which uses as first argument the
          application context. Wafe supports only one application
          context, which is invisible for a Wafe user.
          we use: addTimeOut

        * example XtSetValues vs. XtVaSetValues
          Wafe's setValues (sV) is implemented using XtSetValues
          but has argument conventions closer to XtVaSetValues
          we use: sV or setValues

        * distinction between xlib commands and Xt commands are
          not important for a Wafe user; in many cases where 
          windows are expected as arguments (typical for xlib commands),
          widgets are passed in Wafe; the distinction between a xlib
          and a command xt command is not important for an enduser, who 
          might ask: "why is it called XBell and XtTranslateCoords".
          we use: bell and translateCoords

 b) consistency: 

        * XtSetSensitive <Widget> <Boolean>
          setBusy <Widget> <Boolean>
          Xt's XtSetSensitive sets a widget and it's children sensitive or
          insensitive, Wafe's own setBusy has same argument structure and 
          busy-fies the specified Widget. Using for one command the name 
          'XtSetSensitive' and the other 'setBusy' is confusing, giving Wafe's 
          setBusy an Xt or X prefix (setBusy is implemented using various Xt 
          and Xlib commands) is misleading.
          we use: setSensitive and setBusy

        * XtDisownSelection and ownSelection
          Wafe's ownSelection differs significantly from XtOwnSelection
          where several function pointers and procedures are involved,
          so we should not call it XtOwnSelection. Using for "Disown"
          the Xt prefix and for "Own" no prefix is confusing.
          we use: disownSelection and ownSelection

 c)  Xt and Xlib are the basic underlying mechanism in Wafe, they
     are the true core of Wafe. Replacing these libraries by others 
     is more work than replacing Tcl by another interpreter. Xt and Xlib 
     will be used always in Wafe. Naming conflicts will be highly unlikely 
     since each additional widget set will have its own prefix. 


 We provide two migration tools to change older wafe applications 
 scripts to the new naming conventions:

     a) auto aliasing of old naming conventions to new ones:
        the Tcl library of wafe has a subdirectory called bc 
        (backward compatibility) which provides name automatic 
        aliasing: if an old name is used a warning message is 
        displayed and the new name is used instead. The warning
        message is displayed only once for each command. 

        Example: if you execute the following script

           !#/usr/bin/X11/wafe --f
           command c topLevel label "Hello World"
           realize

        the warning message
           ** alias command Command
        will be displayed and "Command" will be executed
        instead of "command"

        Note1: automatic name aliasing requires
          1) the standard Tcl library (not Wafe specific); 
             As shipped this library will be installed in
             /usr/local/lib/tcl; this default directory name can 
             be altered during compilation of tcl. At runtime of 
             Wafe, the environment variable TCL_LIBRARY could be used
             to point to to this library if it is on a different place.

          2) the Wafe specific Tcl library
             (the standard location as distributed is /usr/lib/X11/wafe, 
             the standard location can be altered in wafe/src/Imakefile,
             the environment variable WAFELIB can be used to point
             at runtime to a different place)

        Note2: auto aliasing works only for undefined commands, so it
             will not automatically map the old "list ....." to "List ...."
             you will have to change this command by hand or by using
             renameCommands (see next item)

     b) wafe/src/renameCommands

        This is a small Perl script that expects a wafe program as 
        single command line argument (i.e. perl-script, wafeperl/mofeperl
        script or a pure wafe/mofe script) and changes command names
        from the old naming conventions to the new ones. 
     
        renameCommands makes first a backup copy of the old script
        (adding .bak to the name of the old script) substitutes commands
        and writes to a new file with the same name. at the end the
        renameCommands displays the differences between the old and the new
        script.

        note1: renameCommands is a simple minded script to support
               the renaming transition. it is far away from being 
               perfect. In particular, watch out for occurrences of

               - Label   (using the old naming conventions "label"
                         is both a command to create an instance
                         of the label widget class and a resource 
                         name)
               - Form    (some scripts use form as widget name)

               renameCommands changes short names (up to 5 characters,
               where unintended changes are likely) more carefully 
               by checking whether the command is not preceded by a
               $ or { (Tcl variables or arguments) and verifying that
               the following word starts with a character (this will 
               handle for example 'command c topLevel label "xxx"' 
               correctly by not changing the resource name 'label')

        note2: renameCommands reads the information about old and
               new naming conventions from $WAFELIB/tcllib/bc. 
               if tcllib is not installed in /usr/lib/X11/wafe,
               set the environment variable WAFELIB to the right
               directory. If you have not installed wafe at all,
               you might set WAFELIB to the src directory of Wafe
               (<SOMEPATH>/wafe/src).


