home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 2 / CDPD_II_2352.bin / mousetrap / mt.doc < prev    next >
Text File  |  1992-11-10  |  13KB  |  277 lines
  1. *****************************************************************************
  2.  
  3. MOUSETRAP FOR CDTV - DOCUMENTATION
  4.  
  5. Written for the Buxton Group (UK Amiga Multimedia Research Group),
  6. © 1992 Dave Parkinson.
  7.  
  8. This document by DaveP, 3-Apr-92
  9.  
  10. Dave Parkinson, DP Consultants, 20 Mostyn Gardens, London NW10 5QX.
  11. Tel: +81 960 2623, Fax: +81 960 9089, Nets: ariadne@CIX.compulink.co.uk
  12.  
  13. *****************************************************************************
  14.  
  15. Terms and conditions
  16. ~~~~~~~~~~~~~~~~~~~~
  17. This software documentation etc is copyright (c) Dave Parkinson 1992, but may
  18. be freely distributed under the following conditions:
  19.  
  20.   1. You are welcome to spread this stuff around as you like on BBSs etc - 
  21.      but please only distribute the archive in full, including the source-
  22.      code and these notes.
  23.  
  24.   2. License is granted to include the MouseTrap program in commercial
  25.      CDTV titles, or to incorporate the code in your own programs.  If you do
  26.      this, please consider making a donation to the Terrence Higgins Trust,
  27.      52-54 Gray's Inn Road, London WC1X 8BR (UK AIDS/HIV charity) or some
  28.      equally deserving cause.
  29.  
  30.   3. No warrenty of any kind is given as regards the suitability of this
  31.      software for any purpose whatsoever!  The source-code is included in
  32.      the archive so you can check it if you like; don't blame me if it
  33.      screws up your gold disk.
  34.  
  35. What's it for?
  36. ~~~~~~~~~~~~~~
  37. The MouseTrap program for CDTV serves three functions:
  38.  
  39.   1. To make it much easier to handle the recommended user-interface,
  40.      by making the remote controller arrow-keys and A and B buttons
  41.      return key closures such as 'u', 'd', 'l', 'r', 'a' and 'b' rather
  42.      than mouse move and click events.  The A button also by default
  43.      acts as a shift key, so you can tell if A is being held down while
  44.      arrow-keys are pressed.  An option exists to trap IR controller events,
  45.      but leave alone trackball or IR-mouse input - this allows an application
  46.      to adapt transparently to different input devices.
  47.  
  48.   2. To allow a remote mouse and keyboard to be used on 'slave' CDTV via a
  49.      serial-port link to a 'master' Amiga.  This can be very useful in a
  50.      development environment - see notes on the "Two Bits of Wire"
  51.      development system under 'Master and Slave' below.
  52.  
  53.   3. To provide remote diagnostics of input events on CDTV on a 'master'
  54.      Amiga.  This can be very useful in tracking down certain bugs - eg
  55.      are you missing input events, or is the Remote Controller failing to
  56.      generate them?
  57.  
  58. Limitations
  59. ~~~~~~~~~~~
  60. The current version of MouseTrap is limited as follows:
  61.  
  62.   1. It only generates key-down events, not key-ups - ie it emulates a weird
  63.      sort of keyboard in which the keys go down as often as you like, but
  64.      never come back up!  This doesn't seem to be a problem in practice (but
  65.      let me know if I'm wrong about this).
  66.  
  67. Use from CLI
  68. ~~~~~~~~~~~~
  69. MouseTrap will normally be run from the CLI, eg in the startup-sequence of a
  70. title.  When run from CLI, MouseTrap will start a new process then return,
  71. allowing the CLI it was run from to close.  There is therefore never any need
  72. to 'run MouseTrap'.
  73.  
  74. Command-line syntax is as follows:
  75.  
  76. Mousetrap keys/K/N buttons/K/N grain/K/N delay/K/N speed/K/N device/K
  77.    unit/K/N\n baud/K/N diag/K/N nohandshake/S noshift/S notrap/S noball/S
  78.    master/S slave/S off/S
  79.  
  80. Numeric parameters can be given either in decimal, or with a leading 0x in
  81. hex.
  82.  
  83. Meanings of the various fields are as follows:
  84.  
  85. keys:          Raw key-codes for up, down, left, right.  The default is 
  86.                0x16222813 meaning 'u', 'd', 'l' and 'r'.  Raw key-codes (in
  87.                hex) and the corresponding UK characters are as follows:
  88.  
  89.      00 '      10 q      20 a      30        40 space  50 F1     60 l shift
  90.      01 1      11 w      21 s      31 z      41 bs     51 F2     61 r shift
  91.      02 2      12 e      22 d      32 x      42 tab    52 F3     62 caps lock
  92.      03 3      13 r      23 f      33 c      43 enter  53 F4     63 ctrl
  93.      04 4      14 t      24 g      34 v      44 return 54 F5     64 l alt
  94.      05 5      15 y      25 h      35 b      45 esc    55 F6     65 r alt
  95.      06 6      16 u      26 j      36 n      46 del    56 F7     66 l amiga
  96.      07 7      17 i      27 k      37 m      47        57 F8     67 r amiga
  97.      08 8      18 o      28 l      38 ,      48        58 F9     68
  98.      09 9      19 p      29 ;      39 .      49        59 F10    69
  99.      0A 0      1A [      2A #      3A /      4A kpad - 5A kpad ( 6A
  100.      0B -      1B ]      2B        3B        4B        5B kpad ) 6B
  101.      0C =      1C        2C        3C kpad . 4C up     5C kpad / 6C
  102.      0D \      1D kpad 1 2D kpad 4 3D kpad 7 4D down   5D kpad * 6D
  103.      0E        1E kpad 2 2E kpad 5 3E kpad 8 4E right  5E kpad + 6E
  104.      0F kpad 0 1F kpad 3 2F kpad 6 3F kpad 9 4F left   5F help   6F
  105.  
  106.                For example, to alias the arrow-keys to cursor-keys use
  107.                'MouseTrap keys 0x4C4D4F4E'.
  108.  
  109. buttons:       Raw key-codes for middle, A, B.  The default is 0x00332035
  110.                meaning 'c', 'a', and 'b'.  (Okay, C= producing an
  111.                IR-controller with a middle mouse-button is pretty unlikely
  112.                - but I'm ready for them if they do!)  For example, to alias
  113.                the A and B buttons to return 'y' and 'n', use
  114.                'MouseTrap buttons 0x1536'
  115.  
  116. grain:         Time units to delay before generating first key closure.  The
  117.                default is 0.  Larger values give a slower response.
  118.  
  119. delay:         Time units to delay before starting key-repeat.  The default
  120.                is 8.  To disable key repeat, use 'MouseTrap delay 0'
  121.  
  122. speed:         Time units to delay between key-repeats.  Default 2.  For
  123.                maximum repeat-speed, use 'MouseTrap speed 1'.
  124.  
  125. device:        Device to use for master/slave serial comms, and for remote
  126.                diagnostics.  The default is 'serial'.  To remote control a
  127.                CDTV attached an Amiox board serial port 2, you would use
  128.                'Mousetrap master device aserial unit 2'.
  129.  
  130. unit:          Unit number to use for master/slave serial comms, and for
  131.                remote diagnostics.  The default is 0.  To remote control a
  132.                a CDTV attached to a CBM multi-serial board port 2, you would
  133.                use 'Mousetrap master unit 2'.
  134.  
  135. baud:          Baud-rate to use for master/slave serial comms, and for remote
  136.                diagnostics.  The default is 9600.  To push it up to 19200 you
  137.                would use 'Mousetrap master baud 19200'.
  138.  
  139. diag:          Followed by a numeric parameter 0 1 or 2 as follows:
  140.  
  141.                         0       -       no diagnostics
  142.                         1       -       normal diagnostics, excluding timer
  143.                         2       -       full diagnostics, including timer
  144.  
  145.                Note that with full diagnostics, baud rate needs to be set to
  146.                at least 9600.
  147.  
  148. nohandshake:   Disable 7-wire handshake for master/slave serial comms, and
  149.                for remote diagnostics.  Normally, MouseTrap expects to use
  150.                a 7-wire null-modem cable between machines (see below for
  151.                wiring); if you are only using a 3-wire cable, use something
  152.                like 'Mousetrap master nohandshake'.
  153.  
  154. noshift:       Don't treat the A button as a shift-key.  The default is to
  155.                do so, so if A is held down you will get 'U' 'D' 'L' and 'R'
  156.                back from the arrow keys rather than 'u' 'd' 'l' and 'r'.
  157.  
  158. notrap:        Don't trap mouse-events at all.  Eg, if you just want remote
  159.                diagnostics, use 'MouseTrap diag 1 notrap'.
  160.  
  161. noball:        Trap mouse-events from the conventional IR controller, but
  162.                leave alone events from trackball or infra-red mouse.  This
  163.                allows an application to adapt to input device transparently:
  164.                if you get key closures u, d, l, and r, then use a bouncing
  165.                highlight; if you start getting mouse-moves, then put up a
  166.                cross-hair.
  167.  
  168. master:        Remote control a CDTV - see below.  Is taken to imply
  169.                'notrap'.
  170.  
  171. slave:         Be remote controlled by an Amiga - see below.
  172.  
  173. off:           Switch off a previously installed MouseTrap.
  174.  
  175.  
  176. Use from Workbench
  177. ~~~~~~~~~~~~~~~~~~
  178. MouseTrap can also be run from Workbench, either from a Tool icon or from a
  179. Project icon with default tool set to MouseTrap - examples of both are
  180. provided in the archive.  When running from Workbench, the command line
  181. options above are given in ToolTypes.  For example to get the same effect as
  182.  
  183.         MouseTrap keys 0x4C4D4F4E delay 10 diag 1 noball
  184.  
  185. you could set up an Icon with tooltypes
  186.  
  187.         KEYS=0x4C4D4F4E
  188.         DELAY=10
  189.         DIAG=1
  190.         NOBALL
  191.  
  192. Exiting MouseTrap
  193. ~~~~~~~~~~~~~~~~~
  194. MouseTrap can be switched off by any of the following methods:
  195.  
  196.   1. Use 'MouseTrap off' from the CLI.
  197.  
  198.   2. Use an icon with tooltype OFF.
  199.  
  200.   3. Via a hot-key - hold down left-Amiga and press Escape.
  201.  
  202. When running Master/Slave, using left-Amiga-Escape on the master will shut
  203. down the master only and leave the slave running; using left-shift-left-
  204. Amiga-Escape will close down both.
  205.  
  206. Trying to start MouseTrap when it is already active will close-down the old
  207. version before running the new one.
  208.  
  209. The diagnostic console (see below) has a close box - but note that this is
  210. used only to get rid of the console, it won't switch off MouseTrap.
  211.  
  212. Master and Slave
  213. ~~~~~~~~~~~~~~~~
  214. MouseTrap can be used to allow a 'slave' CDTV to be remote-controlled using a
  215. 'master' Amiga's mouse and keyboard.  To do this, the two machines need to
  216. be connected using a 7-wire null-modem cable between serial ports, connected
  217. as follows:
  218.  
  219.           One end                 Other end
  220.  
  221.          pin 2 (TXD) --------------  3 (RXD)
  222.              3 (RXD) --------------  2 (TXD)
  223.              4 (RTS) --------------  5 (CTS)
  224.              5 (CTS) --------------  4 (RTS)
  225.              6 (DSR) -------------- 20 (DTR)
  226.              7 (GND) --------------  7 (GND)
  227.             20 (DTR) --------------  6 (DSR)
  228.  
  229. Alternatively, if you are using the NOHANDSHAKE option, only the three wires
  230. connecting pins 2, 3 and 7 are needed - but you stand a greater risk of
  231. losing characters.
  232.  
  233. The CDTV should then be set up to run 'MouseTrap slave' (with other options
  234. 'notrap', 'diag', etc as needed) which the Amiga runs 'MouseTrap master'.
  235. The Amiga mouse and keyboard can then be toggled between local use and
  236. remote-control of the CDTV by the special key combination CTRL-LEFT-AMIGA.
  237.  
  238. Note the following additional points about Master and Slave:
  239.  
  240.   1. If you have specified the 'diag' option on the slave CDTV, then as soon
  241.      as the Master Amiga starts to notice diagnostic messages coming back
  242.      it will open a 'Diagnostic Console' to display them.  This can be
  243.      got rid of using its close box.
  244.   
  245.   2. The slave system can tell remote 'master' mouse events from its IR
  246.      controller.  So if you're not using 'notrap' on the slave system,
  247.      IR mouse events will be aliased to key closures, but the 'master'
  248.      mouse will function normally.
  249.  
  250.   3. 'Master' is taken to imply 'notrap' - it's assumed you don't want
  251.      to trap the mouse on your Amiga!
  252.  
  253.   4. The MouseTrap master/slave option is ideally used along with ParNet
  254.      in the 'Two Bits of Wire' CDTV development system, in which Amiga and
  255.      CDTV are linked by both a serial cable as above and a ParNet cable
  256.      between parallel ports, used to download code from Amiga to CDTV for
  257.      remote execution.  If you are willing to cut an early test-disk with
  258.      some test data (only) on it, this means that you can test your code 'for
  259.      real' on the CDTV as you develop.
  260.  
  261. Remote diagnostics
  262. ~~~~~~~~~~~~~~~~~~
  263. The diag keyword to MouseTrap can be used to give input event diagnostics to
  264. a remote terminal attached via a null-modem cable.  This can either be a
  265. standard package such as NComm running with appropriate baud-rate and
  266. handshake options, or it can be another copy of MouseTrap running in 'master'
  267. mode.  The format of a typical diagnostic message is as follows:
  268.  
  269.         RawMouse: Cl=2 Sb=0 Cd=$FF Ql=$8000 X=0 Y=8 Tm=447496928.860541
  270.  
  271. where the various symbols stand for Class, Sub-class, Code, Qualifier, X, Y,
  272. and Time-stamp.  You can chose whether to ignore timer events in diagnostics
  273. (diag 1), or whether to give diagnostics for everything including timer (diag
  274. 2).
  275.  
  276. TTFN... DaveP.
  277.