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

Libraries:

Xlib	- an Xlib interface (low level routines)
Xrm	- an Xrm interface (resource manager)
Xt	- an Xt interface (X toolkit)
Xaw	- and 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 <schnetter@student.uni-tuebingen.de>.  This text was
last updated on 1995/02/08.

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 TIME and CLOCK classes:

TIME holds a timestamp with the maximum precision of your system.
CLOCK is a timer that can be started and stopped.

value class 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?

   #TIME
   #TIME (seconds: FLTD)

   GMT: 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: TIME

   TIME::get: TIME		-- get the actual time

   wait_for			-- sleep some time
   wait_until

   for_time!			-- iterate some time
   until_time!



class CLOXK is

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

   #CLOCK
   #CLOCK (time: TIME)

   Reset
   Start
   Stop
   Set (time: TIME)
   Get: 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 (>1.0.4) 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 -debug -only_reachable
cs 3d.sa -o 3d -main MAIN -debug -only_reachable

The '-only_reachable' really speeds things up.  You should use it
every time, unless you want to test code that is not included in your
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
