Re: CLIM on a UX displaying through Motif

[aihaug@AUSTIN.LOCKHEED.COM (Daniel A Haug)]

Here is an approach that I'm about to investigate.  Its not CLIM, but rather
provides a Motif lisp binding that should execute on your UX.

dan haug
Internet: haug@austin.lockheed.com
UUCP:     ut-emx!lad-shrike!aihaug
Phone:    (512) 448-5634
===========================================================================

Received: by gmdzi.UUCP id AA06394; Mon, 16 Jul 90 17:06:42 -0200
Date: Mon, 16 Jul 90 17:06:42 -0200
From: Andreas Baecker <gmdzi!baecker>
To: aihaug@AUSTIN.LOCKHEED.COM
Subject: Info an CLM and GINA
Status: R

=============================================================================

Version 1.0.0 of CLM is now publicly available. Along with CLM comes an 
alpha version of our UIMS GINA and an alpha version of an Interface Builder 
for OSF/Motif and GINA.

The software is available via anonymous ftp. It is stored in the ~ftp/contrib
directory on expo.lcs.mit.edu (18.30.0.212). The distribution consists of
the two files Clm.README.Z and Clm.tar.Z (~500k). The README.Z file is also
appended to this message. Please note that the expo server is unaccessible
between 9am and 6pm.

For people in Europe: We can also provide the software on Sun streamer tapes
in tar format.  Please send us a tape if you want to get the distribution.

===============================================================================
Clm.README
===============================================================================

The Clm.tar.Z file contains

    1. CLM - A language binding for OSF/Motif and Common Lisp Version 1.0.0
       including full documentation and 15 demo applications.
    2. A prototype of the User Interface Management system GINA.
       About 10 demos for GINA including a simple Finder.
    3. A prototype of an Interface Builder (IB) for GINA and OSF/Motif.

This software is publicly available. See the COPYRIGHT files for details.

Please read the abstracts below for a short description of what this software
does. Full documentation (Postscript and LaTeX source) for CLM and GINA is 
contained in the distribution.

CLM is a stand alone package. GINA requires CLM. The IB requires GINA.

To run this software, the following software is required:

    - To run CLM:
      
      1. UNIX, X11R3 or X11R4 server, X11R3 Xlib library (libX11.a),
	 OSF/Motif libraries 1.0 (libXt.a and libXm.a) 
	 and the Motif header files.
      2. Allegro Common Lisp 3.1 or
	 Sun Common Lisp 4.0 + CLX X11R3 (optional) or
	 A Symolics machine with Genera OS and CLX X11R3 (optional)

    - To run GINA and the IB:

      1. All the stuff for CLM
      2. CLX X11R3 (X11R4 has not been tested, but is supposed to work.)
      3. PCL (At least Victoria day PCL 5/22/89)
	 (GINA does't run with the PCL provide by Sun CL 4.0)

This software has been tested on the following configurations:

   - Sun 3 with SunOS 4.0, X11R3/4 server, X11R3 xlib, Motif 1.0,
     and Sun CL 

   - CLM only: Sun 3 with SunOS 4.0, X11R3/4 server, X11R3 xlib, Motif 1.0,
               and Sun CL 
     We havn't tested GINA on Sun CL because we don't have Victria Day PCL
     for it, but we think it works ...
     (Please drop us a note where to obtain PCL !)

   - Sun 4 (Sparc) with SunOS 4.0, X11R3/4 server, X11R3 xlib, Motif 1.0,
     Allegro CL 3.1 and Sun CL (Lucid) 4.0

   - Symolics machines (ask spenke@gmdzi for details) with the Motif server
     and X server running on a Sparc station.

INSTALLATION:
=================

    1. Create a directory for the sources and cd to this directory.
    2. uncompress and unpack the tar file.
    3. Follow the directions in clm/INSTALL and gina/README.
    4. In case of trouble: email baecker@gmdzi or spenke@gmdzi
                           phone +2241 14-2078 or -2642

==============================================================================

CLM -- A Language Binding for Common Lisp and OSF/Motif

Author:
  Andreas Baecker 
  GMD (German National Research Center for Computer Science)
  P.O. Box 1240
  D-5205 Sankt Augustin 1
  Federal Republic of Germany 
  e-mail: baecker@gmdzi

CLM is a language binding for Common Lisp and OSF/Motif.  It consists a
Motif daemon and a Motif server.  The Motif daemon runs on an
arbitrary machine in the network and listens for Lisp processes requesting to
use CLM.  The Motif daemon forks Motif server processes which communicate
with their Lisp processes over a network-transparent TCP/IP connection. 

The Motif server offers the functionality of the X toolkit and the convenience
functions of OSF/Motif on a network-transparent TCP/IP protocol.  A package of
Common Lisp functions provides a high-level interface to this protocol. 

The Motif daemon forks a Motif server process for every application that is
using OSF/Motif.  This enables multiple Lisp processes using Motif to run in a
single Lisp world without getting in trouble with the non-reentrant Motif code. 

Connections to the Motif daemon can be requested even from remote hosts, which
allows client programs running on hardware which is not capable of running X
and Motif (e.g. Lisp machines or Lisp boards) to use OSF/Motif for their user interface.

The Motif server is implemented in C and is designed to be highly portable.  The
system dependent part of the Motif interface is a single Lisp function which is
used to establish a connection between Lisp and the Motif server.  This function
is similar to the CLX function that opens a connection to an X display and is
coded in much the same way.  The functions that read and write to the connection
are coded in standard Common Lisp.  For efficiency reasons, some of these
functions can also be coded in C and can be integrated using a foreign function
interface. 

The Motif server solution is very efficient and results in good performance at
the user interface level.  Redraw operations and geometry management operations
are performed by the X toolkit Intrinsics and the Motif widgets and are handled
locally in the Motif server.  User interaction like browsing through menu items
is also handled by the Motif widgets and requires only the execution of C code. 
Interactions like clicking a push-button lead to the execution of callbacks
and cause an interaction with Lisp. 

Client programs can use the graphics functions of CLX for drawing into
the Motif DrawingArea and DrawnButton widgets. This is achieved by establishing
a second connection to the X server and by directly drawing into the widget's
window using raw CLX calls. 

Communication Between Lisp and Motif
====================================

The communication between Lisp and the Motif server is realized by an 
asynchronous protocol. The protocol can be put into a synchronous mode for
debugging purposes. Errors and warnings are then reported at the moment they
occur.

The communication medium is a UNIX socket. Depending on whether the Motif server
runs on the local host or on a remote machine, the Motif interface automatically
chooses a UNIX domain socket or an Internet socket for communication.

The Lisp process sends commands to the Motif server to create and modify 
widgets. The Motif server sends callbacks to the Lisp process as a reaction to
user actions suchs as moving a scrollbar's slider or pressing a push-button.

A command record consists of a command header and an arbitrary number of 
arguments. The command header contains the opcode and the number of arguments.
Arguments can be any simple Lisp types such as fixnums, strings and symbols. 

A callback has the same format as a command record. The arguments describe
the Lisp function to be called and the arguments that should be passed to
the Lisp function. Additional arguments are provided from the widget's 
call data structure (for example the current state of a toggle-button).

The Lisp process can send commands to the Motif server at any time. This
allows the programmer to work with the Motif server in an interactive manner:
He can create and pop up widgets while a Motif application is already running
and he can interactively modify the widgets of a running application.

Integration of the Motif Widget Classes
=======================================

All Motif widget classes are integrated into the Motif server and can be used in
Lisp applications.  Adding new widget classes to the Motif server is simply
achieved by including their public header files into some of the server's code
modules and by appending the widget's class pointer to the table of known widget
classes.  Additionally, the code that implements the widget class must be linked
with the Motif server.  In rare cases resource converters have to be
implemented, that convert the Lisp representation of the resource values to
their C representation. 

When creating widgets, resources and their values can be specified by keywords
naming the resource to be set followed by the resource value.  The Motif server
already has a build-in set of resource converters for all Motif widget classes.
Most of the resource converters are needed to build a better
interface to the numerous enumerative data types in OSF/Motif: Instead of
fiddling out the integer value for XmHORIZONTAL for a resource of type
XmROrienatation, the programmer can simply type the keyword
:horizontal.  The Motif interface automatically converts this keyword and
calls XtSetValues with the corresponding integer value. 

Fonts can be specified by name and are automatically converted by the Motif
server to a format suitable for use with XtSetValues.  Bitmap resources
are simply specified by their path name and are automatically converted to a
bitmap structure by the Motif server.  Colors are specified as strings (for
example "Light blue") and are automatically converted to color structures
by the Motif server. 

Applications can provide arbitrary complex Lisp structures as client data
for callback functions. To avoid sending these complex Lisp structures to the
Motif server when attaching callbacks to a widget's callback list, the Motif
interface uses a hash function to compute a hash value for the client data.
This hash value is attached to the widget's callback list. When the callback
is executed, the Motif interface uses that hash value to look up the
original client data.

===============================================================================
===============================================================================

GINA - the Generic Interactive Application
==========================================
	
Author: Mike Spenke (spenke@gmdzi)

GINA is an object-oriented application framework written in CommonLisp
and CLOS. It is based on CLM.

The concepts of GINA are described in the file "PAPER". A copy of the
paper including the figures can be obtained from the authors.

Disclaimer
==========

GINA is included here to demonstrate CLM, our CommonLisp/Motif interface.  GINA
comes with about 10 simple demo applications with a complete graphical user
interface.  This experimental version of GINA forms the base to compile the demo
applications.  However, it is not yet very well suited for the development of
new applications.  Especially, there is no detailed and consistent
documentation. 

If somebody wants to make a try anyway, there is the following information available:
- the paper
- the source code of the demos
- the file headers.lisp containing the headers of all GINA classes, methods, ...
  together with a semiformal comment
- the source code of GINA
- the inspector, which can be used to examine the structure of a running 
  application
- the CLM documentation
- the MOTIF documentation 

Compiling and loading GINA
==========================

 1. Start Lisp with the CLX and PCL package (Victora day PCL 5/22/89 !)
 2. Load the CLM stuff
 3. Type (load "load-gina") to compile and load GINA.
	
Testing GINA
============

To test GINA you have to start the toolkit server and then call
	(GINA:MAKE-APPLICATION)
from Lisp.  If the toolkit server and the X server do not run on the local host
you can supply the keyword parameters :TOOLKIT-HOST and :DISPLAY-HOST.  You can
also set the global variables GINA:*DEFAULT-DISPLAY-HOST* and
GINA:*DEFAULT-TOOLKIT-HOST* before calling GINA:MAKE-APPLICATION.  As a result
the empty, generic application is started.  It does not have any special
functionality, but a complete user interface.  Documents of this application can
be saved and reloaded.  The window can be resized and scrolled.  The arbitrarily
placed buttons just beep when pressed. 

Compiling and loading the GINA demo applications
================================================

    1. Load the GINA stuff
    2. Type (load "load-ib") to load the demos.

Testing the GINA demo applications
==================================
There is now a set of simple GINA applications available, the most important of
which is the Finder.  It is similar to the Macintosh Finder but much simpler. 
The Finder is started by the call (GINA:AC).  Again there are keyword parameters
to specify the hosts, where the servers run.  As a result, a window comes up
showing the contents of the current directory.  Therefore, you should change to
the documents-directory before calling the Finder or you have to make a walk
through the directory tree now. 

Once you have reached the documents-directory you can double-click a file name
(or select it and the press the start-button) to launch an application.  There
are application files (xxx.appl) and documents (e.g.  the-s.hello) which belong
to a certain application.  Opening a document implicitly also starts the
corresponding application (you know that from the Mac). 

A short overview of the demos is given in the paper. 

Within all applications you can call the inspector which is part of GINA.  For
example, executing the menu entry DEBUG/INSPECT DOCUMENTS pops up a dialog box
showing the slots of the document object and their current values.  Clicking a
slot you follow pointers to other objects or see more details of lists and other
data structures.  Furthermore, each widget shown on the screen can be inspected
using the so-called inspect-click.  This is control-key plus right mouse button.

The demos "hello" and "graphic-editor" exploit the unlimited undo/redo facility
of GINA.  Instead of executing many undo or redo menu entries you can also pop
up the so called history scroller with the menu entry edit/history-scroller. 
You can now scroll back and fourth in the command history. 

GINA contains so called direct manipulation objects which can be installed in a
view and then can be immediately moved around and resized.  The move and resize
commands are undoable.  This feature is demonstrated by the graphic-editor demo.

Bugs
====
- It is not yet possible to remove entries from the menu bar.  Therefore, e.g. 
the Finder contains some menu entries that make no sense and may lead to
crashes. 

- Printing of documents is not yet fully implemented even though the
corresponding menu entries are available

- sometimes, the automounter on SUNs makes it impossible to reach a directory
with the finder. 

Organization of the sourcefiles
===============================

- The file package.lisp creates the package GINA

- metainfo.lisp contains macros like defginaclass, defginamethod which are
  almost equivalent to defclass and defmethod but which allow additional
  semiformal comments.  These comments are collected and form an information 
  base about the structure of GINA.  For example it is stored which methods 
  have to be overridden when a new application is written.  A browser for this 
  information base is not yet available. 

- globals.lisp contains some global variables

- OS-dependent.lisp contains some operating system dependent routines,
  especially for the file system interface. 

- classes.lisp contains all class definitions of GINA, because they have to be
  compiled first.  This file is automatically generated by a function in
  extract-classes.lisp, which has to be called whenever a class definition has
  been changed.  The class definitions are written down in the different source
  files but are quoted.  The source files are scanned to generate the file
  classes.lisp

- framework.lisp contains the classes APPLICATION and DOCUMENT

- motif-widgets.lisp contains the encapsulation of the MOTIF widgets in CLOS
  objects. 

- dialogs.lisp contains predefined standard dialog boxes

- views.lisp contains the code for the views (drawing areas) and the objects
  which can be installed there and moved around

- commands.lisp contains the framework for undoable commands

- in extract-classes.lisp there is also a utility to extract the headers of all
  GINA classes, methods, functions, ... 

Testing from the editor
=======================

It is possible to call GINA function directly from the editor for debuggin
purposes as soon as one application is running.  To execute code from the
editor, the connections to the X-server and the toolkit-server of a running
process are used.  Therefore, this process has to be arrested as long as the
editor executes the code.  This is accomplished by the macro
with-application-stopped, which has just a body. 

An example:

(with-application-stopped
  (setq box (make-modeless-dialog-box "test" :resize t))
  (make-push-button box "Press me")
  (pop-up box))
	
This code create a dialog box containing a bush button.

Another example:

(with-application-stopped
  (setq box (make-modeless-dialog-box "test" :resize t))
  (setq view (make-view (make-frame box) :width 200 :height 300
			:document (first (document-list *application*))))
  (install (make-direct-manipulation-object 100 100) view)
  (pop-up box))

This code creates a dialog box containing a view with a rectangular object that
can be moved and resized.

Future plans
============

A complete, stable version of GINA, including full documentation is planned
for the autumn of 1990.

===============================================================================
===============================================================================

An Interface Builder for GINA and OSF/Motif
==========================================

The IB can be used to construct dialog boxes for OSF/Motif. It generates Lisp
code which can be used with GINA.

Features:
=========
- Nearly all widget class of GINA can be used in dialog boxes.

- Dialog boxes are constructed bottom-up by first creating the basic widgets
  like buttons and labels etc. and then grouping them together into RowColumns,
  forms etc.

- All relevant widget resources can be set interactively

- Code for new dialog classes and constructor functions can be generated,
  saved, loaded and compiled. This code can be used with GINA applications.

- Unlimited Undo/Redo for most commands (Create, Grouping, Clear ...)

Missing Features:
=================

- Save/Restore/Print of IB documents.

- The Form widget can not be used.

- ... (And many others)

==============================================================================

Loading the IB:
===============

- Start a Lisp image which contains GINA.
- Go to the ib directory.
- Type (load "load-ib") to compile and load the IB.
- Save the image.

Running the IB:
===============

- Start the IB from the Finder. There is a file "interface-builder.appl" in the
  "documents" directory. Double-clicking this file start the IB.
- Alternatively, start the IB by typing 
      (gina:make-application :class 'ib::ib-application)

- The IB then displays a main window with a menu bar, a palette and a work area.

Creating dialog boxes:
======================

- Dialog boxes are created bottom-up: You must first create the basic widgets
  like buttons etc. and then group them together into row-columns etc.

- To create a basic widget: Select "Push Button" in the palette.
  Left-Click into the work area where you want the push-button to appear.

- To create a scrollbar, scale, separator: Select the appropriate entry in the 
  palette. Press the left mouse button where you want the upper left edge of the
  widget to appear. Drag the mouse while holding down the left mouse button
  to where you want the lower right edge to appear. 

- To group widgets together: Select row-column,frame,paned-window or
  scrolled-window from the palette. Select the widgets you want to group 
  together: Click-and-drag a rectangle. You'll get a feedback consisting of a 
  rectangle with dashed borders. All widgets which intersect with this
  rectangle are then selected.

- Widgets and groups can be grouped again to an arbitrary depth.

- Moving widgets: Select the widget. Press the left mouse button near the
  dashed border of the widget and move it while holding the mouse button down.

- resize widgets: Select the widget. Press the left mouse button inside the
  little solid rectangle in the lower right corner of the widget's frame. 
  Resize the widget by moving the mouse poimter while holding the mouse 
  button down.

- Delete widgets: Select all widgets you want to delete. Select "Edit"/"Clear"
  from the menu.

- Undo/redo works for Create/Clear/Move/Resize/Grouping.

- Edit resources: Double-Clicking the left mouse button between the widget's
  border and the dashed frame surrounding the widget pops up a modeless
  dialog box for editig the resources. Shift/Left-Click inside the widget also
  pops up this dialog box.

- Save code: Select "Save" from the "Code" menu entry. This creates a file
  "new-dialog.lisp" in the current working directory.
  Load code: Select "Load" from the "Code" menu entry. This loads the 
  "new-dialog.lisp" file.
  Compile code: Select "Compile" from the "Code" menu entry. This compiles
  the "new-dialogs" file. The select "Code"/"Load" to load the compiled code.

- Instantiate a dialog box: Select "Show"/"Create Instance" from the menu.

- Show code: Select "Show"/... to display the code in a text widget.