home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / fileutils / fileact / !FileAct / Docs / Guide next >
Encoding:
Text File  |  1993-05-29  |  14.5 KB  |  378 lines
  1. >Guide
  2. _______________________________________________________________________________
  3.  
  4. FileAct 2.12                                        --------------------------
  5.                                                      This program is FREEWARE
  6. Version date : 29 May 1993                          --------------------------
  7.  
  8. ----------------
  9. - Introduction -
  10. ----------------
  11.  
  12. FileAct performs actions on (groups of) files and directories, optionally
  13. recursing through subdirectories. In addition, it can execute specific command
  14. lines on detection of specific key presses, enabling key-press application
  15. launches, short-hand OSCLI commands, etc..
  16.  
  17. You may define command lines to invoke on objects, or a predefined 'edit'
  18. action that calls a text editor or the Basic editor for appropiate files.
  19.  
  20. Powerful and flexible 'group' actions on objects may be performed by using
  21. command lines with variables in them that will be filled in with (parts of) the
  22. object's full pathname on execution.
  23.  
  24. Wimp_StartTask is used for all invocations, so it is possible to execute entire
  25. programs per object. The full pathname of the object is always available in a
  26. system variable.
  27.  
  28.  
  29. -------------------------
  30. - Using the application -
  31. -------------------------
  32.  
  33. To start up FileAct, double-click on the '!FileAct' icon.
  34.  
  35. It will install itself on the icon bar, and clicking MENU on FileAct's icon
  36. pops up the main menu, giving the usual 'Info' and 'Quit' options, and others,
  37. which will be discussed further on.
  38.  
  39.  
  40. -----------------
  41. - The main menu -
  42. -----------------
  43.  
  44. This menu, popped up by clicking MENU on FileAct's iconbar icon, contains a
  45. number of icons (some of which lead to submenu's/windows). The functions of the
  46. icons will be discussed below.
  47.  
  48. The main purpose of the main menu is to provide access to FileAct's control
  49. window (via the 'Control' icon), which contains (in groups) most of the
  50. available options and controls.
  51.  
  52. -----------
  53. | Control |
  54. -----------
  55.  
  56. Gives access to FileAct's control window, which contains most of FileAct's
  57. options and controls, divided into groups.
  58.  
  59. Clicking on this icon will make this window permanent (but it can be closed
  60. again by clicking on its close icon).
  61.  
  62. Several types of icons appear in the control window :
  63.  
  64. - Toggle icons. These are square, and clicking on them switches the
  65.   corresponding option on (red square in its middle) or off ('closed' box).
  66. - Radio icon sets. Icons in these sets are diamond shaped, and act like the
  67.   toggle icons, but only one of them may be on. Switching any one on will
  68.   switch off all the others in the same set (hence the name 'radio' icons).
  69. - Writable icons. These are square icons with a border and a white background,
  70.   in which you may click an subsequently enter a value or text.
  71.  
  72. The functions of the icons in the control window are discussed below. Icons are
  73. identified by giving their 'path', i.e. group name (name on the border
  74. surrounding the group), if appropiate followed by sub-category (medium grey
  75. heading), followed by the icon's own name, seperated by '|'s.
  76.  
  77. \\\\\\\\\
  78.  Actions  ***
  79. /////////
  80.  
  81. The text icons below this ('No action', 'Invoke Text editor or Basic editor'
  82. and several writable icons) indicate the actions that may be performed on
  83. objects.
  84.  
  85. You may change the text in the writable icons to any command line (see 'Command
  86. lines' for details on the syntax and semantics of command lines), while 'No
  87. action' and 'Invoke Text editor or Basic editor' are fixed actions.
  88.  
  89. There are three sets of radio icons preceding the action text icons. These
  90. indicate which of the actions will be performed on objects that are
  91.  
  92. - Dragged to FileAct's iconbar icon ('Bar')
  93. - Double-clicked on while holding the ALT key ('Alt')
  94. - Double-clicked on while holding the CTRL key ('Ctl')
  95.  
  96. In addition, a particular action may be executed by dragging the object(s) to
  97. the appropiate action text icon.
  98.  
  99. 'No action' indicates that no action will be taken in these situations.
  100.  
  101. 'Invoke Text editor or Basic editor' invokes a Basic editor for all BASIC
  102. files, and a Text editor for all the other filetypes. See 'Running programs'
  103. for details.
  104.  
  105. \\\\\\\\\\\\\\\\\\\
  106.  Options | Recurse  ***
  107. ///////////////////
  108.  
  109. This toggle icon switches on/off directory recursion.
  110.  
  111. When recursion is ON, directory objects are recursed, i.e. they are recursively
  112. entered, and all files and other subdirectories in them will also be subject to
  113. the chosen action.
  114.  
  115. This is very useful to, say, unlock all files and directories in applications
  116. that insist on the opposite for some reason (e.g. Acorns C release 3). You
  117. would simply use, e.g., 'Access %f WR' as the action.
  118.  
  119. NOTE : The recurse option should be used with caution. Be careful when invoking
  120. the Text or the Basic editor, as recursion can cause invocation on a *lot* of
  121. objects. As errors are not returned by Wimp_StartTask, you will not be able to
  122. abort a long sequence of invocations by using ESCAPE.
  123.  
  124. \\\\\\\\\\\\\\\\\\\\
  125.  Options | Run Text  ***
  126. ////////////////////
  127.  
  128. This toggles on/off catching of plain double-clicks on Text (filetype &FFF)
  129. files.
  130.  
  131. When ON, the Text editor is invoked as in 'Invoke Text editor or Basic editor'.
  132. When OFF, no action is taken.
  133.  
  134. ----------
  135. | Status |
  136. ----------
  137.  
  138. This icon gives access to a submenu of status handling functions.
  139.  
  140. FileAct's status consists of the items marked ***, and the settings of the
  141. 'Bar', 'Alt' and 'Ctl' radio icon sets.
  142.  
  143. - Save
  144.  
  145. Clicking on this icon will save the current status in FileAct's status file.
  146.  
  147. This file (when present) is always loaded on startup, or may be explicitly
  148. loaded by using the 'Load' option (to override the current status).
  149.  
  150. - Load
  151.  
  152. Clicking on this icon explicitly (re-)loads the status file, overriding the
  153. current status.
  154.  
  155. - Default
  156.  
  157. Clicking on this icon selects the default status settings.
  158.  
  159. - Kill
  160.  
  161. Clicking on this icon will remove the status file. 'Standard' defaults will
  162. be used when FileAct is next started up.
  163.  
  164.  
  165. --------------------
  166. - Running programs -
  167. --------------------
  168.  
  169. It is possible to run entire programs by using an appropiate command line
  170. action that calls them.
  171.  
  172. The system variable 'FileAct$ObPath' will always contain the full pathname of
  173. the object that the action was invoked on.
  174.  
  175. In the !FileAct directory is an example program 'ExProg' that simply prints
  176. some info on the object on which the action was invoked. It may be executed by
  177. using a command line saying '<FileAct$Dir>.ExProg'.
  178.  
  179. When executing the 'Invoke Text editor or Basic editor' action, in addition the
  180. system variable 'FileAct$ObDir' will be set to the directory that the object is
  181. in.
  182.  
  183. Then the obey file 'TextEd' or 'BasicEd' (which are in the !FileAct directory)
  184. will be executed as appropiate. Change these if needed (e.g. your editor
  185. modules are probably different and elsewhere).
  186.  
  187. When clicking SELECT or ADJUST on the iconbar icon, the obey file 'TextEd0' or
  188. 'BasicEd0' (which are in !FileAct's directory) will be executed as appropiate.
  189. As with 'TextEd' and 'BasicEd', change these if needed.
  190.  
  191.  
  192. -----------------
  193. - Command lines -
  194. -----------------
  195.  
  196. The command lines can be made very powerful by using variable names in them
  197. that will be replaced on invocation with (parts of) the object's full pathname.
  198.  
  199. Prior to execution, the command line is scanned for special sequences of the
  200. form '%<id>', which will be fully replaced with the appropiate (part of) the
  201. object's full pathname.
  202.  
  203. The <id> part determines which part is substituted, as follows. In the examples
  204. following, the object's full pathname is 'adfs::mydisc.$.dir1.dir2.fred'.
  205.  
  206. ----------------------------------------------------------
  207.   <id>   Meaning             Result for example
  208. ----------------------------------------------------------
  209.    f     full pathname       adfs::mydisc.$.dir1.dir2.fred
  210.    p     (pre-leaf) pathname adfs::mydisc.$.dir1.dir2
  211.    s     filing system name  adfs
  212.    m     media name          mydisc
  213.    d     directory path      $.dir1.dir2
  214.    l     leafname            fred
  215. ----------------------------------------------------------
  216.  
  217. In addition, by using upper case instead of lower case (i.e. F,P,S,M,D or L),
  218. the part chosen may be 'cut down' by a MID$ operation, as in BASIC.
  219.  
  220. The full <id> is then of the form '<upchar><arg1><arg2>', where <upchar> is the
  221. upper case selection character, and <arg1> and <arg2> are 3-character values
  222. representing the arguments for the MID$ function (i.e. their VAL is taken).
  223. When a value is negative or zero, the value LENr$+value is taken, where r$ is
  224. the pathname part selected by <upchar>.
  225.  
  226. Some examples :
  227.  
  228. ---------------------------------------------------------------------
  229.   <id>     Result for example             Function
  230. ---------------------------------------------------------------------
  231.  F001-01   adfs::mydisc.$.dir1.dir2.fre   MID$(r$,1,LENr$-1)
  232.  D003005   dir1.                          MID$(r$,3,5)
  233.  L-02002   re                             MID$(r$,LENr$-2,2)
  234.  F002000   dfs::mydisc.$.dir1.dir2.fred   MID$(r$,2,LENr$)=MID$(r$,2)
  235. ---------------------------------------------------------------------
  236.  
  237. The power of this option (especially for *Rename's) will be demonstrated by
  238. giving a few example command strings :
  239.  
  240. -----------------------------------------------------------------------
  241.  Command string          Result for example
  242. -----------------------------------------------------------------------
  243.  Rename %f %f!           Appends a '!' to the end of the object's name
  244.  Rename %f %p.%L001002   Truncates leafname to first two characters
  245.  Rename %f %p.%L001-01   Cuts off last character of leafname
  246.  Rename %f %p.%L002000   Cuts off first character of leafname
  247.  Rename %f %s::%m.$.%l   Move object to root of media it's on
  248.  Access %f WR            Set object's access to public write/read
  249.  SetType %f 123          Set object's filetype to &123
  250.  Namedisk :%m %l         Names the object's disc 'fred'
  251.  Type %f -TabExpand      *Types file, with TAB expansion
  252.  Dump %f 1000            *Dumps file, from PTR=&1000 onwards
  253. -----------------------------------------------------------------------
  254.  
  255. NOTE : Some full pathnames, as delivered by the filer(s) via the WIMP, may not
  256. contain a media or filing system name, e.g. when referring to RAM disc objects
  257. (which are usually of the form 'RAM:$.etc' instead of 'RAM::RamDisc0.$.etc').
  258. In these cases, the corresponding %m, %s or other <id>'s will return an empty
  259. string. For example, the above example that does 'Move object to root of media
  260. it's on' should be entered as 'Rename %f %s:$.%l' when using the RAM disc. You
  261. can always check what the exact name of the object will turn out to be by
  262. looking at the relevant filer window's title.
  263.  
  264.  
  265. ---------------------
  266. - Key-press actions -
  267. ---------------------
  268.  
  269. In addition to the 'click-or-drag' actions on files, FileAct can also execute
  270. specific commands on detecting specific key-presses.
  271.  
  272. To this end, the user creates a definition file, containing the keys or key
  273. combinations to be detected, and the appropiate command to send to
  274. Wimp_StartTask when this keypress is detected (i.e. enabling application
  275. launch, quick OS_CLI actions, etc.).
  276.  
  277. The definition file simply consists of any number of single definition lines,
  278. which start with a tokenised specification of the key or key combination,
  279. followed by a single space character, followed by the command to be sent to
  280. Wimp_StartTask.
  281.  
  282. The key token consists of a single character specifying the 'special' key to be
  283. pressed, followed by an uppercase ASCII A-Z or 0-9, or 'TAB' (for the TAB key).
  284. The special key characters are :
  285.  
  286. 's' : SHIFT
  287. 'c' : CTRL
  288. 'a' : ALT
  289. 'n' : none, i.e. key pressed on its own
  290.  
  291. I.e. 'cH' signifies CTRL-H, 'nA' signifies A pressed on its own, etc..
  292.  
  293. An example definition file would be :
  294.  
  295. cF Run IDEFS::4.$.!FileAct
  296. n0 Filer_OpenDir ADFS::0.$
  297.  
  298. which would run !FileAct on a CTRL-F keypress, or open a viewer on the root
  299. directory of the floppy in drive 0 when 0 is pressed on its own.
  300.  
  301. The definition file should be named 'KeyDefs', and should reside in a directory
  302. which may be anywhere on your (hard)disk, enabling your definitions (and
  303. accompanying short 'util programs') to be stored seperately from FileAct. This
  304. directory is made known to FileAct by setting the variable 'FileAct$KeyActDir'
  305. to the full pathname of the directory (i.e. IDEFS::4.$.!Boot.FileAct).
  306. FileAct's !Run file is the appropiate place to set this variable.
  307.  
  308. The !Run file that comes with your !FileAct copy probably contains the last
  309. user's own path for this, so change this to your own. If 'FileAct$KeyActDir'
  310. does not exist on startup, or the directory it points to is non-existant, or
  311. the key definition file 'KeyDefs' cannot be found, FileAct's keypress actions
  312. function will be inactive.
  313.  
  314. There is an example 'definitions directory' called ExDefs inside the !FileAct
  315. directory. Note it is ok to insert comments into the definition file as long as
  316. they don't resemble a definition line (i.e. start with a special character
  317. token).
  318.  
  319. NOTE : FileAct will only react to the keypresses defined when the caret is not
  320. owned by any application (e.g. when you're editing writable icons, you would
  321. not want every CTRL-U to have the side-effect of booting up an application !).
  322.  
  323. RELATED NOTE : Pressing the right-hand ALT and the right-hand CTRL together
  324. will disown the caret, enabling FileAct to react to keypresses immediately
  325. afterwards.
  326.  
  327.  
  328. ----------------
  329. - Memory usage -
  330. ----------------
  331.  
  332. FileAct uses a fixed amount of memory. It does not claim any extra memory in
  333. any situation.
  334.  
  335. Be prepared to have some memory free though, as all invocations are through
  336. Wimp_StartTask, which needs a wimp slot to run. How large the wimp slot needs
  337. to be depends on any programs executed. Most commands do not take any extra
  338. memory.
  339.  
  340.  
  341. -----------
  342. - The end -
  343. -----------
  344.  
  345. This application is Freeware, which means it may be copied freely, as long as
  346. it is not charged for and is copied completely and unchanged.
  347.  
  348. If you have praise, complaints, comments, bugs(!), or anything else to offer
  349. me, do not hesitate to write to
  350.  
  351. John Kortink
  352. Nutterbrink 31
  353. 7544 WJ Enschede
  354. The Netherlands
  355.  
  356. or try email to john@dialis.hacktic.nl.
  357.  
  358. New versions of the application are available from the same address : just send
  359. £1 to cover postage and a self-addressed envelope containing a formatted 3.5"
  360. disc.
  361.  
  362. It is not very likely though that many new versions will appear. !FileAct
  363. serves a simple purpose, and does it quite well.
  364.  
  365. Happy filing !!!
  366.  
  367. _______________________________________________________________________________
  368.  
  369. !!! NOTE !!!
  370.  
  371. You may NOT change this application or use ANY part of it in other products
  372. without my approval. You may spread it freely (with *ALL* files included), but
  373. not for any profit. This software is provided 'as is'. Using it is entirely at
  374. your own risk.
  375.  
  376. _______________________________________________________________________________
  377.  
  378.