_____________________________________________________________________________

                             P h o t o F i l e r

                Picture thumbnailing extension for the Filer

                           Written by David Thomas
                         for Sliced Software,  1998

                          version 1.00 (28 Jun 1998)
_____________________________________________________________________________

____________

Introduction
____________

PhotoFiler is a utility program which adds the ability to thumbnail
pictures to the Filer.

With PhotoFiler loaded, a miniature version of the picture is shown in
directory displays in place of the usual file type icon.  This is very
useful for organising collections of pictures, as it enables you to rapidly
identify the contents of a picture file just by looking at its icon.

In addition to thumbnailing, PhotoFiler provides additional controls over
the presentation of icons in directory displays.  You can define your own
icons for directories which will be used instead of the usual directory
sprites.  This is ideal for providing a graphic representation of a
directorys purpose.

PhotoFiler also attempts to alleviate a long-standing problem - that of the
pling (!) character in front of application names.  These can hidden from
view in directory viewers, giving neater looking directory displays.

PhotoFiler requires RISC OS 3.6 or later.  RISC OS 3.5 is supported, if the
SpriteExtend 0.99 and DrawFile 1.46 modules are available.

PhotoFiler is SHAREWARE.

________

Features
________

  Sprites, JPEGs and DrawFile pictures are thumbnailed in the background
   and displayed in place of the file type icon.

  Full control over the dithering of thumbnails is provided for Sprites
   and JPEGs.

  Pictures which are found to be faulty are shown with a warning symbol.

  Directories can be given customised sprites by merging a sprite into the
   common sprite pool.  Sprites can be provided for the four possible
   directory states of open/closed and selected/unselected.

  The pling symbol (!) can be removed from the start of application
   names, giving neater looking directory displays.  This modification
   occurs in display only so that sorting orders are not affected.

  PhotoFiler is transparent in operation, written in 100% ARM assembler.
   None of the Filer modules code is modified, meaning that PhotoFiler
   uses very little memory itself.

_________

Interface
_________

Icon Bar Icon

  SELECT on the icon bar icon opens the Control Panel.
  MENU opens the icon bar menu.

Control Panel

The control panel is available by clicking SELECT on the icon bar icon.

  Show Sprite thumbnails        When set, sprite files will be thumbnailed.
    Simple dithering            Performs a simple dithering technique on
                                  the thumbnail.
    Application sprites         Forces thumbnailing off for sprites that
                                  are part of applications.

  Show JPEG thumbnails          When set, JPEG images will be thumbnailed.
    No dithering                Quickest, but lowest quality, thumbnails.
    Simple dithering            Medium speed, medium quality, thumbnails.
    Error diffusion             Slowest, but highest quality, thumbnails.
                                  (Note that youre unlikely to notice
                                  any great speed/quality difference
                                  between these last two options).

  Show Draw thumbnails          When set, DrawFiles will be thumbnailed.

  Hide application plings       When set, applications will have their
                                  initial pling character (!) removed
                                  from view.

Icon Bar Menu

  Quit
  -> Control panel only         Removes PhotoFilers control panel only,
                                  the module - which does the work - will
                                  remain active.
  -> All of PhotoFiler          Removes PhotoFiler completely from memory.

________

Features
________

Thumbnails

PhotoFiler generates thumbnails on the fly as soon as you open a directory
viewer containing Sprites, JPEGs or DrawFiles.

The first thing you will notice upon opening such a directory is that the
pictures usual file icon is shown in shaded grey until the thumbnail is
generated.  You will normally only see this icon for a fraction of a second,
especially on faster machines, as even the largest thumbnails take only a
few seconds to load and render.  Once the thumbnail is ready, it is
displayed in the place of the icon in the Filer window.  Thumbnails are
processed in the background so you can continue to use the desktop whilst
thumbnailing is taking place.

Only icons that are visible on screen are seen by PhotoFiler.  This means
that if you scroll a directory viewer to reveal more icons, they will then
be noticed by PhotoFiler and processed.

PhotoFiler can handle any number of thumbnails in any number of directory
displays simultaneously, although things will slow down proportionately with
the number of directory displays that are active.


PhotoFiler always attempts to generate the largest size thumbnail it can,
given the aspect ratio of the picture and the amount of space available for
the thumbnail in the Filer window.

The maximum size of a thumbnail sprite is 172 by 74 OS units, which equates
to a maximum of 86 by 37 pixels in a typical square pixel mode.  Due to the
way Filer windows are laid out, any thumbnails bigger than that would be
displayed incorrectly and obscured by the text of the filename.

Thumbnails are always created in the current screen mode so that the user
has control over the quality vs. memory tradeoff.  If you change screen
mode, thumbnails will not be re-rendered to the new mode.


Sprite Thumbnails

Sprite thumbnails are thumbnailed using RISC OSs sprite scaling features.

When the Show application sprites option is off, PhotoFiler will not
generate thumbnails for files with the word Sprites in their name.  This
stops most sprite files belonging to applications being shown.  (Note that
this check is case-sensitive).

If a sprite has no palette present then the default desktop palette is used.
This matches the behaviour of RISC OS Paint when its Use desktop colours
option is on.

Only the first sprite in any multiple-sprite file will be shown.


JPEG Thumbnails

The JPEG rendering feature of RISC OS 3.6 and later is used to generate
thumbnails for JPEG images.

JPEG images are always tested for completeness and integrity before being
rendered.  This means that partial or corrupt JPEG files will not be
presented as thumbnails.

The RISC OS JPEG rendering calls are quite particular about the files that
they will render.  Images with certain non-standard settings in the file
header will often be rejected.  You may wish to obtain a copy of the
JPEGTrans utility which can clean and optimise JPEG images.

Progressive JPEGs cannot be thumbnailed, unless they are first converted to
normal JPEGs by using JPEGTrans.

 Freeware, by Chris Egan of Skullsoft. http://www.eganc.demon.co.uk/


DrawFile Thumbnails

PhotoFiler uses the DrawFile module, built into RISC OS 3.6 and later, to
generate thumbnails of DrawFiles.

Before being thumbnailed, the DrawFile is (mildly) validated to ensure that
it can be rendered correctly.  Any file that fails the validation will be
shown with the error symbol.

The DrawFile module performs no anti-aliasing when scaling down, so
thumbnails may look innacurate with respect to the original file.  This is
especially evident if Thin lines are used in the DrawFile.

If fonts are used in the DrawFile, then a large font cache will speed things
up.

________________________

Custom Directory Sprites
________________________

PhotoFiler can adjust the sprite used by the Filer to represent directories.
This is done by defining a new sprite for each possible directory icon
state.

                                     Sprite name  Small sprite name
                                       
        Directory closed, unselected   #dirname      sm#dirname
        Directory closed, selected     $dirname      sm$dirname
        Directory open, unselected     %dirname      sm%dirname
        Directory open, selected       &dirname      sm&dirname

If no sprite is found for the current sprite state, then the Filers default
display will be used.  (This behaviour isnt ideal, and may be revised in a
future version).

Note that when a custom directory sprite is in use, the text of the icon
will not be inverted when selected as usual.

_________________________

Hiding Application Plings
_________________________

With the Hide application plings option selected, the names of
applications displayed in Filer windows will be adjusted so that their
initial pling character (!) is removed.

The advantage of this is that it gives cleaner looking directory displays
and is potentially less confusing for novices.

The character is only removed from the display of the name, it does not
affect the physical name of applications on your disc or in any other part
of the system.

Using this option will not affect the sorting order of directory displays.

_____

Notes
_____

Suppressing Thumbnailing

Holding down Ctrl when opening a new directory display will suppress
thumbnailing for that directory.

Automatic Quit

Adding -autoquit to the last line of !PhotoFiler.!Run will make the front-
end automatically quit once the module is initialised.  This is useful for
use in desktop boot sequences.

Sprite Cache Dynamic Area

Even if you use the All of PhotoFiler option to quit, PhotoFiler will not
fully remove its PhotoFiler sprites dynamic area.  This is not a bug.

When PhotoFiler is active it points the sprite area control block of each
newly created directory display directly to its own sprite area.  If
PhotoFiler is removed, these pointers remain in place.  Removing the sprite
cache dynamic area whilst these directory displays are still in use would
cause a crash, so the area is in left in place but reduced in size as much
as possible.

If PhotoFiler is later restarted, then it will automatically take over any
existing sprite cache area.

Bugs in RISC OS

Unfortunately, PhotoFiler is affected by a number of faults in RISC OS. 
They are detailed here to explain some of PhotoFilers more esoteric
behaviour.

1. There is a bug in both current variants of the SpriteExtend module - the
   RISC OS module which deals with JPEG images.  The bug is three redundant
   instructions which perform a read from an assumed location in the
   controlling tasks wimpslot.  This causes an abort on data transfer
   exception if the calling application has less than 24K of wimpslot.

   Since PhotoFiler is not a wimp task, it has no wimpslot, so calling
   SpriteExtend to render JPEG images will always fail.  PhotoFiler
   automatically fixes this bug by copying the SpriteExtend module into RAM
   and disabling the redundant instructions.  This fix takes approximately
   75K of memory.

2. There is another bug in RISC OSs own sprite handling code which causes
   apparently random crashes.  PhotoFiler includes a work-around fix for
   this. The net result of this is that PhotoFiler has to claim at most 4K
   more sprite memory than it actually needs.

3. And again, there is another bug in SpriteExtend which means that JPEGs
   which scale to one pixel in either thumbnail dimension will be rejected
   in order to prevent a machine crash.

___________

Limitations
___________

  PhotoFiler works by filename alone, and for reasons of speed does not
   monitor file operations, so if you delete a picture then rename another
   file or directory to the same name, the previous thumbnail will be used
   for that object.

  Pictures are loaded whole into memory before being rendered.  Pictures
   which are too large to load will be shown with the warning icon.

  If PhotoFiler should run out of memory, then it will start showing
   thumbnails with the warning icon.  If memory is in very short supply
   then PhotoFiler will ignore the icons completely.

  PhotoFiler slows down the window redraw speed of the Filer.

_____________

Compatibility
_____________

It is unlikely that PhotoFiler will work in conjunction with any other
programs that tries to provide the same sort of functionality.  This
includes programs such as Album, ProFiler and Filer+, for example.

Utilities such as (my own) QuickFiler will work, as it services a different
area of functionality.

______

Future
______

 - Support for ArtWorks files.
 - Resolution of first limitation (see above).

________

Versions
________

1.00 (28 Jun 1998)
  - First general release.

_______

Credits
_______

Many thanks to go to Justin Fletcher for his original source upon which this
program is based and to the brave souls who took part in the testing of
prerelease versions.  Thanks to Andrew Clover for the WimpSWIVe module.

_______________

Sliced Software
_______________

Sliced Software is an Acorn Registered Developer.

_________

Copyright
_________

This software (PhotoFiler) is copyrighted work of David Thomas, it is
supplied to you, the user, as is; you use this application entirely at
your own risk.  The author makes no warranty as to the fitness of this
software for any purpose.  In no circumstances will the author be liable
for any loss arising from the use or inability to use this software.

THIS SOFTWARE IS SHAREWARE.  PLEASE ABIDE BY THE SUPPLIED CONDITIONS OF USE.

_____________________

Contacting the Author
_____________________

If you have any comments, bug reports or suggestions for future versions
then you can contact me via:

        Post:  Mr D.P. Thomas
               20 Rosebery Avenue
               Waterloo
               Liverpool
               L22 2BH

        Mail:  photofiler@sliced.demon.co.uk

        Web:   http://www.sliced.demon.co.uk/software/photofiler/
        
If you have a question, then please check it has not already been answered
in this documentation before mailing.
_____________________________________________________________________________

