________________________________________________________________________

Program Name:   SmartOpenDir
Purpose:        Intelligent directory opener
Author:         Tony Houghton
Version:        1.30 (3 April 2003)
Requirements:   RISC OS 3.1 or later
Status:         Freeware
________________________________________________________________________

Contact details:

Tony Houghton
271 Upper Weston Lane
Woolston
Southampton
SO19 9HY

mailto:riscos@realh.co.uk
URL:http://www.realh.co.uk

Note: you will require the latest !System 32bit files to use this.
You can get these from http://www.iyonix.com/32bit/system.shtml

________________________________________________________________________

Important news
______________

The comment character has changed from # to double quote (") so that you can
have a # at the start of a pattern.

Licence
_______

SmartOpenDir is distributed under the terms of the GPL. See the file COPYING
for details.

Overview
________

In general I prefer to use the default options in my filer display, but for
some directories it's more useful to use small icons or full info or sort by
date etc. SmartOpenDir allows this to be done automatically by matching any
directory about to be opened against a set of wildcarded patterns and setting
the filer display options immediately before displaying it.

SmartOpenDir isn't especially user-friendly to configure, but the philosophy
behind it, apart from doing its job as seamlessly as possible, is to achieve
it with minimum programming effort, so the user has to do some of the
calculation of values that might otherwise be left to the program. The source
is provided for anyone who might want to work on improvements in this area.

Loading
_______

It's set up as an application, !SmartDir, which automatically loads the
module with its default Patterns file when run. This is ideal for adding to a
Risc PC boot sequence.

If you want to load the module "manually", uase a line like the following:

RMLoad SmartDir [-a] [-f <Patterns filename>]

Both optional parameters are recommended. -a causes an alias to be set for
Filer_OpenDir, redirecting it to the SmartOpenDir command, which is an
extended version of Filer_OpenDir, opening directories intelligently. If set,
the alias will automatically be reset when the module is killed. The Patterns
filename following the -f parameter is a text file containing a list of
wildcarded directory patterns and their corresponding filer options.

Commands provided
_________________

SmartOpenDir                    Extended Filer_OpenDir with pattern matching
SmartOpenDirLoad <filename>     Loads a replacement Patterns file

Patterns file syntax
____________________

A Patterns file is a text file with one or more lines of the following
syntax:

Pattern         Code

Any number of tabs or spaces may be used between fields. Lines
beginning with tabs or spaces or the double quote (") character are comments.
Patterns are matched on a first matched first used basis, so a specific
pattern can be included before a more general pattern which would otherwise
include the specific one.

The Pattern consists of a directory name with the following wildcards:

  #     Match any single character
  *     Match any number of characters
  %     Match until the next directory separator (.) or end of filename

The Code consists of two hexadecimal digits, affecting bits 0-3 of a flags
word. The first digit is the mask. Any bits set in the mask cause the
corresponding bits to be cleared in the flags. The second digit is the value
to be ORed with the masked flags value. The bits have the following meaning:

Bits 0-1: Icon options  0     = Large icons
                        1     = Small icons
                        2     = Full info
                        3     = Reserved
Bits 2-3: Sort options  0     = Sort by name
                        1 (4) = Sort by type
                        2 (8) = Sort by size
                        3 (C) = Sort by date

Therefore the only values likely to be useful for the mask are:

        0       leave everything alone
        3       affect icon display options only
        C       affect sort options only
        F       affect display and sort options

If using with RISC OS 4 the only mask value likely to be of any use is F. See
the file "RISCOS4" for more details.

Look at the supplied patterns file for examples. The first 8 patterns are for
C source and header directories etc, opening them with small icons. The
second !NewsDir entry is for Newsbase's "debug" backup news and mail folders,
opening them with small icons and sorted by date. Read on for an explanation
of the last option.

Extended codes
______________

There are 5 extended codes which take one of these forms:

        1nnppqq
        2llppqq
        3llnnppqq
        4llnnppqq
        5llnnppqq

where ll, nn, pp and qq are 2-digit hexadecimal values. The first digit and
ll and/or nn represent conditions, while pp is the code (see above) to use if
the condition is not met, qq is the code to use if the condition is met. ll
represents a limit on the length of any filename in the directory, nn on the
number of files in a directory. The first digit decides how breaking of these
limits should be interpreted:

        1       True if number of files is exceeded
        2       True if filename length is exceeded
        3       True if either limit is exceeded (OR)
        4       True if both limits are exceeded (AND)
        5       True if one bot not both limits are exceeded (XOR)

The final line in the supplied Patterns file dictates that if any directory
which hasn't already been matched is opened, then if it contains more than 24
(&18) objects or a filename longer than 16 (&10) characters it will be opened
with small icons, otherwise it will use the configured options.

Precautions
___________

Nothing special, but SmartOpenDir gives you one more reason to shut down the
computer properly before switching off; otherwise the last directory opened
could end up leaving the configuration set that way.

If you manually click any option in the Filer Display submenu, all subsequent
directories will be opened with *all* of the display options as set in that
menu, which may have been affected by SmartOpenDir whose effect was intended
to be temporary.

If using the -a option, it will clash with any other aliases set for
Filer_OpenDir.

Acknowledgements
________________

SmartOpenDir was inspired by Ian Clark's SmallDir. It had a number of
limitations though, and after some experiments it became clear that a
completely different approach was needed.

Thanks to Michael Rozdoba for a performance enhancement and small bug fix in
1.11.

Technical details
_________________

First let me say that SmartOpenDir is a module, which does not have
particularly complex or extensive code, written in C. Some may consider this
a flagrant breach of RISC OS programming ettiquette, but I have some points
to make in my defence:

  The module is under 12K in size, and its total memory use is less than the
  minimum size of 32K required by a USR-mode task on a 4MB Archimedes.

  If I'd had to worry about the intricacies of assembler, I might not have
  bothered writing it at all, and it certainly wouldn't have got done so
  quickly.

  Writing a module in C was a useful learning exercise.

SmartOpenDir uses a "two-pronged attack" to ensure that all directories get
opened intelligently and as seamlessly as possible.

Its first line of attack is to implement a new command to replace
Filer_OpenDir, and redirect the original command to it using an alias. The
Filer itself does not use the command when opening a directory when
double-clicked on etc, or when Adjust-clicking a close icon, so
SmartOpenDir's second line of attack is to filter events being sent to the
Filer.

Either way, when a directory is about to be opened it temporarily
reconfigures the computer to use the relevant options, resetting the
configuration the next time the filer receives an event.

SmartOpenDir used to "cheat" a little to find whether the number of objects
in a directory was above or below a given value, using a single SWI with a
reasonably small buffer. This was found to cause crashes when used with CDFS,
so I've switched to a longer-winded approach.

SmartOpenDir may cause a delay when opening a directory containing many
objects, but I think it's worth living with for the benefits it brings.
