This file contains general information for several Sather libraries
and demo programs.

Libraries:

Xlib	- an Xlib interface (low level routines)
Xrm	- an experimental Xrm interface (resource manager)
Xt	- an experimental Xt interface (X toolkit)
Xaw	- an experimental Xaw interface (Athena widget set)
Time	- a timer class
Math	- easier access to mathematical functions.

Demos (not for watching them, but for looking at the source code):

mandelbrot.sa	- calculates and displays Mandelbrot's set
3d.sa		- a very simple ray tracer
hello.sa	- basic widget handling

If you have questions concerning this file, the libraries, or the demo
code, mail to <erik.schnetter@student.uni-tuebingen.de>.  This text was
last updated on 1995/04/27.

The file INSTALLING describes how to install the libraries on your
system.



------------------------------------------------------------



The Math library:

The current Sather syntax for invoking a library function such as sin
is <expression>.sin:

class MAIN is
   main is
      #OUT + (1.5).sin + "\n";
   end;
end;

To people not used to the object oriented notation, this seems to be a
rather peculiar way of expressing things.  If you don't want to get
used to this syntax, then you may do the following:

class MAIN is
   include MATHFLT;
   main is
      #OUT + sin(1.5) + "\n";
   end;
end;

where MATHFLT defines all the functions for FLT expressions.



There are several classes yoy may include:

MATH: everyting

MATHI, MATHF, MATHC: integer, float, and complex functions

MATHINT, MATHINTI,
MATHFLT, MATHFLTD, MATHFLTX, MATHFLTDX, MATHFLTI,
MATHCPX, MATHCPXD, MATHCPXX, MATHCPXDX, MATHCPXI,
MATHCPX{ <FLT-type> }: for the corresponding types only

(There are some other classes defined in this package.  Do not use any
of these classes.  These are for internal use only.)

These classes are intended for including only.  They do not define any
attributes.  It does not make sense to define objects of these
classes.

When optimizing, the Sather compiler can easily get rid of the
overhead introduced by these classes.



------------------------------------------------------------



The UNIX_TIME and CLOCK classes:

UNIX_TIME holds a timestamp with the maximum precision of your system.
It uses non-ANSI-C system calls, i. e. it may perhaps not work on your
system.  CLOCK is a timer that can be started and stopped.

value class UNIX_TIME is

   const granularity: INT;	-- 1 tick is 1/granularity seconds

   attr ticks: INTI;		-- ticks since 1970/01/01 00:00:00
   attr timezone: INT;		-- minutes of time west of GMT
   attr dst: BOOL;		-- is daylight saving time active?

   #UNIX_TIME
   #UNIX_TIME (seconds: FLTD)

   GMT: UNIX_TIME		-- transpose self into GMT

   fltd: FLTD			-- seconds since 1970/01/01 00:00:00
   str: STR			-- a string representation

   is_eq, is_neq, is_lt, is_leq, is_gt, is_geq: BOOL
   is_zero, is_pos, is_neg, is_non_zero, is_non_pos, is_non_neg: BOOL

   negate, plus, minus, times, div: UNIX_TIME

   UNIX_TIME::get: UNIX_TIME	-- get the actual time

   wait_for			-- sleep some time
   wait_until

   for_time!			-- iterate some time
   until_time!



class CLOCK is

   UNIX_TIME: TIME		-- time on this clock
   is_running: BOOL		-- is the clock currently running?

   #CLOCK
   #CLOCK (time: UNIX_TIME)

   Reset
   Start
   Stop
   Set (time: UNIX_TIME)
   Get: UNIX_TIME



------------------------------------------------------------



The Sather X routines are supposed to provide an interface between
Sather and the X window system.  This system is quite huge, and these
libraries are not finished yet.

The Xlib interface (providing low-level access) is almost finished.
The data structures are there, but some routines are still missing.
Pre- and postconditions, assertions and exceptions are not complete.
Currently the demo programs are the only test code for the library.

Please feel free to send me comments about the code.



The Xt/Xaw interface is by now barely able to provide the minimum
functionality for a very basic "hello, world!" program.  I am waiting
for the next release of Sather that will fix some problems with bound
routines and abstract types.



Here an example in Sather for the Xlib interface:

class MAIN is
   main is
      [...]
      display ::= #X_DISPLAY;
      display.Open;
      [...]
      window ::= #X_WINDOW (display);
      window.CreateSimple (display, parent, position, size, 2, white, black);
      window.StoreName ("Test - Test - Test");
      window.SelectInput ( |ExposureMask, KeyPressMask| );
      window.Map;
      [...]
      event_handler.HandleNextEvent;
      [...]
      window.Unmap;
      window.Destroy;
      display.Close;
      [...]
   end; -- main
end; -- class MAIN

class MY_EVENT_HANDLER < $X_EVENT_HANDLER is
   ExposeEvent (event: X_EXPOSE_EVENT) is
      pixmap.CopyArea (window, gc, event.r, event.r.p);
   end; -- ExposeEvent

   KeyPressEvent (event: X_KEY_PRESS_EVENT) is
      [...]
   end; -- KeyPressEvent
end; -- class MY_EVENT_HANDLER



Coming with this preliminary version of the library is the demo code
for 'mandelbrot' and '3d'.  They use some of the basic X (and none of
the Xt/Xaw) functions.

How to compile Mandelbrot and 3d:

cs mandelbrot.sa -o mandelbrot -main MANDELBROT -only_reachable
cs 3d.sa -o 3d -main MAIN -only_reachable

The '-only_reachable' really speeds things up.  I use it every time,
unless I want to test (library) code that is not used in the
executable program.

The iters in Sather allow for an almost natural way of doing two
things at once, namely calculating the graphic and answering to the
events sent by X.  It would be even more elegant in pSather.



How to use Mandelbrot:

'mandelbrot' accepts the following options:

-size <width> <height>:
<width> and <height> specify the size of the window that is created.
Both must be integer and greater than zero.  Currently 'mandelbrot'
does not respond to resizing the window while the program is running.

-frame <re-min> <im-min> <re-max> <im-max>:
These four real parameters specify the part of the complex plane that
is displayed.

The program calculates the mandelbrot set and displays it in a window.
Exposure events are handled.  KeyPress Events (pressing a key while
the mouse pointer is in the window) quit the program.



How to use 3d:

'3d' accepts the following options:

-size <width> <height>:
<width> and <height> specify the size of the window that is created.
Both must be integer and greater than zero.  Currently '3d' does not
respond to resizing the window while the program is running.



Of course, these programs could use some major enhancements;
especially the user interfaces.  But as they are only demo programs...



-erik
