----------------- ICFS documentation follows ... --------------------
ICFS - interface description                            March 19, 1994

ICFS installs a cookie "ICFS". The value of this cookie is the address
of a function via which programs can communicate with ICFS.

The following description is in C syntax (Pure C resp. Turbo C, to be
exact). Therefore, an "int" is a signed 16 bit word, an "unsigned
int" it's unsigned equivalent. A "*" (or "&") in front of a variable's
name represents a pointer, which means that the variable's address is
passed rather than it's value. All parameters are passed via the stack.
The leftmost parameter is pushed onto the stack first, the rightmost
parameter last. That means that the rightmost parameter is on top of
the stack when the function is called. ICFS makes use of a special
C feature: functions with varying parameters. If you want to call
ICFS functions in an other programming language, you probably have to
build several bindings for every sub function.

The current server's version number is 0.10. It knows the following
sub functions ("0x" means that it's a hex number):

#define ICF_GETSIZE  0x0000
#define ICF_GETPOS   0x0001
#define ICF_FREEPOS  0x0002
#define ICF_FREEALL  0x0100
#define ICF_INFO     0x0200
#define ICF_CONFIG   0x0201
#define ICF_SETSIZE  0x0202

Use the following code, if you're programming in C

     int cdecl (*server)(int f,...);

     server=get_cookie('ICFS');


List of sub functions:

ICF_GETSIZE:

  C call: version=(*server)(ICF_GETSIZE,&w,&h);
                  int version, *w, *h;

  w and h are pointers to ints. The server returns the current size
  of an iconified window (w: width, h: height) and ICFS's version
  number.

ICF_GETPOS:

  C call: posno=(*server)(ICF_GETPOS,&x,&y,&w,&h);
                int posno;
                int *x, *y, *w, *h;

  The server returns a position for an iconified window (x and y) and
  it's size (w and h). This position (posno) is allocated from now on
  and must be freed with ICF_FREEPOS if you don't need it any more.

ICF_FREEPOS:

  C call: (*server)(ICF_FREEPOS,posno);
          int posno;

  Frees a window's position allocated by ICF_GETPOS. posno is the
  window position returned by ICF_GETPOS.

ICF_FREEALL:

  C call: (*server)(ICF_FREEALL);

  Frees all window positions. This may be used to free positions
  allocated by programs which have crashed. Don't call this function
  without asking the user.

ICF_INFO:

  C call: realsize=(*server)(ICF_INFO,&conf,size);
                   ICFSCONFIG *conf;
                   int realsize, size;

  conf is a pointer to a struct ICFSCONFIG which is defined as
  follows:

  struct _config
  {
   unsigned reserved : 13; /* unused, should be 0 */
   unsigned yfirst   : 1;  /* bit 2: 1=y direction first */
   unsigned right    : 1;  /* bit 1: 1=start right */
   unsigned top      : 1;  /* bit 0: 1=start at the top */
  };

  typedef struct
  {
   unsigned int version;  /* version number as BCD */
   struct _config config; /* config., see above */
   int xsize, ysize;      /* width & height of a window, default=72 */
  } ICFSCONFIG;

  The struct starts with ICFS's version number as BCD (that means a
  value of 0x0010 represents version 0.10), followed by a bit field
  (a 16 bit word) with the above meanings. This is followed by the
  current width and height of an iconified window.

  Using ICF_INFO you get all important information at once. ICF_INFO
  takes a pointer to memory in your program(!) where the above values
  will be copied to. The size parameter holds the size of your memory
  region whereas ICF_INFO returns the actual size of it's internal
  structure. This is to prevent trouble if future versions of ICFS will
  use larger structures. The size parameter guarantees that only those
  parts of the struct are copied of which your program is aware.

  Since the structure is copied to the program's memory, any change to
  it is futile. Use the following sub functions to change these values:

ICF_CONFIG:

  C call: (*server)(ICF_CONFIG,config);
          unsigned int config;

  Changes the strategy used to tile the iconified windows on the
  screen.

  bit 0: 0 = start at the bottom
         1 = start at the top
  bit 1: 0 = start left
         1 = start right
  bit 2: 0 = x direction first
         1 = y direction first

  The strategy used by MultiTOS (start at the lower left corner, going
  left to right an up) would therefore be 0, whilst 7 would be "start
  at the upper right corner, going top to bottom and left". All other
  bits are unused and should be zero.

ICF_SETSIZE:

  C call: ret=(*server)(ICF_SETSIZE,nw,nh);
              int ret, nw, nh;

  Sets a new width (nw) and height (nh) for the iconified windows. If
  there are iconified windows, when this call is initiated the new
  size will not be taken until all those windows are closed
  (ICF_GETSIZE and ICF_GETPOS will return the original sizes until
  then). ret contains zero if the new size has been taken immediately
  otherwise it will contain 1.

  Atari recommends to draw an icon into an iconified window. Given an
  icon with 32 by 32 pixels and text, 64 by 64 pixels seems to be the
  smallest sensible size of an iconified window (since 64 by 64 pixels
  are the outer dimensions of the window).


All functions return (via register D0) an int as return code. Zero
means "Ok, no errors", a negative value represents an error. Invalid
function numbers return -32 (gemdos error code EINVFN).

ICF_FREEALL, ICF_CONFIG and ICF_SETSIZE should not be called by a
normal application. Use ICFS.CPX by John McLoud to call these
functions.

To implement iconify without MultiTOS you only need to call ICF_GETPOS
and ICF_FREEPOS.


Annotations

ICFS is not intended to implement an MultiTOS-style iconify. This
could not be realized without modification of the AES itself. The
single task of ICFS is to coordinate positions of iconified windows
if there are several programs using iconification.

The current version of ICFS returns position numbers which are
equivalent to certain positions on the screen. Please do not rely on
this, since it will change in future versions of ICFS.

Known problems: ICFS is only capable of handling 32 by 32 icon
windows. This is probably not enough for virtual resolutions.


The original idea for "iconify without MultiTOS" is by

     Rosin Datentechnik
     Reiner Rosin
     Peter-Spahn-Str. 4
     D-65375 Oestrich-Winkel
     Germany
     Telefon 06723 4978  Fax 7190

     email Reiner Rosin @ WI2 (MausNet) / Reiner_Rosin@wi2.maus.de

whereas the program ICFS and this text were written by

     Dirk Haun
     Europastr. 8
     D-64569 Nauheim
     Germany

     e-mail: Dirk Haun @ WI2 (MausNet)
