0. General Remarks
==================
The Grafix package is far from beeing complete and surely not bug free.
Please keep in mind that I have written the whole code in some months as a
part time job. Several features are of rudimentary functionality but I hope
to improve them step by step. (It depends upon how much time I can afford
for this task). Nevertheless, the basic structure of the system can be
considered as unchanging.

Beta testers and bug reports are wellcome, also improvement suggestions.
However, I cannot make ports to other platforms. If a user intends to do
this I will offer my support.
Feel free to ask me if you have problems, questions about any part of the
system.
This text "HOWTO" is also not yet complete. As with the whole package it
will be completed step by step.

My Email address is :
                          wolf@first.gmd.de
  
1. Demonstration Programs
=========================

The look at the demos in most cases enables a much faster understanding of the
imbedded connections and functionality of a programming interface than reading
a manual.
So the first step should be the installation of the demos and the second trying
to understand how they work.

For this purpose I have added several demos :

1.1 simple demos
------------
win-demo.c : shows the working of all basic window functionality; like
    	main_window, buttons, popups, help-popups, pulldowns, displays, 
	scrollbars, etc.

calc.c : an implementation of a simple calculator
        with hex/dec/bin conversion, arithmetic and logic operations

edit-demo.c : usage of "edit_window" for entering strings

file-browser.c: a complete browser which shows the usage of the 
	"file selection box" class, vertical scrollbars, text view

pal-demo.c : X-window colors palette display and manipulation

1.2. numerical demos
--------------------
one-dim.c : a quite realistic example developed for practical use;
        it shows the use of real coord-systems for displaying real-valued
    	functions, the use of pulldown menus for selecting values,
	the animation technique for integrating a differential eq.

lat2demo.c : demonstrates the use of lattice_manager class
        generates pictures of two functions inside one main window, each having
   	its own lattice-manager functionality buttons and popups 
        for manipulating its appearance; only some 40 lines code

lat-demo.c : another demo of the lattice_manager class for displaying
	two dimensional functions. 
	It combines the lattice_manager functionality with 2 additional 
	pulldowns for interactively selecting a function and setting a new
	grid size. The code needed for this is only some 50 lines.

two-dim.c : a realistic example; shows the use of the lattice_manager class
	for displaying and animating two dimensional functions (or arrays)
 	based on solvers for the two dimensional advection equation.
	It allows the user to change interactively the grid size, time step
	value, some parameters of the initial values, the flow direction,
	the integration method, the number of time steps to integrate, etc.

  
2. Making and running the demos
===============================
  After unpacking the shell archives you should at first type :
        "gmake demos"
  which compiles and links all demo programs together with the archive in
  the current directory.
  To get a first glance of the whole thing then type :
   	"gmake demorun"
  which invokes all demos consecutively.

  If make fails there are probably some path related problems, eg. the Xlib
  is not found under the standard path. If this is the case you have to replace
  the corresponding macros in the file "Makefile" with the proper values for 
  your system.
  If the compiler g++ is not to be found on your system, you are in trouble.
  (see README).

  Note that an X Window server must run on your computer, of 
  course, and the DISPLAY environment variable must be set. 
  For users not so famliar with this topic; you have to use
     	export DISPLAY=`hostname`:0.0 
  for bash, or 
     	setenv DISPLAY `hostname`:0.0 
  for csh or similiar shells.
  
  The order of using the demos should be like listed above, since it works up
  from simple to complex. 

  If the demos do work try all buttons and play with the parameters.
  The left mouse button activates a button or pulldown, the right button
  gives a specific help popup for this window (if installed).
  The optical behaviour of active buttons is Motif-like, ie. they show  their
  state "up" or "down" with a three-dimensional frame. However, there is 
  additionally the feature that the "state of activity" of an button is 
  indicated by "flattening" the frame if the pointer enters it.

  I also recommend using a color display; on black-and-white displays the
  appearence will be poorly.

3. More detailed information about the demos
============================================
4. Some basic concepts of Grafix
================================  
  * window tree
  The user should know the basics of the tree structure of windows under X.
There is one root window that represents the screen. An application can
create "main windows" (in Grafix of type "main_window") that are children
of root. Their appearence on the screen is usually managed by the window
manager. 
Then it can recursively create subwindows of certain size and at positions
relative to the parent window .(0,0) is the left upper corner.
In Grafix the user should not need to interact with X directly but through
creation of window instances of some class. Each class represents a
X-window with some specific behaviour. However, the tree structure is the
same as under X. The behaviour of the class is mainly determined from the
callbacks attached with it (see below).

  * window classes
The basic classes defined in window.h are
window  	as funadamental class for all others
main_window  	that are defined as having no parent (always root),
buttons  	to initiate actions if the mouse button is pressed
		usually not directly used, but to inherit subclasses
		from which dozens are defined 
pulldown_window a main_window that is attached to a button. It pops up
 		directly under the button. Mainly for making a selection. 
plate		window with 3 dim appearance (mainly for buttons)
menu_bar 	to place other windows (mostly buttons) automatically
scrollbar	to interactively enter a number with a slider
text_popup	to show text in an popup (eg. a help text)
pixmap_window 	has a backing store mechanism so it is used for complicated
		drawings (functions, lattices..)
coord_window	defines real valued co-ordinates and drawing functions that
		operate directly on them (world co-ordinates)

  * mapping between X-events to window instances

The main problem in writing an object-oriented X-interface is the 
interaction between windows and events. Since every window should be 
represented as an instance of a peculiar class any X-event that is assigned
to this window should be able to trigger class specific action.
While the second part of this problem is easily solved with virtual
functions of C++ the first requires a little trick. 
In Grafix I use a table which maps the window-IDs that are generated from
the X-server calls to XCreateWindow() to the this-pointer of the attached  
window instance.
This approach is obviously very fast but requires a certain behaviour of
the X-server (and a limitation of the number of actually open windows). 
While the X-servers where I tested the package matched these demands there
might be others that won't. 
Moreover another limitation arises: even if a window is destroyed the
assigned ID is not used again from the X-server (this might be
implementation dependent). 
An application that makes use of many temporarily generated windows (not to
be confused with MAPPING windows!) can run out of ressources. This will
produce the error "too many windows". 
It is possible to avoid this error by using the propper programming technique.
 I intend to overcome these limitations in a next release, probably by
using a hash table mechanism.

  * basic callbacks mechanism : the main_loop

Any X-application must implement a loop for handling events. In Grafix this
"main_loop" is a method of "main_window". This means in a typical
application one creates a main_window instance (surely with some children
windows) and then before the closing "}" of main it calls "mw->main_loop();".

All the rest (the interactive run) has to be managed inside this call.

Here I will give a short glance how this internally works. 
(The reading of this paragraph should not be obligate for a normal user) 
The first statement in this loop is a call to XNextEvent() which queries
the X-server for the next event in the queue. From the window-ID of the
event-structure the corresponding instance is computed (this-pointer) and
the general "CallBack" function is invoked which calls the virtual function
that is attached to the event type. There a specific event handling takes
place.   
Some important event types should be mentioned here :
Expose
ButtonPress, 
KeyPress
Enter/Leave
Configure
All event types have a default virtual handler in the window class which
can (and will) be modified in inherited classes. 

An application can have more than one main_windows and therefore invoke a
main_loop for each of them. This is not useful in normal applications
since they all basically do the same. However, this can be used to temporarily
define main_windows (on the execution stack, ie. as local object inside a
function) and then call it's main_loop to prevent the execution to leave
this function before a certain action is performed. This is used eg. in
the "confirm_box" and "file_selection_box" class.
 
5. How to write own applications with Grafix (overview)
=======================================================
5.0 "Hello World" example 

Here is the whole code of the well known "Hello World" program with Grafix :

	#include "window.h"
	main(int argc, char *argv[]) {
  	  main_window mw(argv[0],200,200);
  	  text_win *tw = new text_win(mw,"Hello World !",180,20,10,50);
  	  button *qb = new quit_button(mw,100,20,50,150);
  	  mw.main_loop();
	}

5.1 general hints, the class "window" 

  * the window class

window is the superclass of all others. Each window keeps a list of its
children. This list is needed for mapping, resizing, and deleting.
It is quite easy to reconstruct from this the complete window tree of a
running application starting with the root window, or for any main_window.

  * some basic methods for the window class

constructor : takes as arguments parent window, width and height (in pixel)
the relative position on the parent (with resp. to left upper corner = 0,0)
and the border width. The constructor mainly calls "XCreateSimpleWindow"
with default parameters, sets the this pointer in the global pointer table
and  appends itself to the window tree.

  * the window mapping, expose events and the related callbacks

the exposing of a window is the most important event. It is usually the
first trap a newcomer to X falls in. "Why doesn't the window appear when I
draw it ?". The reason is that the mapping and drawing has to be done
(nearly) asynchronuously with other things. Exposing events are triggered
whenever a part of a window becomes visible. That is the case when it is
mapped for the first time but also when an obscuring window is removed (from
the window manager eg.). 
The normal course in creating a window is as follows:
At the start of the main loop a "RealizeChildren" is invoked which recursively
parses the window tree and invoking for each subwindow the function chain

 -> Realize
    -> XSelectInput
    -> Map
        -> draw_interior
	-> XMapWindow

Here "draw_interior" is a virtual function that serves only as hook for more
complicated classes (pixmap_window, see below).

Up to this stage nothing is shown on the screen. The actual exposing is
performed indirectly through the event loop. Upon Map request the X server
generates an expose event that invokes the Expose_CB callback. This virtual
function simply calls the "redraw" function.

So the actual drawing has to be done by defining of a new "redraw" function
for any derived class. This function is invoked every time the window (or
parts of it) becomes visible.

The redraw function can (and will) be also called directly from other
functions or callback handlers.

  * pointer and button events

Each X event correspods to a virtual function that is usually a dummy.
The only exception is the Button Press 3 that serves per default as a help
button which can popup a help menu for this window.
For instance the button class uses the events Enter and Leave to show a
changing appearance and the ButtonPress or ButtonRelease to perform some
action (ie. a callback)

  * configure and resize events

If the user interactively resizes a main window (with the help of the window
manager) by drawing the border or edges the X server issues a configure
event. This event type is managed by the virtual function "resize".
By default this method enlarges or shrinks all children recursively by the
same factor. If another behaviour is intended (eg. for buttons and menubars
this is of course not appropriate) it should be overwritten.

  * drawing methods

These methods can be used to change the interior of a window
clear
DrawString
PlaceText
line
DrawPoint
Usually they draw directly into the X window and thus are to be seen
immediately. However, they are overwritten in the pixmap_window class (see
below) 

  * destructors

The proper handling of deleting windows requires some thoroughness. 
Firstly, one has to consider that a deletion of any window automatically
deletes all of its children recursively. This is straightforward, however,
it leads to trouble if a window is defined as a local object inside a
function or block.
Upon leaving this block it is automatically deleted as usually. But since
it is also always a child of another window a second destructor is invoked
when the parent is destroyed -> crash.
  The solution for this is to define all window objects dynamically with
new and destruct only the main_windows (or define them locally). 
The root window is the only exception that does not delete its children.

Of course, it is even simpler to ignore the error upon program exit :-)

 * general remarks about callback functions

Let us consider the example of a push button instance which shall invoke
some action - eg. computing some values and then show the results in some
windows. The constuctor for a simple callback_button eg. takes as argument a
void function with no arguments. It is, of course, easy to define for each
action a function which invokes the intended actions. However, if the
action refers to a window then this window has to be defined globally (or
the this pointer) to make it accessable to the callback function.
 
This approach is neither elegant nor does it allow more complex actions.
(It is used in some examples nevertheless).
On the other hand it is not possible to define parameter types that fit to a
class that will be defined in the future. 

To evade this problem there are defined some button types which allow for
complicated callback functions (template_button, instance_button,
function_button, radio_button). For special actions the user has to define
his own button classes.

5.2 files 

window.h	basic include file, definition of all fundamental classes 
		also defines some general functions (set color, set GC ..)
window.c 	corresp. code, 
lattice.h	include file for lattice_manager classes
lat_win.c       )
reg_man.c	)  the sources for these classes
lat_man.c	)
libwin.a	an archive which combines all object files
eventnames.h  	from Xlib for debugging
icon.h        	the icon image
palette.h  	include file for palette manipulations
palette.c   
files.h		for file selection box
files.c  
calc.c 		calculator demo
edit-demo.c     more demos
pal-demo.c        
file-browser.c    
color_table.c          
win-demo.c
cursors.c      	show all X cursors
lat-demo.c     	)
lat2demo.c      ) demos for the lattice class
solver.c	)
one-dim.c	) the one-dim example
two-dim.c 	)
smolark.h	) the two-dim example
smolark.c	)

6. Some details about other basic classes : 
===========================================
   main_window	: a direct child of the root window. It is managed by the
		window manager. It can be connected with an icon (method 
		set_icon). Each application must have at least one main_window,
		other main_windows can be used as popup windows.

   pixmap_window: a window for complex drawings eg. functions, figures, etc. 
		for which a complete redrawing upon each expose event would
		be too slow. Drawing actions are performed indirectly into a 
		pixmap which is mapped from the expose or redraw methods.
		The virtual function "draw_interior" MUST be overwritten
		(it is a pure virtual function), so it cannot be instantiated
		directly.

   coord_window : derived from pixmap_window with additional functions to 
		define real co-ordinates and drawing functions that operate
		in these coordinates. Thus useful for displaying functions as
		graphs, co-ordinate systems aso. Examples can be found in the
		one-dim and two-dim demos and the lattice_window class

   menu_bar 	: enables a simpler definition of buttons (autoplacement)

   buttons	: call an action on button press

   system_button: calls "system" with a passed string as argument

   xwd_button 	: makes a window dump with the "xwd" program
		to get a direct hardcopy with that button define eg. :

                new xwd_button(*mb2,"hardcopy"," | xpr | lpr",this)
		which will pipe the output of the xwd command directly to the
		printer (assumed to be "lpr"). The "this" pointer is the window
		that shall be copied.

   pulldown_window  : special main window that is not managed by the WM. It is
		usually attached to a button and pops up beneath it.

   scrollbars	: window with a slider to enter a numerical value interactively

   edit_window  : allows editing of strings
 
7. the window class tree (simplified)
=====================================
  these classes are defined in window.h and lattice.h
  window
    main_window
      pulldown_window
      text_popup
    pixmap_window
      coord_window
	region_manager (lattice.h)
        lattice_window     "
	  lattice_manager  "
    text_win
    menu_bar
    plate      
      slider
      pure_scrollbar
	scrollbar
      display_window
      edit_window
      button
	delete_button
	quit_button
	help_button
	callback_button
	template_button
	instance_button
	function_button
	toggle_button
	  toggle_redraw_button
	pulldown_button
	radio_button
	popup_button
	unmap_button
	system_button
	xwd_button

  other classes are defined in palette.h lattice.h files.c 
  Also numerous examples are to be found in the demos.

8. portations to other platforms
================================ 
The platform specific handlic should be ideally restricted to the file
"grafix.mk" 
which is included by the Makefile.

Here the paths to the compiler an Xlib can be set depending on HOSTTYPE,
and possibly compiler definitions set.

Tested platforms :

  Sun - sparc station (SunOS, Solaris)
  Bull DPX/20 (PowerPC and AIX 3.2.5).
  IBM compatible PCs (i386..i586), Linux
