                          Dokumentation zum

                                 ICFS

                                V1.00
                              06.08.1995

                                 von

                              Dirk Haun
                             Europastr. 8
                           D-64569 Nauheim

                           Dirk Haun @ WI2



Inhaltsverzeichnis
==================

 0 ICFS - Was ist denn das schon wieder?

 1 ICFS.PRG
   1.1 Die Installation (ICFS)
   1.2 Die Bedienung (ICFS)
   1.3 Patchbereich
   1.4 Copyright / Rechtliches

 2 ICFS.CPX
   2.1 Dokumentation zu ICFS.CPX v1.20
   2.2 Die Installation (CPX)
   2.3 Die Bedienung (CPX)
   2.4 Schlubemerkungen

 3 ICFS-untersttzende Programme

 4 Kontaktadressen

 5 Entwicklerdokumentation
   5.1 Beschreibung der Schnittstelle
   5.2 Hinweise fr andere Programmiersprachen
   5.3 Anmerkungen
   5.4 ICFS-Versionen
   5.5 Unterschiede der Versionen

 6 Beschreibung der Funktionen
   6.1 ICF_GETSIZE
   6.2 ICF_GETPOS
   6.3 ICF_FREEPOS
   6.4 ICF_SNAP
   6.5 ICF_GETBIGPOS
   6.6 ICF_GETLOC
   6.7 ICF_GETWPOS
   6.8 ICF_FREEWPOS
   6.9 ICF_SNAPW
   6.10 ICF_GETBIGWPOS
   6.11 ICF_GETWLOC
   6.12 ICF_FREEALL
   6.13 ICF_SCREEN
   6.14 ICF_NEXTPOS
   6.15 ICF_INFO
   6.16 ICF_CONFIG
   6.17 ICF_SETSIZE
   6.18 ICF_SETSPACE
   6.19 ICF_SETBORDER
   6.20 ICF_NEXTINFO
   6.21 ICF_WINOPEN
   6.22 ICF_GETPATH

Anhang
======

 A MultiTOS-Iconify



0 ICFS - Was ist denn das schon wieder?
=======================================

In der MultiTOS-Version 1.07 hat Atari ein neues Feature eingefhrt,
das sogenannte Iconify. Damit kann man ein Fenster auf eine Gre,
nur noch etwas grer als ein Icon, zusammenschrumpfen lassen (daher
der Name). Eine praktische Idee, kann man doch so schnell alle Fen-
ster von Programmen, die man gerade nicht braucht, aus dem Weg ru-
men, ohne da man das entsprechende Programm zu beenden bruchte.
Durch einen Klick auf ein solches verkleinertes Fenster erlangt es
seine ursprngliche Gre und Lage zurck.

Leider sind die MultiTOS-Versionen, die ber dieses Feature verfgen,
nur fr Betatester erhltlich (und es ist sehr unwahrscheinlich, da
sie jemals fr Normalanwender erhltlich sein werden). Auerdem wre
es wnschenswert, diese Mglichkeit auch unter MagiC, den alten Multi-
TOS-Versionen und evtl. sogar fr SingleTOS zu haben. Nun ist es kein
Problem, eine zumindest hnliche Lsung in ein Programm einzubauen.

Was jedoch zwischen verschiedenen Programmen koordiniert werden mu,
ist die Lage der verkleinerten Fenster - und genau das leistet der
ICFS.

MagiC bietet ab der Version 3 ein MultiTOS-kompatibles Iconify an, so
da ICFS dort eigentlich nicht bentigt wird. Jedoch lt sich ICFS
dort auch installieren und "berredet" MagiC dann dazu, das Iconify
ber ICFS abzuwickeln. Somit kommen dann alle Programme, die ein MTOS-
Iconify untersttzen, automatisch in den Genu der ICFS-Features:

    Snapping
     Nach dem Verschieben eines Iconfensters rastet dieses wieder an
     einer Iconposition ein. Die "Kachelung" der Iconfenster auf dem
     Bildschirm bleibt also erhalten.

    whlbare Fenstergre
     Die Gre eines Iconfensters kann frei gewhlt werden. Beim
     MultiTOS-kompatiblen Iconify hat ein Iconfenster immer eine
     feste Gre (72x72 Pixel).

    whlbare Startecke
     Es kann frei gewhlt werden, in welcher der vier Bildschirmecken
     das erste Iconfenster abgelegt werden soll (MTOS: immer links
     unten).

    whlbare Belegungsrichtung
     Ausgehend von der gewhlten Startecke kann auch die Richtung
     gewhlt werden, in der weitere Iconpositionen angefordert wer-
     den, also wahlweise horizontal oder vertikal (MTOS: immer
     horizontal).

    Abstand der Iconfenster
     Auch der Abstand, der zwischen zwei nebeneinander liegenden Icon-
     fenstern gelassen wird, kann mit ICFS frei eingestellt werden
     (MTOS: kein Abstand).

    Abstand vom Bildschirmrand
     Schlielich und endlich kann auch der Abstand zum Bildschirmrand
     eingestellt werden (MTOS: kein Rand).

ICFS kann in diesen Punkten also auch noch als Anregung fr das "rich-
tige" Iconify verstanden werden.

Hinweis: Die Defaulteinstellungen im ICFS entsprechen denen von Multi-
TOS bzw. MagiC, die ICFS-Features mssen erst mit dem ICFS.CPX einge-
stellt werden.



1 ICFS.PRG
==========


1.1 Die Installation (ICFS)
---------------------------

Die Installation unter SingleTOS, MagiC 1 und 2 sowie MultiTOS (Ver-
kaufsversion) ist einfach: Kopieren Sie das Programm ICFS.PRG in den
AUTO-Ordner und booten Sie den Rechner neu. Das ist alles.

Unter MagiC!3 und MagiCMac sollten Sie ICFS.PRG dagegen in den APPS-
Ordner (also den Ordner, in dem die Autostart-Applikationen stehen
und dessen Pfad in der Datei MAGX.INF in der Zeile #_APP angegeben
ist) kopieren und den Rechner ebenfalls neu booten.


Der ICFS legt einen Cookie an, ber den Programme Positionen fr die
verkleinerten Fenster anfordern knnen. Unter MagiC!3 bzw. MagiCMac
hngt sich ICFS zustzlich in den AES-Trap (XBRA-Kennung: ICFS).


1.2 Die Bedienung (ICFS)
------------------------

Und wie benutzt man das jetzt?

Mit der Maus:

Ein Fenster wird ikonifiziert (als Icon abgelegt), indem man auf das
Schliefeld (Closer) eines Fensters klickt und dabei eine der folgen-
den Umschalttasten gedrckt hlt:

    [Alternate] - ein einzelnes Fenster verkleinern
    [Control]   - alle Fenster in ein einziges verkleinern
    [Shift]     - alle Fenster einzeln verkleinern

Dies mu jedoch von dem jeweiligen Programm untersttzt werden!

Die Control-Taste fr das Iconify aller Fenster wurde analog zum
Control-Klick auf das Iconifier-Symbol beim MultiTOS-Iconify gewhlt,
kollidiert aber leider mit der Belegung der Control-Taste unter Winx.
Es wird daher empfohlen, diese Funktion noch zustzlich ber die
Kombination

    [Alternate][Shift] + Klick auf den Closer

anzubieten.


Per Tastatur:

Fr das Verkleinern eines einzelnen Fensters auf Icongre verwenden
die meisten Programme die Tastenkombination

    [Control][Alternate][Leertaste]

Sollen gleich alle Fenster zu einem einzigen Icon verkleinert werden,
so ist zustzlich die (linke) Shift-Taste zu drcken.

Mit den gleichen Tastenkombinationen sollte sich das Icon dann auch
wieder zu einem bzw. mehreren Fenstern ffnen lassen. Fr das Ablegen
aller Fenster als einzelne Icons ist keine Tastenkombination vorge-
sehen.

Einige ltere Programme verwenden noch [Control][Leertaste] (einzel-
nes Fenster) bzw. [Control][Shift][Leertaste] (alle Fenster).


MagiC!3/MagiCMac:

Unter MagiC!3 bzw. MagiCMac werden Fenster dagegen einfach durch
einen Klick auf den Smaller (auch "Iconifier" genannt), das neue Fen-
sterelement in der rechten oberen Ecke, als Icons abgelegt - ganz wie
gewohnt. ICFS tritt hier nicht weiter in Erscheinung, da er seine Auf-
gabe "im Hintergrund" abwickelt.

Das Ablegen von Fenstern mit [Control][Alternate][Leertaste] wird
auch unter MagiC von immer mehr Programmen untersttzt.


1.3 Patchbereich
----------------

Die verschiedenen Einstellungen, die an ICFS vorgenommen werden kn-
nen, sind mit Defaultwerten belegt und werden im Normalfall mit dem
ICFS.CPX verndert. In manchen Situationen kann es aber erwnscht
sein, da ICFS andere Defaulteinstellungen annimmt, z.B. dann, wenn
Sie auf den Einsatz des CPX oder des Kontrollfeldes verzichten wol-
len, oder wenn Programme schon Fenster als Icons ablegen wollen, be-
vor das CPX geladen wurde (was in einem Multitasking-System durchaus
vorkommen kann). Daher existiert ab Version 1.00 ein Patchbereich im
ICFS.PRG, in den die Defaulteinstellungen eingetragen werden knnen.
Im Normalfall wird dies bereits vom ICFS.CPX erledigt, Sie knnen
diese nderungen aber auch selbst vornehmen:

Mit einem Diskmonitor oder einem hnlichen Programm (z.B. "HexEdit"
von Dirk Sabiwalsky) sucht man nach der Zeichenfolge 'PatchHere:'
(ohne Hochkommata). Dahinter befindet sich eine Struktur vom Typ
ICFSCONFIG (siehe ICF_INFO), in der die Defaultwerte stehen. Diese
knnen nun nach Wunsch verndert werden. Das Ende des Patchbereichs
ist durch die Zeichenkette ':ereHhctaP' gekennzeichnet.


Als Hexdump sieht der unvernderte Patchbereich so aus:

   50 61 74 63 68 48 65 72 65 3A   PatchHere:
   01 00                           ICFS-Version
   00 00                           Konfigurationsbits
   00 48 00 48                     Gre eines Iconfensters
   00 00 00 00                     Abstand zwischen Iconfenstern
   00 00 00 00                     Abstand zum Bildschirmrand
   3A 65 72 65 48 68 63 74 61 50   :ereHhctaP


1.4 Copyright / Rechtliches
---------------------------

Kurzfassung:

Der ICFS ist Freeware. Sie drfen dieses Programm Ihrer eigenen Soft-
ware beilegen. Dies darf auch teilweise geschehen, mu dann aber
neben ICFS.PRG mindestens einen Anleitungstext, also z.B. ICFS.TXT,
ICFS.ENG oder ICFS.HYP/ICFS.REF umfassen.


lange Fassung:

Das Programm ICFS ist Freeware. Es darf beliebig kopiert und weiterge-
geben, aber nicht einzeln verkauft werden. Das Programm darf ber
Mailboxen oder hnliche nichtkommerzielle Systeme (z.B. ftp) frei ver-
breitet werden, solange dem Empfnger dabei keine zustzlichen Kosten
(auer den ohnehin anfallenden Gebhren) entstehen. Ein Vertrieb ber
PD-Disketten ist gestattet, solange der Einzelpreis einer solchen
Diskette 10 DM nicht bersteigt. Das Programm darf nicht ohne Rck-
sprache auf Coverdisks (oder hnliche, an Zeitschriften gebundene
Disketten) bernommen werden. Eine bernahme auf CDs (zusammen mit
anderer Software) ist dagegen gestattet. Das Programm darf zusammen
mit kostenloser sowie mit kommerzieller Software vertrieben werden,
solange deutlich wird, da ICFS nicht Bestandteil dieser Software
ist.

In jedem Fall mu ICFS.PRG mindestens noch einer der Anleitungstexte
ICFS.TXT oder ICFSKURZ.TXT oder ICFS.ENG oder ICFS.HYP/ICFS.REF beige-
legt werden.

Die obigen Regelungen knnen in Einzelfllen aufgehoben werden, dazu
ist aber unbedingt mein schriftliches Einverstndnis einzuholen.

Wenn Sie als Anwender dieses Programms den begrndeten Verdacht ha-
ben, da gegen eine oder mehrere der obigen Bedingungen verstoen
wurde, so bitte ich um entsprechende Benachrichtigung. Vielen Dank.



2 ICFS.CPX
==========


2.1 Dokumentation zu ICFS.CPX v1.20
-----------------------------------

Einen wunderschnen guten Morgen (oder was auch immer).

Dieses kleine Schreiben setzt die Kenntnis um ICFS voraus. Wer also
gar nicht wei, um was es hier geht, sollte sich erst mal die Doku zu
ICFS durchlesen.

Nur mal kurz zur Erinnerung: ICFS stellt ber einen Cookie eine Pro-
grammierschnittstelle zur Verfgung, damit Programme das Iconifizie-
ren von Fenstern (auch ohne MultiTOS oder MagiC!3) durchfhren kn-
nen. Das schafft schon Platz auf dem Bildschirm und ist recht prak-
tisch, wenn viele Fenster offen sind, die man im Moment nicht
braucht.

Wie dem auch sei, jedenfalls gibt es die Mglichkeit, die iconifizier-
ten Fenster nach Geschmack platzieren zu lassen; auch die Gre ist
whlbar.

Mit diesem CPX kann man diese Parameter nun komfortabel einstellen.


2.2 Die Installation (CPX)
--------------------------

Die Datei ICFS.CPX wird in den Ordner kopiert, in dem auch alle ande-
ren CPXe stehen. Was ein CPX ist? Hmm. Besorgen Sie sich das modulare
Kontrollfeld XCONTROL.ACC von ATARI, dann wissen Sie's.

Mehr is nich. Das war die Installation. Jetzt mssen Sie nur neu
booten (oder die Module des XCONTROL neu laden) und schon steht Ihnen
das CPX zu ICFS zur Verfgung.


2.3 Die Bedienung (CPX)
-----------------------

Mein alter Lehrer wrde sagen 'Nun, was sehen wir denn, wenn wir das
CPX ffnen?' und ich mchte ihm hier beipflichten.

Also, was sehen wir?

    Links oben einen Text "ICFS vx.xx", wobei 'x.xx' fr die Versi-
     onsnummer des installierten ICFS steht.

    Button 'Freigeben':
     Dieser Button ffnet als Reaktion auf das Anklicken Ihrerseits
     eine Alarmbox, und diese will wissen ob Sie das auch ernst mei-
     nen, was Sie gerade tun wollen.

     Sollten Sie mit 'OK' antworten werden alle Icon-Positionen wie-
     der freigegeben und ICFS beginnt wieder bei der eingestellten
     Startecke.

    Checkbox 'ICFS Snap':
     Nur anwhlbar, wenn ICFS ab v1.00 installiert ist. Schaltet die
     Option, Icon-Fenster nur an ICFS Positionen verschieben zu kn-
     nen, an bzw. aus.

    Checkbox 'Mega Icons':
     Sie ist nur anwhlbar, wenn man ICFS ab Version 1.00 installiert
     hat, und aktiviert/deaktiviert die Mglichkeit Icons zu benut-
     zen, die ein Vielfaches der normalen Icongre haben.

    PopUp 'Gre':
     Hier kann man wunderbar ablesen, wie gro die Icons gezeichnet
     werden. Ein Klick auf den PopUp gengt, und man hat die Wahl zwi-
     schen fnf verschiedenen Gren:

         64 x 64
         72 x 72
         80 x 80
         88 x 88
         96 x 96

     Es sollte also fr jeden etwas dabei sein.

     Wenn nicht, ein Klick auf den Button "Gre" gengt, und schon
     kann man sich eine eigene Gre eintragen.

    PopUp 'Rand':
     Nur anwhlbar, wenn ICFS ab v1.00 installiert ist.

     Es ffnet sich ein PopUp, aus dem man den Abstand der ICFS-Fen-
     ster zum Bildschirmrand whlen kann. Folgende Mglichkeiten
     stehen zur Wahl:

          0 Pixel
          4 Pixel
          8 Pixel
         12 Pixel
         16 Pixel

     Auch hier gilt: ber den Button "Rand" ist eine eigene Ein-
     stellung mglich.

    PopUp 'Abstand':
     Nur anwhlbar, wenn ICFS ab v0.11 installiert ist.

     Es ffnet sich ein PopUp, aus dem man den Abstand der ICFS Fen-
     ster whlen kann. Folgende Mglichkeiten stehen zur Wahl:

          0 Pixel
          4 Pixel
          8 Pixel
         12 Pixel
         16 Pixel

     Mittlerweile sollte bekannt sein, was passiert, wenn man den
     Button "Abstand" anklickt ...

    PopUp 'Startecke':
     Hiermit wird bestimmt, von welcher Ecke aus die iconifizierten
     Fenster auf dem Desktop angeordnet werden.

     Sozusagen serienmig ist 'Links unten' eingestellt. Ein Klick
     auf den PopUp ermglicht die Wahl zwischen:

         links unten
         links oben
         rechts unten
         rechts oben

     Wer die Icons also lieber von rechts oben angeordnet htte,
     bitte sehr.

    PopUp 'Ausrichtung':
     Sollte defaultmig auf 'Horizontal' stehen und bestimmt, in
     welche Richtung von der Startecke aus die Icons angeordnet wer-
     den.

    Button 'Sichern':
     Hat man seine Lieblingseinstellung gefunden, bettigt man 'Si-
     chern'. Die Parameter werden im CPX gespeichert und bei jedem
     Reboot des Rechners wieder so eingestellt.

     Auch hier gibt's erst 'ne Sicherheitsabfrage, ob Sie wirklich
     speichern wollen. Ab ICFS 1.00 besteht die Mglichkeit, die
     Einstellungen auch in ICFS.PRG zu speichern. Dazu mu das CPX
     allerdings wissen, wo sich ICFS.PRG befindet. Ab ICFS 1.00 exi-
     stiert dazu ein Mechanismus, der aber unter manchen widrigen
     Umstnden (hoffentlich nicht zu oft) nicht greift. In dem Fall
     wird der werte Benutzer ber einen Fileselektor aufgefordert,
     das Programm selbst zu finden.

    Button 'OK':
     Der wohl meistbenutzte Button einer jeden CPX. Klick gengt, und
     das Modul verabschiedet sich, bis es wieder aufgerufen wird.
     Alle Aktionen, die man gettigt hat, behalten ihre Gltigkeit.

    Button 'Abbruch':
     Der am zweitmeisten verwendete Button einer jeden CPX.

     Auch dieser lsst das Modul wie von Geisterhand verschwinden,
     stellt aber alles wieder so ein, wie es war, bevor Sie das CPX
     aufgerufen haben.

     Nur wenn Sie Icons freigegeben haben, kann man das nicht mehr
     rckgngig machen. Aber Sie wurden ja auch gefragt, ob Sie das
     wirklich wollten.

Ansonsten war's das. Der Vollstndigkeit halber will ich noch erwh-
nen, da es (noch) keine Tastaturbedienung fr das CPX gibt. Ledig-
lich ein Druck auf 'Return' lst die Funktion des am dicksten einge-
rahmten Buttons aus, aber das wei wohl jeder ATARI-User.


2.4 Schlubemerkungen
---------------------

Zum Schlu sei noch folgendes gesagt.

Ich bernehme keinerlei Haftung fr irgendwelche Schden, die das CPX
verursacht (was immer das auch sein soll).

Dafr drfen Sie das CPX auch kostenlos nutzen, sooft und viel Sie
wollen.

Das Copyright liegt (und bleibt) aber bei mir, was bedeutet, da Sie
das CPX, auer mit dem Button 'Sichern' des ICFS CPX nicht verndern
drfen.

Bemerkung am Rande: Ich bin nicht der Urheber des ICFS; ich wurde
lediglich dazu verdonnert, das CPX zu schreiben. Die Idee zum ICFS
stammt von Reiner Rosin, und wurde erstmals in seinem Programm
'Zeig's mir' realisiert. Der Server (ICFS.PRG im AUTO-Ordner) wurde
von Dirk Haun geschrieben; somit stand ICFS allen zur Verfgung, und
war nicht mehr nur auf 'Zeig's mir' begrenzt.

Ein herzlicher Dank geht an Martin Osieka, der ein paar gute Bug-
reports verfasst hat, und von dem die Idee stammt, auch die Versi-
onsnummer des Servers anzuzeigen, obwohl im CPX kein Platz mehr war.

John McLoud

Viel Spa!!!



3 ICFS-untersttzende Programme
===============================

Zur Zeit untersttzen folgende Programme den ICFS (Stand 27.07.1995):

 Programm      ab Version Typ               Autor
----------------------------------------------------------------------
 800XL-Deejay   2.30      Laufwerksemulator Kolja Koischwitz
 ACDP           1.00      CD-Player         Christian Mittendorf
 APP_List       0.3       Systemutility     Ralf Zimmermann @ OF2
 Avalon         3.72      Shell             Stephan Slabihoud
 Avalon4Semper  3.72      Shell             Stephan Slabihoud
 Ballerburg2    2.00      Denkspiel (o:     Kolja Koischwitz
 Casio-SF       1.25      Transferprogramm  Stephan Slabihoud
 Chatwin        3.01      Shell             Dirk Haun @ WI2
 Dialler        alle      Telefondatenbank  Christoph Spengler @ RS
 DomesTOS       alle      Shell             Christoph Spengler @ RS
 DWBH           1.00      GEM-Spiel         Dirk Hagedorn @ MK2
 gale          2.0       Dateiutility      David Reitter @ WI2
 EGEM-Utilities Rel. 2    11 Utility-PRGs   Christian Grunenberg @ LB
 Freedom        0.999     Fileselektor      K. Koischwitz, Ch. Krger
 GEM-Solitaire  1.13      GEM-Spiel         Dirk Hagedorn @ MK2
 Gewicht        alle      Gewichtskontrolle Christoph Spengler @ RS
 IconMan        0.63      Icon-Utility      Dirk Haun @ WI2
 IdeaList       3.60      ASCII-Druckprog.  Christoph Bartholme @ KA2
 Jedi           0.29      GAL-Assembler     Ralf Zimmermann @ OF2
 Kandinsky      1.69      Zeichenprogramm   Ulrich Rossgoderer @ M
 Lazaz!         2.07      Packershell       Andreas Papula @ WI2
 McFli          0.5       Animationsplayer  John McLoud @ WI2
 MoveIt         1.01      GEM-Spiel         Dirk Hagedorn @ MK2
 SCANGENI       1.0       Scannertreiber    Christian Mittendorf
 SysInfo        2.10      Systeminfo        Thorsten Bergner @ B
 Tel-Upate      alle      Rufus-Tool        Christoph Spengler @ RS
 Tricky         1.00      GEM-Spiel         Dirk Hagedorn @ MK2
 WinLupe        6.70      Utility           Christian Grunenberg @ LB
 XAcc-Spy       25.03.94  XACC-Utility      Thomas Much @ KA2
 Yukon          Rel. D    Kartenspiel       Dirk Haun @ WI2
 zControl       0.20      Kontrollfeld      Ralf Zimmermann @ OF2
 Zeig's mir     0.22      Dateiviewer       Reiner Rosin @ WI2
----------------------------------------------------------------------
 (e-mail-Adressen: MausNet)


Folgende Bibliotheken untersttzen den ICFS, so da sich Program-
mierer viel Arbeit sparen knnen:

  Bibliothek   ab Version Sprache(n)     Autor
 ------------------------------------------------------------------
  EnhancedGEM   2.00      PC, LC, GC     Christian Grunenberg @ LB
  ObjectGEM     1.11      Pure Pascal    Thomas Much @ KA2
  STJ-Oberon-2  2.05      Oberon-2       Stephan Junker @ AC2
  SysGEM        1.10      PC, PP         Andreas Pietsch @ WI2
  Windoze       PL 0      Pure C         Dirk Haun @ WI2
 ------------------------------------------------------------------
  (PC: Pure C, PP: Pure Pascal, LC: Lattice C, GC: GNU C)


Autoren, die nicht ber's MausNetz erreichbar sind:

 Christian Mittendorf: chris@ostkupan.ct.se
 Kolja Koischwitz:     joust@cs.tu-berlin.de
 Christian Krger:     chrisker@cs.tu-berlin.de
 Stephan Slabihoud:    Stephan Slabihoud @ 2:2448/2020.6 (Fido)

Ergnzungen zu dieser Liste bitte an mich (Dirk Haun) senden, Adresse
siehe unter "Kontaktadressen".



4 Kontaktadressen
=================

Wer ist hierfr verantwortlich?

Niemand, denn auch diese Software verwenden Sie auf eigene Gefahr.
Die Idee stammt jedoch von

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

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

und die Ausfhrung (ICFS.PRG) sowie diese Dokumentation sind von

    Dirk Haun
    Europastr. 8
    D-64569 Nauheim

    e-mail: Dirk Haun @ WI2 (MausNet)

Das ICFS.CPX und seine Beschreibung sind von

    John McLoud
    Mozartstrae 1a
    D-65439 Flrsheim am Main

    e-mail: John Mcloud@WI2 (MausNet)



5 Entwicklerdokumentation
=========================


5.1 Beschreibung der Schnittstelle
----------------------------------

Der ICFS legt einen Cookie namens 'ICFS' an. Der Wert dieses Cookies
ist die Adresse einer Funktion, ber die Programme den ICFS aufrufen
knnen.

Die folgenden Beschreibungen erfolgen in C-Syntax (genauer: Pure C).
Wenn Sie mit C nicht vertraut sind, sollten Sie sich zuvor die Hin-
weise fr andere Programmiersprachen durchlesen.

Der aktuelle Server hat die Versionsnummer 1.00. Er kennt folgende
Subfunktionsnummern (ein "0x" kennzeichnet eine Hex-Zahl):

#define ICF_GETSIZE    0x0000  /* Fenstergre, Version abfragen  */
#define ICF_GETPOS     0x0001  /* Fensterposition anfordern       */
#define ICF_FREEPOS    0x0002  /* Fensterposition freigeben       */
#define ICF_SNAP       0x0003  /* Fenster verschieben             */
#define ICF_GETBIGPOS  0x0004  /* groes Fenster anfordern        */
#define ICF_GETLOC     0x0005  /* Fensterposition abfragen        */
#define ICF_GETWPOS    0x0021  /* Fensterposition anfordern       */
#define ICF_FREEWPOS   0x0022  /* Fensterposition freigeben       */
#define ICF_SNAPW      0x0023  /* Fenster verschieben             */
#define ICF_GETBIGWPOS 0x0024  /* groes Fenster anfordern        */
#define ICF_GETWLOC    0x0025  /* Fensterposition abfragen        */
#define ICF_FREEALL    0x0100  /* alle Positionen freigeben       */
#define ICF_SCREEN     0x0101  /* Bildschirmgre bergeben       */
#define ICF_NEXTPOS    0x0102  /* nchste freie Position erfragen */
#define ICF_INFO       0x0200  /* Einstellungen abfragen          */
#define ICF_CONFIG     0x0201  /* Konfiguration ndern            */
#define ICF_SETSIZE    0x0202  /* Fenstergre ndern             */
#define ICF_SETSPACE   0x0203  /* Fensterabstand ndern           */
#define ICF_SETBORDER  0x0204  /* Abstand zum Bildschirmrand      */
#define ICF_NEXTINFO   0x02A0  /* neue Einstellungen abfragen     */
#define ICF_WINOPEN    0x02A1  /* Anzahl offener Fenster abfragen */
#define ICF_GETPATH    0x0300  /* Pfad fr ICFS.PRG erfragen      */

In C definiert man am besten

      int cdecl (*server)(int f,...);
    
      server=get_cookie('ICFS');


Alle Funktionen geben (im Register D0) einen int als Fehlercode zu-
rck. 0 bedeutet "kein Fehler", eine negative Zahl steht fr einen
Fehler. Ungltige Funktionsnummern werden mit -32 (Gemdos-Fehlermel-
dung EINVFN, "Invalid function number") quittiert.

Die Funktionen mit Nummern ab 0x0100 sollten von einem normalen Anwen-
derprogramm nicht aufgerufen werden. Hierfr existiert das ICFS.CPX
von John McLoud, mit dem die Einstellungen bequem vorgenommen werden
knnen.

Ein Programm, das Iconify ohne MultiTOS untersttzen will, braucht
eigentlich nur die Funktionen ICF_GETPOS und ICF_FREEPOS zu unter-
sttzen, die Verwendung von ICF_SNAP wird angeraten.

Alternativ knnen in neueren ICFS-Versionen auch die Funktionen mit
einem 'W' im Namen verwendet werden (also ICF_GETWPOS, ICF_FREEWPOS
und ICF_SNAPW), dazu mehr bei der Beschreibung der einzelnen Funk-
tionen.


5.2 Hinweise fr andere Programmiersprachen
-------------------------------------------

Dieser Text kann natrlich keine Einfhrung in die Sprache C sein.
Dies ist auch nicht notwendig, da fr das Verstndnis nur wenige
Elemente von C bentigt werden.

Es finden (fast) ausschlielich die Datentypen "int" bzw. "unsigned
int" Verwendung. Ein "int" ist eine 16-Bit-Zahl mit Vorzeichen (Werte-
bereich -32768..+32767), ein "unsigned int" entsprechend eine 16-Bit-
Zahl ohne Vorzeichen (Wertebereich 0..65535).

Ein "*" bzw. "&" vor einem Variablennamen kennzeichnet einen Zeiger,
d.h. da statt des Werts der Variablen deren Adresse bergeben wird.

Bei einigen wenigen Funktionen werden Strukturen und Bitfelder verwen-
det, dies betrifft aber nur Konfigurationsaufrufe, mit denen der Pro-
grammierer im Normalfall nichts zu tun hat:

Eine Struktur (struct) entspricht einem Record in anderen Sprachen
und dient dazu, mehrere Variablen zu einem neuen Variablentyp
zusammenzufassen.

Ein Bitfeld ist eine besondere Struktur, bei der die einzelnen Bits
eines Wortes mit Namen belegt werden knnen. Anschlieend knnen die
Bits dann wie normale Elemente einer Struktur angesprochen werden.
Wenn ihre bevorzugte Programmiersprache dies nicht bietet, so knnen
Sie auch mittels der blichen bitweisen Operationen darauf zugreifen.
Es ist jeweils angegeben, welches Bit gemeint ist.

Die bergabe der Parameter bei allen ICFS-Aufrufen geschieht ber den
Stack nach C-Konvention. D.h. da der beim Aufruf am weitesten rechts
stehende Parameter zuerst auf den Stack gelegt wird und der am wei-
testen links stehende Parameter zum Schlu, d.h. beim Einsprung in
den ICFS, obenauf liegt.

C erlaubt Funktionen, bei denen die Zahl und Art der Parameter variie-
ren knnen, davon wird hier Gebrauch gemacht. Fr andere Sprachen mu
man daher ggfs. fr jede Subfunktion ein eigenes Binding erstellen.


5.3 Anmerkungen
---------------

Der ICFS kann das MultiTOS-Iconify nicht nachbilden. Dies wre nur
durch tiefe Eingriffe in die AES zu erreichen. Die einzige Aufgabe
des ICFS ist, die Belegung der Iconpositionen zwischen verschiedenen
Programmen abzustimmen. Fr das eigentliche Iconify ist jedes Pro-
gramm selbst zustndig.

Wenn sowohl ICFS als auch ein MultiTOS-kompatibles Iconify angeboten
werden, so sollten Programme den ICFS ignorieren und das Iconify nach
der MultiTOS-Methode abwickeln. Unter MagiC!3 bzw. MagiCMac lt sich
ICFS bei Bedarf so installieren, da er auch auf das MultiTOS-Iconify
Einflu nimmt, wodurch sich fr den Anwender eine Mischform (Ablegen
als Icons ber das Smaller-Fenstersymbol, Anordnung und Gre der Fen-
ster ber ICFS einstellbar) ergibt.

In den ICFS-Versionen 0.10-0.12 bestand ein direkter Zusammenhang zwi-
schen der zurckgegebenen Positionsnummer ("Handle") und der tatsch-
lichen Position des Iconfensters auf dem Bildschirm. Ab ICFS 1.00
werden die Handles anders vergeben und fortlaufend hochgezhlt.

Einschrnkungen: Die ICFS-Versionen 0.10-0.12 konnten nur ein Feld
von 32x32 Iconfenstern verwalten, was bei virtuellen Auflsungen u.U.
nicht ausreichend war. Ab ICFS 1.00 werden maximal 1024 Iconfenster
in beliebiger Anordnung verwaltet.


5.4 ICFS-Versionen
------------------

Bisher wurden folgende ICFS-Versionen verffentlicht:

       Version  Datum     Anmerkung
      ----------------------------------------
        0.10  07.03.1994  erste Version
        0.11  25.03.1994  neu: ICF_SETSPACE
        0.12  18.11.1994  Bugfix: Cookie Jar
        1.00  06.08.1995  14 neue Funktionen,
                          MagiC-Untersttzung

ICFS 1.00 wurde um insgesamt 14 Funktionen (ICF_SNAP, ICF_GETBIGPOS,
ICF_GETLOC, ICF_GETWPOS, ICF_FREEWPOS, ICF_SNAPW, ICF_GETBIGWPOS,
ICF_GETWLOC, ICF_SETBORDER, ICF_SCREEN, ICF_NEXTPOS, ICF_NEXTINFO,
ICF_WINOPEN und ICF_GETPATH) sowie um die Untersttzung fr MagiC!3
und MagiCMac erweitert, daher auch der groe Sprung in der Versi-
onsnummer.


andere Versionen

Versionen mit Nummern kleiner 0.10 haben niemals existiert. Versi-
onen, die ein '' (gr. Beta) hinter der Versionsnummer fhren, sind
Beta-Versionen, d.h. Testversionen, die u.U. noch Fehler enthalten.
Sollten Sie eine solche Version besitzen, so vernichten Sie sie bitte
und besorgen Sie sich eine aktuellere Version.


5.5 Unterschiede der Versionen
------------------------------

Die folgende Tabelle zeigt, welche Funktionen ab welcher ICFS-Version
zur Verfgung stehen:

      Funktion       ab Version
     ---------------------------
      ICF_CONFIG      alle
      ICF_FREEALL     alle
      ICF_FREEPOS     alle
      ICF_FREEWPOS    1.00
      ICF_GETBIGPOS   1.00 (siehe Anmerkung)
      ICF_GETBIGWPOS  1.00 (siehe Anmerkung)
      ICF_GETLOC      1.00
      ICF_GETPATH     1.00
      ICF_GETPOS      alle
      ICF_GETSIZE     alle
      ICF_GETWLOC     1.00
      ICF_GETWPOS     1.00
      ICF_INFO        alle
      ICF_NEXTINFO    1.00
      ICF_NEXTPOS     1.00
      ICF_SCREEN      1.00
      ICF_SETBORDER   1.00
      ICF_SETSIZE     alle
      ICF_SETSPACE    0.11
      ICF_SNAP        1.00 (siehe Anmerkung)
      ICF_SNAPW       1.00 (siehe Anmerkung)
      ICF_WINOPEN     1.00

Allgemein gilt aber, da das Vorhandensein einer Funktion nicht ber
die Versionsnummer abgefragt werden sollte! Stattdessen sollte der
Rckgabewert der jeweiligen Funktion ausgewertet werden, denn alle
ICFS-Versionen liefern -32 (den Gemdos-Fehlercode fr "Funktion nicht
vorhanden"), wenn sie mit einer unbekannten Funktionsnummer aufge-
rufen werden.

Von dieser Mglichkeit sollten Sie insbesondere bei den Funktionen
ICF_GETBIGPOS bzw. ICF_GETBIGWPOS und ICF_SNAP bzw. ICF_SNAPW Ge-
brauch machen, da diese jederzeit mit ICF_CONFIG ein- und ausgeschal-
tet werden knnen!

brigens werden die bergebenen Parameter nicht verndert, wenn eine
Funktion nicht zur Verfgung steht. Daher knnen Sie einen Aufruf von
ICF_SNAP beispielsweise so formulieren:

     int ret, new_x, new_y, width, height,
         win_handle, ic_handle;
    
     ret=server(ICF_SNAP,ic_handle,&new_x,&new_y);
     if(ret==-32 || ret==0)
       wind_set(win_handle,WF_CURRXYWH,new_x,new_y,width,height);
     else bell(); /* Fehler */

Die Funktion ICF_CONFIG verhlt sich ab ICFS 1.00 etwas anders: Die
angegebenen nderungen werden nur dann sofort bernommen, wenn kein
Iconfenster offen ist, andernfalls werden sie zwischengespeichert und
erst dann gesetzt, wenn einmal keine Iconfenster mehr offen sind.
Somit verhlt sich ICF_CONFIG nun wie ICF_SETSIZE, ICF_SETSPACE und
ICF_SETBORDER.



6 Beschreibung der Funktionen
=============================

ICFS 1.00 bietet die folgenden Funktionen an:

     ICF_CONFIG         ICF_GETPOS       ICF_SETBORDER
     ICF_FREEALL        ICF_GETSIZE      ICF_SETSIZE
     ICF_FREEPOS        ICF_GETWLOC      ICF_SETSPACE
     ICF_FREEWPOS       ICF_GETWPOS      ICF_SNAP
     ICF_GETBIGPOS      ICF_INFO         ICF_SNAPW
     ICF_GETBIGWPOS     ICF_NEXTINFO     ICF_WINOPEN
     ICF_GETLOC         ICF_NEXTPOS
     ICF_GETPATH        ICF_SCREEN


6.1 ICF_GETSIZE
---------------

 Name          ICF_GETSIZE - Gre der Iconfenster abfragen

 Nummer        0

 Definition    int server(ICF_GETSIZE,int *w,int *h);

 Beschreibung  ICF_GETSIZE liefert in 'w' (Breite) und 'h' (Hhe) die
               aktuelle Gre eines ikonifizierten Fensters zurck.

 Rckgabe      Die Funktion gibt die Versionsnummer des ICFS als BCD
               zurck (d.h. der Wert 0x0010 entspricht der Version
               0.10).


6.2 ICF_GETPOS
--------------

 Name          ICF_GETPOS - eine Iconposition anfordern

 Nummer        1

 Definition    int server(ICF_GETPOS,int *x,int *y,int *w,int *h);

 Beschreibung  Der Server liefert eine Fensterposition (in 'x' und
               'y') und die aktuelle Gre eines ikonifizierten Fen-
               sters (in 'w' und 'h') zurck. Diese Position ist nun
               belegt und mu mit ICF_FREEPOS wieder freigegeben wer-
               den, wenn sie nicht mehr bentigt wird.

 Rckgaben     >=0: die Nummer der Position, genannt "Handle"
                -1: Fehler (keine Position mehr frei)

 siehe auch    ICF_FREEPOS, ICF_GETBIGPOS, ICF_SNAP


6.3 ICF_FREEPOS
---------------

 Name          ICF_FREEPOS - eine Iconposition freigeben

 Nummer        2

 Definition    void server(ICF_FREEPOS,int posnr);

 Beschreibung  Gibt das Fenster 'posnr' (Nummer der Fensterposition
               wie von ICF_GETPOS oder ICF_GETBIGPOS geliefert) wie-
               der frei.

 Rckgaben     keine

 siehe auch    ICF_GETPOS, ICF_GETBIGPOS


6.4 ICF_SNAP
------------

 Name          ICF_SNAP - ein Iconfenster an eine andere Position
               verschieben

 Nummer        3

 Definition    int server(ICF_SNAP,int handle,int *x,int *y);

 Beschreibung  Wenn ein Iconfenster verschoben wird, ist es wnschens-
               wert, da es wieder an einer Position "einrastet", die
               ein Vielfaches der aktuellen Hhe und Breite eines
               Iconfensters ist.

               Die Funktion erwartet in 'handle' ein Icon-Handle, wie
               es von ICF_GETPOS oder ICF_GETBIGPOS vergeben wurde
               und in 'x' und 'y' die gewnschte neue Position (linke
               obere Ecke des Fensters).

               Wird eine neue Position gefunden, so wird diese in 'x'
               und 'y' zurckgegeben, andernfalls bleiben 'x' und 'y'
               unverndert.

 Rckgaben      0: neue Iconposition gefunden
               -1: Fehler (Handle unbekannt oder an der gewnschten
                   Stelle ist kein Platz mehr)

 siehe auch    ICF_GETPOS, ICF_GETBIGPOS

 Anmerkung     Diese Funktion steht erst ab ICFS 1.00 zur Verfgung.
               Testen Sie aber bitte nicht die Versionsnummer ab, son-
               dern rufen Sie die Funktion einfach auf und berprfen
               Sie, ob ICF_SNAP -32 (Funktion nicht vorhanden) oder 0
               bzw. -1 (s.o.) liefert! Bedenken Sie bitte auch, da
               diese Funktion jederzeit abschaltbar ist (siehe
               ICF_CONFIG).


6.5 ICF_GETBIGPOS
-----------------

 Name          ICF_GETBIGPOS - eine Iconposition fr ein groes Icon-
               fenster anfordern

 Nummer        4

 Definition    int server(ICF_GETBIGPOS,int wf,int hf,int *x,int *y,
                          int *w,int *h);

 Beschreibung  Der Server liefert eine Fensterposition (in 'x' und
               'y') zurck. Im Gegensatz zu ICF_GETPOS knnen hiermit
               auch Iconfenster angefordert werden, deren Breite und
               Hhe ein Vielfaches der Gre eines normalen Iconfen-
               sters ist.

               'wf' und 'hf' geben die Faktoren an, d.h. bei wf=2 und
               hf=1 wird ein Fenster angefordert, das doppelt so
               breit und genauso hoch wie ein normales Iconfenster
               ist. 'wf' und 'hf' knnen aber auch beide 1 sein, die
               Funktion verhlt sich dann wie ICF_GETPOS.

               In 'w' und 'h' wird die tatschliche Breite und Hhe
               in Pixeln zurckgeliefert. Dies bercksichtigt auch
               einen evtl. eingestellten Abstand zwischen den Iconfen-
               stern.

 Rckgaben     >=0: die Nummer der Position, genannt "Handle"
                -1: Fehler (keine Position mehr frei)

 siehe auch    ICF_FREEPOS, ICF_GETPOS, ICF_CONFIG

 Anmerkung     ICF_GETBIGPOS ist per Default deaktiviert und mu erst
               mit ICF_CONFIG eingeschaltet werden. Wenn die Funktion
               nicht vorhanden oder deaktiviert ist, wird statt eines
               Handles -32 zurckgegeben.


6.6 ICF_GETLOC
--------------

 Name          ICF_GETLOC - Position eines Iconfensters abfragen

 Nummer        5

 Definition    int server(ICF_GETLOC,int handle,int *x,int *y,
                          int *w,int *h);

 Beschreibung  Die Funktion liefert die aktuelle Position (in 'x' und
               'y') und die aktuellen Ausmae (in 'w' und 'h') des
               Iconfensters mit dem Handle 'handle' zurck.

 Rckgaben     ==0: Position wurde ermittelt und zurckgegeben
                -1: Fehler (Handle unbekannt oder ungltig)

 siehe auch    ICF_GETPOS, ICF_GETBIGPOS, ICF_SNAP


6.7 ICF_GETWPOS
---------------

 Name          ICF_GETWPOS - eine Iconposition anfordern

 Nummer        $21 (dez. 33)

 Definition    int server(ICF_GETWPOS,int win,int *x,int *y,
                          int *w,int *h);

 Beschreibung  Der Server liefert eine Fensterposition (in 'x' und
               'y') und die aktuelle Gre eines ikonifizierten Fen-
               sters (in 'w' und 'h') zurck. Diese Position ist nun
               belegt und mu mit ICF_FREEWPOS wieder freigegeben wer-
               den, wenn sie nicht mehr bentigt wird.

               Im Gegensatz zu ICF_GETPOS bergibt man hier in 'win'
               das Handle eines bereits mit wind_create() erzeugten
               Fensters. Die zurckgelieferte Iconposition ist nun
               fr dieses Fenster reserviert.

 Rckgaben     ==0: es wurde eine Iconposition gefunden und fr das
                    Fenster reserviert
                -1: Fehler (keine Position mehr frei)

 siehe auch    ICF_FREEWPOS, ICF_GETBIGWPOS, ICF_SNAPW


6.8 ICF_FREEWPOS
----------------

 Name          ICF_FREEWPOS - eine Iconposition freigeben

 Nummer        $22 (dez. 34)

 Definition    void server(ICF_FREEWPOS,int win);

 Beschreibung  Gibt die Position frei, die das Fenster mit AES-Handle
               'win' gerade belegt. Diese Position mu zuvor mit
               ICF_GETWPOS oder ICF_GETBIGWPOS angefordert worden
               sein.

 Rckgaben     keine

 siehe auch    ICF_GETWPOS, ICF_GETBIGWPOS


6.9 ICF_SNAPW
-------------

 Name          ICF_SNAPW - ein Iconfenster an eine andere Position
               verschieben

 Nummer        $23 (dez. 35)

 Definition    int server(ICF_SNAPW,int win,int *x,int *y);

 Beschreibung  Wenn ein Iconfenster verschoben wird, ist es wnschens-
               wert, da es wieder an einer Position "einrastet", die
               ein Vielfaches der aktuellen Hhe und Breite eines
               Iconfensters ist.

               Die Funktion erwartet in 'win' ein AES-Handle eines
               Fensters, das mit wind_create() angelegt und fr das
               bereits mit ICF_GETWPOS oder ICF_GETBIGWPOS eine Posi-
               tion angefordert wurde. In 'x' und 'y' wird die ge-
               wnschte neue Position (linke obere Ecke des Fensters)
               erwartet.

               Wird eine neue Position gefunden, so wird diese in 'x'
               und 'y' zurckgegeben, andernfalls bleiben 'x' und 'y'
               unverndert.

 Rckgaben      0: neue Iconposition gefunden
               -1: Fehler (Fenster unbekannt oder an der gewnschten
                   Stelle ist kein Platz mehr)

 siehe auch    ICF_GETWPOS, ICF_GETBIGWPOS

 Anmerkung     Diese Funktion steht erst ab ICFS 1.00 zur Verfgung.
               Testen Sie aber bitte nicht die Versionsnummer ab, son-
               dern rufen Sie die Funktion einfach auf und berprfen
               Sie, ob ICF_SNAPW -32 (Funktion nicht vorhanden) oder
               0 bzw. -1 (s.o.) liefert! Bedenken Sie bitte auch, da
               diese Funktion jederzeit abschaltbar ist (siehe
               ICF_CONFIG).


6.10 ICF_GETBIGWPOS
-------------------

 Name          ICF_GETBIGWPOS - eine Iconposition fr ein groes Icon-
               fenster anfordern

 Nummer        $24 (dez. 36)

 Definition    int server(ICF_GETBIGWPOS,int win,int wf,int hf,
                          int *x,int *y,int *w,int *h);

 Beschreibung  Der Server liefert eine Fensterposition (in 'x' und
               'y') fr ein Fenster zurck, dessen AES-Handle in
               'win' bergeben wird. Im Gegensatz zu ICF_GETWPOS kn-
               nen hiermit auch Iconfenster angefordert werden, deren
               Breite und Hhe ein Vielfaches der Gre eines norma-
               len Iconfensters ist.

               'wf' und 'hf' geben die Faktoren an, d.h. bei wf=2 und
               hf=1 wird ein Fenster angefordert, das doppelt so
               breit und genauso hoch wie ein normales Iconfenster
               ist. 'wf' und 'hf' knnen aber auch beide 1 sein, die
               Funktion verhlt sich dann wie ICF_GETWPOS.

               In 'w' und 'h' wird die tatschliche Breite und Hhe
               in Pixeln zurckgeliefert. Dies bercksichtigt auch
               einen evtl. eingestellten Abstand zwischen den Iconfen-
               stern.

 Rckgaben     ==0: es wurde eine Iconposition gefunden und fr das
                    Fenster reserviert
                -1: Fehler (keine Position mehr frei)

 siehe auch    ICF_FREEWPOS, ICF_GETWPOS, ICF_CONFIG

 Anmerkung     ICF_GETBIGWPOS ist per Default deaktiviert und mu
               erst mit ICF_CONFIG eingeschaltet werden. Wenn die
               Funktion nicht vorhanden oder deaktiviert ist, wird
               -32 zurckgegeben.


6.11 ICF_GETWLOC
----------------

 Name          ICF_GETWLOC - Position eines Iconfensters abfragen

 Nummer        $25 (dez. 37)

 Definition    int server(ICF_GETWLOC,int win,int *x,int *y,
                          int *w,int *h);

 Beschreibung  Die Funktion liefert die aktuelle Position (in 'x' und
               'y') und die aktuellen Ausmae (in 'w' und 'h') des
               Iconfensters mit dem AES-Handle 'win' zurck.

 Rckgaben     ==0: Position wurde ermittelt und zurckgegeben
                -1: Fehler (Fensterhandle unbekannt oder ungltig)

 siehe auch    ICF_GETWPOS, ICF_GETBIGWPOS, ICF_SNAPW


6.12 ICF_FREEALL
----------------

 Name          ICF_FREEALL - alle Iconpositionen freigeben

 Nummer        $100 (dez. 256)

 Definition    void server(ICF_FREEALL);

 Beschreibung  Gibt alle belegten Fensterpositionen frei. Gedacht ist
               dies hauptschlich dazu, um von abgestrzten Program-
               men nicht mehr freigegebene Positionen und Handles wie-
               der nutzbar zu machen.

               Diese Funktion sollte nicht automatisch aufgerufen,
               sondern nur auf besonderen Wunsch des Anwenders ausge-
               lst werden knnen.

 Rckgaben     keine

 Anmerkung     Das ICFS.CPX von John McLoud bietet diese Funktion an.


6.13 ICF_SCREEN
---------------

 Name          ICF_SCREEN - Bildschirmgre bergeben

 Nummer        $101 (dez. 257)

 Definition    void server(ICF_SCREEN,int x,int y,int w,int h);

 Beschreibung  Hierber kann die Gre des Bildschirms, d.h. die ver-
               fgbare Arbeitsflche, bergeben werden.

               Normalerweise berprft ICFS bei jedem Aufruf die Bild-
               schirmgre mit

                  wind_get(0,WF_WORKXYWH,&x,&y,&w,&h);

               In manchen Situationen kann dieser AES-Aufruf aber un-
               erwnscht sein (z.B. wenn der ICFS seinerseits aus den
               AES heraus aufgerufen wird). In solchen Fllen mu
               dann die Gre des Arbeitsbereichs ber ICF_SCREEN
               bergeben werden.

               Achtung: Wenn ICF_SCREEN einmal aufgerufen wurde, wird
               der ICFS ab dann keinen wind_get(WORKXYWH)-Aufruf mehr
               durchfhren. Alle nderungen der Auflsung mssen also
               durch weitere ICF_SCREEN-Aufrufe mitgeteilt werden.

               Diese Funktion ist nur in ganz wenigen Spezialfllen
               von Nutzen. Wer immer sie aufruft, sollte genau wis-
               sen, was er tut ...

               Unmittelbar nach ICF_SCREEN sollte nach Mglichkeit
               auch ICF_FREEALL aufgerufen werden.

 Rckgaben     keine


6.14 ICF_NEXTPOS
----------------

 Name          ICF_NEXTPOS - nchste freie Iconposition erfragen

 Nummer        $102 (dez. 258)

 Definition    int server(ICF_NEXTPOS,int *x,int *y,int *w,int *h);

 Beschreibung  Die Funktion ermittelt die nchste freie Iconposition,
               d.h. die Position, die beim nchsten Aufruf von
               ICF_GETPOS oder ICF_GETWPOS vergeben wird.

               Man darf sich nun natrlich nicht darauf verlassen,
               bei einem nachfolgenden Aufruf von ICF_GETPOS auch
               wirklich diese Position zu bekommen, da die Position
               zwischenzeitlich an ein anderes Programm vergeben
               worden sein knnte.

 Rckgaben     ==0: freie Position gefunden
                -1: Fehler (keine Position mehr frei)


6.15 ICF_INFO
-------------

 Name          ICF_INFO - Informationen abfragen

 Nummer        $200 (dez. 512)

 Definition    int server(ICF_INFO,ICFSCONFIG *conf,int size);

 Beschreibung  'conf' ist ein Zeiger auf eine Struktur ICFSCONFIG,
               die wie folgt definiert ist:

               struct _conf
               {
                unsigned resvd  : 11; /* unbenutzt, sollte 0 sein   */
                unsigned snap   : 1;  /* Bit 4: 1=Snapping ein      */
                unsigned bigics : 1;  /* Bit 3: 1=groe Iconfenster */
                unsigned yfirst : 1;  /* Bit 2: 1=y-Richtung zuerst */
                unsigned right  : 1;  /* Bit 1: 1=rechts anfangen   */
                unsigned top    : 1;  /* Bit 0: 1=oben anfangen     */
               };

               typedef struct
               {
                unsigned int version; /* Versionsnummer als BCD     */
                struct _conf config;  /* Konfigurationsbits, s.o.   */
                int xsize, ysize,     /* Breite, Hhe des Fensters  */
                    xspace, yspace,   /* Abstand zwischen Fenstern  */
                    xborder, yborder; /* Abstand vom Bildschirmrand */
               } ICFSCONFIG;

               In der Struktur steht als erstes die Versionsnummer
               als BCD (d.h. 0x0010 fr Version 0.10), dann folgt ein
               Bitfeld, d.h. ein 16-Bit-Wort, dessen einzelne Bits
               die angegebene Bedeutung haben (vgl. auch ICF_CONFIG).
               Anschlieend stehen noch die aktuelle Breite und Hhe
               eines ikonifzierten Fensters, sowie der Abstand zwi-
               schen zwei solchen Fenstern und zum Bildschirmrand.

               Durch diesen Aufruf hat man Zugriff auf alle wichtigen
               Informationen der aktuellen Konfiguration. Beim Aufruf
               wird ein Zeiger auf einen Speicherbereich im Anwender-
               programm(!) bergeben, den der ICFS dann mit den Wer-
               ten fllt. In 'size' wird die Gre dieses Bereichs
               bergeben, als Rckgabewert erhlt man (als Informati-
               on) die tatschliche Gre der Struktur. Sptere ICFS-
               Versionen knnten eine grere Struktur verwenden,
               durch den Parameter 'size' kopiert der ICFS aber immer
               nur soviele Daten, wie der Aufrufer kennt (tatschlich
               wurde diese Struktur bereits zweimal erweitert).

               Da die Struktur in den Speicherbereich des Anwenderpro-
               gramms kopiert wird, ist ein Verndern der Werte natr-
               lich ohne Wirkung. Dafr existieren die Funktionen
               ICF_CONFIG, ICF_SETSIZE, ICF_SETSPACE und
               ICF_SETBORDER.

 Rckgabe      Die Gre der ICFSCONFIG-Struktur der installierten
               ICFS-Version.

 siehe auch    ICF_CONFIG, ICF_SETSIZE, ICF_SETSPACE, ICF_SETBORDER

 Anmerkung     Die Elemente 'xspace' und 'yspace' existieren in der
               Struktur erst ab ICFS 0.11, 'xborder' und 'yborder'
               erst ab ICFS 1.00.


6.16 ICF_CONFIG
---------------

 Name          ICF_CONFIG - ICFS konfigurieren

 Nummer        $201 (dez. 513)

 Definition    int server(ICF_CONFIG,unsigned int config);

 Beschreibung  Mit den untersten drei Bits von config kann die Art
               und Weise eingestellt werden, wie die Iconfenster auf
               dem Bildschirm plaziert werden:

               Bit 0: 0 = unten anfangen
                      1 = oben anfangen
               Bit 1: 0 = links anfangen
                      1 = rechts anfangen
               Bit 2: 0 = erst in x-, dann y-Richtung belegen
                      1 = erst in y-, dann x-Richtung

               Die MultiTOS-Methode (unten links beginnen, in x-Rich-
               tung weiter) entspricht also dem Wert 0, oben rechts
               beginnend in y-Richtung (nach unten) wre der Wert 7.

               ber das vierte Bit knnen ab ICFS 1.00 Iconfenster
               aktiviert werden, deren Breite und Hhe ein vielfaches
               der normalen Fenstermae sind (siehe ICF_GETBIGPOS
               bzw. ICF_GETBIGWPOS):

               Bit 3: 0 = groe Iconfenster nicht erlaubt (default)
                      1 = groe Iconfenster erlaubt

               ber das fnfte Bit kann, ebenfalls ab Version 1.00,
               das Snapping aktiviert oder deaktiviert werden (die
               Defaulteinstellung ist "aus"):

               Bit 4: 0 = Snapping aus (default)
                      1 = Snapping ein

               Die restlichen Bits werden z.Z. nicht verwendet und
               sollten 0 sein.

 Rckgaben     ICFS 0.10-0.12: immer 0, Konfiguration wird sofort
               bernommen

               ab ICFS 1.00:
                0: Konfiguration wurde bernommen
                1: Konfiguration wird bernommen, sobald keine Icon-
                   fenster mehr offen sind

 siehe auch    ICF_INFO, ICF_NEXTINFO, ICF_GETBIGPOS, ICF_GETBIGWPOS

 Anmerkung     Die Werte fr die Schalter fr groe Iconfenster (Bit
               3) und das Snapping (Bit 4) werden immer sofort ber-
               nommen, unabhngig davon, ob noch Fenster offen sind.


6.17 ICF_SETSIZE
----------------

 Name          ICF_SETSIZE - Iconfenstergre setzen

 Nummer        $202 (dez. 514)

 Definition    int server(ICF_SETSIZE,int nw,int nh);

 Beschreibung  Setzt eine neue Breite 'nw' und Hhe 'nh' fr Iconfen-
               ster fest. Sind noch Fensterpositionen belegt, so wird
               diese Angabe erst bernommen, wenn einmal alle Positi-
               onen frei sind (Die Aufrufe ICF_GETSIZE, ICF_GETPOS
               bzw. ICF_GETWPOS und ICF_GETBIGPOS bzw. ICF_GETBIGWPOS
               liefern solange auch noch die alten Grenangaben).

 Rckgaben     -1: ungltige Grenangaben
                0: Grenangabe wurde bernommen
                1: Grenangabe wird bernommen, sobald kein Icon-
                   fenster mehr offen ist

 siehe auch    ICF_INFO, ICF_NEXTINFO, ICF_GETSIZE, ICF_GETPOS

 Anmerkung     Atari empfiehlt, in ein ikonifiziertes Fenster ein
               Icon zu zeichnen. Geht man von einem normalgroen Icon
               aus (32x32 Pixel mit Text darunter), dann erscheint
               eine Fenstergre von weniger als 64x64 Pixel nicht
               sinnvoll (64x64 sind die Auenmae).


6.18 ICF_SETSPACE
-----------------

 Name          ICF_SETSPACE - Abstand zwischen Iconfenstern setzen

 Nummer        $203 (dez. 515)

 Definition    int server(ICF_SETSPACE,int nx,int ny);

 Beschreibung  Setzt den Abstand zwischen zwei ICFS-Fenstern fest, ge-
               trennt nach x- und y-Abstand ('nx' bzw. 'ny'). Sind
               noch Fensterpositionen belegt, so werden diese Angaben
               erst bernommen, wenn einmal alle Positionen frei
               sind. ICF_INFO liefert solange noch die alten Werte.

 Rckgaben     -1: ungltige Abstandsangaben
                0: Abstnde wurden bernommen
                1: Abstnde werden bernommen, sobald kein Icon-
                   fenster mehr offen ist

 siehe auch    ICF_INFO, ICF_NEXTINFO

 Anmerkung     Diese Funktion existiert erst ab ICFS 0.11 (ebenso wie
               die zugehrigen Elemente in ICFSCONFIG). ltere Versi-
               onen liefern bei Aufruf von ICF_SETSPACE die Rckgabe
               -32.


6.19 ICF_SETBORDER
------------------

 Name          ICF_SETBORDER - Abstand vom Bildschirmrand einstellen

 Nummer        $204 (dez. 516)

 Definition    int server(ICF_SETBORDER,int bx,int by);

 Beschreibung  Mit dieser Funktion kann ein Abstand eingestellt wer-
               den, den die Iconfenster vom Bildschirmrand einhalten
               sollen. Der Abstand kann fr die x- und y-Richtung ge-
               trennt angegeben werden ('bx' bzw. 'by') und gilt je-
               weils fr den linken und rechten bzw. oberen und unte-
               ren Rand, d.h. bei einem Wert von 4 fr 'bx' werden
               vom linken und vom rechten Rand jeweils vier Pixel Ab-
               stand gelassen.

               Sind beim Aufruf von ICF_SETBORDER noch Fensterpositi-
               onen belegt, so werden die Angaben erst bernommen,
               wenn einmal alle Positionen frei sind. ICF_INFO lie-
               fert solange noch die alten Werte.

 Rckgaben     -1: ungltige Abstandsangaben
                0: Abstnde wurden bernommen
                1: Abstnde werden bernommen, sobald kein Icon-
                   fenster mehr offen ist

 siehe auch    ICF_INFO, ICF_NEXTINFO

 Anmerkung     Diese Funktion existiert erst ab ICFS 1.00 (ebenso wie
               die zugehrigen Elemente in ICFSCONFIG). ltere Versi-
               onen liefern bei Aufruf von ICF_SETBORDER die Rckgabe
               -32.


6.20 ICF_NEXTINFO
-----------------

 Name          ICF_NEXTINFO - neue Informationen abfragen

 Nummer        $2A0 (dez. 672)

 Definition    int server(ICF_NEXTINFO,ICFSCONFIG *conf,int size);

 Beschreibung  Mit dieser Funktion knnen die Informationen abgefragt
               werden, die als nchstes eingestellt werden. Ansonsten
               funktioniert dieser Aufruf exakt wie ICF_INFO.

               Die Aufrufe ICF_CONFIG, ICF_SETSIZE, ICF_SETSPACE und
               ICF_SETBORDER zeigen keine Wirkung, solange noch Icon-
               fenster offen sind. Die neuen Werte werden aber zwi-
               schengespeichert und eingestellt, sobald einmal kein
               Iconfenster mehr offen ist. Und genau diese zwischenge-
               speicherten Werte knnen mit ICF_NEXTINFO abgefragt
               werden.

 Rckgabe      Die Gre der ICFSCONFIG-Struktur der installierten
               ICFS-Version.

 siehe auch    ICF_INFO, ICF_CONFIG, ICF_SETSIZE, ICF_SETSPACE


6.21 ICF_WINOPEN
----------------

 Name          ICF_WINOPEN - liefert Anzahl der offenen Iconfenster

 Nummer        $2A1 (dez. 673)

 Definition    int server(ICF_WINOPEN);

 Beschreibung  ber diesen Aufruf kann abgefragt werden, ob und wie-
               viele Iconfenster noch offen bzw. dem ICFS bekannt
               sind.

               Diese Funktion ist nicht fr normale Anwenderprogramme
               gedacht, sondern fr Konfigurationsprogramme, die die
               ICFS-Einstellungen ndern wollen und dazu wissen ms-
               sen, ob die nderungen gleich oder erst spter ber-
               nommen werden.

               Die Funktion knnte auch beim Debugging behilflich
               sein, um festzustellen, ob Programme vergessen haben,
               ihre Iconfenster beim ICFS abzumelden.

 Rckgabe      Anzahl der offenen Iconfenster


6.22 ICF_GETPATH
----------------

 Name          ICF_GETPATH - Pfad von ICFS.PRG erfragen

 Nummer        $300 (dez. 768)

 Definition    void server(ICF_GETPATH,char *path);

 Beschreibung  Diese Funktion liefert den kompletten Pfad- und Datei-
               namen, unter dem ICFS.PRG gestartet wurde. Dazu ber-
               gibt man in 'path' einen Zeiger auf einen ausreichend
               groen Speicherbereich, in dem ICFS dann den Namen als
               nullterminierten C-String ablegt.

               Achtung: Es sind Flle denkbar, in denen ICFS seinen
               Pfad nicht oder nicht korrekt ermitteln kann (z.B.
               wenn MetaDOS unter einem Multitasking-System luft
               oder wenn ICFS im AUTO-Ordner liegt und nicht ICFS.PRG
               heit). Bevor man den Pfad verwendet, sollte man also
               nachprfen, ob die angegebene Datei tatschlich exi-
               stiert.

               Im Normalfall, d.h. wenn ICFS.PRG aus dem AUTO- oder
               unter MagiC aus dem APPS-Ordner heraus gestartet wur-
               de, stimmt der Pfad aber.

 Rckgaben     keine




A MultiTOS-Iconify
==================

Das MultiTOS-Iconify (ab MultiTOS 1.08beta sowie unter MagiC!3 und
MagiCMac) wird ausgelst ber das neue Fensterelement "Smaller" (auch
"Iconifier") genannt. Wenn der Smaller angeklickt wird, erhlt das
Programm eine Nachricht WM_ICONIFY bzw. WM_ALLICONIFY (wenn gleich-
zeitig die Control-Taste gedrckt wurde).

Die Nachrichten sind wie folgt aufgebaut:

      msg[0] = WM_ICONIFY (34)
      msg[1] = Application-ID des Absenders
      msg[2] = 0
      msg[3] = Handle des Fensters, das ikonifiziert werden soll
      msg[4] = x-Koordinate fr das Iconfenster
      msg[5] = y-Koordinate fr das Iconfenster
      msg[6] = Breite des Iconfensters (Auenmae)
      msg[7] = Hhe des Iconfensters (Auenmae)

Die Nachricht WM_ALLICONIFY ist genauso aufgebaut, nur msg[0] enthlt
den Wert 36.

Als Reaktion auf WM_ICONIFY sollte das Programm

      wind_set(msg[3],WF_ICONIFY,msg[4],msg[5],msg[6],msg[7]);

aufrufen. Das Fenster wird dann als Icon abgelegt. Nach einem Doppel-
klick in ein solches Fenster erhlt das Programm dann die Nachricht
WM_UNICONIFY (Nr. 35), die ebenfalls wie WM_ICONIFY aufgebaut ist,
dann aber die alten Koordinaten und Mae des Fensters vor seiner
Verkleinerung enthlt.

Wenn ein Programm von sich aus ein Fenster als Icon ablegen will
(z.B. als Reaktion auf die Tastenkombination [Control][Alternat][Leer-
taste]), dann kann es dazu wie folgt vorgehen ('win' sei das Handle
des Fensters):

      wind_close(win);
      wind_set(win,WF_ICONIFY,-1,-1,-1,-1);
      wind_open(win,-1,-1,-1,-1);

Dieser "Trick" wurde nachtrglich fr MultiTOS dokumentiert und funk-
tioniert auch unter MagiC!3 und MagiCMac (dort mu das Fenster sogar
nicht extra geschlossen werden, der angegebene Aufruf von wind_set()
gengt vllig).

Noch einige Anmerkungen:

    Wenn das Fenster vor wind_set(win,WF_ICONIFY,-1,-1,-1,-1) ge-
     schlossen wird, kann WM_UNICONIFY natrlich keine gltigen Koor-
     dinaten fr das alte Fenster liefern, das Programm mu sich
     diese dann also selbst merken.

    Als Reaktion auf WM_ALLICONIFY sollte ein Programm alle seine
     Fenster schlieen und stattdessen ein neues Iconfenster ffnen.
     Andere bereits als Icons abgelegte Fenster der gleichen Applika-
     tion sollten aber in ihrem Zustand belassen werden.

     Darber, ob ein Programm beim "All-Iconify" auch seine Men-
     leiste sperren sollte, so da keine neuen Aktionen ausgelst
     werden knnen ("Applikation ikonifizieren") herrscht z.Z. noch
     Uneinigkeit, es erscheint aber logisch: Einzel-Iconify wird
     normalerweise dann verwendet, wenn man ein einzelnes Fenster
     "aus dem Weg rumen" mchte. Der Wunsch, alle Fenster zu ikonifi-
     zieren deutet eher darauf hin, da mit einer anderen Applikation
     weitergearbeitet werden soll und man zum aktuellen Programm erst
     spter wieder zurckkehren will (dies gibt in diesem Punkt aber
     nur die persnliche Meinung des Autors dieser Zeilen wider ...).

    Durch den Aufruf von wind_set(WF_ICONIFY) mit den Koordinaten
     aus der WM_ICONIFY-Nachricht wird das Fenster automatisch an die
     neue Position versetzt. Es ist also nicht notwendig, zustzlich
     noch wind_set(WF_CURRXYWH) aufzurufen, wie es einige Programme
     unntigerweise tun.

    Atari empfiehlt, in ein als Icon abgelegtes Fenster ein Icon zu
     zeichnen. Wenn ein Programm mehrere Fenster hat, dann sollte aus
     dem Iconfenster bzw. dem darin dargestellten Icon zumindest der
     Typ des ursprnglichen Fensters hervorgehen (also nicht einfach
     in jedes Iconfenster das gleiche Icon malen).

     Eine andere sinnvolle Nutzung des Iconfensters besteht in einer
     verkleinerten oder verkrzten Darstellung des ursprnglichen Fen-
     sterinhalts, also z.B. einer verkleinerten Darstellung eines
     Bildes oder der Angabe der Anzahl der im Fenster dargestellten
     Objekte.

    Beim Redraw des Iconfensters sollte man mglichst die gerade
     aktuellen Ausmae (z.B. mit wind_get(WF_WORKXYWH)) abfragen.
     Insbesondere sollte man nicht davon ausgehen, da das Fenster
     immer 72 Pixel breit und hoch ist (auch wenn dies die Default-
     einstellung in allen Systemen ist, die Iconify untersttzen).

    Die Ausgabe des Icons bzw. des verkleinerten Fensterinhalts
     sollte mglichst zentriert erfolgen (aktuelle Ausmae abfra-
     gen!).

    Das neue Fensterelement Smaller kann (und sollte) immer bei
     wind_create() mit angegeben werden, wenn das Fenster als Icon
     abgelegt werden knnen soll. Die Bitkombination fr den Smaller
     wurde von Atari extra nochmals gendert, damit dieses Bit auch
     wirklich gefahrlos unter allen TOS-Versionen gesetzt werden
     kann.

     Infolgedessen sollte man auch immer damit rechnen, WM_ICONIFY-
     Nachrichten zu empfangen. Fr Betriebssystemversionen, die kein
     Iconify anbieten (z.B. SingleTOS), sind Zusatzprogramme denkbar
     (bzw. existieren sogar schon), die das Iconify dort nachrsten.


Konstanten:

/* new AES messages */

#define WM_ICONIFY       34
#define WM_UNICONIFY     35
#define WM_ALLICONIFY    36


/* new window defs */

#define WF_ICONIFY       26
#define WF_UNICONIFY     27

#define SMALLER      0x4000



