===== How to use Hermit PicView =====
Version 1.01 release
Copyright (c) the Hermit 1997/8
http://www.celticedge.com/hermit/
e-mail: hermit@celticedge.com
=======================================

CONTENTS 
 l:  conditions of use
 2:  version history
 3:  applet overview
 4:  class files
 5:  the <applet> tag
 6:  the <param> tags
 7:  color values
 8:  hints & tips
 9:  appletdata format
10:  HTML code example
11:  troubleshooting
12:  commercial licenses

Please read this file carefully before contacting the Java Hermit
for technical assistance.


1: CONDITIONS OF USE
====================
PicView may be used freely FOR NON-COMMERCIAL PURPOSES ONLY.
Commercial users require a license. Use is considered to be
commercial if PicView is used for more than 30 days on any
Internet site that offers/advertises goods and/or services
for sale. Use on a private network operated by a commercial
organisation also requires a license. Purchase of a license
permits use on any single web site. Use on multiple sites
requires a separate license for each site. See end of file
for more license information.

PicView must not be sold or offered for download from any other WWW
site without the author's consent. The author retains copyright. The
author accepts no responsibility for any loss, damage or other
consequence alleged to be a result of it's use.

If you use PicView on a free (unlicensed) basis please acknowledge
by arranging a link from your web pages to the Hermit's site, HTML
code examples...

  <A HREF="http://www.celticedge.com/hermit/index.html">
  PicView applet by the Hermit</A>

or you can use the supplied gif file...

  <A HREF="http://www.celticedge.com/hermit/index.html">
  <IMG SRC="picview.gif" WIDTH=88 HEIGHT=31></A>

---------------------- // --------------------------


2: VERSION HISTORY
==================
version 0.90 beta dated 16 November 1997.

version 1.00 release dated 14 January 1998.

version 1.01 release dated 30 January 1998
  DELIMETERS parameter added.
  Repaint flicker reduced.

version 1.02 release dated 23 February 1998
  Buttons code updated.


---------------------- // --------------------------


3: APPLET OVERVIEW
==================
PicView is a multiple image presentation applet written using
JDK 1.0.2. It's designed purpose is the sequential display of
several GIF and/or JPG images each with accompanying explanatory
text. Each image can have an optional link associated with it.

The appearance of the applet is configurable via parameters
(listed below). A list of images, captions, text and optional
links is used to provide data, the structure of which is
discussed below. The list can be in the form of a server based
ascii text format configuration file, or alternatively this
information can be included in the applet parameters.

------------------------ // --------------------------


4: CLASS FILES
==============
PicView uses 4 class files, total size approx 20k...

  PicView.class (main file)
  PVCaption.class
  PVCanvas.class
  PVButton.class

PicView.class is the main file that is specified in the APPLET tag.
Ensure all other class files are present in the same directory as
the main file.

-------------------------- // -------------------------


5: THE <APPLET> TAG
===================
In your HTML code the applet tag should look like this...

    <APPLET CODE="PicView.class" WIDTH=xxx HEIGHT=xxx>
      (PARAM tags go here)
    </APPLET>

where WIDTH= and HEIGHT= specify the exact size in pixels you 
want the applet to be. To fit in your images/text you will have to 
experiment with the sizes until you get it right. Unless you know 
how to use the CODEBASE tag you must place the class files in the
same directory as the HTML file that uses the applet. Remember
class file names are Case Sensitive.

----------------------------- // -------------------------


6: THE <PARAM> TAGS
===================
These specify how the applet behaves. They are inserted in the HTML code 
at the point (PARAM tags go here) in the <APPLET> example above. 

Note that PARAM NAME= entries are not case sensistive but VALUE= entries
may be and, where quotation marks are shown, they should be included
(usually string, path or filename info).

Most params have a default value - if you do not specify them in your HTML
code the default value is assumed.


// appletdata

<PARAM NAME=APPLETDATA VALUE="xxx">
  where xxx is the [path/]name of an ASCII text file containing
  the list of images/captions/text/links to be displayed. File format
  is explained later in this document. If path information is included
  it should be relative to the Document Base (the directory
  containing the HTML file in which the applet is used).
    Alternatively the entire file content can be specified here,
  avoiding the need for the applet to establish a network connection
  with the server. An example of this approach may be seen later in
  this document.
  Default: NONE, this param must be specified.


<PARAM NAME=DELIMITERS VALUE="xx">
  Where xx is the pair of characters recognised as configuration data
  tag delimiters, for example the < and > in <SHOW...> and </SHOW>.
  Default: "<>"


// default links target

<PARAM NAME=DEFTARGET VALUE="xxx">
  Where xxx is the name of a frame or window, or one of the
  reserved names _self, _top, _blank or _parent. This target
  is used for untargeted links specified in the applet data.
  Default: "_self" (the same frame/window that contains the applet)


// borders

<PARAM NAME=BORDERWIDTH VALUE=x>
  Where x is a decimal number between 0 and 8, 
  represesenting the pixel thickness of the applet border.
  Default: 0 (no border)

<PARAM NAME=BORDERCOLOR VALUE=x>
  Where x is the required color of the applet border.
  May be a decimal or Hexadecimal color number.
  Default: #c0c0c0 (silver)

<PARAM NAME=BORDERSTYLE VALUE=x>
  where x is a decimal number between 1 and 4.
  1 = solid, 2 = 3D raised, 3 = 3D sunk, 4 = 3D frame.
  Note: 3D borders only work with medium brightness colors.
  Default: 1 (solid)


// caption

<PARAM NAME=CAPTIONFONTSIZE VALUE=x>
  Where x is the required font size in points.
  Default: 12

<PARAM NAME=CAPTIONBACKCOLOR VALUE=x>
  Where x is the required color of the caption bar background.
  May be a decimal or Hexadecimal color number.
  Default: #FFFFFF (white)

<PARAM NAME=CAPTIONTEXTCOLOR VALUE=x>
  Where x is the required color of the caption bar text.
  May be a decimal or Hexadecimal color number.
  Default: #000000 (black)


// buttons

<PARAM NAME=SCROLLBUTTONS VALUE=x>
  Where x is a decimal number 0 = scoll buttons
  hidden or 1 = scoll buttons visible.
  Default: 1 (visible)

<PARAM NAME=BUTTONBORDER VALUE=x>
  Where x is a decimal number 1 or 2 specifying button
  3D raised border thickness. Othe values are ignored.
  Default: 1

<PARAM NAME=BUTTONCOLOR VALUE=x>
  Where x is the required background color. May be a
  decimal or Hexadecimal color number. Use medium brightness
  colors for correct rendering of 3D button edges.
  Default: #CCCCCC (silver gray)


// list

<PARAM NAME=LISTWIDTH VALUE=x>
  Where x is the required list width in screen pixels.
  Default: 100

<PARAM NAME=LISTFONTSIZE VALUE=x>
  Where x is the required list font size in points.
  Default: 12

<PARAM NAME=LISTBACKCOLOR VALUE=x>
  Where x is the required color of the list background.
  May be a decimal or Hexadecimal color number.
  Default: #FFFFFF (white)

<PARAM NAME=LISTTEXTCOLOR VALUE=x>
  Where x is the required color of the list entry text.
  May be a decimal or Hexadecimal color number.
  Default: #000000 (black)


// font attributes

<PARAM NAME = FONTFACE VALUE="xxx">
  where "xxx" is the facename of the preferred font, for example
  "Verdana". If the font you specify is not available on the host 
  computer the default will be substituted. Remember only 3 fonts
  are guaranteed available in JDK 1.0.2 - Dialog (Arial in Win95),
  TimesRoman and Helvetica.
  Default: "Helvetica"

<PARAM NAME=FONTSIZE VALUE=x>
  Where x is the required font size in points.
  Default: 12

<PARAM NAME=FONTSTYLE VALUE=x>
  Where x is the font style, coded as follows:
  0 = plain, 1 = bold, 2 = italic, 3 = bold italic.
  Default: 0 (plain)


// image/text display area (canvas)


<PARAM NAME=CANVASBACKCOLOR VALUE=x>
  Where x is the required color of the canvas background.
  May be a decimal or Hexadecimal color number.
  Default: #666666 (dark gray)

<PARAM NAME=CANVASTEXTCOLOR VALUE=x>
  Where x is the required color of the canvas text.
  May be a decimal or Hexadecimal color number.
  Default: #FFFFFF (white)

<PARAM NAME=CANVASBORDERCOLOR VALUE=x>
  Where x is the required color of the canvas border. This
  is an optional border between the canvas itself and the
  applet border (see canvasborderwidth).
  May be a decimal or Hexadecimal color number.
  Default: #CCCCCC (silver gray)

<PARAM NAME=CANVASBORDERWIDTH VALUE=x>
  Where x is the width in screen pixels. Use to specify a
  visible border between canvas and applet border/caption.
  Default: 1 

<PARAM NAME=CANVASTEXTALIGN VALUE=x>
  Where x is either 0 (left), 1 (center) or 2 (right).
  Default: 0 (left alignment)


// miscellaneous

<PARAM NAME=IMAGEOFFSETX VALUE=x>
  Where x is the number of screen pixels to offset
  images horizontally.
  Default: 0 (no offset)

<PARAM NAME=IMAGEOFFSETY VALUE=x>
  Where x is the number of screen pixels to offset
  images vertically.
  Default: 0 (no offset)

<PARAM NAME=PARABREAKCHAR VALUE="x">
  Where "x" is a single ascii character to be decoded as a
  paragraph break in the displayed text. Any character can
  be used but you wouldn't want to specify "a" or you'll
  get paragraph breaks all over the place. "~" is usually
  a good choice. Insert it in your text where you want
  a break to occur.
  Default: "" (none)

<PARAM NAME=SAVELASTIMAGE VALUE=x>
  Where x is either 0 (no) or 1 (yes). Setting a value of
  1 (the default) tells PicView to remember which image was
  displayed when the user moves off the web page containing
  the applet. On returning the same image will be presented.
  IMPORTANT - This MUST be set to 0 if you use more than one
  instance of PicView on a web page (not recommended). 
  Default: 1 (yes)

-------------------------- // ----------------------------


7: COLOR VALUES IN PARAM TAGS
=============================
Color values can be decimal or hexadecimal. Decimal values require no
prefix, Hex values can be prefixed with '0x' or '#'. You can't use color 
string constants such as "Red". 'Browser safe' color combinations are
recommended - RGB color triplets made up from the brightness value
hexadecimal numbers 00, 33, 66, 99, CC, FF. For example #0099FF represents
a color mix containing no Red, medium Green, maximum Blue. As you would
expect #000000 = black and #FFFFFF = white.


-------------------------- // -----------------------------


8: HINTS & TIPS
===============
PicView does not allow a scrollable display so you need to ensure
applet width and height are set large enough to display the largest
image/text combination in your list.

When formatting text PicView selects a text position according to
the space taken by the associated image. Text will display either
to the right or below the image. Images are always displayed at top
left of the canvas area. You can use the IMAGEOFFSETX and IMAGEOFFSETY
parameters to specify a border above and to the left of images.

See WARNING about < and > characters and Microsoft Frontpage at end
of following APPLETDATA FORMAT section.


--------------------------- // -----------------------------


9: APPLETDATA FORMAT
====================
To avoid lengthy PARAM statements in your HTML source PicView can
read a simple server-hosted text file that contains your list of
image/text data. This file is specified in the APPLETDATA parameter.

The appletdata filename can be any legal filename. Use any reliable
ASCII text editor to produce it.

Data required by the applet is enclosed (HTML-like) between <SHOW...>
and </SHOW> tags, one pair for each image. Anything you write in the
file (such as comments) outside these tag pairs is ignored by the
applet. Here is the formal declaration for a SHOW tag...

  <SHOW [path/]imagefile | caption | link[,target]> 
  explanatory text 
  </SHOW> 

The first part of the tag contains the image file name with optional
path information, followed by a caption, followed by an optional link
(local reference or full URL). The link can include an optional target
separated from the link itself by a comma. If all your links point to
the same target frame/window you can set it in the DEFTARGET applet
parameter.

File | caption | link are delimited by the | character (shifted
backslash on PC).

The text to be displayed adjacent to the image follows, and the
entry ends with the terminating </SHOW> tag.

Here is the partial content of pvdemo.cfg, the file used for the Java
Hermit web site PicView demonstration (indented for clarity, only first
two entries shown)...


  <SHOW ragdolls.gif|Raggy Dolls>
  A selection of luxury craft kits designed by Maureen Reed. For
  a complete illustrated catalog telephone (UK) 01326 212185.
  ~Note the Hermit has no commercial interest, he just likes teddy
  bears. Particularly vindaloo curried ones with pilau rice and a
  pint of lager.</SHOW>

  <SHOW george.jpg|George|../linktest.html>
  Hello, my name is George. I am made from a woven plush fabric
  with Suedette for paw pads. I have safety eyes, plastic joints 
  and a decorative ribbon. I am 14 inches (36cm) tall. There is
  no truth in the rumour I was caught in the sewing basket with
  Millie.</SHOW>


The second method of supplying the applet with data is to embed
the data file content directly in the APPLETDATA parameter. This
avoids the requirement for the applet to establish a network
connection to read it's data from a server-hosted file. Why might
it be necessary to do this? The server on which your web site resides
might have a firewall that prevents such a connection for security
purposes (rare).

Here is the same data embedded in the APPLETDATA parameter...


  <PARAM NAME=APPLETDATA  VALUE="

  <SHOW ragdolls.gif|Raggy Dolls>
  A selection of luxury craft kits designed by Maureen Reed. For
   a complete illustrated catalog telephone (UK) 01326 212185.
  ~Note the Hermit has no commercial interest, he just likes teddy
   bears. Particularly vindaloo curried ones with pilau rice and a
   pint of lager.</SHOW>

  <SHOW george.jpg|George|../linktest.html>
  Hello, my name is George. I am made from a woven plush fabric
   with Suedette for paw pads. I have safety eyes, plastic joints 
   and a decorative ribbon. I am 14 inches (36cm) tall. There is
   no truth in the rumour I was caught in the sewing basket with
   Millie.</SHOW>

  ">


Note the enclosing VALUE=" and "> before and after the data itself.
Also, because some browser Java implementations don't report carriage
returns/line feeds in PARAM values, it's necessary to include a leading
space at text line breaks to obtain correct text formatting (the
example above is indented for clarity, don't indent in your HTML or the
additional unwanted leading spaces will be included).

WARNING - some html editors (notably Microsoft Frontpage) may attempt to
reformat unrecognised html tags, usually by turning < and > characters
into their special code equivalents &lt; and &gt;. If this happens with
data embedded in the APPLETDATA parameter the applet will not work.
A new parameter, DELIMITERS, has been added (see parameters above) to
permit use of a different character pair - try curly braces { and }.


----------------------------- // ---------------------------


10: HTML CODE EXAMPLE
=====================
Here is the applet code from the Java Hermit site demo HTML file.
Many PARAMs are set to default values and could have been omitted
but are included here for reference. Defaults are indicated by the
trailing <!-- def --> comments... 

<APPLET CODE="PicView.class" WIDTH=310 HEIGHT=212>

  <PARAM NAME=APPLETDATA VALUE="pvdemo.cfg">
  <PARAM NAME=DEFTARGET VALUE="fmain">

  <PARAM NAME=BORDERSTYLE VALUE=4>
  <PARAM NAME=BORDERWIDTH VALUE=0>
  <PARAM NAME=BORDERCOLOR VALUE=#3399CC>

  <PARAM NAME=LISTWIDTH VALUE=100> <!-- def -->
  <PARAM NAME=LISTBACKCOLOR VALUE=#999999>
  <PARAM NAME=LISTTEXTCOLOR VALUE=#FFFFFF>
  <PARAM NAME=LISTFONTSIZE VALUE=12> <!-- def -->

  <PARAM NAME=CAPTIONBACKCOLOR VALUE=#9966CC>
  <PARAM NAME=CAPTIONTEXTCOLOR VALUE=#FFFFFF>
  <PARAM NAME=CAPTIONFONTSIZE VALUE=14>

  <PARAM NAME=SCROLLBUTTONS VALUE=1> <!-- def -->
  <PARAM NAME=BUTTONCOLOR VALUE=#CC9933>
  <PARAM NAME=BUTTONBORDER VALUE=2>

  <PARAM NAME=CANVASBORDERWIDTH VALUE=5>
  <PARAM NAME=CANVASBACKCOLOR VALUE=#333333>
  <PARAM NAME=CANVASTEXTCOLOR VALUE=#CCFFFF>
  <PARAM NAME=CANVASBORDERCOLOR VALUE=#333333>
  <PARAM NAME=CANVASTEXTALIGN VALUE=0> <!-- def -->

  <PARAM NAME=FONTFACE VALUE="Verdana">
  <PARAM NAME=FONTSTYLE VALUE=2>
  <PARAM NAME=FONTSIZE VALUE=12> <!-- def -->

  <PARAM NAME=PARABREAKCHAR VALUE="~">
  <PARAM NAME=IMAGEOFFSETX VALUE=0> <!-- def -->
  <PARAM NAME=IMAGEOFFSETY VALUE=0> <!-- def -->
  <PARAM NAME=SAVELASTIMAGE VALUE=1> <!-- def -->

</APPLET>

--------------------------- // -----------------------------


11: TROUBLESHOOTING
===================
Make sure JAVA is ENABLED in your browser. Remember local testing of applets in 
some browsers may not work because of browser security restrictions. The latest
Win95 browsers (MSIE 4.xx and Netscape 4.xx) appear more likely to run applets
locally without security problems.  

Netscape 3.xx on Win95 can take some time (minutes) to initialise it's Java
virtual machine when asked to run a local applet. Better go make a cup of
coffee while it thinks about it.

Most HTML WYSIWYG editors won't run Java applets in their internal browsers.
It's always essential to final test over a live Internet connection (use a test
page nobody else can view before you release it on the general public).

When you FTP applet files ensure they are sent in binary mode. Note applet
class files are Case Sensistive - your FTP program must not be set to force
all filenames to lower case.

Problems are nearly always caused by spelling mistakes, invalid directory 
information, errors in APPLET/PARAM tags or case sensitivity problems. Check
your tags carefully.

There is a FAQ/problems page on the Hermit's web site. If you have problems
testing your html/applet locally on your own machine you may find some useful
info there.

---------------------------- // -------------------------------


12: COMMERCIAL LICENSES
=======================
At the time of writing the commercial license fee is US dollars 24.00 (2 year)
or US dollars 39.00 (time unlimited). A license covers all Hermit applets,
not just PicView. Please see the Java Hermit web site for current prices
and full license information.

You can purchase licenses online at

    http://www.shareit.com/programs/100627.htm

Alternatively, you can go to http://www.shareit.com and enter the program
number there in the box provided: 100627.

If you do not have access to the Internet, you can register via phone, fax or 
postal mail. Please print out the following form, and fax or mail it to:

Reimold & Schumann Internet Services
ShareIt!
Jahnstrasse 24
50676 Koeln
Germany

Phone:   +49-221-2407279 
Fax:     +49-221-2407278
E-Mail:  register@shareit.com


------------------------- cut here ------------------------------

Java Hermit Applet Collection license application
IMPORTANT - please check with ShareIt! or the Java Hermit
to verify the current license fee amount.


Program/Reference No.: 100627

Last name: ___________________________________

First name: ____________________________________

Company: ____________________________________

Street and #: ______________________________________

City, State, postal code: ________________________________

Country: _______________________________________

Phone: _____________________________________

Fax: ________________________________________

E-Mail: ______________________________________


How would you like to pay the license fee?

credit card - wire transfer - EuroCheque - cash


Credit card information (if applicable)

Credit card: Visa - Eurocard/Mastercard - American Express - Diners Club

Card holder: ________________________________

Card No.: ___________________________________

Date of Expiration : ___________________________________



Date / Signature ___________________________


----------------------------- cut here -------------------------------


// end of file.