
CKBD Deluxe v1.3, 4/1994
Composed Characters Keyboard Driver plus flexible mouse speeder


The ultimate extension for the keyboard driver in TOS computers by
Pascal Fellerich.

This program is Freeware.




Foreword
The problem is well 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 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 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 three: CKBD Deluxe! This utility program 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 
only has 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 distortion 	Mouse button swap feature
	User definable constant angle offset
	Screen resolution independence, automatic adaptation!
	Mouse resolution independence (!!!!)
	Comfortable speedup 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_12.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 aswell don't hesitate to ask me. 
Write to: Pascal Fellerich
45, rue des Gents
L-3482 Dudelange
Luxembourg

Bug reports, suggestions and new CKB tables are welcome as well!


Installation
This software consist 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 the other 
keyboard driver. The CPX module can only be used together with Atari's 
extensible control panel XCONTROL1. 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 and gives you back 
control over the mouse.


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 \"a is made up of the main character2 'a' and the overlay 
character3 '"'. 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 DEC4. On theses 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's nearly the same: hit 
ALTERNATE5 as if it were 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) and MultiChar mode. When in DEC mode a 
compose sequence is terminated after two characters. 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), [o], ['] 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.

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 every so often can be a pain if you type a lot 
of  composed characters. That's why there is the Deadkey-option. 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 output. If you hit the dead key twice or type a space you 
get the 'dead' character once, independent from the used table. Simply try 
it out and see what you get. If you are writing texts 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 ^U6  is not locked out.
Unfortunately a lot of user applications have problems with Extkey, 
sometimes because the shift state returned by GEM/AES is not correct!


ALT-<nnn>: DOS-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 inconvenients keyboard remapping is  still 
useful. The keyboard manager CPX module allows you to load either '*.KBD' 
or '*.CKB' files. The KDB-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. The CKB-files are more 
sophisticated files which contain a header, the three standard mapping 
tables, a compose table and some configuration data. Right now these 
tables must be created using an assembler because there is no editor yet. 
Source codes to show you how to do it have been included.
If a new table has been loaded you must specify to what it should apply. 
Why that? Easy example: imagine you got 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 youload 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.2. 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. As an alternative you may 
create a CKB file called 'AUTOLOAD.CKB' which allows you to do some basic 
set-up operations.  But without the matching tool this is only for 
professionals.


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 Atari7. 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 speedup is exactly the Sam 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 speedup 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 speedup 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 speedup 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 that you have 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. 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.

Also, some programs have problems with the composed characters... try!



Version history:

Compose-CPX:
v1.00:	(26.3.94) the great rewrite, improved user interface
v0.8:	Bugfree version
v0.7:	File selector gives wrong paths
v0.1:	Test version

Mouse-CPX:
v1.00:	(26.3.94) new CPX, first release

TSR:
v1.2:	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


NOTES:
1	If you don't have this control panel you can get it from your Atari 
dealer. It runs as ACC and PRG.
2	usually normal  letters from a..z 3	usually accents and other 
'decoration' letters
4	Digital Equipment Corporation, the company making VAX computers
5	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.
6	^U = close the top window in GEM applications.
7	Neither Mac nor PC have a similar thing...

