ImgView 3.6b Java Applet Copyright (C) 1998, 1999 Mihai Munteanu This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. You can contact me at: * http://www.obs-us.com/people/mihai * e-mail: munteanu_m@yahoo.com * Mihai Munteanu str. M.Eminescu 44 2200 Brasov, ROMANIA * fax: +40 (0)68 410330 This fille contains a description about how to install and use the ImgView applet. CONTENTS: 1. FEATURES 1.1 Usage 1.2 Compatibility 1.3 Main Features 2. Package Content and Installation 2.1 Package Content 2.2 Installation 2.3 What You Would See after Installation 2.4 The APPLET Tag 2.4.1 APPLET Tag Example 2.4.2 The WIDTH, HEIGTH and CODEBASE Attributes 2.4.3 The Applet Parameters 3. The Configuration File 4. Compatibility 4.1 Applet Compatibility 4.2 Known Incompatibility Problems 5. History IMPORTANT NOTES: The applet is called Image View. The class file of this applet is called ImgView.class. Sometimes in this document the applet is called ImgView. The two names refer the same applet. 1. FEATURES Image View 3.6b is an image browser and viewer java applet. It is fully customisable and has browsing and zoom controls. Image View 3.6b is compatible with all java enabled web browsers. 1.1 Usage The applet was designed for web sites with many images such as: image archives, on line exhibitions, photo albums, slide shows and many more. It can be used in Internet Web sites, intranet or off line for personal photo albums. 1.2 Compatibility The Image View applet was tested in most of the common web browsers and in many operating systems. It is created using Sun’s java developer kit 1.02. It means that it is 100% pure java and it is compatible with any java 1.02 or java 1.1 virtual machine implementation. The Class file was tested using Sun's JavaPureCheck tool. It obtains the 100% Pure Java Certification for both java 1.02 and java 1.1. See section 4 for a complete list of browsers and operating systems that I used to test the applet . 1.3 Main Features The applet allows the user to browse through large photo archives, using a list that contains the images captions, and to display the chosen images. By default the images are fitted in the display area, but the applet has zoom controls that allow the user to explore the details of the images. The applet displays the images while loading. It also displays a custom caption below each image. The applet is widely customisable using the applet parameters and a very simple configuration file. The customisable items are: - The size of the applet. - The number of the images - Images’ filenames, paths and captions - Most of the colors - The zoom in control - The layout style It works with both JPG and GIF image format. There are some limitations with the animated and transparent GIFs. They are not working in some browsers (see section 4.2). There are no limitations for the images sizes. By default the image is fitted in the display area. The number of pictures is limited only by the java virtual machine implementation. It should be up to at least few hundreds. 2. Package Content and Installation 2.1 Package Content Unpack the zip file in an empty directory. Make sure you preserve the same directory structure as presented below. The imgview3.6b.zip archive contains the following files: ImgView.README.txt this file ImgView.class the main class file ImgView.html contains the APPLET tag example ImgView.java the source ImgView.toc configuration file error.jpg contains "Image not found" error message gnu_gpl.txt GNU GENERAL PUBLIC LICENSE pics/ subdirectory. Contains sample images autumn.jpg brasov.jpg carpathians.jpg sample images gentians.jpg map.gif mmmUtil/ subdirectory ReadParam.class contains auxiliary functions used by the applet HelpWindow.class The class file of the help (info) window 2.2 Installation Open ImgView.html in a java enabled web browser. See section 1.3 for more details about what you would see. The package in the zip file contains all the files needed by the applet. It works without editing any configuration file. You can change latter the configuration file to place your images in different directories (see section 3). To ensure that the applet will work, the following files must be always in the same directory: IMPORTANT NOTES: The applet can NOT work without ImgView.toc file. It contains images' file names, paths and optionally a caption for every image, displayed bellow the image. error.jpg is a file with the image displayed when the applet couldn't find an image on the server. If this file is not in the same directory with the class file, when the applet couldn't find an image, the applet will behave strange and will not work any more!! You can replace it with any other jpg image named error.jpg. 2.3 What You Would See after Installation After loading the ImgView.html file in a java enabled browser, you would see the applet. It has the following regions: The display area with its scroll bars - on the upper part. The caption area - bellow the display area. The browsing controls: -Next and Previous picture buttons -A list with all the captions The zoom controls - there are 4 buttons placed on the bottom side of the applet: 'Fit', '1 : 1', 'Zoom In' and 'Zoom Out' buttons. If you see the text: ‘Your browser can't run java applets...’ it means that your browser do not run java applets or the java is disabled. You should use Netscape or internet explorer version 3 or newer, HotJava browser, or other java enabled browser or an applet viewer. 2.4 The APPLET Tag 2.4.1 APPLET Tag Example The applet tag in the ImgView.html file looks like: Your browser can't run java applets... 2.4.2 The WIDTH, HEIGTH and CODEBASE Attributes Depending on your web page design and on your pictures, you can size the applet using the WIDTH and HEIGTH attributes. There is a lower limit. The width of the applet has to be bigger than 240 pixels and the height bigger than 180 pixels. The components size and the display area are automatically resized. If a new displayed image is bigger than the display area, by default the image is fitted to the display area. Add a CODEBASE attribute if the class file is in a different directory than the HTML file that contain the APPLET tag. 2.4.3 The Applet Parameters The tag has the following parameters: numberOfPhotos maxZoomIn backColor titlesColor listBackColor buttonsColor buttonsPrevNextColor layoutType You can use these parameters to customise the colors, layout and behaviour of the applet numberOfPhotos parameter is used by the applet to allocate memory for the specified number of photos. The applet works well without this parameter but to minimise the resources used by the applet, a good idea is to fix it not much bigger than the number of the images from the configuration file. The default value of this parameter is 1024. IMPORTANT NOTE: If the parameter 'numberOfPhotos' is smaller than the number of photos found in the ImgView.toc file, the applet displays only 'numberOfPhotos' images. There will be a message on the standard output of the applet (java console). maxZoomIn parameter sets the maximum size of the zoomed-in image. If the value of this parameter is X, the maximum zoomed-in image will be about X times bigger than the 1 to 1 image size. If the images are large, a good idea is to set this value to a lower value not to wait to long for image re-sizing. For images about 500x400 pixels a reasonable value for maxZoomIn parameter would be 3-4. A bigger zoom is often useless for normal images. The default value is 3. Use backColor, titlesColor, listBackColor and buttonsColor parameters to customise the colors of the applet. An example about how to use this color parameters is: In this example: 0 is the value of the RED component of the color 102 is the value of the GREEN component of the color 204 is the value of the BLUE component of the color These 3 values must be separated using commas. Extra spaces are ignored. * backColor - background color of the display area. * titlesColor is background color of the image caption. * listBackColor - background color of the list that contains the images captions. * buttonsColor - background color of the buttons (except "next" and "prev" buttons). * buttonsPrevNextColor - background color of the "next" and "prev" buttons The default colors are: backColor - black titlesColor - yellow listBackColor - white buttonsColor - light gray IMPORTANT NOTE: listBackColor and buttonsColor may not work in some older browsers. Also the result of using these two parameters looks different with different window managers. Try to use only small variations of these colors from the default colors: light grey for buttons and white or white grey for the list. layoutType parameter sets the layout style of the applet. The default value is "large". Possible values are "large" or "compact". The large version of the layout is the same as in the previous version 2.10 and it contains all the controls. In the compact version of the layout the list of the images is not displayed and the "next" and "previous" buttons are layed down horizontally. It makes the applet controls area smaller leaving more space for the photos 3. The Configuration File ImgView.toc is the configuration file for the ImgView applet. This file must be placed in the same directory with the applet class file (ImgView.class). For an example look inside the ImgView.toc file extracted from the imgview3.6b.zip archive. All lines that do NOT start with '*' character are ignored. So you can easily insert comments. A '*' at the beginning of a line means that next characters until the first space or tab character are a file name. The file name must contain the relative path to the file from the directory where the applet (ImgView.class) is placed. Examples: *image.jpg the image .jpg is in the same directory with the class file. *images/image.jpg the image .jpg is in a sub-directory called images, placed in the same directory with the class file. *../image.jpg the image .jpg is in the upper directory of the directory where the class file is placed, and so on. The image caption must be placed on the same line as the filename. After the filename, and one or more space or tab characters, a '>' character means that the text which follows until the end of the line is the caption for the image. The applet displays this caption under the displayed image in the caption area. If there is no caption for an image, the applet will use the file name as a caption. 4. Compatibility 4.1 Applet Compatibility The Image View applet was tested in most of the common web browsers and in many operating systems. It is entirely created using Sun’s java developer kit 1.02. It means that it is 100% pure java and it is compatible with any java 1.02 or java 1.1 virtual machine implementation. This is a list of the browsers used to test the applet: in win95: Netscape 3.0, 3.04, 4.0, 4.02, 4.06, 4.51; internet explorer 3, 4 in Linux: Netscape 4.06, 4.08 in Sun and Solaris: Netscape 3.04, 4.6, HotJava 1, 2 The applet was also tested using Sun’s appletviewer from jdk 1.02 and 1.1.4, on win95 and Solaris. And finally, the class file was tested using Sun’s JavaPureCheck tool. The applet Image View 3.6b has the 100% Pure Java Certification for both java 1.02 and java 1.1. 4.2 Known Incompatibility Problems The Image View Applet was tested with most of the common web browsers, under many operating systems (see previous section). Custom colors for buttons and the list may not work in some older browsers. Also the result of using these two parameters looks different with different window managers. Try to use only small variations from the default colors: light grey for buttons and white or light grey for the list. In some browsers there are problems with transparent and animated GIFs. Try to avoid this files. Anyway if the browser works with animated GIFs it will display only the first frame of the animation. If the browser works with transparent GIFs, the transparent color will be replaced with the background color from the display area. The scroll bars of the display area behave a bit strange in Netscape 3.0 and internet explorer 4, but they are still fully working. In some browsers (ie4) the image is a flickering during loading and when using scroll-bars, especially for big images (bigger than about 500x500 pixels). 5. History ImgView 1 - April 98 - basic functionality, no zoom controls, no customisable colors ImgView 2.10 - October 98 - zoom controls added - applet parameters customisable colors - improved (faster) loading of the pictures - info/help button ImgView 3.6 - June 99 - new applet parameter to control the layout style (compact or large). Thanks to Robert Kaplan for the layout suggestions. ImgView 3.6a - June 99 - add new parameter for next/prev button colors. Fix compact layout buttons width. Thanks to Robert Kaplan for the layout suggestions. ImgView 3.6b - August 99 - Eliminate the annoying behaviour of help button. Now it only opens the help window and does not change the picture display area. It also makes the applet smaller and faster!