home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / utility / system / winx21 / winxprog.ger < prev   
Text File  |  1993-09-09  |  13KB  |  272 lines
  1. HINWEISE FÜR ENTWICKLER (zur WINX Version 2.1 [9.9.1993])
  2.  
  3. Diese Datei enthält Hinweise zum Umgang mit der Fensterverwaltung des
  4. GEM im allgemeinen und der von WINX im speziellen.
  5.  
  6. - In der Testphase eigener Programme sollte man WINX immer so
  7.   konfigurieren, daß fehlerhafte wind_-Aufrufe angezeigt werden.
  8.   Die einzige wind_-Funktion, die man mit einer ungültigen
  9.   Fensterkennung aufrufen darf ohne eine Fehlermeldung zu
  10.   bekommen, ist übrigens wind_get( WF_OWNER).
  11.  
  12. - wind_get()/wind_set()
  13.   Diese beiden Funktionen liefern jetzt im Fehlerfall den Wert
  14.   0, sonst 1 (bisher wurde immer der Wert 1 zurückgegeben).
  15.   Ein Fehler wird z.B. gemeldet, falls ein WF_-Modus nicht
  16.   implementiert ist, bzw. ein Funktionsaufruf mit einer ungültigen
  17.   Fensterkennung erfolgte. Beim Start eines Programms sollte
  18.   man zunächst prüfen, ob wind_get() einen sinnvollen Rückgabe-
  19.   wert liefert. 
  20.     #define WF_RETURN 1
  21.     retok = (wind_get( 0, WF_RETURN, &ign, &ign, &ign, &ign) == 0);
  22.   Es ist unkritisch unter den bisherigen GEM-Versionen einen
  23.   unbekannten WF_-Modus zu benutzen, da dieser ignoriert wird.
  24.  
  25. - wind_get( 0, WF_WINX(=22360), &version, &date, &rsv1, &rsv2)
  26.   Liefert 1, falls WINX >= 2.1 installiert ist, sonst 0.
  27.   version: Bit [15..12]  Beta-Kennung
  28.            Bit [11.. 8]  Major (momentan 2)
  29.            Bit [ 7.. 4]  Minor (momentan 1)
  30.            Bit [ 3.. 0]  Interne Kennung
  31.   date:    Erstellungsdatum im GEMDOS-Format
  32.  
  33. - wind_get( 0, WF_WINXCFG(=22361), &gmask, &gflags, &lmask, &lflags)
  34.   Liefert die für die Applikation gültigen Konfigurationsschalter.
  35.   gmask:   Ein gesetztes Bit bedeutet, daß der Schalter existiert.
  36.   gflags:  Globale Konfigurationsschalter. Ein Schalterwert ist nur
  37.            dann gültig, wenn das entsprechende Bit in gmask gesetzt
  38.            ist (Bit 0 entspricht Schalter 1, etc.).
  39.   lmask:   Ein gesetztes Bit bedeutet, daß der Schalter existiert.
  40.   lflags:  Lokale Konfigurationsschalter. Ein Schalterwert ist nur
  41.            dann gültig, wenn das entsprechende Bit in lmask gesetzt
  42.            ist (Bit 0 entspricht Schalter 1, etc.).
  43.   Obwohl man die Konfigurationsschalter mit dieser Funktion abfragen
  44.   kann, sollte man trotzdem möglichst darauf verzichten. Der
  45.   Funktionswert muss unbedingt geprueft werden!
  46.  
  47. - wind_get( rsv0, 22362-22400, &rsv2, &rsv3, &rsv4, &rsv5)
  48.   wind_set( rsv0, 22362-22400, rsv2, rsv3, rsv4, rsv5)
  49.   Undokumentierte bzw. reservierte WINX-Erweiterungen.
  50.       
  51. - wind_get( 0, WF_TOP, &topwin, &topowner, &belowwin)
  52.   Liefert die Kennung des obersten Fensters im Fensterstapel.
  53.   Ist kein Fenster offen, enthält topwin 0.
  54.  
  55. - wind_get( win, WF_OWNER(=20), &owner, &isopen, &abovewin, &belowwin)
  56.   Liefert Informationen über ein Fenster. Das Fenster kann auch
  57.   geschlossen sein (d.h. es ist nicht im Fensterstapel), bzw.
  58.   gar nicht existieren (dann liefert die Funktion 0).
  59.  
  60. - wind_set( win, WF_BOTTOM(=25), 0, 0, 0, 0)
  61.   WF_BOTTOM stellt ein Fenster im Fensterstapel nach hinten. Das
  62.   Fenster muß offen sein.
  63.  
  64. - wind_get( 0, WF_BOTTOM(=25), &bottomwin)
  65.   Liefert die Kennung des untersten Fensters im Fensterstapel.
  66.   Ist kein Fenster offen enthält bottomwin -1 (NOWINDOW).
  67.  
  68. - wind_set( win WF_BEVENT(=24), 0/1, 0, 0, 0)
  69.   WF_BEVENT sorgt dafür, daß der Besitzer des Fensters beim Klick
  70.   in das Fensterinnere keine WM_TOPPED-Nachricht erhält, wenn das
  71.   Fenster nicht aktiv ist. Stattdessen wird ein MU_BUTTON aus-
  72.   gelöst, falls der Besitzer eine entsprechende Anforderung bei
  73.   evnt_multi() gestellt hat.
  74.  
  75. - wind_get( win, WF_BEVENT, &v1, &v2, &v3, &v4)
  76.   Liefert den BEVENT-Status des Fensters im Bit 0 von v1.
  77.  
  78. - wind_get( win, WF_NEWDESK, &treehig, &treelow, &treeroot, &ign)
  79.   Liefert den aktuellen Hintergrundbaum und sein Wurzelobjekt.
  80.   ACHTUNG: Bisher ist nicht dokumentiert wie man diese Information
  81.   nutzen kann.
  82.  
  83. - wind_get( win, WF_COLOR, &obj, &col1, &col2);
  84.   Liefert die Farben eines Objekts des Fensterrahmens.
  85.   ACHTUNG: obj muß in intin[ 2] übergeben werden. contrl[ 1] muß
  86.   auf 3 vergrößert werden!
  87.  
  88. - wind_get( 0, WF_DCOLOR, &obj, &col1, &col2);
  89.   Liefert die Defaultfarben eines Objekts des Fensterrahmens.
  90.   ACHTUNG: obj muß in intin[ 2] übergeben werden. contrl[ 1] muß
  91.   auf 3 vergrößert werden!
  92.  
  93. - Position und Größe des ROOT-Objekts eines eigenen Hintergrund-
  94.   baums, der mit wind_set( WF_NEWDESK) angemeldet wird, sollten
  95.   vorher mit einen Aufruf von
  96.     wind_get( 0, WF_WORKXYWH, &deskx, &desky, &deskw, &deskh)
  97.   bestimmt werden (also nicht mit WF_CURRXYWH).
  98.  
  99. - wind_set( win, WF_CURRXYWH, x, y,w, h), wind_open( win, x, y, w, h)
  100.   Nach diesen Operationen sollte man immer mit
  101.     wind_get( win, WF_CURRXYWH, &currx, &curry, &currw, &currh)
  102.   die tatsächlichen Werte ermitteln, da das AES Position und Größe
  103.   eventuell automatisch korrigiert hat.
  104.   
  105. - wind_set( WF_NAME, text), wind_set( WF_INFO, text)
  106.   Man sollte keine Annahmen darüber machen, ob die Fensterverwaltung
  107.   eine Kopie des Strings <text> anlegt oder nur den Zeiger ablegt.
  108.   <text> sollte nach dem Aufruf der Funktion nicht mehr verändert
  109.   werden.
  110.   
  111. - [WM_BOTTOMED(=33) apid 0 win 0 0 0 0]-Nachricht
  112.   Diese Nachricht benutzt der SCRENMGR um die Applikation aufzu-
  113.   fordern, das Fenster mit
  114.     wind_set( win, WF_BOTTOM, 0,0,0,0)
  115.   nach hinten zu stellen.
  116.   Nach dieser Aktion sollte die Applikation NICHT explizit ein 
  117.   eigenes Fenster aktivieren. Hat die Applikation mehr als ein Fenster
  118.   offen, und will sie deren Reihenfolge nicht ändern, sollte sie
  119.   alle eigenen Fenster nach hinten stellen (praktisch wäre es,
  120.   wenn das AES dafür eine Funktion anbieten würde...).
  121.  
  122. - inverse 'Fenster wechseln' Funktion
  123.   Ein Applikation die diese Funktion anbietet, sollte dabei
  124.   ihr oberstes Fenster mit WF_BOTTOM nach hinten stellen und
  125.   das jetzt oberste in der eigene Fensterliste mit WF_TOP
  126.   aktivieren (um sicherzustellen, daß die Applikation die
  127.   Tastaturkontrolle behält.
  128.  
  129. - [WM_UNTOPPED(=30) apid 0 win 0 0 0 0]-Nachricht
  130.   [WM_ONTOP(=31) apid 0 win 0 0 0 0]-Nachricht
  131.   Diese Meldungen werden dazu benutzt, um Applikationen über eine
  132.   Veränderung des aktiven Fensters zu informieren. WM_UNTOPPED
  133.   wird nach dem Öffnen bzw. Aktivieren eines Fensters an den
  134.   Besitzer des vorher aktiven Fensters geschickt. WM_ONTOP
  135.   wird nach dem Schließen bzw. Deaktivieren des aktiven Fensters
  136.   an den Besitzer des danach aktiven Fensters geschickt.
  137.   Zum Zeitpunkt der Ankunft der Nachricht kann sich der Fenster-
  138.   stapel bereits wieder verändert haben.
  139.  
  140. - [WM_ARROWED apid 0 win WA_aaa speed_aaa WA_bbb speed_bbb]
  141.   Die WM_ARROWED-Nachricht wurde in WINX erweitert um - über das neu
  142.   Kontrollelement 'Scrollbox' - in beliebige Richtungen mit variierbarer
  143.   Geschwindigkeit scrollen zu können.
  144.   
  145.   Die Auswertung könnte in C etwa folgendermaßen aussehen:
  146.   
  147.   switch (mesag[ 0]) {
  148.   case WM_ARROWED:
  149.     scrollx = scrolly = 0;
  150.     speed = (mesag[ 5] < 0) ? -mesag[ 5] : 1;
  151.     switch (mesag[ 4]) {
  152.     case WA_UPLINE: scrolly = -speed; break;
  153.     case WA_DNLINE: scrolly = speed; break;
  154.     case WA_LFLINE: scrollx = -speed; break;
  155.     case WA_RTLINE: scrollx = speed; break;
  156.     case WA_UPPAGE: scrolly = -(speed * linesperpage); break;
  157.     case WA_DNPAGE: scrolly = (speed * linesperpage); break;
  158.     case WA_LFPAGE: scrollx = -(speed * linesperpage); break;
  159.     case WA_RTPAGE: scrollx = (speed * linesperpage); break;
  160.     };
  161.     if (mesag[ 7] < 0) {
  162.       speed = -mesag[ 7];
  163.       switch (mesag[ 6]) {
  164.       case WA_UPLINE: scrolly = scrolly - speed; break;
  165.       case WA_DNLINE: scrolly = scrolly + speed; break;
  166.       case WA_LFLINE: scrollx = scrollx - speed; break;
  167.       case WA_RTLINE: scrollx = scrollx + speed; break;
  168.       case WA_UPPAGE: scrolly = scrolly - (speed * linesperpage); break;
  169.       case WA_DNPAGE: scrolly = scrolly + (speed * linesperpage); break;
  170.       case WA_LFPAGE: scrollx = scrollx - (speed * linesperpage); break;
  171.       case WA_RTPAGE: scrollx = scrollx + (speed * linesperpage); break;
  172.       };
  173.     };
  174.     if ((scrollx != 0) || (scrolly != 0)) {
  175.       scroll_window( mesag[ 3], scrollx, scrolly);
  176.     };
  177.   };
  178.   
  179.   ACHTUNG: Diese Erweiterung wurde von ATARI noch nicht abgesegnet!
  180.   Sie ist aber kompatibel zu den bisherigen TOS-Versionen [Stand 6/93]
  181.  
  182. - wind_update() speicherte bisher Applikationen, die auf die
  183.   Update-Kontrolle warteten, in einer LIFO-Warteschlange (d.h.
  184.   der letzte der die Update-Kontrolle anforderte erhielt sie als
  185.   nächster). WINX benutzt hingegen eine FIFO. 
  186.      
  187. - wind_update( BEG_UPDATE|0x100); wind_update( BEG_MCTRL|0x100);
  188.   WINX implementiert den 'check and set mode' von AES 4.0.
  189.   Dabei wird die Update-Kontrolle nur noch übernommen, falls
  190.   keine andere Applikation die Kontrolle hat bzw. die eigene
  191.   Applikation besitzt. Kann die Applikation die Kontrolle nicht
  192.   übernehmen, liefert die Funktion den Wert 0.
  193.  
  194. - wind_update( END_...) wird jetzt auf Unterlauf geprüft und im
  195.   Fehlerfall mit einem Alert gewürdigt.
  196.  
  197. - wind_new() loeschte bisher immer rigoros alle anstehenden 
  198.   Update-Anforderungen. WINX interpretiert wind_new() als Aufräum-
  199.   funktion für eine abgestürzte Hauptapplikation und löscht daher
  200.   auch nur noch deren Update-Anforderungen. Die Neuinitialisierung
  201.   der Fensterverwaltung führt WINX jetzt unter Update-Kontrolle
  202.   durch, dadurch ist garantiert, daß die Fenster nicht verschwinden
  203.   während ein ACC die Update-Kontrolle besitzt.
  204.  
  205. - appl_getinfo()
  206.   Ab der Version 2.1 stellt WINX die AES-Funktion appl_getinfo() über
  207.   den Trap 2 zur Verfügung. Die momentan von WINX implementierten Sub-
  208.   funktionen 11 und 12 liefern als Funktionswert 1, die anderen 0.
  209.   ACHTUNG: Bevor man appl_getinfo() aufruft, muß man prüfen, ob das
  210.   AES diese Funktion unterstützt, da ansonsten ein Fehlermeldungsalert
  211.   ausgegeben wird. appl_getinfo() wurde von ATARI ab der AES-Version
  212.   4.00 implementiert. Momentan kann man z.B. folgende Testfunktion
  213.   benutzen:
  214.  
  215.     int has_appl_getinfo( void)
  216.     /* Liefert TRUE, falls das AES appl_getinfo bereitstellt */
  217.     {
  218.       int winxversion, ign;
  219.       
  220.       if (aesversion >= 0x400) return( TRUE);
  221.       if (wind_get( 0, WF_WINX, &version, &ign, &ign, &ign) != 0) {
  222.         return( (version & 0x0FFF) >= 0x210);
  223.       };
  224.       return( FALSE);
  225.     } /* has_appl_getinfo */
  226.       
  227. - Echtzeitaktionen
  228.   Während einer Echtzeitaktion gibt der SCRENMGR die Ausgabekontrolle
  229.   ab. Die Mauskontrolle bleibt hingegen beim SCRENMGR (allerdings kann
  230.   sie temporär von einer Applikation übernommen werden). Während der
  231.   Echtzeitaktion wird die Applikation, der das zugeordnete Fenster
  232.   gehört, gezwungen mehr Zeit an das AES abzugeben.
  233.  
  234. - Musterbezugspunkt
  235.   Ist die Schalter eingeschaltet, sorgt WINX dafür, daß bei der
  236.   Ausgabe eines GEM-Objekts der Bezugspunkt eines Füllmusters in
  237.   der linken oberen Ecke des Objekts liegt (statt wie bisher bei
  238.   0/0). Nur so ist es z.B. möglich, nach dem Verschieben eines
  239.   Fensters, die Ausgabe auf die vorher unsichtbaren Teile der
  240.   Objekte zu beschränken.
  241.  
  242. - Redraw von Fenstern
  243.   Die Fensteroperationen wind_open(), wind_set( WF_CURR|WF_TOP), etc.
  244.   senden Redraws für die Bereiche des Fensters, die neu sichtbar
  245.   werden. Einige AES Version senden statt dieser Teilredraws Redraws
  246.   für das komplette Fenster (dies ist unter Umständen notwendig,
  247.   damit Füllmuster, etc. zusammenpassen). Will/muß man gleichzeitig
  248.   zur Fensteroperation den Fensterinhalt ändern, sollte man sich
  249.   selbst mit appl_write() ein Komplettredraw schicken, welches dann
  250.   mit den von der Fensterverwaltung erzeugten Redraws vereinigt wird.
  251.   Unter AES 4.00 werden die Redraws momentan nicht vereinigt, daher
  252.   kann man für dieses AES entweder eine Sonderbehandlung implementieren
  253.   oder hoffen, daß ATARI irgendwann zur alten Lösung zurückfindet.
  254.  
  255. - Der WINX-Cookie enthält als Wert einen Zeiger auf eine Funktion
  256.   über die bestimmte Eigenschaften der akt. WINX-Version erfragt
  257.   werden können.
  258.  
  259.     long cdecl winxfunc( short funcid, ...);  /* PureC-Syntax */
  260.  
  261.   Die Parameter werden auf dem Stack übergeben, der Resultatwert 
  262.   wird in D0 zurückgegeben. Wenn es nicht anders angegeben ist,
  263.   bedeutet der Resultatwert -1L, daß die Funktion nicht existiert
  264.   bzw. momentan nicht ansprechbar ist.
  265.   Einige Funktionen sind für die interne Kommunikation reserviert.
  266.   Außer dem Register D0 werden keine weiteren Register verändert.
  267.  
  268.   Der Zugriff auf einige internen Variablen von WINX ist für
  269.   TSR-Programme möglich. Diesbezügliche Informationen können
  270.   beim Autor bezogen werden.
  271.        
  272.