home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / f / fileact / !FileAct / Docs / Guide next >
Encoding:
Text File  |  1997-01-12  |  9.6 KB  |  262 lines
  1.  
  2. __________________
  3.  
  4. FileAct user guide
  5. __________________
  6.  
  7.  
  8. User, please note
  9. =================
  10.  
  11. FileAct is Freeware, i.e. it is free software.
  12.  
  13. Copyright notice
  14. ================
  15.  
  16. The copyright (c) of this program belongs to John Kortink. All rights are
  17. reserved.
  18.  
  19. You may not change this program (except for documented configuration
  20. changes). You may not use any part of this program in any other program or
  21. product without my written approval. You may spread this program freely, but
  22. only in complete and unchanged form, and only against bare distribution costs
  23. (if any). This program is provided 'as is'. No fitness of this program for
  24. any particular purpose is implied. Using this program is entirely at your own
  25. risk.
  26.  
  27.  
  28. //
  29. //
  30. // Introduction
  31. //
  32. //
  33.  
  34. FileAct can perform freely programmable operations on multiple files and/or
  35. directories, which takes the chore out of many common tasks. In addition,
  36. FileAct can be used to detect specific keypresses, and execute corresponding
  37. code (enabling keypress application launches, keypress execution of common
  38. OSCLI commands, etc..).
  39.  
  40. The operation to perform on the target objects (i.e. a set of files and/or
  41. directories) is defined by an OSCLI-type command line which is executed using
  42. Wimp_StartTask (which enables an external program to be invoked if needed).
  43. The command line definition may contain 'variables', which are replaced by
  44. (parts of) the object's full pathname before execution of the command line.
  45. For example, something like 'strip off the last two characters of the object
  46. pathname' may be specified by 'Rename %f %p.%L001-02' (for an explanation,
  47. see below). The full pathname of the target object is also available
  48. seperately as the value of a system variable.
  49.  
  50. An operation may be invoked by :
  51.  
  52. - Dragging a set of objects to a command line definition icon.
  53. - Dragging a set of objects to the icon bar icon.
  54. - Double-clicking on an object while holding down an Alt or Ctrl key.
  55.  
  56.  
  57. //
  58. //
  59. // Using FileAct
  60. //
  61. //
  62.  
  63. On FileAct's iconbar menu the usual 'Info' and 'Quit' icons can be found. In
  64. addition, 'Control' gives access to the 'FileAct control' window (click on
  65. 'Control' to make the window permanent) and 'Status' gives access to the
  66. 'Status' menu. The 'FileAct control' window and the 'Status' menu are
  67. described below.
  68.  
  69.  
  70. //
  71. //
  72. // The 'FileAct control' window
  73. //
  74. //
  75.  
  76. In this window, you will find two parts, called 'Actions' and 'Options'.
  77.  
  78. The 'Actions' part has two subparts : three columns of radio icons (headed by
  79. 'Bar', 'Alt' and 'Ctl'), and a set of writable icons (below the icon saying
  80. 'No action').
  81.  
  82. The command line definitions may be specified in the writable icons (there is
  83. room for seven different command line definitions). Dragging a set of objects
  84. to this icon will perform the operation directly. The 'Bar', 'Alt' and 'Ctl'
  85. columns select the operation to perform when a set of objects is dragged to
  86. FileAct's icon bar icon ('Bar' column), or when an object is double-clicked
  87. on while holding down an Alt key ('Alt' column), or when an object is
  88. double-clicked on while holding down a Ctrl key ('Ctl' column). When 'No
  89. action' is selected, no operation is performed.
  90.  
  91. The 'Options' part contains a flag called 'Recurse'. If 'Recurse' is checked,
  92. and a target object is a directory, all of the contents of that directory is
  93. also processed, recursively.
  94.  
  95. NOTE : Use the 'Recurse' option with caution. If you execute a potentially
  96. harmful operation, the damage you can do if recursion is enabled is, of
  97. course, much larger.
  98.  
  99.  
  100. //
  101. //
  102. // Command line definitions
  103. //
  104. //
  105.  
  106. On execution of a command line, the full pathname of the target object is
  107. always available in the system variable 'FileAct$ObName'. This may be useful
  108. in a number of situations.
  109.  
  110. Prior to execution, the command line definition is scanned for special
  111. sequences of the form '%<id>', which will be replaced by the corresponding
  112. part of the full pathname of the target object.
  113.  
  114. The <id> selects which part is substituted. In the examples following, the
  115. object's full pathname is 'adfs::mydisc.$.dir1.dir2.fred'.
  116.  
  117. ---------------------------------------------------------
  118.  <id>  Meaning              Result for example
  119. ---------------------------------------------------------
  120.  f     full pathname        adfs::mydisc.$.dir1.dir2.fred
  121.  p     (pre-leaf) pathname  adfs::mydisc.$.dir1.dir2
  122.  s     filing system name   adfs
  123.  m     media name           mydisc
  124.  d     directory path       $.dir1.dir2
  125.  l     leafname             fred
  126. ---------------------------------------------------------
  127.  
  128. In addition, by using upper case characters (i.e. F,P,S,M,D or L), the part
  129. may be cut down further by a MID$-like operation, as in BASIC.
  130.  
  131. The full <id> is then of the form '<upchar><arg1><arg2>', where <upchar> is
  132. the upper case selection character, and <arg1> and <arg2> are 3-character
  133. values representing the arguments for the MID$ function (i.e. their VAL is
  134. taken). When a value is negative or zero, the value LEN(r$)+value is taken,
  135. where r$ is the pathname part selected.
  136.  
  137. Some examples :
  138.  
  139. -------------------------------------------------------------------
  140.  <id>     Result for example            Function
  141. -------------------------------------------------------------------
  142.  F001-01  adfs::mydisc.$.dir1.dir2.fre  MID$(r$,1,LENr$-1)
  143.  D003005  dir1.                         MID$(r$,3,5)
  144.  L-02002  re                            MID$(r$,LENr$-2,2)
  145.  F002000  dfs::mydisc.$.dir1.dir2.fred  MID$(r$,2,LENr$)=MID$(r$,2)
  146. -------------------------------------------------------------------
  147.  
  148. The power of this scheme will be demonstrated by giving a few example command
  149. line definitions :
  150.  
  151. ---------------------------------------------------------------------
  152.  Definition             Result for example
  153. ---------------------------------------------------------------------
  154.  Rename %f %f!          Appends a '!' to the end of the object's name
  155.  Rename %f %p.%L001002  Truncates leafname to first two characters
  156.  Rename %f %p.%L001-01  Cuts off last character of leafname
  157.  Rename %f %p.%L002000  Cuts off first character of leafname
  158.  Rename %f %s::%m.$.%l  Move object to root of media it's on
  159.  Access %f WR           Set object's access to public write/read
  160.  SetType %f 123         Set object's filetype to &123
  161.  Namedisk :%m %l        Names the object's disc 'fred'
  162.  Type %f -TabExpand     *Types file, with TAB expansion
  163.  Dump %f 1000           *Dumps file, from PTR=&1000 onwards
  164. ---------------------------------------------------------------------
  165.  
  166.  
  167. //
  168. //
  169. // Key definitions
  170. //
  171. //
  172.  
  173. FileAct can also execute specific command lines on detecting specific
  174. keypresses.
  175.  
  176. To use this feature you have to create a key definition file, containing a
  177. list of keypresses to be detected, and the corresponding command line to
  178. execute.
  179.  
  180. The key definition file simply consists of a number of definition lines. A
  181. definition line starts with a key token, followed by a single space
  182. character, followed by the command line to execute. If the key token is not
  183. recognized, the definition line is ignored (you may use this to insert
  184. comments).
  185.  
  186. A valid key token consists of a single character specifying the 'special' key
  187. to be pressed, followed by an uppercase A..Z or 0..9, or 'TAB' (for the TAB
  188. key). The special key characters are :
  189.  
  190. 's' : SHIFT
  191. 'c' : CTRL
  192. 'a' : ALT
  193. 'n' : none, i.e. the key must be pressed on its own
  194.  
  195. E.g. 'cH' means 'CTRL and H pressed simultaneously', 'nA' means 'A pressed on
  196. its own', 'sTAB' means 'SHIFT and TAB pressed simultaneously', etc..
  197.  
  198. An example key definition file would be :
  199.  
  200. cF Run IDEFS::4.$.!FileAct
  201. n0 Filer_OpenDir ADFS::0.$
  202.  
  203. The pathname of the key definition file is '<FileAct$KeyActDir>.KeyDefs',
  204. i.e. the system variable 'FileAct$KeyActDir' must be set to the directory
  205. path, without a trailing '.' (FileAct's !Run file is a good place for this),
  206. and your key definition file must be called 'KeyDefs' and placed in that
  207. directory. The !Run file that comes with your !FileAct copy may contain
  208. somebody elses setting for 'FileAct$KeyActDir', so you probably want to
  209. change this to your own. If the 'FileAct$KeyActDir' system variable is
  210. undefined on startup, or if the directory that it points to does not exist,
  211. or if the definition file 'KeyDefs' cannot be found in that directory,
  212. FileAct's keypress functions will be silently disabled.
  213.  
  214. There is an example key definition directory called 'KeyActDir' inside the
  215. !FileAct.Examples directory.
  216.  
  217. NOTE : FileAct will only try to detect keypresses if the caret is 'disowned'
  218. (i.e. if it is not used by any application), because otherwise all keypresses
  219. that have a 'FileAct definition' would cause two different things to happen
  220. at the same time. E.g. pressing '0' in a writable icon would not only insert
  221. a '0' but also cause FileAct's 'n0' definition to be executed each time.
  222.  
  223. RELATED NOTE : Pressing the right-hand ALT key and the right-hand CTRL key
  224. together is pre-programmed to disown the caret, enabling FileAct to react to
  225. keypresses immediately afterwards.
  226.  
  227.  
  228. //
  229. //
  230. // The 'Status' menu
  231. //
  232. //
  233.  
  234. In this menu you can manipulate FileAct's 'status', which consists of a
  235. number of configuration settings.
  236.  
  237. - 'Save' will save the current status.
  238. - 'Load' will load the saved status.
  239. - 'Default' will load the default status.
  240. - 'Kill' will remove the saved status.
  241.  
  242. When FileAct starts up it loads the saved status, or the default status if
  243. there is no saved status.
  244.  
  245. The status consists of the 'Actions' and 'Options' settings.
  246.  
  247.  
  248. //
  249. //
  250. // Epilogue
  251. //
  252. //
  253.  
  254. Updates of FileAct will be made available by (in order of preference) :
  255.  
  256. - World Wide Web, on www.inter.nl.net/users/J.Kortink.
  257. - Electronic mail, to kortink@inter.nl.net.
  258. - Snail mail, to : John Kortink, Nutterbrink 31, 7544 WJ Enschede, The
  259.   Netherlands. Include a DD or HD floppy, return envelope and one
  260.   International Reply Coupon (IRC).
  261.  
  262.