

                           A-MAN 1.7
                        Programmier-Doku

                          Sven Kopacz


1. A-MAN ist ein Programm, das unter allen TOS-Systemen neue 
AES-Funktionen zur Verfgung stellt. A-MAN ist Freeware und darf 
eigenen Programmen ohne weiteres beigelegt werden. A-MAN existiert in 
einer speziellen Version, die auer dem eigenen Cookie ('AmAN') noch 
einen weiteren Cookie ('WICO') anlegt. Diese Version liegt dem 
WinCom-Archiv bei. Die Funktionalitt der im jeweils aktuellen 
WinCom-Archiv enthaltenen A-MAN-Version stimmt mit der jeweils 
aktuellen A-MAN 'standalone'-Version berein.

2. A-MAN
Die Existenz von A-MAN erfhrt man durch Suche nach dem Cookie 'AmAN',
dessen Wert ein Zeiger auf folgende Struktur ist:

typedef struct
{
 long date;

 int *dcolor_a;
 int *dcolor_b;

 int *currxywh;
 int *kind;
 int *owner;
 char **name;
 char **info;

 unsigned char *menu_id;
 OBJECT **menu_tree;
 int  *flags;

 /* Ab Version 1.5 */

 int *vslpos;
 int *vslsiz;
 int *hslpos;
 int *hslsiz;
}A_MAN;

'date' ist BCD kodiert und stellt Versionsnummer und -Datum wie folgt
dar:
 aabbccdd
 aa-Versionsnummer a.a
 bb-Tag
 cc-Monat
 dd-Jahr
 14030195 bedeutet also Version 1.4 vom 3.1.1995

Ist die Versionsnummer mindestens 1.4, so stehen folgende Funktionen
zur Verfgung:
(Die Versionsnummer 1.4 mu nicht explizit geprft werden, da ohnehin
 erst ab dieser Version der Cookie 'AmAN' angelegt wird)

(Fr die im folgenden erwhnten wind_get()-Funktionen gilt: Die
 AES.LIB von PureC liefert bei den meisten Funktionen fehlerhafte
 Werte! Verwenden sie stattdessen eine eigene wind_get()-Funktion.
 Wenn ihr PureC-Programm "#include <aes.h>" enthlt, so knne sie
 wind_get auch durch die untenstehende wnd_get Routine ersetzen.
 Diese Routine bercksichtigt alle Rckgabewerte.)

ACHTUNG! Fr die Fenster des im TOS integrierten Desktop sind 
keinerlei Informationen ber A-MAN verfgbar!

'dcolor_a' ist ein ber die Fensterelementnummer indiziertes Feld und
gibt die Farbe dieses Elements fr ein aktives Fenster an.
Diese Werte knnen auch ber wind_get(WF_DCOLOR) erfragt werden. Die
entsprechende AES-Funktion wird von A-MAN zur Verfgung gestellt.

'dcolor_b' wie dcolor_a fr inaktive Fenster
Diese Werte knnen auch ber wind_get(WF_DCOLOR) erfragt werden. Die
entsprechende AES-Funktion wird von A-MAN zur Verfgung gestellt.

'currxywh' ist ein ber 4*Fensterhandle indiziertes Feld. Jeweils vier
aufeinanderfolgende Eintrge geben die momentanen Ausmae des Fensters
an. Eintrge fr nicht vorhandene Fenster sind undefiniert!
Will man also die Ausmae des Fensters mit Handle 'wid' auslesen,
lauten die Abfragen:
 x=currxywh[4*wid];
 y=currxywh[4*wid+1];
 w=currxywh[4*wid+2];
 h=currxywh[4*wid+3];
Der Vorteil gegenber der herkmmlichen wind_get-Abfrage ist der, da
dieses Feld auch problemlos in Interrupts etc. ausgelesen werden kann.

'kind' ist ein ber das Fensterhandle indiziertes Feld. Es gibt die
bei 'wind_create' angemeldeten Fensterelemente wieder. Eintrge fr
nicht vorhandene Fenster sind nicht definiert!
Diese Werte knnen auch ber wind_get(wid, WF_KIND, &kind...) erfragt
werden. Die entsprechende AES-Funktion wird von A-MAN zur Verfgung
gestellt.

'owner' ist ein ber das Fensterhandle indiziertes Feld. Es gibt den
Eigner des Fensters an. Eintrge fr nicht vorhandene Fenster sind
nicht definiert!
Die owner-Werte werden von A-MAN NICHT ber wind_get zur Verfgung
gestellt!

'name' ist ein ber das Fensterhandle indiziertes Feld. Es gibt die
Zeiger auf die NAME-Texte der Fenster an. Eintrge fr nicht
vorhandene Fenster sind nicht definiert!
Die Zeiger knne auch ber wind_get(wid, WF_NAME, &hi, &lo..) erfragt
werden. Die entsprechende AES-Funktion wird von A-MAN zur Verfgung
gestellt.

'info' ist ein ber das Fensterhandle indiziertes Feld. Es gibt die
Zeiger auf die INFO-Texte der Fenster an. Eintrge fr nicht
vorhandene Fenster sind nicht definiert!
Die Zeiger knne auch ber wind_get(wid, WF_INFO, &hi, &lo..) erfragt
werden. Die entsprechende AES-Funktion wird von A-MAN zur Verfgung
gestellt.

'menu_id' ist ein ber die AES-ID indiziertes Feld und gibt die
menu_id eines installierten Accessories an. Fr AES-IDs, die keinem
installierten Accessory zuzuordnen sind, wird -1 geliefert. Die Werte
knnen auch ber menu_register(-1,"?\0\n") erfragt werden, wobei n die
AES-ID des fraglichen Accessories angibt. Der Rckgabewert stellt dann
die menu_id (oder -1) dar.

'menu_tree' ist ein ber die AES-ID indiziertes Feld und gibt die
Zeiger auf die Menbume der Applikationen an. Fr Applikationen, die
kein Men angemeldet haben, wird NULL geliefert. Die Zeiger knnen
auch ber
hi=menu_bar((OBJECT*)n, -2);
lo=menu_bar((OBJECT*)n, -3);
erfragt werden, wobei n die AES-ID des fraglichen Programms angibt.

'flags' ist ein ber das Fensterhandle indiziertes Feld, wobei die
einzelnen Bits folgende Bedeutung haben:
Bit 0: gesetzt=Fenster ist geffnet
Bit 1: gesetzt=Fenster ist ikonifiziert
Eintrge fr nicht vorhandene Fenster sind nicht definiert!


Ist die Versionsnummer mindestens 1.5 stehen auerdem folgende Felder 
zur Verfgung:

'vslpos' ist ein ber das Fensterhandle indiziertes Feld und gibt die 
Position des vertikalen Sliders an (0-1000).

'vslsiz' ist ein ber das Fensterhandle indiziertes Feld und gibt die 
Gre des vertikalen Slider an (0-1000).

'hslpos' und
'hslsiz' 
 wie 'vslpos' und 'vslsiz' aber fr den horizontalen Slider
 
Der Vorteil gegenber der herkmmlichen wind_get-Abfrage ist der, da
diese Felder auch problemlos in Interrupts etc. ausgelesen werden 
knnen.

Fr alle vier Felder gilt: Eintrge fr nicht vorhandene Fenster sind 
nicht definiert. Ebenso sind Eintrge fr zwar vorhandene Fenster aber 
nicht vorhandenen Elemente (also Fenster ohne Slider) nicht definiert!



Sonstiges:

Alternative wind_get-Routine fr PureC:

int wnd_get(int w_hnd, int func, int *p1, int *p2, int *p3, int *p4)
{

 AESPB	c;
 c.contrl=_GemParBlk.contrl;
 c.global=_GemParBlk.global;
 c.intin=_GemParBlk.intin;
 c.intout=_GemParBlk.intout;

 _GemParBlk.contrl[0]=104;
 _GemParBlk.contrl[1]=2;
 _GemParBlk.contrl[2]=5;
 _GemParBlk.contrl[3]=0;
 _GemParBlk.contrl[4]=0;

 _GemParBlk.intin[0]=w_hnd;
 _GemParBlk.intin[1]=func;

 _crystal(&c);

 *p1=_GemParBlk.intout[1];
 *p2=_GemParBlk.intout[2];
 *p3=_GemParBlk.intout[3];
 *p4=_GemParBlk.intout[4];

 return(_GemParBlk.intout[0]);
}
