
CKBD Deluxe v1.5
Composed Characters Keyboard Driver plus flexible mouse speeder



The ultimate extension for the keyboard driver under
TOS, MTOS, MagiC, MagicMac, MagicPC
by
Pascal Fellerich.

This program is Freeware.




Foreword
The problem is largely known: you want to type a German text on an 
American keyboard. At the first occurrence of an umlaut you will see 
that there are some characters missing!
	Solution number one: Simply install a german keyboard mapping 
table. Of course this works, but then 'QWERTY' turns into 'QWERTZ', 
and this is quite discomforting if not annoying.
	Solution number two: Assign the special characters you need 
to the numeric keypad. But then you have to get used to it and 
moreover it slows down typing because you have to move your right 
hand from the keyboard to the numeric keypad for every special 
character.
	Solution number three: CKBD Deluxe! This utility gives you 
easy access to any special character available in the system 
character set on any keyboard! Moreover CKBD Deluxe is configurable 
so that even completely different character sets like the ISO set can 
be used.

As you are using a graphical user interface you also use a mouse. But 
unfortunately the standard mouse driver in TOS is not very 
comfortable. It has only a linear response and you have to move the 
mouse a lot over your desk. That's why most people use a mouse 
accelerator. However these mouse speeders are in general not very 
flexible - either they're too fast or too slow, they cause jerky 
pointer movements, distort the mouse movement angles, are only made 
for one type of mice and with a high resolution mouse they go out of 
control. CKBD Deluxe also takes care of this special problem: It 
offers a really flexible mouse speeder which offers you the following 
features:
	Smooth mouse acceleration using a polynomial of the third 
	degree, internal resolution is 0.004 pixel!
	No angle distorsion 	Mouse button swap feature
	User definable constant angle offset
	Screen resolution independence, automatic adaptation!
	Mouse resolution independence (!!!!)
	Comfortable speed-up curve editor


Status
CKBD Deluxe is freeware. This means that this software: 
	may be used without paying a fee
	may be distributed via BBS systems and 'PD' libraries 
	may not be sold
	may not be modified. This implies that only the self 
extracting archive CKBD_15.TOS may be distributed. This is simply to 
make sure that everyone gets the complete software package. This 
software is copyrighted by P. Fellerich as it is not public domain.
CKBD Deluxe may be distributed together with commercial software only 
with permission from the author. Currently this applies only to the 
word processor PAPYRUS by R.O.M. Software (Germany). If you are 
interested in distributing CKBD with your software as well don't 
hesitate to ask me. Write to: Pascal Fellerich
45, rue des Gents
L-3482 Dudelange
Luxembourg
or via E-mail:
	Pascal_Fellerich@aia.com
	Pascal Fellerich on 2:270/16.3 (FidoNet)
Bug reports, suggestions and new CKB tables are welcome as well!


Installation
This software consists of three parts::
	The TSR-program (Terminate and Stay Resident) called CKBD.PRG
	The CPX-module COMPOSE.CPX used to configure the keyboard 
	driver
	The CPX-module MOUSE.CPX used to configure the mouse driver .
The TSR program CKBD.PRG must be copied into your auto-folder on your 
boot partition. If you have to use another keyboard driver, e.g. for 
a PC keyboard on the Atari, make sure that CKBD.PRG is executed after 
this keyboard driver. The CPX module can only be used together with 
Atari's extensible control panel XCONTROL(** If you don't have 
this control panel you can get it from your Atari dealer. It runs as 
ACC and PRG.**). If you have XCONTROL installed simply copy the files 
COMPOSE.CPX and MOUSE.CPX into the CPX folder. After that, reboot 
your computer to activate the resident driver and the CPX modules. 
That's it!

Before you go on reading this manual please note: 
	The option 'Language' in both CPX allows you to reconfigure 
	the CPX to another language.
	If you have configured the mouse speeder to death hold down 
	the Alternate key. This will bypass the mouse speeder 
	temporarily.


User manual for the Compose CPX
The resident driver CKBD.PRG is now part of the TOS and can be 
reconfigured by means of the two CPX. As there is one CPX module for 
the keyboard functions and one for the mouse functions I start with 
the new keyboard features and the associated CPX.
The basic idea behind CKBD is to compose special characters by 
'overtyping' two or more standard characters available on your 
keyboard. For example an '' is made up of the main 
character(** usually normal  letters from a..z **) 'a' and the 
overlay character(** usually accents and other 'decoration' 
letters **) '"'. CKBD Deluxe offers in total five different options to 
access special characters: 
	Compose
	Deadkey
	Extkey
	ALT-<nnn>
	'classical' Keyboard remapping


Compose.
This method is called 'Composed Characters' and is based upon the 
concept of DEC(** Digital Equipment Corporation, the company 
making VAX computers **). On these DEC terminals you hit the key 
labelled 'Compose Character', then you type the two characters you 
want to put together. So,  Compose, [a], [e]  gives  []. On the 
Atari  it is nearly the same: hit ALTERNATE(** On the VT200 
terminals by DEC there's a special key to the left side of the space 
bar labelled 'Compose Character', exactly where the Atari keyboard 
has the Alternate key. **) as if it was a normal key, then type [a], 
[e] and watch the [] appearing. If you hold the Alternate key 
depressed too long it doesn't work. This is to make sure that it 
doesn't interfere with the normal Alternate key functions.
If a compose sequence has been started successfully you hear a key 
click, even if you have turned it off. If a compose sequence is 
recognised as invalid after the second character you will hear the 
system bell even if it was turned off.
If you have started a compose sequence and you don't want to continue 
you can escape from the compose mode by hitting either ESC, BackSpace 
or any other key with no ASCII code (Function keys, cursor keys...) 
The order in which the two characters are typed doesn't matter unless 
you change this behaviour in the CPX module.

CPX: The option 'Compose' switches this function on or off. By 
clicking on the button 'Setup' you get to a second dialogue page 
which offers you some more options:
Compose mode:
Chooses between DEC VT200 (default), MultiChar and Automatic 
MultiChar mode. When in DEC mode a compose sequence is terminated 
after two characters, and during the composition process no 
characters are echoed. This is the most compatible method which 
usually works even in very badly written programs. When in MultiChar 
mode a compose sequence is only aborted if the first invalid 
combination is encountered. This allows you to put more than two 
characters together, for example: Compose (MultiChar), [u], ['] gives 
[], then typing [`] finally gives []. Before you go for this 
sequence be informed that this sequence is not defined in the 
standard tables. To use this feature you have to create your own 
tables. And from v1.5 on there is the new  Automatic MultiChar mode. 
Basically it works like the MultiChar mode but you don't need to hit 
the ALT key before a compose sequence. This mode was implemented for 
Vietnamese according to the VIQR standard; there it is called 
'implicit composition with immediate echo'.

Compose order:
Chooses between Order indifferent and order sensitive. The default is 
order indifferent so that you don't have to care about the order 
you're keying in the letters. This feature is only useful if you are 
using a table which assigns a different depending which order you use.


Deadkey
When typing longer texts you may notice that Compose Character works 
perfectly without interfering with any other action but unfortunately 
hitting the Alternate key ever so often can be a pain if you type a 
lot of  composed characters. That's why there is the Deadkey 
function. With this option enabled some keys with overlay characters 
like ['], [`], [^] and ["] are defined as dead keys. If you hit one 
of these, nothing happens. Only if you type the second character you 
get a result: if the sequence makes sense as for example ["] and [o] 
you get an []. If not, both characters are passed to the main 
application. There are three exceptions to that rule: First, if you 
hit the dead key twice you get the 'dead' character once. Second, 
Escape and Backspace abort a sequence - no character code is sent to 
the application. Third, if you hit Space after a dead key both 
characters are output, regardless of the table in use. If you are 
writing documents in a foreign language, Deadkey will be your 
preferred option. If you are a programmer the Deadkey option may 
interfere too often because it composes characters by itself every 
time it has the possibility - unlike the Compose option which must be 
initiated manually.

CPX: The button 'Deadkey' switches the option on or off. By clicking 
the button  labelled 'Setup' you get to the second dialogue page 
where you find a line showing the dead keys currently in use. You can 
modify this line to match your needs - but be careful: every ASCII 
code is OK, so it's up to you to configure your system to death.



ExtKey
The well-known feature known from the program ExtKey by Alex Esser. 
Again the same idea: a special character is made up of a main 
character and an overlay character. With Extkey, you first type the 
main character, then the overlay character with the Control-key 
depressed. Then the main character disappears and is replaced by the 
newly composed character. Example: you type [o], then <Control>-["] 
and you get [].  Extkey requires that you stick to the order main 
char, overlay char. It is not possible to generate a [] by typing 
[^], <Control>-[u]. This is to make sure that the shortcut 
^U(** ^U = close the top window in GEM applications. **)  is not 
locked out.
Unfortunately a lot of user applications have problems with Extkey, 
because the shift state returned by GEM/AES is not always correct!


ALT-<nnn>: DOS-o-Matic...
The preferred method for MS-DOS fanatics. Simply hold down the 
Alternate key and type the decimal ASCII code on the numeric keypad. 
This option has only been implemented to make CKBD Deluxe more 
complete; in TOS 2.06/3.06 it's included anyway. So don't shout at me 
if  it seems to work even when turned off - in that case it's TOS 
which takes over and does it.


Keyboard remapping
Despite its simplicity and inconvenience keyboard remapping is  still 
useful. The keyboard manager CPX module allows you to load either 
'*.KBD' or '*.CKB' files. The KBD-files are standard keyboard mapping 
tables with a total length of exactly 384 bytes, made up of mapping 
tables for unshift, shift and capslock key assignments. **NEW** The 
CKB-files are ASCII files which contain (optionally) the three 
standard mapping tables, a compose table and some configuration data. 
These tables can be created or modified with any normal ASCII text 
editor. The three CKB files that are included shall serve as an 
example.
If a new table has been loaded you must specify to what it should 
apply. Why is that? Easy example: imagine you have a CKB file which 
defines new compose sequences and you want to use it. Unfortunately 
it has been set up for a Swiss keyboard. In that case you load the 
file and enable it only for 'Compose'.  Usually if you want to use a 
CKB file totally you enable it for both keyboard and compose.


The rest of the Compose-CPX...
The CPX should be quite understandable now; but anyway here are some 
hints:
	The blue info line in the CPX displays the identification 
string of the currently installed driver, in this case CKBD Deluxe 
v1.5. A click on this info line brings up an alert box telling you 
the CPX version number and some more information.
	The pop-up menu titled 'Language' is used to determine the 
menu language in the CPX. This has no influence on the keyboard 
layout! The CPX title and the icon colour is fixed and can only be 
changed with Atari's 'Config. CPX'. To make your set-up permanent 
don't forget to save your settings. 
	'Save' stores your set-up only in the CPX module, not in 
the resident driver. If you want to have different settings than 
the standard set-up you have to boot Xcontrol as an accessory.


User manual for the Mouse CPX
There is an abundant choice of mouse speeders, maybe because it's 
quite straightforward to write a little mouse speeder. But until now 
there is no really flexible and easy to use mouse speeder for the 
Atari(** Neither Mac nor PC have a similar thing...**). That 
has come to an end, CKBD Deluxe offers you the most complete mouse 
speeder the world has ever seen.
When you invoke the CPX module you are in the main dialogue, exactly 
as in COMPOSE.CPX. The upper pop up menu Mouse speeder is used to 
switch the mouse speeder on or off. The box beneath has another pop 
up menu Mse buttons which swaps the mouse buttons. Left handed people 
can then use the mouse in the same fashion right handed people do. By 
the way, the button swap feature works even if the mouse speeder is 
turned off.
The entry Rotation: 0 determines by how many degrees the X/Y 
reference is turned, as indicated in the small picture on the left 
side of the dialogue. If you hold the mouse twisted a little bit 
counter clockwise, this means that the X/Y reference is turned by a 
negative angle. I get the best results if I use a negative angle 
offset of -6..-7 degrees.
The entry Resolution: 100 dpi is to tell CKBD Deluxe the mouse 
resolution. The standard Atari mouse has about 100 dpi (my TT mouse 
has 116 dpi), other mice may have much higher resolutions. In order 
to avoid that a new mouse with a higher resolution is uncontrollable 
you have to enter the correct resolution and then the speed-up is 
exactly the same as with the old mouse. However, a mouse with a high 
resolution has the big advantage that it offers a better fine 
control! If you want to determine the resolution of your mouse, 
proceed as follows:
	Disable the mouse speeder.
	Move the pointer to the left screen border.
	Guide the mouse horizontally along a ruler until the pointer 
reaches the right border. Write down the distance by which you moved 
the mouse.
	Multiply the horizontal resolution of your screen (TT Mid or 
ST High: 640 pixel) by 2.54 and divide this number by the distance 
recorded at the previous step. The result is the mouse resolution in 
dpi.
The button polynomial editor brings you to another dialogue which 
displays the polynomial coefficients and the resulting speed-up curve 
defined by the polynomial y=ax+bx+cx. You can enter the 
coefficients directly and accept them by clicking into the graphical 
edit field. The resulting curve is then displayed and the mouse is 
already using the new speed-up curve. But you can also move the four 
little boxes around (standard drag & drop technique). The CPX then 
calculates the new polynomial and displays it. As such move 
operations often produce weird results the new acceleration curve is 
not installed until you click in the edit field, close the window or 
quit the dialogue with 'OK'. Should it happen that the mouse has 
become uncontrollable hold down the alternate key. This bypasses the 
mouse speeder!
And finally this dialogue offers you five different speed-up presets 
under the pop up menu labelled Presets.
Back to the main menu: There are more set-up options! By clicking on 
the mouse picture you get to the second main dialogue page dedicated 
to the screen. There you find the entry Pixel W/H = 256:256 which 
determines the pixel width to height ratio for the current 
resolution. In ST-High, ST-Low, TT-Mid and other sensible screen 
resolutions the pixel ratio is 1:1, which is the same as 256:256. But 
in ST-Mid for example this ratio is 2:1 which corresponds with 
256:128!
Next to it is the entry Resolution: 72_ dpi. As a small screen is 
depicted left to it, it should be clear that the screen resolution is 
meant. Here the correct value should be entered, too. In ST-Low and 
TT-Low, the resolution is around 35 dpi, for other modes it is around 
70 dpi. If you enter the correct values CKBD Deluxe compensates not 
only for different mice but also for different resolutions!
To avoid having to update these fields every time you change 
resolutions there is an option to set these values automatically. 
Enable it by clicking on the button auto detect. When you switch it 
on the values are updated as well, not only at the next reboot. The 
CPX gets these values from the VDI, so if it displays obviously 
incorrect values, don't blame me!
As a final highlight you find the pop up language which gives you the 
choice between several languages. The other controls in the CPX are 
standard and don't need further explanations.


Hints
Before you throw away this manual please read the following hints:
	Utilities having the same functions should be discarded or at 
least be switched off if order to avoid undesired side effects, as 
for example overloading the ikbdsys interrupt. This includes all 
sorts of mouse speeders including Atari's MACCEL.
	It is recommended to have a look in the standard compose 
tables. This will help you a lot when it comes to composing 
characters.
	Unfortunately there are still a lot of programs which do not 
accept composed characters or even show weird effects upon receiving 
such characters. In that case the user application is to blame, not 
CKBD Deluxe!
	The extensible control panel runs only under TOS 1.4 or 
higher.
	CKBD.PRG itself runs on every TOS version. As the interface 
between the CPX modules and the driver is fully documented it should 
be easy to write a special set-up accessory...
	If  you find this software useful, don't hesitate to signal 
this to me!


It's not a bug, it's a feature!!
Unfortunately there's no program without any shortcomings. For 
example the auto detect function in the Mouse CPX doesn't give 
correct results under older TOS versions. This is because the VDI 
gives incorrect pixel size and aspect ratio values. Take for example 
the three ST resolutions:







You see that the TT-TOS - and thus hopefully every TOS version higher 
than 2.06 - gives correct results. Correct refers of course to the 
pixel ratio data, the screen resolution cannot be 100 % correct 
because the operating system doesn't know the exact size of the 
monitor.


Version history:
Compose-CPX:
v1.10:	New (ASCII!) format for CKB tables.
v1.01:	(1.1.1996) 3D-look, cosmetics...
v1.00:	(26.3.1994) the great rewrite, improved user interface
v0.8:	Bugfree version
v0.7:	File selector gives wrong paths
v0.1:	Test version

Mouse-CPX:
v1.01:	(1.1.1996) 3D-look, cosmetics...
v1.00:	(26.3.94) new CPX, first release

TSR:
v1.5:	(April 1996)
		 New mode for compose character; improved handling.
		 Support for VIQR/VISCII (Vietnamese ASCII; 
		suggestion by Oliver Skelton)
v1.4:	(January 1996)
		 NVDI 3 jumping mouse fix
		 new compose tables for use with NVDI 3
		 new order-sensitiveness flag within the tables 
		supported
		 Deadkey modifications
		 Autoload feature cancelled
v1.3:	Improvement done to Deadkey (suggested by Mr. Papyrus)
v1.2:	(March 1994) official new version with mouse speeder
v1.1:	Test version, never release. Should have become something 
	different
v1.0:	Bug free version from 1992
v0.9:	Occasional crashes under TOS 1.0 .. 1.4 when hitting the ALT 
	key. Cause: a badly written dispatcher in these TOS versions.
	Under KAOS: no problems.
v0.8:	bad pointers...
v0.7:	First official release


_____________________________________

1992-1996 by Pascal Fellerich

