pstoedit -- Java 2 backend

# Readme for pstoedit -- Java 2 backend

17 April 2000
Wolfgang Glunz/Gisbert W. Selke

## Contents

- Introduction
- Preparation
- Use within HTML documents
- Viewing the results
- Optional parameters for the applet
- Restrictions, limitations, further development
- Legal stuff
- Authors

## Introduction

The file PSDrawing.java contains the Java 2 source code of the classes needed to run the code generated by the -f java2 option of pstoedit.

## Preparation

To use the output, do (using Java 2, i.e., at least JDK 1.3):

      javac PSDrawing.java

This needs done once only.

Note: You may want to set the DEBUG flag near the beginning of PSDrawing.java to 0 before compiling.

## Use within HTML documents

### Conversion

First, convert PostScript to Java and compile it (assuming you are using the JDK):

      pstoedit -f java2:myclass myfile.ps myclass.java
      javac myclass.java

Alternatively, if you are using GSView, you can do the conversion via the menu item Edit -> Convert to vector format.... You'll still have to compile it either via the JDK compiler or using your favourite Java programming environment.

### Use within Netscape Navigator

Then create an HTML document including code like this (this syntax is for Netscape browsers only):

      <html>
      <head>
      <title>PSDrawing generated by pstoedit</title>
      </head>
      <body>
      <p>This is the applet:</p>
      <embed type="application/x-java-applet;version=1.2.2"
          pluginspage="http://java.sun.com/products/plugin/1.2.2/plugin-install.html"
          code="myclass.class"
          option1="option_value_for_applet"
          width="700" height="500" align="baseline">
        <noembed>
          This applet needs support for at least Java 1.2.
        </noembed>
      </embed>
      </body>
      </html>

### Use within Internet Explorer

Unfortunately, the syntax for the Internet Explorer is quite different:

      <html>
      <head>
      <title>PSDrawing generated by pstoedit</title>
      </head>
      <body>
      <p>This is the applet:</p>
      <object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
          width="700" height="500" align="baseline"
          codebase="http://java.sun.com/products/plugin/1.2.2/jinstall-1_2_2-win.cab#Version=1,2,2,0">
        <param name="code"       value="myclass.class">
        <param name="type"       value="application/x-java-applet;version=1.2.2">
        <param name="option1"    value="option_value_for_applet">
        <param name="scriptable" value="true">
        This applet needs support for at least Java 1.2.
      </object>
      </body>
      </html>

### Use within either Netscape Navigator or Internet Explorer

And if you want to cope with both, and hopefully others, you have to go through considerable contortions:

      <html>
      <head>
      <title>PSDrawing generated by pstoedit</title>
      </head>
      <body>
      <p>This is the applet:</p>
      <object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
         width="700" height="500" align="baseline"
         codebase="http://java.sun.com/products/plugin/1.2.2/jinstall-1_2_2-win.cab#Version=1,2,2,0">
        <param name="code"       value="myclass.class">
        <param name="type"       value="application/x-java-applet;version=1.2.2">
        <param name="option1"    value="option_value_for_applet">
        <param name="scriptable" value="true">
      <comment>
      <embed type="application/x-java-applet;version=1.2.2"
          pluginspage="http://java.sun.com/products/plugin/1.2.2/plugin-install.html"
          code="myclass.class"
          option1="option_value_for_applet"
          width="700" height="500" align="baseline">
        <noembed>
        </comment>
          This applet needs support for at least Java 1.2.
        </noembed>
      </embed>
      </object>
      </body>
      </html>

(Indeed, this is, strictly speaking, malformed syntax. So there.)

### Use within other browsers

If you want still other browsers to at least fail gracefully if they can cope with neither form, you'll have to go to even greater lengths involving JavaScript. Please refer to the documentation for Sun's HTML converter available at http://java.sun.com/products/plugin which the above examples have been adapted from.

## Viewing the results

Then launch a web browser for which a Java 2 plugin exists. If the plugin is not installed, the above code will get it from Sun's site (given that an Internet connection is accessible). Note that currently (early 2000), for most browsers, built-in support for Java 2 is not sufficient, so a simple <applet> tag will not do any longer. If you want to be free from this restriction, use the `-f java` option, which produces Java 1 code, but which has some other limitations.

The applet supports panning by pressing the primary mouse key and dragging.

For testing purposes, using the appletviewer (which comes with the JDK) may be faster than employing a full-fledged browser.

## Optional parameters for the applet

Currently there are 4 optional parameters for the applet.

- The first is called `zoom`. If it is present in the HTML code for the specification of the applet, the user will be presented with zoom in and zoom out buttons. If it starts with a valid positive number, this will be the initial zoom factor at which the applet is displayed. The default value is 1. If it contains another valid number greater than 1, separated by a blank, this will be the zoom step which is applied whenever the zoom-in button is pressed. The default is 1.2.
- The next parameter is `rotate`. If it is present in the HTML code for the specification of the applet, the user will be presented with a rotate button. If it starts with a valid number, this will be the initial rotation (measured counter-clockwise in degrees) at which the applet is displayed. The default value is 0. If it contains another valid number, separated by a blank, this will be the increment in the angle whenever the rotate button is pressed. The default is 90. -- This whole feature is mainly useful for viewing graphics in landscape or skyscape orientation rather than portrait. Note that there is no rotate clockwise button.
- The third parameter is `offset`. Two valid numbers may be supplied (default: 0 0) which specify an initial `x`/`y` shift for the display.
- Finally, for multi-page data, the starting page to be displayed can be specified using the parameter `page`, numbered from 1. Usually, the first page is chosen. Note that the user is offered previous/next buttons automatically whenever more than one page is present. Neither does this depend on the presence of the `page` parameter, nor can it be switched off via a parameter.

### Examples:

- Netscape Navigator:

        zoom="yes"   or    zoom="0.5 1.4" within the <embed ...> tag
        rotate="-90 45"
        offset="-100 200"
        page="3"

- Internet Explorer:

        <param name="zoom" value="yes">  or
        <param name="zoom" value="0.5 1.4">
        <param name="rotate" value="-90 45">
        <param name="offset" value="-100 200">
        <param name="page" value="3">

## Restrictions, limitations, further development

The classes provide limited functionality at the moment. It is work in progress. Topics that need to be addressed include:

- bitmap images are currently displayed in grayscale only; in any case, support is still very sketchy. Do not rely on this to work yet.
- not all types of bitmaps (e.g., CMYK colour model) are supported
- add printing
- add applet parameter for background colour?
- add support for use as stand-alone application (rather than applet)
- add proper javadoc comments to PSDrawing.java

Since the whole thing is pretty much alpha, I'd appreciate bug reports and suggestions on the Java 2 backend. Mail to Gisbert. (Please, do not ask for extensions of the Java 1.x backend. That one is as good as it gets. Please, do not ask me (Gisbert) about functionality of pstoedit in general. I don't even know how it works its magic.)

## Legal stuff

Finally, the source code is covered by the GPL the same way as pstoedit. It is copyright © 1998-2000 Wolfgang Glunz and Gisbert W. Selke. This does not include the code generated by pstoedit! That code is free without any restrictions. See the file Copying in the main directory of the pstoedit distribution for the details of the GPL.

The icons for zoom-in and zoom-out have been nicked from the fine product GSView by Russell Lang/Ghostgum.

## Authors

pstoedit was created and is maintained by Wolfgang Glunz.
Java support was created by Wolfgang, too. It is currently under development by Gisbert W. Selke of TapirSoft Gisbert & Harald Selke GbR.