
__________________

FileAct user guide
__________________


User, please note
=================

FileAct is Freeware, i.e. it is free software, but not public domain.

Copyright notice
================

The copyrights (c) of this program belong to John Kortink. All rights are
reserved.

You may not make changes to this program (except for documented configuration
changes). If you distribute it, you may only distribute the complete and
unchanged original copy (as you first received it). You may distribute this
program freely, but must obtain written permission from me if it is to be
distributed as part of, or alongside, any product that is meant to generate
profits. This program is provided 'as is'. Fitness of this program for any
particular purpose is not implied. Using it is entirely at your own risk.


//
//
// Introduction
//
//

Features :

- Remembers 7 different (OSCLI) command lines that can be invoked on files or
  directories in three different ways (double clicking while pressing ALT or
  CTRL, dragging to an appropriate command line icon, or dragging to FileAct's
  iconbar icon).

- Allows C-like '%' type arguments in those command lines, to be substituted
  with (parts of) a target object's path prior to execution of the command
  line.

- Can optionally recurse into directories (i.e. also invoke the command line on
  all objects found within the directory).

- As an extra, can execute a command line on detecting specific keypresses.

Just before execution of every command line, the target object's full path,
directory path (full path minus leaf name and trailing period) and leaf name is
assigned to system variables FileAct$ObjectFullPath, FileAct$ObjectDirectory
and FileAct$ObjectLeafName respectively.


//
//
// Compatibility
//
//

FileAct should be compatible with :

- RISC OS 3.1 and later
- ARM 2 and later processors (26-bit architectures only)


//
//
// Using FileAct
//
//

Start !FileAct. Click MENU on FileAct's iconbar icon.

FileAct's iconbar menu pops up, showing the following entries :

- 'Info' and 'Quit' require no explanation.
- 'Choices' gives access to the 'Choices' menu.
- Clicking 'Control ...' opens the 'Control' window.

The menu and window mentioned are discussed in detail below.


//
//
// The 'Control' window
//
//

You will find two sections in this window, 'Actions' and 'Options'.

The 'Actions' section allows specification of the command lines (in the 7
writable fields), and allows selection of the 'drag to iconbar icon' (buttons
below 'Bar'), 'double click pressing ALT' (buttons below 'Alt') and 'double
click pressing CTRL' (buttons below 'Ctl') command lines. The selected command
line, in each case, is the one directly to the right of the selected button.

Dragging a file or directory to one of the writable fields normally executes
the command line it holds, but if SHIFT is pressed at the same time, the full
path of the file or directory is entered in the writable field instead.

The 'Options' section contains the 'Recurse' option icon. If it is ticked, and
a target object is a directory, it is 'recursed', which means that the relevant
action is executed not only for the directory itself but also for all objects
(directory or file) contained in it. Use the 'Recurse' option with caution : if
enabled, executing a potentially dangerous command line can do a lot of damage.


//
//
// Command lines
//
//

Command lines may contain arguments, to be substituted by (parts of) the target
object's path before execution. Arguments take the form of '%<id>', where <id>
indicates which part of the target object's path is to be substituted.

The available <id>s are listed below. The 'result' column indicates what is
substituted if the target object's path is 'adfs::mydisc.$.dir1.dir2.fred'.

---------------------------------------------------------
 <id>  Means                Result
---------------------------------------------------------
 f     full path            adfs::mydisc.$.dir1.dir2.fred
 p     directory path       adfs::mydisc.$.dir1.dir2
 s     filing system name   adfs
 m     media name           mydisc
 d     directory name       $.dir1.dir2
 l     leaf name            fred
---------------------------------------------------------

Alternatively, an upper case character may be used (i.e. F, P, S, M, D or L),
followed by two integer values seperated by a comma. The result string is then
trimmed in a BASIC MID$(result$, value1, value2) kind of way. If <= 0, a value
becomes LEN(result$) + value.

A few examples :

------------------------------------------------------------------------
 <id>   Result                        Effective BASIC equivalent
------------------------------------------------------------------------
 F6,10  :mydisc.$.                    MID$(result$, 6, 10)
 F2,-2  dfs::mydisc.$.dir1.dir2.fre   MID$(result$, 2, LEN(result$) - 2)
 F-2,2  re                            MID$(result$, LEN(result$) - 2, 2)
 F10,0  isc.$.dir1.dir2.fred          MID$(result$, 10)
------------------------------------------------------------------------

Note that "x,0", i.e. MID$(result$, x, LEN(result$)) is always effectively
MID$(result$, x), whatever x is, negative or positive.

A few example *Renames making good use of the available substitutions :

---------------------------------------------------------------------
 Definition             Result for example
---------------------------------------------------------------------
 Rename %f %f!          Appends '!' to leaf name
 Rename %f %p.!%l       Prepends '!' to leaf name
 Rename %f %p.%L1,2     Truncates leaf name to first two characters
 Rename %f %p.%L1,-1    Removes last character of leaf name
 Rename %f %p.%L2,0     Removes first character of leaf name
 Rename %f %s::%m.$.%l  Moves object to the root of the media it's on
---------------------------------------------------------------------


//
//
// Key commands
//
//

FileAct can also execute a command line on detecting specific keypresses.

To use this feature you have to create a key commands file, containing a list
of keypresses to be detected, and the corresponding command lines to execute.

The key commands file should be a text file, and should contain a number of
definition lines. A definition line starts with a key token, followed by 1 or
more spaces, followed by the command line to execute. If the key token is not
recognized, the definition line is completely ignored (this can be used to
insert comments).

A valid key token consists of a single character specifying the 'special' key
to be pressed (if any), followed by an uppercase A..Z, or 0..9, or 'TAB' (for
the TAB key). The special key characters are :

's' : SHIFT
'c' : CTRL
'a' : ALT
'n' : none of the above, i.e. the key must be pressed on its own

E.g. 'cH' means 'CTRL and H pressed simultaneously', 'nA' means 'A pressed on
its own', 'sTAB' means 'SHIFT and TAB pressed simultaneously', etc..

The key commands file name is '<FileAct$ChoicesDir>.Commands'. If the key
commands file is not found there, key commands will be silently disabled.

The !FileAct.Examples directory contains an example key commands file (and a
program). You may want to try them by copying both to '<FileAct$ChoicesDir>'
(enter *Show FileAct$ChoicesDir in a Task window to see where it points). The
example key commands file 'instructs' the 0 key to open a Filer window for the
floppy in drive 0, and CTRL-TAB to *Dir to the directory shown by the Filer
window that the pointer is currently 'on'.

Note that FileAct follows standard WIMP conventions for detecting 'hot keys'. A
drawback is that FileAct can only detect a keypress if the caret is not owned
(i.e. is not in use by any application) and the keypress is not intercepted and
handled by another application. Sometimes you may want to execute a FileAct key
command while some application owns the caret. To help, FileAct offers a quick
and dirty way to disown the caret : simply press the *right-hand* ALT key and
the *right-hand* CTRL key at the same time.


//
//
// The 'Choices' menu
//
//

In this menu you can manipulate FileAct's 'choices'.

- 'Save' will save the current choices.
- 'Load' will load the saved choices.
- 'Default' will load the default choices.
- 'Kill' will discard the saved choices.

When FileAct starts up it loads the saved choices, or the default choices if no
choices were saved.

The choices consist of all the settings in the 'Control' window.


//
//
// Epilogue
//
//

Updates of FileAct (if any appear) will be made available by (in order of
preference) :

- World Wide Web : visit web.inter.nl.net/users/J.Kortink
- Electronic mail : email kortink@inter.nl.net

Enjoy !


John Kortink



