Crawly Crypt Collection 1/crawlyvol1.bin/sound/digistuf/click/click.doc

Text File | 1992-08-20 | 15KB | 400 lines

                            Digital Keyclick

                        Copyright (C) 1991, 1992
                            By David Baggett


--------------------------------------------------------------------------------
                             User Contract

This program is SHAREWARE.  You may distribute it at will, provided you

        1) do not charge any money for it,
        2) distribute it WITH the documentation, and
        3) do not change the program or documentation in ANY WAY.

The idea here is that you get to TRY before you BUY.  So try, then BUY.

--------------------------------------------------------------------------------


Introduction
------------

   Are you completely sick of the cheesy ST keyclick?  Do you envy those
Mac users who can make their keyboards sound like 1929 manual typewriters?
Well, wait no longer!  This program will let you install a different
digital sound for every key on the keyboard!  Are we having fun yet?!

   Digital Keyclick now supports the STe's (and TT's, and Falcon's) DMA
sound capabilities.  So you can even have stereo keyclicks -- how
gratuitous can you get?


General Usage
-------------

   Put click.prg in your AUTO folder.  Then create a file called click.inf
with a standard ASCII text editor and put it in the root directory of
your boot partition (e.g., if your AUTO folder is C:\AUTO\, put click.inf
in C:\).

In click.inf you specify which sounds will be mapped to which keys.  Each
entry in click.inf consists of a sound file name, a playback speed
(in  Hertz), and a list of the keys that will produce that sound.  Here's
an example click.inf:

{stedma}
[d:\usr\sounds\vowel.snd]       {stereo}    8000    a e i o u
[d:\usr\sounds\cons.snd]    {stereo}    8000    b c d f g h j k l m n
                            p q r s t v w x y z
[d:\usr\sounds\return.snd]              11000   return

Filenames MUST be enclosed in square brackets.  Some white space (spaces,
tabs, newlines) must separate each field, but the amount of white space
is unimportant. Key names (the letters "a e i o ..." and "b c d ..." above)
must be separated by some white space as well.  In other words,

[d:\usr\sounds\vowel.snd]       8000    aeiou

is incorrect.

Any printable character is a valid key name.  For example,

[d:\usr\sounds\special.snd]     8000    ! @ # $ % ^ & * ( )
[d:\usr\sounds\boing.snd]       11000   ~

is perfectly acceptable.

   If a file name appears twice, the file will be loaded and stored in
memory twice, so always list each file only once.  Instead of writing

[d:\usr\sounds\my.snd]          8000    a e i o u
[d:\usr\sounds\my.snd]          8000    y
[d:\usr\sounds\my.snd]          8000    return

write

[d:\usr\sounds\my.snd]          8000    a e i o u
                                        y
                                        return
or

[d:\usr\sounds\my.snd]          8000    a e i o u y return

Remember that once you've installed Digital Keyclick, the sound samples
remain resident in memory until you reboot.


Other Key Names
---------------

   You may have noticed "return" as a key name in the example above.
Key names are provided for other unprintable characters as well:

        backspace       clrhome         delete          esc
        help            insert          return          space (or spacebar)
        tab             undo

are all valid key names and can be used just like printable characters.


Wildcards
---------

   Several wildcards are provided for mapping large groups of keys.  These
can also be used like printable characters.  They include

        all             arrows          funkeys         letters
        lower           numbers         upper

where "arrows" refers to the four cursor keys, "funkeys" refers to function
keys F1 through F10, "letters" refers to upper and lower case letters A
through Z, "lower" refers to lower case letters a through z, "numbers" refers
to the numbers 0 through 9 (on the keypad as well), and "upper" refers  to
upper case letters A through Z.  "all" maps all keys on the keyboard.

   It is important to realize that keys are mapped in the order the names
appear, so you generally want to put wildcards first.  For example,

[d:\usr\sounds\nifty.snd]       11000   numbers
[d:\usr\sounds\boring.snd]      11000   all

will cause all keys, including the number keys, to get mapped to the
second sound, since the "all" wildcard will override the effect of the
"numbers" entry.


ASCII and Scan Codes
--------------------

   Each key on the keyboard generates an ASCII code and a scan code
when pressed.  For example, the C key generates the ASCII value 67 and
a scan code of 46.  ASCII values are the same on all machines (so the
C key generates an ASCII code of 67 on a Mac, Amiga, Sun 3/60, etc.) but
scan codes are specific to the Atari ST keyboard.  Special keys, for
example function keys, generate an ASCII code of zero. This means that you
can only refer to these keys in terms of scan codes.

   Digital Keyclick lets you name a key on the keyboard by either ASCII
or scan code.  To name a key by ASCII code, use the decimal ASCII value
follwed by an "A" (with no white space intervening):

[d:\usr\sounds\controlc.snd]    11000   3A

refers to the Control-C combination, which has ASCII code 3.

   Naming keys by scan code is similar -- just use "S" instead of "A":

[d:\usr\sounds\alt_q.snd]       11000   16Q

refers to the Alt-Q combination, which has ASCII code zero, scan code 16.

   Note that only special keys that generate ASCII codes of 0 can be
named this way.  If a key generates a nonzero ASCII value, that value will
be used instead of the scan code.  So it's not possible to distinguish,
for example, between the Return key and the Enter key (on the keypad), since
both of these keys generate an ASCII code of 13.

   The wildcard "scan" refers to all keys that generate an ASCII code of
zero.  Similarly, the wildcard "ascii" refers to all keys that generate
a nonzero ASCII code.

   A table of ASCII and scan codes is included at the end of this
document.


Making Keys Silent
------------------

   You may want to "unmap" a key previously named with a wildcard to make
it silent.  To do this, use two square brackets with no white space between
them as the filename, and omit the playback speed.  Writing

[d:\usr\sounds\loud.snd]        11000           all
[]                                              7A esc

will prevent Digitial Keyclick from playing a sound when either Control-G
or Esc are pressed.


Enabling and Disabling Digital Keyclick
---------------------------------------

   When click.prg is invoked with no parameters, it reads the click.inf
file and loads all the sounds.  This typically occurs at bootup in the
AUTO folder.  However, you can run click.prg from a command shell (or
from the desktop if you rename a copy click.ttp) as well.  To turn
Digital Keyclick off, type

        click off

from a command shell, or run click.ttp from the desktop with parameter
"off".

   Similary, type

        click on

to turn Digital Keyclick back on.


Specifying an Alternate D/A Device
----------------------------------

   Digital Keyclick can be configured to play its samples through
other D/A devices.  Currently, the Hippo/Navarone and ST Replay digitizers
are supported.  The STe's (and TT's, and Falcon's) 8-bit D/A is also
supported, with either the DMA or the MFP for timing.  (If you use the
DMA for timing, you can only play at certain sample rates, so sounds may
sound too fast or slow.  On the other hand, if you use the MFP for timing
you can play stereo samples at any rate but the sound quality isn't quite
as good.)

Other digitizers will be supported if people send me info on them.

   To use an alternate D/A device, put one of the following keywords
in curly brackets somewhere in your click.inf file:

    hippo    replay    dma    mfp

For example, a click.inf containing

{dma}
[d:\usr\sounds\type2.snd]    8000    all

will cause Digital Keyclick to play typewriter sounds through the
DMA sound device, using the DMA for timing.  (This won't work on machines
that don't have DMA sound capabilities, of course.)

   Note that the normal ST keyclick will still be masked, even if
you don't use the speaker as the D/A device.


Different Kinds of Samples
--------------------------

   Unless you tell it otherwise, Digital Keyclick assumes your sounds
are unsigned 8-bit mono samples.  You can use stereo and/or unsigned
samples with Digital Keyclick too, by putting one of the following
keywords in brackets after the filename:

    stereo    signed

For example, a click.inf containing

[d:\usr\sounds\type2.snd]    {stereo}    8000    all

will make Digital Keyclick interpret type2.snd as stero data instead
of mono.  (Stereo sounds will play on mono devices; the channels are
just mixed together.)

Similarly the line

[d:\usr\sounds\type2.snd]    {signed}    8000    all

tells Digital Keyclick that type2.snd has signed 8-bit samples instead
of unsigned samples.  Some digitizing software saves sounds in this
format instead of the usual unsigned format.  If you're not sure what
you've got, a general rule of thumb is that if a sound sounds very noisy
you should try it as signed.


Technical Information
---------------------

   Digital Keyclick steals the Bios trap #13 vector and looks at
the return values from all Bconin(2) calls.  This means that it will
work with all applications that call Bconin(2) (at some level) to
get keypresses.  Some applications remap certain keys; this will
obviously change the way keys are mapped to sounds but will otherwise
not cause Digital Keyclick any problems.

   The program uses about 28K when resident, not including the space
taken up by the sample data.  (Down from 38K in version 1.0)

   In earlier versions, Digital Keyclick used the high bit of the CONTERM
global to enable and disable itself.  Unfortunately, this conflicted with
at least one person's hard disk driver.  (Don't ask me why.)

   This version uses the high bit of memory location 768, chosen arbitrarily
from the list of user interrupt vectors.  If for some reason Digital Keyclick
will not run with a particular application resident, try moving the keyclick
flag somewhere else in memory.  To do this, put the desired flag address in
angle brackets somewhere in your click.inf file; e.g.,

<1020>
[d:\usr\sounds\type1.snd]    8000    all

will cause Digital Keyclick to use 1020 (decimal) as the memory location
for the click on/off flag.  To then enable and disable Digital Keyclick,
pass the address as a third parameter to the click [on | off] call; e.g.,

    click off 1020

will mask bit 7 of the byte at location 1020 decimal, thereby disabling
Digital Keyclick.

Memory locations 512 through 1020 are good candidates for flag locations
since they are currently not claimed by Atari.

Whenever Digital Keyclick is on it masks the normal system keyclick by
clearing the appropriate bit in CONTERM.

   Digital Keyclick is well-behaved and should work with all versions
of TOS.  It does not use any undocumented techniques or memory locations,
except of course for the keyclick flag itself, which can be moved elsewhere
in memory if necessary.


Caveats
-------

   Some programs do different things to read special keys.  The wildcards
"arrows" and "funkeys" may not work with some applications for this reason.
(One such program is GULAM.)

   The program will not know it has already been installed if you
run it twice (or ten times) in a row.  Doing so will use up more and
more memory.

   Using playback speeds faster than about 16 kHz with MFP timing may
cause problems.  At very fast rates, the machine can do very little but
send samples out the speaker, so keyboard interrupts may get lost.  The net
result is that you'll press a key and the "release" event will get lost; i.e.,
you'll get infinite key repeat.  I find that mashing down lots of keys
fixes this, but it's really easier to use 11 kHz and 8 kHz samples...


Do You Like This Program?
-------------------------

   If you do, please become a registered owner.  Send a MERE $15 to me and
you'll not only be encouraging me to write more nifty utilities, but
also get a FREE disk with TONS OF SAMPLES for use with Digital Keyclick,
PLUS other neat public domain software.  Remember to include your
address so I know where to mail the disk.  Mail to:

        Dave Baggett
        5640 Vantage Point Road
        Columbia, MD 21044  USA

Thanks!


Table of ASCII and Scan Codes
-----------------------------

   Here are ASCII and scan codes for various keys, in decimal:


ASCII  Key         ASCII  Key         ASCII  Key         ASCII  Key

  1    Control-A     2    Control-B     3    Control-C     4    Control-D
  5    Control-E     6    Control-F     7    Control-G     8    Control-H
  9    Control-I     10   Control-J     11   Control-K     12   Control-L
  13   Control-M     14   Control-N     15   Control-O     16   Control-P
  17   Control-Q     18   Control-R     19   Control-S     20   Control-T
  21   Control-U     22   Control-V     23   Control-W     24   Control-X
  25   Control-Y     26   Control-Z     27   Control-[     28   Control-\
  29   Control-]     30   Control-6     31   Control--     32   Space Bar


SCAN   Key         SCAN   Key         SCAN   Key         SCAN   Key

 16   Alt-Q         17   Alt-W         18   Alt-E         19   Alt-R
 20   Alt-T         21   Alt-Y         22   Alt-U         23   Alt-I
 24   Alt-O         25   Alt-P

 30   Alt-A         31   Alt-S         32   Alt-D         33   Alt-F
 34   Alt-G         35   Alt-H         36   Alt-J         37   Alt-K
 38   Alt-L

 44   Alt-Z         45   Alt-X         46   Alt-C         47   Alt-V
 48   Alt-B         49   Alt-N         50   Alt-M

 59   F1            60   F2            61   F3            62   F4
 63   F5            64   F6            65   F7            66   F8
 67   F9            68   F10

 71   Home          72   Up Arrow      75   Left Arrow    77   Right Arrow
 80   Down Arrow    82   Insert        83   Delete

114   Control-Help  115   Control- <-  116   Control- -> 119   Control-Home

120   Alt-1         121   Alt-2        122   Alt-3       123   Alt-4
124   Alt-5         125   Alt-6        126   Alt-7       127   Alt-8
128   Alt-9         129   Alt-0        130   Alt--       131   Alt-=