home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d923 / rawinsert.lha / RawInsert / RawInsert.doc < prev    next >
Text File  |  1993-10-07  |  5KB  |  122 lines
  1.  
  2.  ------------------------------------------------------------------------
  3.  RawInsert 1.0 (25.7.93) (w) Franz.Schwarz@mil.ka.sub.org - Public Domain
  4.  ------------------------------------------------------------------------
  5.  
  6.   
  7. RawInsert is a shell utility for Amiga-OS2.04 or above.  It provides you
  8. with the ability to insert text or any other input events like mouse
  9. movements, disc changes, mouse key presses and so on into the input event
  10. stream.  This prooves especially useful in conjunction with Stefan Becker's
  11. Toolmanager in order to control applications' graphical user interfaces
  12. from ARexx scripts or shell batch files.
  13.  
  14.  
  15. The command line argument stencil is
  16.  
  17.    "DELAY=MILLISECS=MS/K/N,DESCR=D/S,FROM=FILE/K,TEXT/F"
  18.  
  19.  
  20.  
  21. The following are the arguments' meanings:
  22.  
  23.  
  24. DELAY=MILLISECS=MS/K/N - Here you can specify the amount of time in
  25. milliseconds to wait between inserting two InputEvents into the input
  26. event stream.  The numbers shall be within the range 0..999.
  27.  
  28. DESCR=D/S - switch that makes RawInsert parse the source data not
  29. as plain ASCII text (default), but as input event descirption data.
  30. These data consist of ordinary plain ASCII text that may furthermore
  31. contain the following ESCape codes:
  32.           \n   -  linefeed (inserted  as carriage return)
  33.           \r   -  carriage return
  34.           \0   -  nul
  35.           \t   -  horizontal tab 
  36.           \f   -  formfeed
  37.           \xff -  ASCII code 0xff (f represents an arbitrary hex nibble)
  38.           \'   -  apostroph 
  39.           \"   -  quotation mark
  40.           \<   -  left angled bracket '<'
  41.           \\   -  backslash '\'
  42. Moreover, separate input events may be specified according to Commodities'
  43. ParseIX() syntax within angled brackets.  The line 
  44. '<lcommand a><tab>Hello!<alt -capslock numericpad enter>\x06\t\5*x\<12\n'', 
  45. for example, represents valid input description data.
  46.  
  47. FROM=FILE/K - this argument specifies the file the input data shall be read
  48. from. This argument and TEXT/F are mutually exclusive.
  49.  
  50. TEXT/F - the source data as command line argument; mutually exclusive with
  51.   FROM=FILE/K.
  52.  
  53. If none of the arguments FROM=FILE/K and TEXT/F is passed, stdin is used as
  54. data source.
  55.  
  56. Linefeeds (0x0a) are automatically converted into carriage returns.  In
  57. addition to this, carriage returns are inserted as key presses of the
  58. plain, simple carriage return rawkey unless the system default keymap
  59. doesn't map that rawkey to carriage return.
  60.  
  61.  
  62. In case of finding a character or an input event description surrounded by
  63. angled brackets for which no matching input event can be generated,
  64. RawInsert fails immediately with return code Dos.fail (20) if you have
  65. specied the DESCR=D/S switch.  No input events at all are inserted in this
  66. case.  However, if you haven't specified the DESCR=D/S argument, RawInsert
  67. just skips that cruical source date and continues with the next one.  You
  68. can still detect that some input events couldn't be created by checking
  69. the return code for Dos.warn.
  70.  
  71.  
  72. Failure during reading source data causes RawInsert to terminate execution
  73. immediately with Dos.fail (20) return code.  No input events have been
  74. inserted in that case.
  75.  
  76.  
  77. Concerning the source data, note that all nul characters (0x00) are
  78. excluded from processing, i.e.  you can only insert nul into the input
  79. event stream by specifying the DESCR=D/S argument and paraphrasing nul with
  80. an ESCape sequence or a matching input event description in angled
  81. brackets.
  82.  
  83.  
  84. Since RawInsert is pure and brief, yet powerful, it's highly
  85. recommened that you make RawInsert resident.
  86.  
  87.  
  88. Implementation details:  RawInsert imports the CxLib (corresponds to
  89. Commodore's cx.lib) and BlackMagic (universal module - Chiefly, RawInsert
  90. uses its support functions for dynamic strings) Oberon modules which are
  91. both written by RawInsert's author (No, the author is not Joseph Stalin,
  92. though he enjoys using third person singular for talking about himself;-)).
  93.  
  94.  
  95.  
  96. RawInsert is Public Domain, i.e.  you may spread, use, abuse and 'do it'
  97. with RawInsert just as you want.  There is no copyright on RawInsert - the
  98. author disclaims all titles and responsibilities that stem from writing
  99. this piece of software.  Of course, this means also 'You use this software
  100. at your very own risk' - the author cannot be held liable for any harm that
  101. may arise directly or indirectly from using (or watching;-)) this software
  102. in any way whatsoever.
  103.  
  104.  
  105.  
  106.               RawInsert written and not copyrighted, 1993 by 
  107.        Franz Schwarz, Mühlenstraße 2, D-78591 Durchhausen, Germany.
  108.           uucp: Franz.Schwarz@mil.ka.sub.org; Fido: 2:241/7506.18
  109.  
  110.  
  111. Suggestions, criticism, flames, money, gold, disks, beer, chocolate,
  112. nice postcards, e-mails, etc.  are welcomed and appreciated!;-)
  113.  
  114.  
  115.  
  116.     Bye
  117.       Franz 'Blacky' Schwarz
  118.  
  119.  
  120.                -Girlfriend Is Better - Talking Heads-
  121.  
  122.