home *** CD-ROM | disk | FTP | other *** search
/ Dream 48 / Amiga_Dream_48.iso / Atari / c / libs / nkcc-293.lzh / DOC / GERMAN.DOC < prev    next >
Text File  |  1995-11-09  |  30KB  |  679 lines
  1.  
  2.    NKCC - NORMALIZED KEY CODE CONVERTER
  3.    =============================================================================
  4.    Version 2.93
  5.  
  6.    von Harald Siegmund                                  Copyright (c) 1989-1995
  7.  
  8.    Die NKCC Library ist Freeware. Das Archiv darf nur in unveränderter Form
  9.    weitergegeben werden. Wird NKCC in einer Applikation eingebaut, so bitte
  10.    ich um einen kurzen Vermerk im Info-Dialog (z.B. "NKCC Tastaturroutinen
  11.    von Harald Siegmund" oder ähnliches). Vielen Dank!
  12.  
  13.    -----------------------------------------------------------------------------
  14.    History:
  15.  
  16.    1989:
  17.       14. Mai: erste Version (NKCC 1.00)
  18.  
  19.       ... (ich hatte keine Lust, die englischsprachige History zu übersetzen;
  20.            wen's interessiert, kann die fehlenden Einträge in ENGLISH.DOC
  21.            nachlesen)
  22.  
  23.    1995:
  24.       31. Okt: Übersetzung der Dokumentation ins Deutsche.
  25.                Korrektur in der Beschreibung des Tastenformats: die Bit-Nummern
  26.                 von NKF_LSH und NKF_RSH waren falsch angegeben.
  27.        9. Nov: Version 2.93:
  28.                Die zusätzlichen Tasten auf der Mac-Tastatur werden nun
  29.                unterstützt.
  30.  
  31.    -----------------------------------------------------------------------------
  32.    Entwickleradresse:
  33.  
  34.    adequate systems
  35.    Gesellschaft für angemessene Systemlösungen mbH
  36.    z.Hd. Harald Siegmund
  37.    Brauereistr. 2
  38.    D-67549 Worms
  39.  
  40.    E-mail : Harald_Siegmund@kl.maus.de (Internet-Adresse)
  41.    Mausnet: Harald Siegmund@KL
  42.    -----------------------------------------------------------------------------
  43.    Neue Versionen von NKCC werden immer abgelegt in:
  44.  
  45.    Maus KL (0631-17901)       !! Programmteil für Nichtzahler gesperrt !!
  46.    Archiv NKCC.LZH            !! von 7 - 9 und 17 - 19 Uhr             !!
  47.  
  48.    FTP server  ftp.uni-kl.de  [131.246.94.94]
  49.          File  pub/atari/programming/nkcc.lzh
  50.  
  51.    =============================================================================
  52.    Inhalt:
  53.  
  54.    1. Was ist eigentlich NKCC?
  55.    2. Dateien, die zum Paket gehören
  56.    3. Das normalisierte Tastenformat
  57.    4. Wie wird NKCC aufgerufen?
  58.    5. NKCC in TOS-Applikationen
  59.    6. NKCC in GEM-Applikationen
  60.    7. Der Button Event Handler
  61.    8. Sonstige Funktionen
  62.    9. Symboltabelle
  63.  
  64.  
  65.  
  66.    1. Was ist eigentlich NKCC?
  67.    =============================================================================
  68.    NKCC ist ein NME-Produkt (Not macht erfinderisch), da₧ bei dem verzweifelten
  69.    Versuch entstanden ist, eine flexible und länderunabhängige Tastenmakro-
  70.    verwaltung zu schreiben. Vorgabe war, möglichst *alle* Kombinationen von
  71.    Shift (links/rechts), Control und Alternate mit einer anderen Taste
  72.    erfassen zu können, unabhängig davon, ob die Applikation auf einem
  73.    deutschen, saudi-arabischen, isländischen oder wasauchimmer-TOS mit
  74.    entsprechender Tastenbelegung läuft.
  75.  
  76.    Kein Problem? Von wegen! Wenn man sich die von TOS/GEM zurückgelieferten
  77.    Tastencodes anschaut, kann einem das kalte Grauen kommen:
  78.  
  79.    a) Alternate plus eine Buchstabentaste liefert lediglich den Scancode des
  80.       Taste zurück, der von der Belegung der Tastatur (Landessprache!)
  81.       abhängt. Als ASCII-Code meldet das OS immer eine 0.
  82.  
  83.    b) Bei einigen Tasten variiert der Scancode abhängig davon, welche
  84.       Zusatztasten gedrückt sind! Ein Beispiel: auf der deutschen
  85.       Tastatur hat die Taste "1 !" den Scancode 2. Wird zusätzlich Alternate
  86.       gedrückt, ändert sich der Scancode zu $78 und als ASCII-Code erhält
  87.       man eine Null.
  88.  
  89.    c) Der Cursortastenblock ist eine einzige Katastrophe. Hier kann man nur
  90.       darauf hoffen, da₧ auf allen Tastaturen die gleichen Scancodes
  91.       geliefert werden. Bei einigen Tasten - nicht allen - ändert sich der
  92.       Scancode, wenn zusätzlich Control gedrückt wird! Der ASCII-Code hängt
  93.       vom Zustand der Zusatztasten (Shift, Control) sowie der aktuellen
  94.       Mondphase ab und spottet jeder Regel.
  95.  
  96.    d) Einige Tastenkombinationen lassen sich so ohne weiteres gar nicht
  97.       auseinanderhalten, da sie den gleichen Tastencode produzieren.
  98.       So sind in den meisten Fällen die Tastencodes für Alternate+irgendeine
  99.       Taste identisch mit Alternate+Shift+irgendeine Taste.
  100.  
  101.    Die Lösung für all diese Probleme hei₧t NKCC.
  102.  
  103.    Ok, nicht ganz so dramatisch:
  104.    *Eine* Lösung für all diese Probleme hei₧t NKCC. ;-)
  105.  
  106.    Die Hauptaufgabe von NKCC liegt in der Konvertierung von Tastencodes in
  107.    ein sinnvolles, scancode- und damit landesspracheunabhängiges Format.
  108.    Mit NKCC können praktisch alle Tastenkombinationen unterschieden werden.
  109.    Ausnahmen bilden lediglich jene Kombinationen, die zu Sonderzwecken
  110.    im Betriebssystem eingesetzt werden (zum Bleistift das altbekannte
  111.    Alternate+Help, das die Hardcopy-Routine des Systems anwirft).
  112.  
  113.    So nebenbei hat NKCC noch einige Zusatzfunktionen in petto:
  114.  
  115.    a) Deadkeys
  116.  
  117.       Mit diesem Mechanismus ist es möglich, defekte Tasten wiederzubeleben.
  118.       Scherz beiseite: Deadkeys braucht man, um akzentuierte Zeichen einzugeben,
  119.       die nicht auf der Tastatur anzutreffen sind. Der Mechanismus funktioniert
  120.       so: als erstes wird die Akzent-Taste gedrückt. NKCC liefert diese nicht
  121.       sofort an die Applikation, sondern wartet erst einmal auf die nächste
  122.       Taste. Das hei₧t, bei der Eingabe der Akzent-Taste passiert erst einmal
  123.       gar nichts, deshalb der Name "Deadkey" ("tote Taste"). Wenn der nächste
  124.       Tastencode ankommt, versucht NKCC die Akzent-Taste damit zu verbinden
  125.       und einen einzigen Tastencode zu erzeugen, der dann an die Applikation
  126.       gemeldet wird. Ist eine Kombination nicht möglich, so werden beide
  127.       Codes nacheinander unverändert zurückgegeben. Hier ein Beispiel:
  128.  
  129.       ~   danach   A   wird verschmolzen zu   ╖
  130.       ~   danach   X   kommen als   ~   und   X   aus NKCC heraus, da es kein
  131.                                                   X mit Akzent Tilde gibt
  132.  
  133.       NKCC unterstützt folgende Deadkeys:
  134.  
  135.       ^   +   aeiou      =  âêîôû            Akzent Circumflex
  136.       ~   +   nNaoAo     =  ñÑ░▒╖╕           Akzent Tilde
  137.       '   +   eEaiou     =  éÉáíóú           Akzent Akut
  138.       `   +   aeiouA     =  àèìòù╢           Akzent Gravis
  139.       ╣   +   aeiouyAOU  =  äëïöüÿÄÖÜ        Akzent Umlaut
  140.       "   +   aeiouyAOU  =  äëïöüÿÄÖÜ        Akzent Umlaut (*)
  141.       °   +   aA         =  åÅ               Akzent Angström
  142.       ,   +   cC         =  çÇ               Akzent Cedille
  143.       /   +   oO24       =  │▓½¼             kein Akzent, trotzdem nützlich
  144.  
  145.       (*) Das Anführungszeichen (") wird als Synonym für die Umlautpunkte (╣)
  146.           verwendet. So gibt es z.B. auf einer holländischen Tastatur weder
  147.           das Umlautzeichen noch Umlaute.
  148.  
  149.    b) Direkte Eingabe von ASCII-Codes
  150.  
  151.       Das funktioniert folgenderma₧en: Alternate-Taste drücken und halten,
  152.       dann auf der Zehnertastatur den ASCII-Code eingeben. Nach Eingabe von
  153.       drei Ziffern oder Loslassen der Alternate-Taste wird ein Tastencode
  154.       produziert, der den eingegebenen ASCII-Code enthält. Bei Werten über
  155.       255 werden die oberen Bits abgeschnitten (bei Eingabe von 260 = $104
  156.       erhält man als ASCII-Code $04).
  157.  
  158.    c) Control Key Emulation
  159.  
  160.       Tastenkombinationen wie z.B. Control+A kommen normalerweise genauso
  161.       aus NKCC heraus, d.h.: ASCII-Code = 65 ("A"), Control-Flag ist gesetzt.
  162.       Mit der Control Key Emulation kann dieser Teil des Formatkonverters
  163.       umgeschaltet werden. Anstelle von "Control + Taste" erhält man dann
  164.       einen ASCII-Code von 0 bis 31 *ohne* Control-Flag.
  165.  
  166.       Folgende Kombinationen werden von der Emulation beeinflu₧t:
  167.  
  168.       Control + @       ->    $00
  169.       Control + A...Z   ->    $01...$1A
  170.       Control + [       ->    $1B
  171.       Control + \       ->    $1C
  172.       Control + ]       ->    $1D
  173.       Control + ^       ->    $1E
  174.       Control + _       ->    $1F
  175.  
  176.       Achtung:
  177.  
  178.       Nicht alle Kombinationen sind auf allen Tastaturen verfügbar. Zum
  179.       Beispiel ist es auf der deutschen Tastatur nicht möglich, die
  180.       Zeichen @ [ \ ] zusammen mit Control einzugeben. Das hat folgenden
  181.       Grund: sobald die Control-Taste bei der Eingabe gedrückt wird,
  182.       wird ein geschrotteter ASCII-Code vom Betriebssystem an NKCC übermittelt.
  183.       Da diese Zeichen nur durch Drücken von Alternate erzeugt werden können,
  184.       steht ihr ASCII-Code aber auch nicht in einer der TOS-Tastaturtabellen.
  185.       NKCC bleibt nichts anderes übrig, auf den ASCII-Code der Normalbelegung
  186.       zurückzugreifen, d.h. einen der Umlaute. Dadurch spricht die Control
  187.       Key Emulation natürlich nicht an.
  188.  
  189.  
  190.    Jeder einzelne Deadkey sowie die anderen speziellen Features können
  191.    separat ein- und ausgeschaltet werden.
  192.  
  193.  
  194.    Neugierig geworden? Das Programm DEMO.TOS zeigt, was NKCC aus
  195.    Tastendrücken so machen kann. Einfach starten und ein wenig auf
  196.    der Tastatur klimpern.
  197.  
  198.  
  199.  
  200.    2. Dateien, die zum Paket gehören
  201.    =============================================================================
  202.    Im NKCC-Archiv sollten folgende Files enthalten sein:
  203.  
  204.    READ_ME.TXT       die Datei, die eh niemand liest
  205.  
  206.    SOURCE\NKCC.S     der Quellcode von NKCC
  207.  
  208.    HEADERS\NKCC.I    ein Assembler Include-File mit globalen Definitionen
  209.    HEADERS\NKCC.H    ein C Header-File mit globalen Definitionen
  210.  
  211.    LIB\NKCC.O        NKCC als linkfertiges Object File (DRI-Format)
  212.    LIB\NKCC_TOS.O    NKCC ohne die GEM-Routinen und -Symbole als Object File
  213.  
  214.    DOC\NKCC.TXT      Auzug aus NKCC.S mit Dokumentation der Routinen
  215.    DOC\GERMAN.DOC    die Datei, die Sie gerade lesen
  216.    DOC\ENGLISH.DOC   die Doku in englischer Sprache
  217.    DOC\NEWS.TXT      hier sind alle Änderungen am NKCC-Paket dokumentiert
  218.  
  219.    DEMO\DEMO.C       Quellcode des Demo-Programms
  220.    DEMO\DEMO.TOS     Demo-Programm
  221.  
  222.  
  223.  
  224.    3. Das normalisierte Tastenformat
  225.    =============================================================================
  226.    Tastencodes werden von NKCC als 16 Bit Integer zurückgeliefert. Im nieder-
  227.    wertigen Byte steckt der ASCII-Teil des Tastencodes, das höherwertige Byte
  228.    enthält eine Reihe von Flags. Die genaue Belegung sieht so aus:
  229.  
  230.    Bit         Symbolischer Name    Inhalt
  231.    ------------------------------------------------------------
  232.     0... 7                          ASCII-Code/Funktionscode
  233.     8          NKF_RSH              Flag für rechte Shift-Taste
  234.     9          NKF_LSH              Flag für linke Shift-Taste
  235.    10          NKF_CTRL             Flag für Control-Taste
  236.    11          NKF_ALT              Flag für Alternate-Taste
  237.    12          NKF_CAPS             CapsLock-Status
  238.    13          NKF_NUM              Flag: Zehnerblock
  239.    14          NKF_RESVD            reserviert, mu₧ ignoriert werden!
  240.    15          NKF_FUNC             Funktionsflag
  241.  
  242.    Bit 8...11 geben an, ob die jeweilige Taste gedrückt war. In Bit 12 steht,
  243.    ob CapsLock zur Zeit aktiv ist oder nicht. Ist Bit 13 gesetzt, befindet
  244.    sich die Taste auf dem Zehnerblock. Bit 14 wird für interne Zwecke
  245.    verwendet und mu₧ auf jeden Fall ignoriert werden. Achtung: im ersten
  246.    Parameter der Funktion nkc_cmp() hat dieses Bit eine spezielle Bedeutung
  247.    (siehe entsprechendes Kapitel).
  248.  
  249.    Schlie₧lich gibt es noch Bit 15, da₧ angibt, ob es sich um eine
  250.    funktionsbezogene Taste (Bit gesetzt) oder ein druckbares Zeichen (Bit
  251.    gelöscht) handelt. Das Bit wird in folgenden Fällen gesetzt:
  252.  
  253.    a) eine der folgenden "Funktionstasten" wurde gedrückt:
  254.  
  255.       Esc, Tab, Backspace, Delete, Return,
  256.       Help, Undo, Insert, ClrHome, Cursor hoch, Cursor runter, Cursor links,
  257.       Cursor rechts,
  258.       Enter,
  259.       F1, F2, F3, F4, F5, F6, F7, F8, F9, F10
  260.       Page up, Page down, End, F11, F12, F14  (nur auf der Mac-Tastatur!)
  261.  
  262.       Der ASCII-Code solcher Tasten ist immer kleiner als 32 und als NK_...
  263.       in den Header Files definiert (z.B. NK_ESC für die Escape-Taste).
  264.  
  265.    b) irgendeine Taste wird zusammen mit Alternate und/oder Control gedrückt
  266.  
  267.       In diesem Fall wird immer die CapsLock-Version der Taste als ASCII-Teil
  268.       zurückgeliefert. Zum Beispiel erhält man bei Control+A als ASCII-Code
  269.       ein "A" zurück, niemals ein "a".
  270.  
  271.  
  272.    Das Funktionsflag steckt absichtlich in Bit 15, damit sich Tastencodes (die
  273.    als signed 16 Bit Integer definiert sind) sehr einfach in die beiden
  274.    Kategorien einordnen lassen:
  275.  
  276.    wenn Tastencode < 0
  277.       dann handelt es sich um eine Funktion
  278.    sonst
  279.       handelt es sich um ein druckbares Zeichen
  280.  
  281.    Der ASCII-Code eines druckbaren Zeichens kann übrigens alle Werte von
  282.    0 bis 255 enthalten.
  283.  
  284.  
  285.    Einige Tastenkombinationen können niemals von NKCC zurückgeliefert werden:
  286.  
  287.    a) Tasten, die vom System zurückgehalten werden. Dazu gehören zum Beispiel:
  288.       - Alternate + Cursortasten (dienen zur Maussteuerung)
  289.       - Alternate + Help (startet den Hardcopy-Mechanismus)
  290.       - Alternate + Control + Tab (schaltet unter MagiC den Task um)
  291.       usw.
  292.  
  293.    b) Tasten, die beim Halten von Alternate andere Zeichen liefern. Dazu gehören
  294.       z.B. Alternate @ \ [ { ] } auf der deutschen Tastatur, die man durch
  295.       Drücken von Alternate und/oder Shift sowie einer Umlauttaste erhält.
  296.       Der ASCII-Code wird korrekt zurückgeliefert, das Alternate-Flag wird aber
  297.       nie gesetzt. So kann es z.B. die Tastenkombination "Alternate + @" auf
  298.       der deutschen Tastatur nicht geben.
  299.  
  300.    Werden vom Deadkey-Handler oder durch Eingabe des ASCII-Codes auf der
  301.    Zehnertastatur Zeichen erzeugt, dann können nur das CapsLock- sowie das
  302.    reservierte Flag in dem resultierenden Tastencode gesetzt sein. Alle anderen
  303.    Flags sind immer 0. Analog dazu ist das Control-Flag immer gelöscht, wenn
  304.    durch das Einschalten der Control Key Emulation ein druckbares Zeichen
  305.    (z.B. Control A) erzeugt wird.
  306.  
  307.  
  308.  
  309.    Verarbeitung ungültiger Scancodes
  310.  
  311.    Ältere Versionen von NKCC produzierten schlicht und ergreifend Müll,
  312.    wenn eine Taste mit einem ungültigen bzw. unbekannten Scancode vom
  313.    Betriebssystem zurückgeliefert wurde. Ab Version 2.92 kommt NKCC auch
  314.    mit solchen Tastencodes klar und konvertiert sie korrekt in das
  315.    normalisierte Format. Dabei wird folgende Variation des Formats benutzt:
  316.  
  317.    Funktionsflag  = 1
  318.    Alternate Flag = 0
  319.    Control Flag   = 0
  320.    ASCII code     >= 32
  321.  
  322.    Diese Kombinationen können über die reguläre Tastatur niemals produziert
  323.    werden: es handelt sich um ein druckbares Zeichen, das als funktionelle
  324.    Taste markiert ist, aber ohne Alternate und Control.
  325.  
  326.    Und wozu braucht man das? Nun, einerseits reagiert NKCC damit auf eine
  327.    vernünftige Art und Weise auf unbekannte Scancodes. Andererseits lie₧en
  328.    sich damit sehr einfach die Makrotasten des Graphiktabletts einbinden,
  329.    für das ich im Frühjar '94 einen Treiber schrieb. :-) Dieser Treiber
  330.    speist in den BIOS Tastaturpuffer Makrotasten ein, die folgendes
  331.    Format haben:
  332.  
  333.    Scancode   = $84...$FF (Empfehlung: $FF benutzen)
  334.    ASCII Code = $20...$FF (ASCII Codes < $20 werden von NKCC auf $20 gesetzt)
  335.  
  336.    Die Flags für CapsLock und die Shift-Tasten übernimmt der Treiber direkt
  337.    vom System. Alternate und Control werden ebenfalls verarbeitet. Da beide
  338.    Flags aber nicht gesetzt sein dürfen, werden ihre Inhalte zum
  339.    Zehnerblock-Flag zusammengeodert.
  340.  
  341.    Das hat alles nicht direkt mit NKCC zu tun, kann aber als Anregung
  342.    verstanden werden, falls man selbst etwas ähnliches vorhat. Au₧erdem
  343.    verhalten sich die Rückkonverter-Funktionen in NKCC passend dazu:
  344.  
  345.    Wird solch ein normalisierter Tastencode mit nkc_n2gem() oder nkc_n2tos()
  346.    wieder zurückkonvertiert, erhält man als Scancode immer $FF. War das
  347.    Zehnerblock-Flag gesetzt, sind im Ergebnis sowohl das Alternate- als auch
  348.    das Control-Flag gesetzt.
  349.  
  350.  
  351.  
  352.    4. Wie wird NKCC aufgerufen?
  353.    =============================================================================
  354.    Der Umgang mit NKCC ist eigentlich sehr einfach. Es müssen nur ein paar
  355.    Funktionen aufgerufen werden:
  356.  
  357.    a) Initialisierung
  358.  
  359.    Ganz am Anfang mu₧ ein Aufruf von nkc_init() erfolgen. Die Funktion
  360.    bekommt drei Parameter übergeben:
  361.  
  362.    - ein Langwort mit Flags (definiert als NKI_... in den Header Files)
  363.  
  364.      NKI_BUTHND      aktiviert den Button Event Handler
  365.      NKI_BHTOS       zusätzlich: nur bei bestimmten TOS-Versionen
  366.                      (siehe Kapitel "Der Button Event Handler")
  367.                      Beide Flags werden von der TOS-Version von NKCC (die
  368.                      bereits assembliert als NKCC_TOS.O vorliegt) ignoriert.
  369.  
  370.      NKI_NO200HZ     hält NKCC davon ab, sich in den 200 Hz Timer für die
  371.                      Funktion nkc_timer() einzuklinken. Hinweis: wird der
  372.                      Button Event Handler eingeschaltet, so ignoriert NKCC
  373.                      dieses Flag, da die Timer Interrupt-Routine für den
  374.                      Handler benötigt wird.
  375.  
  376.    Die beiden folgenden Parameter von nkc_init() werden nur bei eingeschaltetem
  377.    Button Event Handler ausgewertet und sollten ansonsten 0 sein:
  378.  
  379.    - das Handle einer geöffneten virtuellen VDI Screen Workstation
  380.  
  381.    - ein Zeiger auf das AES global-Array der Applikation
  382.      unter Pure C ist dies:  _GemParBlk.global  (definiert in AES.H)
  383.  
  384.  
  385.    nkc_init() liefert ein 16 bit Integer mit der Versionsnummer von NKCC
  386.    als 4 Ziffer BCD zurück (z.B. $0292 = Version 2.92).
  387.  
  388.    Beispiele:
  389.  
  390.    nkc_init(0,0,NULL);              Default, ohne Button Event Handler
  391.  
  392.    nkc_init(NKI_NO200HZ,0,NULL);    jetzt klinkt sich NKCC nirgendswo mehr ein
  393.  
  394.                                     <handle> wurde von v_opnvwk zurückgeliefert
  395.    nkc_init(NKI_BUTHND,handle,_GemParBlk.global);
  396.  
  397.  
  398.    b) NKCC abmelden
  399.  
  400.    Mit der Funktion nkc_exit() klinkt sich NKCC wieder aus dem System aus.
  401.    Der Aufruf mu₧ auch dann erfolgen, wenn weder 200 Hz Timer noch Button
  402.    Event Handler installiert waren! Die Funktion liefert einen Fehlerstatus
  403.    zurück, wenn eine andere Applikation die XBRA-Kette der im System
  404.    eingeklinkten Routinen zerstört hat. Ist dieser Status < 0, dann darf
  405.    die Applikation auf keinem Fall beendet werden, da NKCC sich nicht mehr
  406.    aus den Vektoren aushängen kann.
  407.  
  408.  
  409.    c) Konfigurieren
  410.  
  411.    Mit der Funktion nkc_set() lassen sich bestimmte Einstellungen vornehmen.
  412.    Die Funktion erhält als Parameter ein Langwort mit Flags. Ein gesetztes
  413.    Flag aktiviert die jeweilige Funktion, ein gelöschtes Flag schaltet sie ab.
  414.  
  415.    NKS_ALTNUM        direkte ASCII-Code Eingabe per Alternate+Ziffernblock
  416.    NKS_CTRL          Control Key Emulation (liefert z.B. "ASCII 1" anstelle von
  417.                      "Control-Taste + ASCII 'A'")
  418.    NKS_D_...         schaltet den jeweiligen Deadkey ein
  419.  
  420.  
  421.    d) Vergleicher
  422.  
  423.    Zum Vergleichen von Tastencodes kann die Funktion nkc_cmp() verwendet
  424.    werden. Die Routine erhält zwei Parameter: den Referenz-Tastencode sowie
  425.    den Test-Tastencode (der vom Benutzer eingegeben wurde). Einige Bits
  426.    des Referenz-Tastencodes haben eine spezielle Bedeutung:
  427.  
  428.    NKF_IGNUM (entspricht NKF_RESVD)
  429.       Wenn gesetzt, dann wird das Zehnerblock-Flag ignoriert (d.h. es spielt
  430.       keine Rolle, ob z.B. eine Zahlentaste auf der Haupttastatur oder auf
  431.       dem Zehnerblock gedrückt wurde).
  432.  
  433.    NKF_CAPS
  434.       Wenn gesetzt, wird keine Unterscheidung zwischen Gro₧- und Kleinbuchstaben
  435.       vorgenommen.
  436.  
  437.    NKF_SHIFT ( *beide* Shift-Tasten; entspricht NKF_LSH|NKF_RSH)
  438.       Wenn *beide* Shift-Tastenflags im Referenz-Tastencode gesetzt sind, wird
  439.       lediglich überprüft, ob im Test-Tastencode *irgendein* Shift-Tastenflag
  440.       gesetzt ist.
  441.  
  442.  
  443.  
  444.    In den nächsten beiden Kapiteln steht, welche Funktionen zur Abfrage
  445.    von Tastenereignissen existieren und wie sie verwendet werden. Im
  446.    Kapitel "Sonstige Funktionen" sind weitere Routinen beschrieben, die bei
  447.    der Entwicklung von NKCC als Nebenprodukt entstanden sind, aber unter
  448.    Umständen sehr nützlich sein können.
  449.  
  450.  
  451.  
  452.    5. NKCC in TOS-Applikationen
  453.    =============================================================================
  454.    Für reine textorientierte Konsole-Applikationen sollte die TOS-Version
  455.    von NKCC verwendet werden (NKCC_TOS.O), da der inaktive GEM-Teil in
  456.    diesem Fall nur Ballast darstellen würde. Folgende Funktionen existieren:
  457.  
  458.    nkc_conin()
  459.       basiert auf der GEMDOS-Funktion Crawcin() und arbeitet genau wie diese,
  460.       mit der Ausnahme da₧ Tastencodes im normalisierten Format zurückgeliefert
  461.       werden. Durch eine geringfügige Modifikation des NKCC-Quellcodes kann
  462.       die Funktion auch auf Cconin() (Eingabe mit Echo) oder Bconin()
  463.       (BIOS-Funktion) abgebildet werden.
  464.  
  465.    nkc_cstat()
  466.       wird anstelle der GEMDOS-Funktion Cconis() (Tastaturstatus abfragen)
  467.       verwendet. Die Routine prüft, ob der Tastaturpuffer leer ist (Status 0)
  468.       oder nicht (Status -1).
  469.  
  470.  
  471.  
  472.    6. NKCC in GEM-Applikationen
  473.    =============================================================================
  474.    Für GEM-Applikationen stellt NKCC ein komplettes Binding zur AES-Funktion
  475.    evnt_multi() zur Verfügung. Die Routine trägt den Namen nkc_multi() und
  476.    unterscheidet sich vom Original in folgenden Punkten:
  477.  
  478.    a) Tastencodes werden im normalisierten Format zurückgeliefert
  479.  
  480.    b) die Tastenflags für Shift/Control/Alternate/CapsLock ("ev_mmokstate")
  481.       werden so geschoben, da₧ sie mit den NKF_...-Konstanten maskiert
  482.       werden können
  483.  
  484.    Für evnt_keybd() gibt es in NKCC keine Entsprechung.
  485.  
  486.  
  487.  
  488.    Erweiterung für Assembler-Programmierer - von Gerd Knops
  489.  
  490.    Das NKCC evnt_multi-Binding kann auch von Assemblerroutinen leicht
  491.    aufgerufen werden:
  492.  
  493.    - die AES Parameter-Arrays werden geladen (hierzu müssen die Arrays
  494.      von NKCC benutzt werden! -> siehe Kapitel "Symboltabelle")
  495.  
  496.    - nkc_amulti() wird aufgerufen. Die Funktion entspricht folgendem Code:
  497.  
  498.       move.l   #aespb,d1      ; Zeiger auf Parameterblock laden
  499.       move     #200,d0        ; opcode: AES
  500.       trap     #2             ; AES aufrufen
  501.       rts                     ; und wieder zurück
  502.  
  503.  
  504.  
  505.    7. Der Button Event Handler
  506.    =============================================================================
  507.    Lang lang ist's her...
  508.  
  509.    ... da veröffentlichte Atari die langerwartete Version 1.04 des ST-
  510.    Betriebssystems TOS. Dummerweise bauten die Jungs aus Sunnyvale einen
  511.    Fehler in den AES Multi Event Handler ein, der sich beim Warten auf
  512.    Timer-Events mit sehr kurzen Zeiten bemerkbar macht. Ist der Timer
  513.    nämlich genau dann abgelaufen, wenn der Benutzer gerade mitten in einem
  514.    Mausklick ist, behauptet evnt_multi(), da₧ ein Timer-Event UND ein
  515.    Button-Event aufgetreten sind. Unter Umständen ist es so niemals
  516.    möglich, einen Doppelklick in die Applikation hineinzubekommen, da
  517.    der Multi Event Handler die halbfertigen Mausklicks bereits an
  518.    die Applikation meldet (als Einfachklicks).
  519.  
  520.    Nach langem Herumexperimentieren habe ich mich schlie₧lich dazu
  521.    durchgerungen, einen eigenen Button Event Handler zu schreiben und
  522.    in NKCC einzubauen.
  523.  
  524.    Der NKCC Button Event Handler wird beim Aufruf von nkc_init() durch
  525.    das Flag NKI_BUTHND aktiviert. Zusätzlich gibt es noch das Flag
  526.    NKI_BHTOS: wenn gesetzt, erfolgt die Installation nur dann, wenn
  527.    eine fehlerhafte TOS-Version erkannt wurde.
  528.  
  529.    Zum Betrieb des Button Event Handlers wird au₧erdem das Handle einer
  530.    geöffneten virtuellen VDI Screen Workstation benötigt, da NKCC
  531.    die VDI-Funktion vex_butv() aufruft. Die Workstation darf nicht vor
  532.    dem Aufruf von nkc_exit() geschlossen werden!
  533.  
  534.    Wenn schon einen eigenen Button Event Handler, dann gleich mit ein paar
  535.    Zusatzfunktionen:
  536.  
  537.    - MU_XTIMER Flag (wird mit den anderen MU_... Flags als Ereignis-Maske
  538.      an nkc_multi() übergeben)
  539.      Ist dieses Flag (zusätzlich zu MU_TIMER) gesetzt, werden keine
  540.      Timer-Events geliefert, wenn der Screen Manager vom System zur
  541.      Zeit die Kontrolle über den Bildschirm hat (z.B. beim Ausklappen
  542.      von Drown Down Menüs oder Schieben eines Fensters).
  543.  
  544.    - Negations-Flag ($100 der Button-Maske)
  545.      In der c't Ausgabe 3/90 oder 4/90 stand ein Artikel über dieses
  546.      Flag, das bereits in der ersten TOS-Version eingebaut war aber nie
  547.      dokumentiert wurde - sehr zum Ärger vieler Programmierer. Denn mit
  548.      diesem Flag lassen sich beide Maustasten ohne gro₧en Aufwand
  549.      simultan abfragen. Wenn gesetzt, wird die "wahr"-Bedingung für
  550.      Button-Events invertiert. Das lä₧t sich am einfachsten an einem
  551.      Beispiel erklären:
  552.  
  553.  
  554.      mask = evnt_multi(MU_BUTTON,2,3,3,...
  555.  
  556.      Soll maximal Doppelklicks (2) abfragen für beide Buttons (3), die Buttons
  557.      müssen gedrückt sein (3). Funktioniert aber nicht, denn es wird getestet:
  558.      Knopf #0 gedrückt UND Knopf #1 gedrückt.
  559.  
  560.  
  561.      Mit Negations-Flag sieht das dann so aus:
  562.  
  563.      mask = evnt_multi(MU_BUTTON,0x102,3,0,...
  564.  
  565.      Hiermit werden wiederum Doppelklicks abgefragt (2) für beide
  566.      Buttons (3). Diesmal wird jedoch auf Loslassen (0) getestet und
  567.      das Ergebnis invertiert (0x1..). Also:
  568.  
  569.      Nicht ( Knopf #0 losgelassen UND Knopf #1 losgelassen )
  570.  
  571.       oder in anderen Worten:
  572.  
  573.      Knopf #0 gedrückt ODER Knopf #1 gedrückt
  574.  
  575.      Ist doch nett, oder? :-)
  576.  
  577.  
  578.  
  579.    8. Sonstige Funktionen
  580.    =============================================================================
  581.    Bei der Entwicklung von NKCC entstanden einige Funktionen, die nützlich
  582.    genug waren, um exportiert zu werden. Es handelt sich hierbei um:
  583.  
  584.    nkc_timer()
  585.       liefert den aktuellen Wert des 200 Hz Timers zurück. Die Funktion ist
  586.       sehr schnell, da sie nur eine Variable laden mu₧ und dann sofort zurück-
  587.       kehrt.
  588.  
  589.       Hinweis: bei ausgeschaltetem Timer (NKI_NO200HZ bei nkc_init()) erhält
  590.                man als Ergebnis immer 0.
  591.  
  592.    nkc_kstate()
  593.       liefert den aktuellen Wert der Shift-Tasten, Control, Alternate und
  594.       CapsLock als NKF_... Flags. Ebenfalls sehr schnell.
  595.  
  596.    nkc_tconv()
  597.       Das Kernstück von NKCC: der Tastencode-Konverter, der 32 Bit BIOS
  598.       Tastencodes in das normalisierte Format umwandelt. Die Spezialfunktionen
  599.       (Deadkeys etc.) werden von dieser Routine nicht gehandhabt (sondern
  600.       von nkc_conin() und nkc_multi()/nkc_amulti()).
  601.  
  602.    nkc_gconv()
  603.       Eine Variation von nkc_tconv(). Anstelle des BIOS Tastencodes wird dieser
  604.       Routine ein 16 Bit GEM-Tastencode übergeben. ACHTUNG!! Aufgrund der
  605.       fehlenden Flags (Shift/Control/Alternate/CapsLock) können nicht alle
  606.       Tastencodes eindeutig konvertiert werden. Es handelt sich hierbei
  607.       um ein Problem von GEM, das für verschiedene Kombinationen ein und
  608.       denselben Tastencode vorsieht (über das Problem habe ich mich im ersten
  609.       Kapitel ja schon ausgelassen). Die Funktion wurde nur für den "Notfall"
  610.       eingebaut, wenn die Flags nicht mehr zur Verfügung stehen. Wann immer
  611.       möglich sollte nkc_tconv() verwendet werden.
  612.  
  613.    nkc_n2tos()
  614.       konvertiert normalisierte Tastencodes zurück in's 32 Bit BIOS Format.
  615.  
  616.    nkc_n2gem()
  617.       konvertiert normalisierte Tastencodes zurück in's 16 Bit GEM Format.
  618.  
  619.    nkc_vlink()
  620.       Hiermit lä₧t sich eine Routine mit XBRA Header in einen Vektor einklinken.
  621.       Der Vektor kann entweder als Adresse (z.B. $502 für die Hardcopy-
  622.       Routine) oder als Nummer angegeben werden (z.B. 2 für den Busfehler-
  623.       Vektor).
  624.  
  625.    nkc_vunlink()
  626.       Das Gegenstück zu nkc_vlink(): eine XBRA-Funktion wird aus einem Vektor
  627.       wieder ausgeklinkt.
  628.  
  629.    nkc_toupper()
  630.       konvertiert Zeichen über eine Tabelle von Klein- nach Gro₧buchstaben.
  631.       Sonderzeichen wie "ä" oder "é" werden korrekt behandelt.
  632.  
  633.    nkc_tolower()
  634.       konvertiert Zeichen von Gro₧- nach Kleinbuchstaben.
  635.  
  636.  
  637.    Genaueres zu den einzelnen Routinen steht in NKCC.TXT.
  638.  
  639.  
  640.  
  641.    9. Symboltabelle
  642.    =============================================================================
  643.    Folgende Symbole werden von NKCC exportiert:
  644.    (Klammern hinter dem Namen identifizieren diesen als Funktion)
  645.  
  646.       nkc_init()     Initialisierung, optional Button Event Handler installieren
  647.       nkc_exit()     Deinitialisierung; NKCC klinkt sich aus dem System aus
  648.       nkc_set()      Sonderfunktionen einstellen
  649.       nkc_conin()    raw console character input (basierend auf Crawcin())
  650.       nkc_cstat()    sample console input status (basierend auf Cconis())
  651.    *  nkc_multi()    Binding zur GEM-Funktion evnt_multi()
  652.    *  nkc_amulti()   dito für in Assembler geschriebene Programme
  653.       nkc_tconv()    Tastencodekonverter (32 Bit BIOS -> normalisiert)
  654.       nkc_gconv()    Tastencodekonverter (16 Bit GEM -> normalisiert)
  655.       nkc_n2tos()    Tastencodekonverter (normalisiert -> 32 Bit BIOS)
  656.       nkc_n2gem()    Tastencodekonverter (normalisiert -> 16 Bit GEM)
  657.       nkc_kstate()   Status von Shift/Control/Alternate/CapsLock erfragen
  658.       nkc_timer()    aktuellen Wert des 200 Hz Timers erfragen
  659.       nkc_cmp()      Tastencodes vergleichen
  660.       nkc_vlink()    XBRA-Funktion in Vektor einklinken
  661.       nkc_vunlink()  XBRA-Funktion aus Vektor ausklinken
  662.       nkc_toupper()  Konvertierung Klein- nach Gro₧buchstaben
  663.       nkc_tolower()  Konvertierung Gro₧- nach Kleinbuchstaben
  664.  
  665.    *  nkc_contrl     AES/VDI control array
  666.    *  nkc_intin      AES/VDI integer input array
  667.    *  nkc_intout     AES/VDI integer output array
  668.    *  nkc_adrin      AES address input array
  669.    *  nkc_adrout     AES address output array
  670.    *  nkc_ptsin      VDI pointers input array
  671.    *  nkc_ptsout     VDI pointers output array
  672.                      (nkc_amulti() wertet diese Arrays aus)
  673.  
  674.  
  675.    *  nur in der GEM-Version von NKCC (NKCC.O).
  676.  
  677.    =============================================================================
  678.    Dateiende
  679.