PROGRAMMERS MANUAL


Technische Spezifikationen
CKBD.PRG ist ein residentes Programm das den Tastaturtreiber des TOS um 
einige Funktionen ergnzt. Als XBRA und Cookie Kennung wird 'CKBD' 
(Composed characters KeyBoard Driver) verwendet.
CKBD.PRG hngt in folgenden Vektoren:
	ikbdsys
	mousevec
	VBL slot
	resvector		(nur TOSse ohne Cookie Jar)
	kcl_hook, bell_hook	(nur TOS unter 1.6, KAOS unter 1.4.1)

CKBD.PRG installiert auch einen Cookie, Kennung CKBD. Es ist ein Zeiger 
auf einen Funktionsdispatcher angegeben.
C-Deklaration:	long cdecl ckbd( int opcode, ... );
Darber sind folgende Funktionen erreichbar: IDENTIFY, EXTKEY, COMPOSE, 
ALT_NNN, CKEYTBL, CBIOSKEYS. Ab CKBD version 1.2 auch DEADKEY und 
MOUSE_CFG.


Funktionsdefinitionen & Beschreibung:
In der Datei CKBD.H sind folgende Definitionen enthalten.
Der COOKIE enthlt einen Zeiger auf die Setup-Funktion ckbd().
C-Deklaration: cdecl long setup(int opcode, ...);

IDENTIFY	opcode 0
gibt in a0 und d0 einen Zeiger auf einen C-type ASCII-string zurck.
	char *ckbd(IDENTIFY);

EXTKEY	opcode 1
schaltet Extkey-modus ein/aus bzw. fragt aktuellen Status ab.
	long ckbd(EXTKEY, int mode);
		mode:	-1 (INQUIRE), 0 (OFF), 1 (ON)
		return:	vorheriger Wert

COMPOSE	opcode 2
schaltet COMPOSE-Modus ein/aus bzw fragt aktuellen Status ab
	long ckbd(COMPOSE, int mode);
		mode:	-1 (INQUIRE)
			0 Set mode, bitmapped:
			bit #0:     OFF/ON
			bit #1:     DEC/MULTICHAR MODE
			bit #2:     ORDER SENSITIVE NO/YES
		return:   vorherige Einstellungen.

ALT_NNN	opcode 3
verwaltet die ALT-ASCII Funktion.
	long ckbd(ALT_NNN, int mode);
		mode:	-1 (INQUIRE), 0 (OFF), 1 (ON)
		return:	vorherige Einstellungen.

CKEYTBL	opcode 4
verwaltet die Tastaturtabellen.
	long ckbd(CKEYTBL, char *unshift, char *shift, char *caps,
				                             char 
				                             *compose );
		unshift, shift, caps:
			Zeiger auf die entsprechenden Tabellen
			(identisch mit XBIOS Keytbl Tabellen)
		compose:	Zeiger auf die Compose-Tabelle.
		return:	Zeiger auf XKEYTAB Struktur (readonly)

Bemerkung: wenn ein Zeiger den Wert 0 oder -1 besitzt, dann wird dieser 
Wert intern nicht verndert. Die vier Tabellen werden in einen internen 
Puffer kopiert, der Aufrufer braucht die Tabellen also nicht selbst im 
Speicher zu behalten.

CBIOSKEYS	opcode 5
setzt die Originaltabellen wieder ein oder schaltet zwischen den 
Tabellen hin und her
	int ckbd(CBIOSKEYS, switch);
		switch:	-1  INQUIRE  (returns XKEYTAB - adr only)
			0: bitmapped:
			bit #0: keyboard table (SET: use secondary)
			bit #1: compose tables (SET: use secondary)
		return:	last setup value.

DEADKEY	opcode 6
kontrolliert die Toten Tasten...
	long ckbd(DEADKEY, short mode, char *deadkeys)
		mode:	-1 (INQUIRE), 0 (OFF), 1 (ON), 2 (SETUP)
	deadkeys:	Wenn mode=SETUP: Zeiger auf nullterminierten 
	String mit neuen Deadkeys. Sonst NULL oder Zeiger auf einen 16 
	Byte groen Puffer, in den dann die aktuell benutzten Deadkeys 
	kopiert werden.
		return:	der zuletzt eingestellte Modus

MOUSE_CFG	opcode 7
Stellt die Mausbeschleuniger-Parameter ein beziehungsweise fragt sie ab.
	int ckbd(MOUSE_CFG, int mode, MSPEEDER_SETUP *mdata);
		mode:	-1: INQUIRE
			0: OFF - deactivate Speeder
			1: ON  - activate Speeder
			2: SET - install new params
	return:	Zeiger auf MSPEEDER_SETUP-Struktur mit den aktiven 
	Daten.



Datenstrukturen

XKEYTAB
Diese Struktur wird von der Funktion XKEYTAB benutzt.
typedef struct {
	char    *unshift;
	char    *shift;
	char    *caps;
	comptab *compose;
} XKEYTAB;

char	Unshift_keymap[128];
char	Shift_keymap[128];
char	Capslock_keymap[128];


COMPTAB_ENTRY
Die Compose-Tabelle ist ein Array von Elementen des Typs COMPTAB_ENTRY. 
Sie enthalten alle mglichen Kombinationen. Die unter primary, 
secondary und composed angegebenen Werte sind ASCII-Codes (und somit 
unabhngig vom verwendeten Tastaturlayout). Das letzte Element einer 
Tabelle mu viermal Null enthalten. Die Tabelle kann jede Lnge 
zwischen 2 und 256 Eintrgen annehmen.
Der 'flags' Eintrag wird eventuell Steuerinformationen enthalten, die 
im Multichar-compose Betrieb das Ende einer Mehrfach-sequenz angeben, 
die verschiedene Compose-Sequenzen fr eines oder mehrere Verfahren 
gezielt verbieten...

typedef struct {
	char    primary;	/* Hauptzeichen */
	char    secondary;	/* Nebenzeichen */
	char    composed;	/* Sonderzeichen */
	char    flags;		/* div. Flags, reserviert. Auf Null 
	setzen */
} COMPTAB_ENTRY;

COMPTAB_ENTRY compose_table[];


MSPEEDER_SETUP
Diese Struktur enthlt die ntigen Einstellwerte fr die Funktion 
Mouse_cfg. Die Polynomfaktoren und X-Y-Ratio Werte sind 
(int)(float_val*256), also 8 bit Fixpointwerte. Der Standardwert fr 
die Mausauflsung ist 100 dpi, fr den Bildschirm 72 dpi. Diese Werte 
entsprechen einer Standard Atari-Maus und einem SM124.

typedef struct {
	struct {
	     unsigned resvd	:13;
	     unsigned lefthand	:1;       /* Button L/R swap */
	     unsigned unused	:1;       /* old feature, removed... */
	     unsigned activity	:1;       /* Speeder ON/OFF */
	} switches;
	short       polynomial[4];	/* speeder polynomial factors */
	short       rotation;	/* rotation in degrees */
	short       ratio;	/* X:Y ratio * 256! */
	short       mouse_rez;	/* M.resolution in dpi (100)  */
	short       screen_rez;	/* screen rez in dpi   ( 72)  */
} MSPEEDER_SETUP;



CKB - Dateiformat
-> siehe Beispieldateien.


RICHTIG PROGRAMMIEREN
Jedesmal, wenn eine etwas leistungsfhigere Tastaturabfrage in einem 
Programm bentigt wird, steht der Programmierer vor einem Problem. Wie 
erfasse ich alle Tastendrcke korrekt, wie kann ich ein Nachlaufen (im 
Editor) wirkungsvoll verhindern ..... usw.

ES IST FALSCH, einfach nur die Scancodes auszuwerten. Das ergibt 
Programme, die auf 'fremden' Tastaturen nicht einmal Z und Y 
unterscheiden knnen.

ES IST FALSCH, einen komplett neuen Tastaturtreiber zu schreiben. Dann 
freuen sich die anderen Applikationen (ACC's etc!). Der User brigens 
auch.

KEINE TASTENKOMBINATION IST UNGLTIG. (MURPHY'S LAW!). Der Scancode 
NULL kann durchaus vorkommen - nmlich immer dann, wenn ein 
zusammengesetzter Buchstabe kommt. Auch TOS 3.06 und 2.06 tun das.

Damit Extkey und Deadkey immer funktionieren, mssen zwei Regeln 
beachtet werden:
1.	BACKSPACE (Scan $0E, ASCII $08) mu immer ausgefhrt werden, 
auch in Verbindung mit der CONTROL, SHIFT oder ALT Taste.
2.	Sehr schnelle Tastenfolgen drfen nicht unterdrckt werden. 
Extkey und auch Compose im Multichar-mode senden typischerweise bei 
einer Tastenbettigung zwei Codes, namentlich BackSpace und NewChar. 
Wobei NewChar wiederum den Scancode Null besitzt. Deadkey sendet bei 
einer ungltigen Kombination auch zuerst das 'tote' Zeichen, dann das 
gerade getippte Zeichen.

Die NKCC Routinen von Harald Siegmund, die dem RCS 'Interface' 
beiliegen, sind sauber aufgebaut. Die neueren Versionen arbeiten 
korrekt, ltere Versionen tun dies bis auf zwei Ausnahmen: ALT-nnn mit 
Werten unter 32 ergibt die Meldung 'NKC_INVALID', und bei COMPOSE wird 
irrtmlich die ALT-Taste als gedrckt gemeldet.


---eof---

