Q-TRANS by Dilwyn Jones


Introduction

Q-Trans is a pointer driven dual window file transfer package
originally developed as part of the Launchpad QL Desktop program, but
released for standalone use.


Credits

Q-Trans was written by Dilwyn Jones, using the Easyptr 3 programming
utility from Albin Hessler, and compiled with the QLiberator compiler
from Liberation Software. The package also uses the DJToolkit from
Norman Dunbar and the Display Code extensions from QL Today. Q-Trans
is a freeware package which may be freely copied for all QLers.
Q-Trans is copyright (C) 2002 Dilwyn Jones.


System Requirements

The software requires pointer environment, Toolkit 2 and expanded
memory to be present.


Backup

Use your favourite backup program to make a copy of the Q-Trans disk,
or use the Toolkit 2 WCOPY command to make a copy.


Configuring The Software

Q-Trans has a standard level 1 configuration block built in, so the
program may be configured with the usual Config or MenuConfig programs
supplied with most pointer driven QL software.

To configure the program, tell Config or MenuConfig to load QTRANS_OBJ
and work through all the options one by one to set the program
defaults listed below.

1. Sound Prompts Off Or On.
The program issues some beeps to accompany any error messages. If
you'd prefer silent running, this can be set to OFF.

2. Default Left Pane Drive/Directory.
The program has two filename listing windows. Both have an associated
drive and directory name, from where filenames are listed. This entry
specifies the default name used for the left hand window (or "left
pane") when the program starts. Normally this would be a drive name
such as FLP1_ or WIN1_. You can also specify a directory if required,
e.g. WIN1_GENERAL_. If this drive/directory is not found when the
program starts, an error message will be issued and the file list
window will be empty until another drive/directory is specified. If
the name is specified as a single underscore character, this will be
converted to the DATA_USE default setting when the program starts up.

3. Default Right Pane Drive/Directory.
Default drive/directory name for the right hand file listing window.
Settings as for the left window described above.

4. Specify Printer Output Device.
This is used for printing files lists or hard copy of files. This will
normally be SER1, SER2 or PAR, though you can enter a filename or
network printer name if required.
5. Print Formfeed After Printouts.
This allows you to eject the last page after printing has finished.
Normally used for laser printers or inkjet printers which may not
release the last page if it is not a full page of text. I normally
have this set to YES.

6. Pause Between Files Printed.
If you'd rather that the program paused between hardcopy of each fle
selected for printing (e.g. so that you can check the previous
printout was OK before proceeding and escape befor eprinting the next
one if the printout is not satisfactory for some reason), set this to
YES. If you just want the program to print selected files continuously
(e.g. the computer is left unattended for the printing) set this to
NO.

7. Specify Initial Display Height.
The program can be configured to start in one of 7 preset display
sizes, to suit the most common QL display heights. If you start the
computer in a smaller display height than that specified here, the
program wll search for the nearest suitable smaller size and attempt
to start the program to suit that size of screen. If all else fails,
the program will start in QL screen (512x256). The available sizes are
as follows, the number indicating the maximum number of visible
filenames per window:
11 lines (about half QL screen size)
21 lines (QL screen)
23 lines (Extended mode 4)
30 lines (EGA screen)
43 lines (VGA screen)
55 lines (SVGA screen)
72 lines (1024x768 screen)
If you like, set this to the largest possible size and Q-Trans will
always try to start with the largest display it can manage.

8. Drive/directory name for Trash can
Up to 10 characters may be specified as a path name for the Trash can.
It is suggested that this be a single character directory name on a
hard disk using an uncommon directory name (e.g. win1_*_), although
the limit would allow a single character directory name over a single
digit network station number if required (e.g. N1_WIN1_*_). If a blank
entry is given, the Trash can facility is disabled - if the system
does not have reasonable capacity drives such as hard disks or high
capacity disks, there is little point trying to use the Trash
facility.

9. Trash can mode of operation
The Trash can stores details of the original path name for a file
(i.e. where it was Trashed from) in a small file with a name ending
with '_t'. One of these files is created for each file Trashed using
Q-Trans. If there are a lot of files in the Trash can, these will
effectively double the length of the list of files. If you don't need
to see the _t files you can reduce the length of the list of files int
he Trash can by opting to 'hide' these files by setting the 'Hide
Trash can _t files' option to Yes.


Starting Q-Trans.

Simply execute the program with the EXEC or EX command or similar
commands from commonly available toolkits.

EXEC FLP1_QTRANS_OBJ

The program can also be launched from most QL desktop programs and
program launchers. It has been tested with Launchpad, Qascade and DEV
Manager and will no doubt work with anything that will launch
QLiberator compiled programs. The program will work in high colour
modes, but always uses the original QL colour scheme for maximum
compatibility. The program is designed to work on both QDOS and SMSQ/E
systems equipped with pointer environment.

If you pass an option command parameter to the program (a string after
the EX command) you can specify the default drive names of both
windows, which will override the configured default drives. The first
drive name should be separated from the second one by a single space
character. This facility is useful for QL desktop programs like
Launchpad where you can use Q-Trans as a form of file menu and pass a
parameter to it to specify which drive(s).

EX FLP1_QTRANS_OBJ;"FLP1_ WIN1_"

This will start Q-Trans with the left pane listing filenames from
FLP1_ and the right window pane listing files on WIN1_. If you just
wish to specify the left hand pane drive, simply specify that:
EX FLP1_QTRANS_OBJ;'FLP1_'

If you wish to specify just the right hand pane drive, omit the first
drive name, and put in a single space before the drive/directory anme
of the right hand files window:
EX FLP1_QTRANS_OBJ;' RAM1_'


Mouse Terminology

HIT - press the left mouse button, or SPACE bar on the keyboard while
over an icon.

DO - press the right mouse button, or ENTER on the keyboard while over
an icon.

Note: users of certain other computers, HIT may be more familiar to
you as 'left click' on a mouse, while DO may be more familiar as a
right mouse click.

ESC - usually a press of the ESCAPE key on the keyboard. Some mouse
systems for thee QL allow the middle button on the mouse to be
configured to mimic the ESC key.


The Program Layout

I hope you like red, black and white, because that's the only colour
scheme. Although the program works under the GD2 "colour drivers" it
only ever uses the standard QL 4 colour mode colours.

The two large black areas bottom left and right are the two file
listing windows. These show the filenames on the drive specified in
the white strip above each window. The top line contains the main
program command icons, while the second and third lines contain icons
helping you to specify the drive names and numbers.

+--------------------------------------------------------------------+
| [MOVE] [RESIZE] [SLEEP]   [commands]   [REFRESH] [COPYRIGHT] [ESC] |
|                                                                    |
| [DRIVE NAMES LEFT PANE]            [DRIVE NAMES RIGHT PANE]        |
| [12345678][<-][DATA$][PROG$][T]    [12345678][<-][DATA$][PROG$][T] |
| [DRIVE/DIRECTORY NAME         ]    [DRIVE/DIRECTORY NAME         ] |
|                                                                    |
| +-----------------------------+    +-----------------------------+ |
| |                             |    |                             | |
| |                             |    |                             | |
| |                             | <- |                             | |
| | Left Pane                   |    |                  Right Pane | |
| |                             | -> |                             | |
| |                             |    |                             | |
| |                             |    |                             | |
| +-----------------------------+    +-----------------------------+ |
+--------------------------------------------------------------------+

The above diagram should help explain things a little. Let us start
with the six red icons at the top. These are fairly standard pointer
environment program control icons.

[MOVE] is the standard pointer environment window move icon - click on
the corner to corner box symbol and an icon will appear - move this to
where you want the program positioned and click again to 'drop' the
program there on screen.

[RESIZE] lets you alter the amount of screen taken up by Q-Trans. It
can occupy from about half a standard QL screen up to the height of a
768 pixel high screen. The bigger the display, the more filenames
visible, the smaller the display, the less intrusive is Q-Trans. Each
time you click on this icon, Q-Trans gets a bit bigger, until it can't
make itslef any larger so it goes back to minimum size. Alternatively,
DO or right click on this icon to pick a size from the menu shown.

[SLEEP] or [Zzz] puts the program to sleep in the QPAC2 button frame
if present. You'll see a small button with the name 'QTRANS' in it. To
re-awaken this minimised form of the program, just move the on-screen
pointer onto the button and DO (right click) on it. This will wake the
program ready for use once again.

[REFRESH] The little red and white 'lightning' symbol will redraw the
program display if it has been corrupted by another program for
example. It will also, where possible, cause a refreshed listing of
the files in the drive associated with both windows.

[] The Copyright symbol icon simply displays a short copyright notice
or 'about' screen. Brings up a short screen with author contact
details and program version number (the program version number can
also be seen when configuring the program).

[X] This is the Exit icon, use this to quit from the program. A short
confirmation dialogue box appears, click on Yes or No to indicate your
choice of actions.

In between these red and white icons, there's a row of white icons
with names prefixed by function key names F1 to F10. Some QL systems
only have function keys F1 to F5, in this case F6 is accessed by SHIFT
F1, F7 as SHIFT F2 and so on.

F1 - Refresh left pane list of files.
F2 - Select (highlight) all filenames in the left pane.
F3 - Deselect (remove highlight from) all filenames in left pane.
F4 - Sort filenames list in left pane into alphabetical order
F5 - Commands, access the "commands" or "context" menu.
F6 - F10 same as F1 to F5, but apply to right hand pane.

The COMMANDS menu is explained in more detail below. If you have used
F4 or F9 to sort a list of files into alphabetical order, the list may
be "unsorted" simply by reading the drive again, e.g. by using F1 or
F6.

The next line contains a list of the directory device names on your
system. The program scans the directory devices list and presents
shortcuts for up to 10 directory devices found. On my system, this
gives me the list: SUB DOS DEV FLP WIN and RAM. Standard QLs will also
have MDV of course. The device names are restricted to 3 characters as
is normal QL practice. If longer device names are found, these are
truncated to 3 characters for display. A HIT or a DO on one of these
drive name icons will drop that device name into the wide white strip
below and the program will look for files on this new device.

SUB DOS DEV FLP WIN RAM
1 2 3 4 5 6 7 8   <-   DATA$   PROG$  [Trash icon]

You will notice that the first letter of a drive name is underlined.
This keystroke nominally selects that drive name as an alternative to
using the mouse, but you may find that having device names starting
with the same letter restricts this a little - how is the program
meant to know that when you press D that you mean DOS device or do you
mean DEV device? In such cases, the first instance of a device name
starting with that letter is selected, any other device names starting
with the same letter have to be selected with a HIT or a DO using the
pointer. Similarly, the icons for the right hand pane may well have to
be selected with the mouse, as they duplicate the names for the other
window.

Under the device names are icons for drive numbers 1 to 8. These are a
quick way of selecting drive number, e.g. changing from FLP1_ to
FLP2_. Press 1 to 8 to apply these to the left hand pane, or SHIFT 1
to SHIFT 8 for the right hand pane.

In the case of network filenames, a name is assumed (from v0.08 of the
program) to be a network name if it starts with a single letter device
name, e.g. N32_ or S1_ (S is the Sernet device), in which case the
device name shortcuts are handled a little differently. Suppose the
window is displaying a list of files on WIN1_. Then you select the N
device to access the QL network, and it changes from WIN1_ to N1_WIN1_
and you can press the icons for 1 to 8 to select network station
number, say station 6. So it becomes N6_WIN1_. If you then select the
FLP device, since it's a network name the FLP is not inserted at the
start of the name, it goes after the separator between the network
station and drive name, so N6_WIN1_ changes to N6_FLP1_. It sounds
difficult, but you should quickly get used to it.

HITting a network filename will stuff the filename into the stuffer
buffer, including the network device name and drive name.

(Note: I am not an expert on the QL network, Sernet and Midinet, so I
hope I have implemented the network name handling correctly).

The <- symbol is used to go back down a directory level. For example,
if the window was listing files on WIN1_EXEC_ and you clicked on the
<- symbol, it would go back down to WIN1_, rather like the use of the
Toolkit 2 command DUP.

A Hit or Do on the DATA$ icon will cause the window to list files on
the DATA default drive, i.e. that set with DATA_USE. You can check the
current DATA default setting with the DATAD$ function from BASIC.
Likewise, a Hit or Do on the PROG$ icon does the same from the PROG or
program default, as set with PROG_USE in BASIC and checked with the
PROGD$ function.

A Hit or Do on the little dustbin or trashcan symbol to the right of
these displays the content of the Trash directory, useful if you
realise you need to restore a file - simply highlight a filename in
the Trash directory and use the Untrash command to transfer the file
back out of Trash.

A Hit or a Do on the wide white strip containing the drive/directory
name will let you edit the name directly. Edit and type in the new
name in the normal way and press ENTER. Pressing the '9' key will let
you edit the left hand pane's drive/directory name, while '0' will let
you do the same for the right hand pane.

The files list windows themselves follow the format of a two letter
column at the left showing the file type, followed by the filename
itself. An executable (file type 1) program is flagged with the letter
E before it, while a directory (file type 255) is indicated by a >
symbol before it. S-ROFF (type 2) files are indicated by a letter R.
If there are more files than will fit in the black window space,
scroll bars will appear, which take the form of a thin bar of green
arrows above and below the list of files. Click on these bars to
"steer" the list in that direction to see the hidden files. A red box
appears to the right of the list, showing where the visible section is
relative to the complete list of files, useful for large lists to help
you see where you are. With large lists of files, it can sometimes be
useful to split the list of files into sections which can be scrolled
independently, allowing you to be able to see the start of a long list
of files above the end of a long list of files for example. To split
the list, DO on the very right of the window in the thin area used by
the red scroll box. A further pair of strips of green arrows will
appear. To get rid of this, DO on the little white strip which appears
alongside the new scroll arrows. They will also disappear if the menu
is redrawn, or a if you enter a new directory.

A HIT or a left click on a filename will "highlight" or "select" that
filename. Files selected in this way are the ones that the COMMANDS
menu will act upon, e.g. highlighted files are the only ones copied
from a list. A DO or right click on a filename will both select it and
bring up the "commands" or "context" menu, offering you commands to
copy, rename, view etc files. The exception to this is when you DO on
a directory name (one preceded by a > symbol). This is interpreted as
a command to enter that directory, e.g. if the file list contains:

  BOOT
E QUILL
> DOCS

A right click on BOOT or QUILL will bring up the commands menu, but a
right click on DOCS would cause Q-Trans to try to enter that directory
and list the files contained within it.

If a few files are highlighted in a window, clicking on the red left
or right arrows between the two panes will cause Q-Trans to try to
copy the files between the drives indicated. For example, if the left
hand pane is listing files in FLP1_ and the right hand pane is listing
files in RAM1_, clicking on the right facing arrow (the bottom one of
the two) will cause Q-Trans to copy any highlighted file from FLP1_ to
RAM1_. Clicking on the left facing red arrow (the top one of the two)
will cause Q-Trans to try to copy any highlighted files from RAM1_ to
FLP1_.

When such copying is complete, the program will try to update the
files list for both drives.

Each time you HIT a filename (i.e. press SPACE or left mouse button
click while the pointer is over a filename), the filename (not the
file!) is copied into the Stuffer Buffer. If you then CTRL C to BASIC
or to another program and press ALT SPACE (hold down the ALT key and
tap the space bar) that filename is "typed into" the other program.
Even older programs like Quill can accept filenames passed via the
stuffer buffer in this way! This allows Q-Trans to be used as a simple
form of pointer driven file selection utility for non-pointered
programs, for example.

Note that the filenames listed generally do not include directory
names in versions of this program after v0.05, this makes it easier to
reliably move or copy files between directories.
Note also that although you can highlight and then copy a directory
(e.g. Hit on > DOCS then use the Copy command in the Commands menu to
copy it) this is unlikely to be useful as the directory 'file' itself
is copied rather than creating the directory on the destination drive.
This may be of some use to programmers wishing to copy a directory to
examine its content but that's about all. If there is interest and the
code can handle it, I may update this in future versions to create a
directory on the destination drive. It is not currently possible to
highlight a directory and copy all the files contained within it.


Commands Menu

This sub-menu contains a list of commands designed to act on selected
files in the appropriate window. It includes the following commands:

+-------------------------------------+
| [MOVE]         ACTION         [ESC] |
+-------------------------------------+
|   Copy        Locate     Trash files|
|  Delete   Make directory  Trashcan  |
|Drive info      Move       Untrash   |
| Execute       Print         View    |
|Files list     Rename     Swap drives|
|  Format     Statistics      Exit    |
+-------------------------------------+

The red icons at the top are the usual double box MOVE symbol to move
the menu around if required, and the [X] symbol to exit from this
menu. You can also use the Exit command to quit in versions supporting
this command.

Copy

This command copies files in exactly the same way as the little red
arrow symbols between the two file list windows. A Copy dialogue box
appears which gives you a choice of the usual Yes/No/All/Esc options
(All causes the program to try to copy all of the files without
further input from you unless an error occurs such as a file already
exists in which case it will ask for confirmation of whether or not to
overwrite it). No will skip the filename shown and go on to the next
filename. Yes copies the filename shown. ESC or the [X] icon stops
copying and returns to the main program display.

+----------------------------------------------+
| [MOVE]                COPY               [X] |
+----------------------------------------------+
| Copy FLP1_BOOT                       No  Esc |
| To   RAM1_BOOT                       Yes All |
+----------------------------------------------+

The white strip to the right of the word TO specifies the name to
which this file will be copied. If you click on this box or press T
you can alter the filename if required. This can be useful when you
wish to make a duplicate of a file on the same drive, for example, as
you might with the equivalent COPY FLP1_FILE1 TO FLP1_FILE1_backup
command in BASIC for example.

Please note that although versions of Q-Trans later than v0.05 attempt
to take directory names into account when copying or moving files
between sub-directories, this may not work very well on substitution
or alias directory devices such as DEV or SUB where you may need to
manually rename files if Q-Trans becomes confused about "hidden"
directory names (e.g. if you are in the habit of, say, setting DEV1_
to be equivalent to WIN1_QUILL_ for example in order to get floppy
based software to run from directories on hard disks).
A suggestion to improve reliability when using DEV or SUB or other
similar devices is to watch out in case part of the substituted names
appear in the F2 or F3 directory window. For example, if DEV1_ is set
to be WIN1_QUILL_ but the F2 window shows DEV1_QUILL_, you may get
problems because DEV1_QUILL_ is really DEV1_QUILL_QUILL_ ! You can tie
yourself up with complex DEV and SUB definitions, so try to use the
'real' names whenever possible. A hint on how to work around this is
to navigate back to the 'root', i.e. if the above exaple shows
DEV1_QUILL_, use the <- button to go back down to DEV1_ then wade back
through the directories. If you start from the 'root' of a DEV or SUB
definition and work your way up the directories you may well find it
does sometimes work. While writing this program, I anticipated
problems handling DEV and SUB names. It is best to expect them to fail
in a Q-Trans context, but they do sometimes work rather better than I
had originally thought even though it takes a bit of getting used t
what Q-Trans ca handle and can't handle.


Delete

This command deletes selected files from the drive specified. A 4
choice menu appears, as king if you want to delete the named file. You
have four choices - the usual Yes, No, All or Esc.

+---------------------------------+
| [MOVE]        DELETE        [X] |
+---------------------------------+
| Delete ram1_BOOT                |
|                                 |
| [Yes]    [No]    [All]    [ESC] |
+---------------------------------+

Drive information

+-----------------------------------------------+
| [MOVE]        DRIVE INFORMATION        [MOVE] |
+-----------------------------------------------+
|                                               |
| +-------------------------------------------+ |
| |Drive   :FLP1_                             | |
| |Name    :test_disk QDOS HD                 | |
| |Capacity:528/2880                          | |
| |Files   :90                                | |
| +-------------------------------------------+ |
|                                               |
|                    [  OK  ]                   |
+-----------------------------------------------+

Shows how many files are on a drive, along with the medium name and
capacity figures, like a DIR command. If a DV3 filing system (able to
read MSDOS disks) it may also show if the disk is QDOS or MSDOS
format.

Execute

Start an executable program or job. There are several options you can
specify, such as sending an option command string to the program, and
the usual Psion, Guardian, Unlock, Freeze and Impure options. Multiple
programs can be executed if selected. If you have File Info II
installed on your system, you can even execute files such as text
files, since File Info II allows you to associate programs with
certain types of files, meaning that if the text file is executed, the
program associated with it is started and loads the file in question.
The normal situation of course is that a single program is executed
with none of these options enabled.

+--------------------------------------------------+
| [MOVE]            EXECUTE OPTIONS            [X] |
+--------------------------------------------------+
| Program:                                         |
| ram1_sample_txt                                  |
|                                                  |
| Command string:                                  |
| [                                              ] |
|                                                  |
| Control options:                                 |
| [Psion KB] [Guardian] [Unlock] [Freeze] [Impure] |
|--------------------------------------------------|
| [Yes,execute this file] [  No, skip this file  ] |
+--------------------------------------------------+

The Command String is passed to the program executed. Some programs
use this command string to load a file as they start up or to specify
some default settings for example. I use the S_Edit program as a
general text editor and frequently pass the filename of a text file to
be edited in this way from BASIC:

EX WIN1_S_Edit_obj;"FLP1_README_TXT"

The command string is in effect the same as such a command from BASIC.

The other options are similar to those you would use in hotkey or EXEP
commands from BASIC.

The Psion KB option is for use with programs like Quill which tend to
grab all available memory for themselves when they start up. This
option lets you specify how many kilobytes of memory they are to be
allowed when starting. For Quill, 32KB will suffice for small files,
while larger amounts of memory may be needed for large documents.

The Guardian option sets up a guardian screen around the windows of a
program which tends to cause chaos for the pointer environment by
altering the size of its own windows frequently. Using a Guardian
window will ensure that a consistent area of the display (usually the
whole display) is saved to prevent the endless chaos caused by partly
overwritten displays and so on.

Unlock is an option to allow programs to continue writing to the
screen even if you CTRL C out of them or bury their windows with
another program. A good example might be one of those little clock
programs which needs to write the time and date to the screen even if
it overwrites part of the display of another program. Using Unlock
will allow that program to continue working.

The Freeze option is useful in exactly the opposite circumstances. If
you have a program which writes direct to the display and does not
stop when you CTRL C out of it or bury it with the display of another
program, this option can be used to force freeze a program when
necessary.

Impure. This specifies that a program is Impure, i.e. its code may
modify itself. Since you cannot run several instances of a program
written in self modifying code (old Turbo compiled programs may be an
example of this), this option will help the QL to organise things
accordingly.

The bottom two buttons are simply to let you say Yes-I really do want
to execute this program now, or simply No it was all a mistake, don't
execute this program. Once you have specified any options for the
program to execute, you would normally click on Yes to execute the
program shown.

Files List

This command lets you print a list of files on the drive/directory
specified. One filename per line, with optional form feed after the
last filename to ensure that the last page is ejected.

+------------------------------------------+
| [MOVE]           FILES LIST          [X] |
+------------------------------------------+
| List files to   : PAR                    |
| Form feed at end: Yes                    |
|                                          |
|               [  OK  ]                   |
+------------------------------------------+

Press F or click on the 'Form feed' box to alter this option - it will
simply toggle between Yes and No.

Press L or click on the 'List files to' box to change where to print
to - normally you would enter SER1, SER2 or PAR here, depending on
which port your printer is connected to.

Finally, click on 'OK' to start printing the list. Note that only
filenames selected or highlighted are actually printed.

Format

This command formats a disk or ramdisk. All you need to do is to enter
the medium name then click on the 'OK' button to start the formatting
operation.

+-----------------------------------------+
| [MOVE]            FORMAT            [X] |
+-----------------------------------------+
|   Enter medium name to format below,    |
| then [OK] to format, or ESC to abandon. |
|                                         |
| NAME: [                               ] |
|                                         |
|                   [ OK ]                |
+-----------------------------------------+

The name entered should include the drive name and any extra
parameters required with the name. For floppy disks, *D, *H and *E are
allowed to specify disk density to format if supported by your disk
interface. For ramdisks, a number after the drive will indicate the
number of sectors to formata static ramdisk. In essence, the name
entered is just like the name you'd specify in a FORMAT command in
BASIC. Note that as far as hard disk systems are concerned, you may
need extra commands entered from BASIC, e.g. WIN_DRIVE or other
specialised hard disk control commands.

Locate

Locate is a command which allows you to search for test within either
the body of a file or within a filename. It pauses each time you have
found a matching file, to give you the opportunity to view the file
(since it's likely that most files searched will be test files).

+---------------------------------------------------------+
| [MOVE]                    LOCATE                    [X] |
+---------------------------------------------------------+
|                                                         |
| Search location:     [                                ] |
| Filenames containing:[                                ] |
| Containing text:     [                                ] |
| Searching in:                                           |
| Found in:            [                                ] |
|                                                         |
|                                                         |
| [    Locate    ]  [   View file   ]  [Use File Info 2]  |
+---------------------------------------------------------+

The search location is always the drive name specified for the window
from which the command was activated. This cannot be altered in the
Locate command itself.

Beneath the Search Location are two boxes into which you can enter the
text to be searched for. If you know part of the filename, you can
enter a vague filename in the 'Filenames containing' box. If one of
the selected filenames contains this text in the filename, it will be
shown in the 'Found in' box. A simple example: you know that the
filename had a letter Z in it, so if you enter the Z into the
'Filenames containing' box, any filename containing a letter Z will be
listed. The search is not case sensitive - Z or z will be found.

If you knew that the file itself contained the word "sprite" somewhere
in the text, you could enter this word into the 'Containing text' box.
Q-Trans will then scan through the selected files searching for this
text. Any file found containing this text will have its filename shown
in the 'Found in' box.

Note: the files are loaded into memory for searching if there is
enough free memory. If not, short parts of the file are loaded at a
time and scanned for the text. This makes searches a bit slower if
free memory is in short supply.

Once a file has been located, you have the option to view it. If the
file is a plain text file the internal file viewer may prove adequate.
For more advanced users who have File Info 2 installed, an additional
viewing option is available to use the file association facility to
launch a suitable viewer as configured in File Info 2. For example,
with File Info 2, it is possible to configure it to launch Quill to
view DOC files and so on. This may also be useful for graphics files.

If you do not have File Info 2 installed on your system, this item
will not be selectable.


Make Directory

This command is equivalent to the MAKE_DIR command in BASIC. On level
2 and higher filing systems it allows you to create a directory with a
given name.

+------------------------------------------+
| [MOVE]        MAKE DIRECTORY         [X] |
+------------------------------------------+
|                                          |
| In this location:                        |
| [FLP1_                                 ] |
|                                          |
| Create a directory called:               |
| [                                      ] |
|                                          |
+------------------------------------------+

The menu contains the usual Move and Exit icons at the top. The next
box down lets you specify the drive/directory in which to create the
new directory. This box defaults to the current drive/directory for
the window pane from which the command was activated. Simply HIT or DO
on this box or press the "i" key to edit what is shown here.
HIT or DO on the bottom box, or press the "C" key to enter a new
directory name. When you press ENTER, Q-Trans tries to create that
directory name. If it already exists, or there is any other error, an
error message is displayed - click on OK in this error message window
and you return to the directory creation screen to try again. There is
no overwrite option when creating directories.

Move

This command lets you move a file from one drive/directory to another.
It is very similar to copying, but the original file is removed. In
other words, it's like a COPY with an option to change the filename
and followed by a DELETE. The main difference between this and a
RENAME is that RENAME can only change the name of a file, it cannot
send the file from one location to another. By default, the source and
destination drives for the Move operation are determined by the
drive/directory settings for the two panes.

+-------------------------------------------------+
| [MOVE]               MOVE                   [X] |
+-------------------------------------------------+
|                                                 |
| MOVE  [FLP1_README_doc           ]  [No ] [Esc] |
|                                                 |
| To    [RAM1_README_doc           ]  [Yes] [All] |
|                                                 |
+-------------------------------------------------+

As with Copy, you have the usual No/Yes/All/Esc options to specify
whether to just move the file shown or to move all remaining selected
files automatically without further input from you. Press ESC or E to
stop at this point.

Click on the white To box to modify the destination filename if
required.

Note: the same cautions concerning the renaming of files or moving
files between sub-directories applies as with the Copy command
described above.

Print

Lets you print a hard copy of the file. Only supports plain text
files. The files selected in the window from which the command was
activated are printed.

+------------------------------------------------+
| [MOVE]                PRINT                [X] |
+------------------------------------------------+
| Print files to  : [SER1                      ] |
| Form feed at end: [Yes]                        |
| Pause in between: [Yes]                        |
|                                                |
|                    [  OK  ]                    |
+------------------------------------------------+

You can specify where to print the file to (normally a printer on the
PAR or SER1 ports). Just click on the white box holding the name and
edit it in the usual way.

The Form Feed At End option ensures that the last page is ejected when
each file has been printed - this helps to ensure that all files are
on separate pages for example. If required, you can tell the program
to pause between each file printed, e.g. if you want to be able to
load different paper for some files.

Rename

Allows you to change the name of a file. All you have to do is to
enter the new name of the file - multiple files can be renamed, just
select or highlight as many filenames as need be renamed and step
through them one at a time.

+-----------------------------------------------+
| Rename  FLP1_README_ASC                       |
| To     [FLP1_README_TXT                     ] |
+-----------------------------------------------+

Just type the new name into the bottom box and press ENTER. If you
wish to abort the rename you can press ESC. If the name in the bottom
box is the same as the one in the top box there is obviously no need
to rename and to prevent an error none is attempted.

Statistics

This command allows the display of rudimentary file statistics for
selected files. It brings up a small menu with filename, file type,
dataspace, file length, update date, backup date and file extra
information (as you'd get with the FXTRA extension of Toolkit 2 for
example.

+-----------------------------------------------+
| [Move]         [FILE STATISTICS]        [Esc] |
+-----------------------------------------------+
| +-------------------------------------------+ |
| | Filename       :WIN1_MyBoot               | |
| | File type      :Data                      | |
| | Dataspace      :0                         | |
| | File length    :285                       | |
| | Update date    :2003 Jan 04 17:35:25      | |
| | Backup date    :1961 Jan 01 00:00:00      | |
| | File extra info:0                         | |
| +-------------------------------------------+ |
|      [Previous]               [  Next  ]      |
+-----------------------------------------------+

The 'Previous' and 'Next' icons let you step through the selected
files one at a time.

Swap drives

This command simply swaps the lists of files in both windows over.
Someone asked for this to be added to v1.01, I'm not sure why!

Trash

From version 0.10, Q-Trans includes a rudimentary Trash can facility,
which allows a degree of restorable deletion of files. It is not a
true 'undelete' or 'recycle' facility as found on other computer
systems and facilities are limited. Basically, a special folder is
created on your hard disk and, using the Trash command, files are
selectively moved into this folder rather than being deleted as such.
If you later realise you have made an error in deleting a file and
wish to restore it, simply enter the Trash directory and copy the file
back out. If the Trash starts to take up too much space, you can of
course remove any number of files to free up space, but files erased
from the Trash cannot of course be recovered later. It is best to give
the Trash directory a short and uncommon name such as WIN1_*_ to
reduce problems with filenames exceeding the QL filename length limit
and being truncated. A single Trash directory serves all devices, so
anything Trashed from floppy, ramdisk, over the network or from the
hard disk will all end up in the same place, there is no support for
separate Trash facilities on each device. Since files from all devices
can end up in the Trash can, it may become hard to know where the
files came from, so there is the facility to create short 'info' files
in the Trash can to store the details of where the file came from.
These info files are called '_t' files, so-called because their names
are derived ffrom the source filename by adding _t to that filename,
truncating if necessary to staywithin the QL filing system name length
limits. So if the Trash is WIN1_*_ and you delete FLP1_letter_doc, it
goes in the Trash can as WIN1_*_letter_doc, and a small file called
WIN1_*_letter_doc_t is created, which stores the original path name
'FLP1_letter_doc'. QL filename length limits mean that files moved
into Trash may get their names truncated to within QDOS/SMSQ filename
length limits.

To Trash a file, simply highlight the file to be Trashed, then from
the commands menu, select the Trash command, which works in the same
way as the Delete equivalent.

Trash can

If the window from which the command is chosen is displaying the
content of the Trash can, this Trash can options menu is available.
From this you can see how many files are in the Trash can and their
total lengths. There are 4 options for deleting files from the Trash
can, to free up space on the drive concerned. When the menu is first
shown, Q-Trans checks the total size of files in the Trash can, so if
there are a large number of files in the Trash can, it might display a
"please wait" message while it reads the details.

+-----------------------------------------------------+
| [Move]               [TRASHCAN]               [Esc] |
+-----------------------------------------------------+
| +-------------------------------------------------+ |
| |Trash can directory is      : WIN1_*_            | |
| |Number of files in Trash    : 486                | |
| |Total size of Trashed files : 1.507302E6         | |
| +-------------------------------------------------+ |
|            [  Empty entire Trash can  ]           | |
| Remove files older than [     ] days from Trash can |
|   Delete files Trashed [     ] or more days ago     |
|   Erase files larger than [     ] KB in Trash can   |
+-----------------------------------------------------+

The first command is easy enough, clicking on [Empty entire Trash can]
simply erases all files from the Trash can. If you have just a backup
of your entire hard disk, for example, or it is some time since you
last deleted anything and feel that nothing could possibly need to be
undeleted or untrashed, or quite simply you are running out of space
on that drive, you may find this command useful, if drastic.

The other three commands are selective deletes for the Trash can
content. They zap files which are older than a given number of days,
or zap files trashed more than a given number of days ago, or simply
remove larger files (size more than a stated number of kilobytes in
length). Simply click on the box to enter the number of days or
kilobytes, press ENTER and the selective delete will begin. Afterwards
it will show how many files were deleted. Selective deletes from the
Trash can are slower than normal deletes.

Please note the differences between the second and third options. The
first is that files OLDER THAN x days are deleted, while files trashed
x OR MORE days ago are deleted. A fuller description of the Trash can
mechanism is given below.

Untrash

With this command, files which have already been Trashed can be
restored to their original selves, provided they were (a) placed in
the Trash can rather than deleted as such, and (b) they have not
already been removed from the Trash can. Untrashing a file removes
both the file and its associated _t file from the Trash can, so once
Untrashed, you cannot Untrash again unless the file is Trashed again.
In fact, there is no magic status to the Trash can, you could COPY or
MOVE a file to the Trash can directory using BASIC or another file
handling program, just that if no _t file is created, the program does
not have the necessary information about where the file came from.

+-----------------------------------------+
| [Move]          UNTRASH           [Esc] |
+-----------------------------------------+
|           Trash is WIN1_*_              |
| Untrash selected files to current path  |
| Untrash selected files to original path |
+-----------------------------------------+

The first option simply untrashes files to the location shown in the
other window of Q-Trans and ignores the information about where the
file originally came from. The second uses the path restore
information, so that if the file Trashed was called LETTER_DOC and it
came from a directory called WIN1_QUILL_ it would offer to restore the
file as WIN1_QUILL_LETTER_DOC. If it cannot find the path restore
information (there is no matching _t file or it has been accidentally
deleted from the Trash can) the program will offer to Untrash to the
current DATA default instead, although you can manually edit filenames
when untrashing anyway. So if you ask to untrash a file called
LETTER_DOC and its LETTER_DOC_T file is not present for some reason,
it will offer to Untrash LETTER_DOC To LETTER_DOC instead, and you can
add the drive/directory name yourself if you wish.

View

This command lets you view a file or selected files on screen. For
plain text files, the internal text viewer will probably suffice,
while for other files it is possible to start the file via its
associated File Info 2 program setting, when File Info 2 is installed
and available.

+------------------------+
| [MOVE]  VIEW WITH  [X] |
+------------------------+
|    Internal viewer     |
|    via File Info 2     |
+------------------------+

HIT or DO on the option you require. If you select the File Info 2
option, Q-Trans tries to call the associated program for the file in
question. For example, most File Info 2 users have it set up to load
Quill to load DOC files. Be careful if using File Info 2 and several
files have been selected - you might end up with on-screen chaos if
several associated programs have to be started one after the other!

The internal viewer is a simple to use file viewer which lets you
scroll up and down through a file and step back and forward between
the files selected.

+--------------------------------------------------------------------+
|[MOVE][TOP][UP][PAGE UP][<<]  VIEW  [>>][PAGE DOWN][DOWN][BOTTOM][X]|
+--------------------------------------------------------------------+
| Text is displayed                                               |  |
| in this window                                                  |  |
| as many lines of text                                           |  |
| as will fit!                                                    |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
|                                                                 |  |
+--------------------------------------------------------------------+

The MOVE icon is the usual one allowing the window to be moved
anywhere within the Q-Trans outline. the X icon quits and returns you
to the main screen.

The Top icon (a vertical arrow with a bar across it) takes you to the
start of the file. The Bottom icon (downward arrow with bar beneath
it) takes you to the bottom of the file. The up and down arrows scroll
up or down one line at a time. The double arrows scroll up or down by
a screenful at a time. The double left and right arrows take you to
the previous file selected if there is one, or to the next file
selected.

The narrow window on the right is a position indicator. It shows how
far through the file you currently are. You can click on this to move
to a given point if you wish - the full length of the window indicates
the complete file, while the red box or bar in the window indicates
the visible section - this is a bit imprecise for small files.

If you click on the text in the viewing window itself, various actions
ar epossible depending on whether it was a Hit or Do, and whether it
was in the top half or bottom half of the window.

Hit in top half - text scrolls up one line
Hit in bottom half - text scrolls down one line
Do in top half - text scrolls up by one screenful
Do in bottom half - text scrolls down by one screenful.

If you hold your finger on a mouse button while the pointer is in this
window, the text will continue scrolling. Indeed, if you move the
pointer up and down past the mid-point, the text can be made to 'rock
and roll' up and down. This may prove useful for browsing if scanning
through a file for certain text.

Exit

Quit from the program.


NOTES ON THE TRASH CAN

The following notes are included in case anyone else would like to
implement a compatible system for 'Trashing' files in their own
programs.

The Trash can is a normal QL directory. It is a 'one for all'
solution, the same Trash can is used for all drives. There is no
separate Trash can for each drive.

When a file is Trashed, the following actions take place:

1. The file is copied into the Trash directory.
2. The update date of the original file is read and copied into the
header of the file in the Trash can. Thus the file in the Trash can
retains the same update date as the original file. This is stored at
offset 52 (decimal) in the file header.
3. The date at which the file was Trashed is stored in the BACKUP long
word in the file header (decimal offset 60).
4. A file called 'filename'&'_t' is created (name limited to 39
characters if required to stay within the limit of 5 character drive
name and 36 character filename) and always has '_t' appended. This
contains the full drive+directory+filename of the original file.
5. The original file is finally deleted.

The system is pretty rudimentary but has served me reasonably well
since I first implemented it. It does mean the programmer has to
handle filename length limitations and the special cases such as when
the _t file is missing or a file has been manually copied into the
Trash can directory (BEWARE of using the selective delete from
Trashcan if you suspect files may have been placed there by another
program as the dates stored in the file header may not be as
expected!)


VERSION HISTORY

0.04 - First Beta test release.
0.05 - Second Beta test release, November 2002, contained more bugs
       than the first, especially when copying files between
       sub-directories.
0.06 - 20th December 2002. Improved copying and moving of files
       between sub-directories, if this version is stable it might
       become the first non-Beta release. Added my new email address.
       Filenames displayed in the files list panes are now 'pure'
       filenames, not including directory names where possible. This
       makes it easier to handle cases where files are being moved
       or copied between directories and even allows a degree of
       operation with DEV AND SUB.
0.07 - 11th January 2003. Colour scheme now changed to be consistent
       with Launchpad. Some colour inconsistencies under GD2 ironed
       out (green becoming cyan, etc). MOVE a file, menu used to say
       'Copy' filename to, QTrans now says 'Move' filename to...
       Directory name problems with DOS device on QPC2 up to v3.03
       tackled with limited improvement (FNAME$ on open directory
       channel gives different results with DOS device compared to
       other devices) - QPC2's author says this will be addressed in a
       future release of QPC2 (possibly QPC2 v3.04). Under older
       versions of QPC2, an access to a DOS device immediately goes to
       a root directory - in v0.06 changing from say WIN1_QUILL_ to
       DOS1_QUILL_ may have resulted in errors with name lengths due
       to the different way in which FNAME$ worked.
       Different appearance in QL screen sized menu of directory
       devices list if less than 10 devices now fixed.
       Viewing just last file in a list of files via File Info 2
       association no longer causes attempts at multiple viewing of
       same file until an error occurs.
0.08 - 15th January 2003. Filename placed in stuffer buffer now
       corrected (directory name missing in v0.07)
       Network timeout error message if issued at all (e.g. by Sernet)
       should now appear in F2 or F3 window as appropriate, no longer
       randomly overwriting the menu.
       Attempt at better handling of network names in F2+F3 windows,
       after request by Jon Dent.
       Change made to RENAME command to address possible problems on
       non-SMSQ/E systems.
       Small change to DOS device handling to help Windows 98SE users.
0.09 - 18th January 2003. Parameter coercion problem in MITEM
       statement affecting RENAME command fixed.
0.10 - 19th January 2003. Trash can facility added.
       Configuration block updated for Trashcan.
       No need to configure maximum number of files per list any more,
       as Q-Trans now does a two pass read of files to generate a
       dynamic list. Especially useful when dealing with Trash can.
1.00 - 8th February 2003. Trash can upgraded to allow Untrash and date
       dependent operations, better handling of 'restore original
       path' untrashing thanks to use of _t files, files can now be
       restored with original update dates, Trashcan options menu now
       shows number of Trashed files and total size of those files.
       File statistics facility added. Configuration block updated for
       new facilities.
1.01 - 13th February 2003. Drive Information command added to Commands
       menu. Swap Drives command added to Commands menu. Layout of
       commands menu changed to 3 columns to accommodate new commands
       in smallest possible Q-Trans display height.
       Incorrect colours for messages during formatting now fixed.
       Move menu heading now centered like Copy.
       Esc option when prompted to overwrite during Copy, Move or
       Untrash fixed - did not work on some systems before.
1.02 - 16th February 2003. Status of [OK] loose item after formatting
       a medium now reset correctly.
1.03 - 20th February 2003. Corruption occurred in configuration block
       if string items were configured to become longer than as
       supplied. Now fixed.
1.04 - 13th November 2003. Switching from a sub-directory on WIN1_ to
       non-existent directory on DOS1_ by using the 'DOS' device icon
       causes name length errors, due to differetn way in which SBASIC
       FNAME$ works with DOS device on QPC2. Now, to work around this,
       Q-Trans always goes to the root of DOS1_ to avoid getting
       trapped in a non-existent directory.

Author: Dilwyn Jones
Email : dilwyn.jones@tesco.net


