Short:    Datatype picture viewer for directory tools
Uploader: thomas-rapp@web.de (Thomas Rapp)
Author:   thomas-rapp@web.de (Thomas Rapp)
Type:     gfx/show
Version:  1.9


New since Version 1.8:
======================

-  Option to disable the info bubble

-  Option to open the info bubble by a key

-  Option to scale pictures to fit the screen size, with or without interpolation



Introduction
============

This program is meant to be configured as picture viewer in directory
tools like DirOpus or DosControl. It shows the doubleclicked picture
in a borderless window on the specified custom screen. The remarkable
about this program is that it reads the whole directory the picture is
in and you can then choose other pictures out of this directory from
a menu or by pressing the cursor keys.



Installation
============

Copy the PicShow executable somewhere where your directory tool can
find it. A good place is the C directory.



Configuration
=============

Call PicShow as a Shell program with the following parameters:

FILE             The picture to show first. You can specify a directory
                 here. In this case the directory is read first and then
                 the topmost picture is shown.

PUBSCREEN/K      The pubscreen where to open the window. Default is the
                 default pubscreen (usually Workbench).

P=PATTERN/K      Only picture files that match this name pattern are
                 shown in the list.

FLASH/S          Flashes the screen (displays beep) after the directory
                 read is complete.

DONTCHECK/S      Files are not checked if they are pictures before they
                 are inserted into the list. This does speed up the
                 directory read a lot, but files that are no pictures
                 are shown in the list, too. You should use the
                 PATTERN parameter to avoid this.

DELAY/N/K        Enable slide show: every n/10 seconds the next picture
                 is shown (DELAY=20 means every 2 seconds a new picture).

SCREEN/S         Open a new screen for PicShow

BG=BACKGROUND/K  Background color for the new screen. Format is six
                 hexadecimal numbers: rrggbb
                 rr = amount of red color (00 - ff)
                 gg = amount of green color (00 - ff)
                 bb = amount of blue color (00 - ff)
                 Default is 000000 (black).

PORT/K           Name of the Arexx port.
                 Default is PICSHOW.

MODEID/N         Decimal ID of screen mode. Default is same as Workbench.

DEPTH/N          Depth to use for custom screen. Default is same as
                 Workbench.

QUIET/S          Disabled error requesters when picture cannot be loaded

CLOSEWB/S        Attempt to close Workbench when screen is open

REQ/S            Force PicShow to open a file requester. FILE is taken as
                 preset file name.

KEYS/K           Name of a file that contains key bindings

NOINFO/S         Disable the info bubble. It can be opened by a key anyway.

SCALE/S          Enable scaling. Pictures will be scaled up or down to fit 
                 the screen size.

INTERPOL/S       Scale pictures using interpolation. Needs much more time
                 than without.


If PicShow is started from the Workbench all of the above can be entered as
tooltypes, either in the program icon or in the picture icon that is
activated first. Tooltypes in the picture icon overide those in the program
icon. Picture icons can be activated by shift-click or by specifying
PicShow as default tool.

There is one additional option that can only be activated as ToolType:

KEY=<key binding>    Rebind one key. May be specified multiple times for
                     different keys. Read the section about key bindings for
                     an explanation of <key binding>.

Example:  KEY=X=QUIT     enable the key X to quit PicShow



Usage
=====

When the window showing a picture is open you can do this:

NOTE: these are the default keys. Read the section about key bindings to
      learn how to change them.

o  Quit PicShow 
   -  double click into the window or
   -  press the ESC key or
   -  press Q

o  Show the next picture
   -  press the cursor down key or
   -  press the cursor right key or
   -  press the cursor down or right keys on the numeric keypad or
   -  press space bar or
   -  press return

o  Show the previous picture
   -  press the cursor up key or
   -  press the cursor left key or
   -  press the cursor up or left keys on the numeric keypad or
   -  press backspace (the <- key above return)

o  Show some infos about the current picture
   -  keep the mouse pointer inside the window and don't move it for
      some time (can be disabled by an option)

o  If the picture is too large to fit into the screen
   -  grab the picture with the left mouse button and move it around.

o  Choose a picture from the list
   -  press the right mouse button and hold it down. The list can scroll
      up and down if there are more files than fit into one page. Just
      move the mouse pointer over the arrow(s).

o  Read a new directory 
   -  Press F1

o  Swap display from Workbench to PicShow's own screen and back
   -  Press F10

o  Invert the background color of PicShow's own screen (e.g. from black 
   to white and vice versa)
   -  Press F9

In the example file PicShow.keys the following additional keys are defined:

o  Copy the displayed picture into RAM:
   - Press C

   The file name is "pic<number>_<width>x<height>x<depth>.<type>".
   Example: pic0001_640x480x8.ilbm
   This is only an example. Read the section about key bindings for a 
   description on how to configure your own shell commands.

o  Open the picture list 
   - press M

o  Open the info bubble
   - press I



Arexx port
==========

The name of the ARexx port is PICSHOW. It can be changed by the parameter
(or tooltype) PORT. The following commands can be sent to the Arexx port:


QUIT                Exit PicShow.

NEXT                Show next picture.

PREV                Show previous picture.

MENU                Open the picture list.

SCREEN              Toggle screen / Workbench.

SCREEN <ON|OFF>     Open or close the screen as desired.

PUBSCREEN <name>    Set the pubscreen name to a new value.

FILE <file>         Show the named picture and read the new directory.

REQ                 Open the file requester.

FLASH <ON|OFF>      Enable/Disable beep as desired.

DONTCHECK <ON|OFF>  Enable/Disable file checking as desired.

DELAY <n>           Set the delay time to a new value. 0 = OFF.

BACKGROUND <color>  Set the background color to a new value.

PATTERN <pattern>   Choose a new file name pattern.
                    Must be set before FILE or REQ.

INVERTBG            Invert background color of PicShow screen.

DEPTH <depth>       Change current screen depth (if screen is open)

MODEID <id>         Change current screen mode id (if screen is open)
                    Id is a decimal mode id inquired for example with
                    GetModeID (included in the Visage archive on Aminet)

SETDEPTH <depth>    Set screen depth for next open

SETMODEID <id>      Set screen mode id for next open
                    Id is a decimal mode id inquired for example with
                    GetModeID (included in the Visage archive on Aminet)

CHANGE              Reopen screen and apply the above changes.

QUIET <ON|OFF>      Dis-/Enables error requesters.

CLOSEWB <ON|OFF>    Set CLOSEWB flag as desired.

KEYS <filename>     Load a new key bindings file

KEY <key binding>   Rebind one key.

INFO                Show the info bubble

INFO <ON|OFF>       Enable or disable the automatic info bubble

NOINFO              Disable the automatic info bubble




Key bindings
============

Key bindings are read from the files 

S:PicShow.keys
env:PicShow.keys
PROGDIR:PicShow.keys
CURRENTDIR:PicShow.keys
the file specified by the KEYS function

if they exist. Each file can contain any number of keys, one per line.

Everytime I talk about a <key binding> in this readme, the following format
is meant:

<key>=<command>

The <key binding> may not contain any spaces (except after the SHELL
command).

<key> can be any key description that also a commodity would accept as a
hot key, except qualifiers like shift, alt and ctrl.

Examples:

a, b, c, 1, 2, 3,           Normal keys
numpad 1, numpad 2, enter   Keys on the numeric key pad
f1, f2, f10, help           Function keys
return, del, backspace      Special keys
up, down, left, right       Cursor keys

<command> is what the key should do. Valid commands are:

QUIT                   Exit PicShow.
NEXT                   Show next picture.
PREV                   Show previous picture.
MENU                   Open the picture list.
SCREEN                 Toggle screen / Workbench.
REQ                    Open the file requester.
INFO                   Open the info bubble.
INVERTBG               Invert background color of PicShow screen.
SHELL <command line>   Execute the command line as a shell command.
NOP                    Unbind this key.

In the command line of the SHELL command the following placeholders can be
used to include information about the current picture:

%p   Path
%f   File name
%n   Number (starting with 1 at the top of the list)
%w   Width
%h   Height
%d   Depth
%t   Type

The placeholders can contain any modifiers that a C format string accepts
(for example %04n for a 4 digit number to the left padded with 0's),

Please look into the file PicShow.keys for examples.



Future Ideas / ToDo
===================

-  blend effects when changing displayed picture

-  palette requester for the background color

-  read configuration from ENV variable

-  configuration editor

-  use multitasking instead of multithreading to speed up responsiveness.

-  preload pictures for more speed (needs multitasking)

-  optimize window handling when in custom screen mode (don't open a new
   window for each picture but blit directly into the background window)


Known bugs:

-  Scaling does only work well on >8bit screens. On <=8bit screens,
   pictures are first dithered and than scaled; looks ugly.