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