ICFS - interface description June 13, 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.11. It supports 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 #define ICF_SETSPACE 0x0203 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 */ xspace, yspace; /* space between two windows, default=0 */ } 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 and the space that is left between two iconified windows (separated for x and y). 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 any 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). ICF_SETSPACE: Aufruf in C: ret=(*server)(ICF_SETSPACE,nx,ny); int ret, nx, ny; Sets how many pixels are to be left free between two iconified windows. nx is the amount in x direction, ny the amount in y direction. If there are any iconified windows when this call is initiated the new amounts will not be taken until all those windows are closed and ICF_INFO will return the old amount of space until then. ret contains zero if the new amount has been taken, otherwise it will contain 1. 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, ICF_SETSIZE and ICF_SETSPACE 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)