

                            WinCom
                        Programmier-Doku

                          Sven Kopacz


A) In diesem Text werden zwei verschiedene Programme beschrieben, die
im Prinzip nichts miteinander zu tun haben: WinCom und A-MAN. Whrend
WinCom ein spezielles Utility fr MagiC darstellt, ist A-MAN ein
Programm, da unter allen TOS-Systemen neue AES-Funktionen zur
Verfgung stellt. Das WinCom-Paket ist Shareware, A-MAN selbst ist
dagegen Freeware und darf eigenen Programmen beigelegt werden. Ein
Archiv, in dem sich nur A-MAN und die dazugehrige Dokumentation
sowie die Bedingungen fr eine evtl. Weitergabe befinden, liegt in der
Maus LB. Die A-MAN-Version aus dem WinCom-Archiv legt auerdem einen
'WICO'-Cookie mit dem Wert NULL an, dieser Cookie wird spter von
WinCom und anderen Programmen aus dem Archiv zur Kommunikation
verwendet. Die A-MAN-Version aus dem einzelnen A-MAN-Archiv legt
diesen Cookie nicht an.


B) WinCom

Ab Version 1.4 ist es mglich, Fenster links aus dem Bildschirm zu
schieben. Um zu prfen, ob man also ein wind_set mit negativer
X-Koordinate durchfhren darf, obwohl das Programm unter MagiC luft,
sollte man folgendes tun:
-Den Cookie 'WICO' suchen
-Dessen Wert prfen. Steht hier nicht NULL, so erhlt man einen Zeiger
 auf ein int-Array. Ist der _zweite_ Eintrag in diesem Array > 70, so
 ist eine WinCom-Version installiert, die ein wind_set mit negativem X
 untersttzt.

Unter WinCom werden Maustastenklicks, die zu Echtzeitaktionen fhren, 
nicht an das System durchgelassen. Natrlich ist auch wind_udpate 
whrend einer solchen Aktion nicht gesetzt. Will man in einem eigenen 
Programm prfen, ob WinCom gerade die Mauskontrolle fr eine 
Echtzeitaktion bernommen hat, geht man wie folgt vor:
-Den Cookie 'WICO' suchen
-Dessen Wert prfen. Stehe hier nicht NULL, so erhlt man einen Zeiger 
auf ein int-Array. Der _erste_ Eintrag in diesem Array ist ein 
Bitfeld, das ausschlielich _gelesen_ werden darf! Ist Bit 2 (Wert: 
4) hier gesetzt, so hat WinCom die Mauskontrolle.

Einige der WinCom-Funktionen knnen von beliebigen Applikationen per
AES-Message veranlasst werden. Dazu mu per appl_find("WINCOM  ") die
AES-ID von WinCom ausfindig gemacht werden.
Die folgenden Nachrichten werden ebenfalls nur von WinCom-Versionen
untersttzt, bei denen der o.g. Eintrag im int-Array > 70 ist. ltere
WinCom-Versionen reagieren einfach nicht auf die Nachrichten. Also am
besten vorher prfen.
Anschlieend kann eine Nachricht an WinCom geschickt werden. Der
Message-Puffer hat dabei folgende Belegung:

/* WinCom-Message def's */
/*
	pbuf[0]=WINCOM_MSG
	pbuf[1]=ap_id
	pbuf[2]=0
	pbuf[3]=<Kommando>
	pbuf[4]=<id, Option>
	pbuf[5]=<id>
*/

#define WINCOM_MSG 0x999

#define	WI_CLS      0 /* Aufrumen */

#define	WI_CALL_APP 1 /* Applikation toppen (AES-ID in pbuf[4]) */

#define WI_CALL_ACC 2 /* Accessory ffnen (AES-ID in pbuf[4]) */

#define WI_HIDE 3     /* App. ausblenden */
        /* pbuf[4]: */
	#define WIH_THIS 0  /* ap_id wird in pbuf[5] angegeben */
	#define	WIH_ACT	1   /* Aktuelle */
	#define	WIH_OTHER 2 /* Alle auer aktuelle */
	#define WIH_ALL 3   /* alle */

#define WI_SHOW	4    /* App. einblenden */
        /* pbuf[4]: */
	#define WIS_THIS 0  /* ap_id wird in pbuf[5] angegeben */
	#define	WIS_ALL 1   /* alle einblenden */

#define	WI_TOPWIN 5  /* Fenster+Men aktivieren, Fenster-ID
                        in pbuf[4] angegeben */

Erluterung:
WI_CLS fhrt einen Redraw ber den ganzen Screen (also auch die
Menleiste) durch.

WI_CALL_APP topped alle Fenster der in pbuf[4] angegebenen Applikation
(AES-ID) und akiviert deren Menleiste, falls vorhanden. Sollte die
Applikation ausgeblendet gewesen sein, so wird sie automatisch
eingeblendet.

WI_CALL_ACC schickt dem in pbuf[4] angegebenen Accessory (AES-ID) eine
AC_OPEN-Nachricht. Dabei wird dem Accessory in pbuf[4] seine eigene
Menu-ID bergeben, wodurch auch Accessories wie XCONTROL auf diese
Nachricht reagieren. Wenn ein bereits geffnetes Accessory auf diese
Nachricht mit dem Toppen seines Fensters reagiert und ausgeblendet
war, so wird es automatisch eingeblendet.

WI_HIDE dient zum Ausblenden von Fenstern. Es werden immer alle
Fenster eine Applikation ausgeblendet, das Ausblenden einzelner
Fenster ist nicht mglich. Zum Ausblenden verschickt WinCom
WM_MOVED-Nachrichten an die betreffenden Applikationen, es hngt daher
von den jeweiligen Programmen ab, ob die Fenster tatschlich
verschwinden. In pbuf[4] wird der Subcode fr WI_HIDE angegeben:
 WIH_THIS: Blendet alle Fenster der in pbuf[5] angegebene Applikation
           aus. Hiermit kann sich eine Applikation auch selbst
           ausblenden. Anschlieend wird automatisch eine andere
           Applikation aktiviert.
 WIH_ACT:  Blendet alle Fenster der aktuellen Applikation aus. Die
           aktuelle Applikation ist diejenige, der entweder das
           oberste Fenster gehrt, oder, falls dieses nicht aktiv ist,
           diejenige, der die Menzeile gehrt. Anschlieend wird
           automatisch eine andere Applikation aktiviert.
 WIH_OTHER:Blendet alle Fenster auer denen der aktuellen Applikation
           aus.
 WIH_ALL:  Blendet alle Fenster aus. Abhngig von den Einstellungen
           des Benutzers wird dabei automatisch die Menleiste des
           Desktops aktiviert.
Es ist unerheblich, ob eine Applikation bereits ausgeblendet ist, die
Nachricht darf trotzdem an WinCom verschickt werden.

WI_SHOW blendet Fenster ein, die mit WI_HIDE (oder vom Benutzer ber
die WinCom-Hotkeys) ausgeblendet wurden. Zum Einblenden verschickt
WinCom ebenfalls WM_MOVED-Nachrichten. In pbuf[4] wird der Subcode fr
WI_HIDE angegeben:
 WIS_THIS: Blendet nur die Fenster derjenigen Applikation ein, die in
           pbuf[5] angegeben wird.
 WIS_ALL:  Blendet alle von WinCom ausgeblendeten Fenster wieder ein.
Es ist unerheblich, ob tatschlich Fenster ausgeblendet waren, die
Nachricht darf trotzdem an WinCom verschickt werden.

WI_TOPWIN topped ein einzelnes Fenster, dessen ID in pbuf[4] angegeben
wird. Sollte die zugehrige Applikation eine Menleiste angemeldet
haben, so wird diese automatisch aktiviert.



C) A-MAN

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]);
}
