JavaFIG - Usage and man page

This page presents a short overview over the JavaFIG functions and the typical usage. Where necessary, I also provide hints about common mistakes and workarounds for JavaFIG bugs. At the moment, this page is the only online-documentation about JavaFIG. Related information can be found in the man-pages and documentation for the XFIGdiagram editor and the TRANSFIG package.

This page is structured as follows:

  1. How to get JavaFIG, and how to get it running?
  2. How to participate!
  3. JavaFIG editor window components (GIF screenshot with short explanation).
  4. Using JavaFIG: basics and object creation
  5. Using JavaFIG: object editing
  6. Bugs and features

1. How to get JavaFIG - and how to get it running

Despite all kinds of magic needed to achieve this with the current Java release, JavaFIG runs as both an applet or standalone application. For a first test, just can download JavaFIG as an applet into your Java 1.1 compatible WWW-browser from here. Probably, you will already have done it - or you won't be reading this documentation.

However, you should consider to download the JavaFIG class archive and to install the JavaFIG classes locally on your computer. This allows file access from the editor and it will greatly improve initialization and start-up time.

1.1 Running Javafig as an applet

Because JavaFIG consists of about 600KB of class-code, loading the applet may take some time. Please be patient ;-)

During initialization, JavaFIG will open a separate editor frame window and tell you to wait until initialization is complete.

Also note that not all classes are preloaded on start-up. If JavaFIG appears to hang, it may just be waiting for some class loaded on demand. Again, I recommend to install the JavaFIG classes locally.

Please take a look at the applet's HTML file and especially the applet tag parameters.

Applet file access

Note that applets are not usually allowed to access (read or write) files or to open a network connection to any computer other than the server they come from. To get file access, install the JavaFIG classes to your computer (see below) and run JavaFIG as an application.

When running JavaFIG as an applet, you can therefore load only the examples provided on our server in the examples directory. To do this, select the File... -> Open URL... menu item and specify the corresponding URL.

You may not be able to save your drawing when running inside a Browser, depending on the Browser's security settings. In that case, select the write to console menu item. This will create and show a FIG 3.1 representation of your drawing in a separate text window. You may then select all text inside this window, copy the text to the clipboard (paste buffer), and from there to a file on your computer. Not very convenient, but it works.

1.2 Installing JavaFIG to your computer

To download an archive with all JavaFIG classes, just get one of the following compressed file archives: ZIP/JAR archive Besides all .class files needed for JavaFIG, the archive contains some documentation and examples.

Unpack the classes to some directory you like, e.g. /users/hendrich/classes/javafig (Unix) or C:\java\classes\javafig (Windows) and be sure to set the CLASSPATH environment variable to include the directory with the JavaFIG classes. The details of the CLASSPATH variable depend on the operating system, Java development system, and WWW browser you use: please consult the documentation for your tools about how to set the CLASSPATH. Without setting the CLASSPATH variable, you will only be able to start JavaFIG from exactly the directory you installed it into.

The main JavaFIG editor class is therefore not called JavaFIG but javafig.gui.MiniEditor. and you start JavaFIG as an application with the following command: java javafig.gui.MiniEditor or java javafig.gui.MiniViewer for the FIG-file viewer.


1.3 Installing TRANSFIG to your computer

At the moment, JavaFIG does not support printing. Instead, it relies on the transfig package to convert a FIG 3.1 format drawing into several other output formats - especially Postscript. In order to print you drawings, you will therefore need to install the transfig package to your computer or to get access to a Unix/Linux system where transfig is already installed. Most Linux distributions come with a complete version of both Xfig and transfig. Just unpack, install, and compile. For other systems you might want to locate an up-to-date version of transfig on a FTP-server near to you with Archie (or a similar tool). After download unpack the transfig archive and try to compile. While Postscript format is supported by transfig - which is fine for most Unix and all Macintosh systems - PCL is not. On a Windows system you might therefore need another program (e.g. Ghostscript) to convert the transfig Postscript output to a format you can actually print :-(

2. How to participate

A lot of functionality is still missing from JavaFIG. As you might have guessed, I only included the functions I typically need. For example, JavaFIG runs on all Java platforms, but it relies on a Unix/Linux computer with Xfig/transfig installed for picture export and printing. (I use JavaFIG at home on my notebook under Windows'95 and I print the drawings at work on our Unix servers...)

If you would like to improve JavaFIG by providing additional editing functionality, additional objects, import- and output filters and especially a better line-drawing algorithm --- please tell me about it. I will provide you with the necessary information for writing the extra classes.

If you find a bug that is not already in the bug-list please complain about it.

Mail all comments, hints, and bugs to Norman Hendrich (hendrich@informatik.uni-hamburg.de)


3. JavaFIG editor window components

The following (old) screenshot shows the JavaFIG editor window running as an applet inside Netscape 2.01 on a SPARCstation:

Xfig users will easily recognize most of the user interface.


4. Using JavaFIG

4.1 Basics

JavaFIG is an modal diagram editor based on Xfig. At every time JavaFIG is in exactly one editing mode and mouse clicks are interpreted according to this mode. For example, in polyline creation mode all mouse clicks are used to create new polygons or to add points to polylines. In object move mode, you can only move objects, while point move mode is used to move points in polylines etc.

Any operation can be interrupted by pressing the ESC-key (Escape), causing JavaFIG to delete the last temporary unfinished object and to enter 'idle mode'.

JavaFIG will read and write FIG 3.1 files. It has been tested with all of the standard Xfig 3.1 examples and a lot of our own Xfig drawings. At the moment, no other file formats are supported. Conversion of FIG 3.1 format files to Postscript format or into several TeX-related file formats (PIC, EEPIC, LaTeX, PicTeX, ...) is possible with the Transfig package.


4.2 Help

While JavaFIG displays a 'Help...' menu, the online help so far is limited to very basic information. When running JavaFIG as an applet, you can always load this file to reread about some command, and afterwards go back to JavaFIG - this will leave any unsaved drawing inside JavaFIG intact. Note the help messages generated by the user interface components of JavaFIG.

4.3 Coordinates

All object coordinates in JavaFIG are internally maintained in integer coordinates at 2400 dpi. This allows for easy conversion to printers and similar devices, which typically operate with multiples of 300, 600, or 1200 dpi.

The rulers and the drawing grid may be displayed in multiples of the units: a factor of 2400 is used for inches, a factor of 960 to approximate mm (less than 1% error), and a factor of 800 to approximate the inch-to-mm conversion used by Xfig (about 10% error between Xfig mm and real mm values).

JavaFIG supports four different levels of a drawing grid as a visual aid. The grid is automatically rescaled on zooming in order to provide a grid spacing of about one centimeter on the display. The grid mode is controlled via the Grid & Zoom... menu. Select 'no grid' to deactivate the grid. Drawing the 'fine grid' may take some time on slow computers.

Beside the drawing grid, JavaFIG also uses a 'magnetic' grid to snap the mouse cursor to fixed positions in order to allow exact object alignment. The allowed mouse positions are multiples of the current visual grid spacing. Select the 'magnetic grid' via the Grid & Zoom... menu or the grid mode button on the bottom of the editor window. To deactivate snapping select 'no snap' or the 'ANY' (ANY point position) of the state button.


4.4 Viewport and object display

JavaFIG support arbitrary zoom factors and image size. Naturally, the image size is limited by Integer.MAX_VALUE (corresponding to about 4km at 2400dpi), and memory requirements :-)

To change the viewport transformation, use the Zoom & Grid menu or the zoom buttons. The zoom-in and zoom-out buttons change the zoom factor by a factor of two. Pressing zoom-1:1 will restore the zoom factor to the default. Numerical values can be set using the Zoom... dialog window.

To change the current viewport offset use the cursor keys (unfortunately, this does not work with Netscape under Unix with the default key mappings) or the rulers. The top and bottom / left and right ends of the rulers work similar to a standard scrollbar. Clicking the mouse over these areas will pan the current viewport by 1/5th of the viewport size. Hold down the SHIFT-key while clicking to pan by 4/5th of the viewport size.

Additionally, you may click somewhere in the middle of the rulers and then drag the mouse (holding the mouse button down) to a new position over the ruler. This will pan the viewport by the specified amount.

Select the 'origin' button or the Zoom & Grid... -> Origin menu item to reset the viewport panning.


4.5 Object creation

Before trying to create some new objects please always finish any ongoing previous operation (e.g. by pressing ESC). Afterwards select the corresponding object mode via the menu Create... -> xxx or by pressing one of the action buttons on the left side (top button group).

Currently, JavaFIG supports the following objects:

Watch the help and status messages when in doubt about what action JavaFIG expects and/or allows. For example, to create some polylines (using the current object attributes) do the following:
  1. Finish the ongoing previous operation.
  2. Press the polyline button.
  3. Move the mouse to the start point of the polyline and click the left button. This will create a polyline object with the first point.
  4. Move to the next point and click the mouse (left button).
  5. Repeat the previous step to append further points to the polyline.
  6. Move to the end point and click the right mouse button. This will finish the polyline object.
  7. Move to the start point of the next polyline and click the left button to draw the next polyline. Repeat steps 4 to 6 as needed.
It is no good idea to double-click on a coordinate. Also, JavaFIG may behave strange if you first click-left on a point and afterwards click-right again at the same point. This is a bug.

Use the corresponding buttons or menu items to create the other JavaFIG objects. For objects with a fixed number of control points/corners only the left button needs to be clicked on the desired coordinates. For objects with arbitrary number of coordinates use the left button to start objects and to append middle points, and the right button to finish the object.


4.6 Text objects

To create a text object, select the desired font and font size (in points) and text alignment. Move the point to the base point of the text object (the left baseline point for left aligned texts, the right baseline point for right alignes texts, etc.) and click the left mouse button. Enter the text for the text object.

Pressing the RETURN (ENTER) keys will finish the text object and automatically start a new text object below the previous object. This allows to quickly enter several lines of text with the same font and alignment. Note, however, that text objects therefore may not contain newline (CR/LF) or escape (ESC) characters.

Pressing the BACKSPACE key will erase the previous character of the text object. To edit a finished text object use the edit object mode explained below.


4.7 Image objects

To include an embedded GIF or JPEG image into your drawing:
  1. Press the 'image' button to select 'image mode'
  2. Move to the opposite corners of the desired image bounding box
  3. Enter the URL of the image to be included into the corresponding Dialog window.

    Due to bugs in the JDK-1.0.x on Windows'95, this dialog window will sometimes 'hide' behind the main JavaFIG editor window. If this happens, iconize the main JavaFIG window, enter the URL, and deiconize JavaFIG. Complain to Sun Microsystems.

  4. JavaFIG will instantly display the image bounding box and asynchronously start to load the image. The image is not displayed fully, until you change the JavaFIG viewport transformation (e.g. by Panning or Zooming). This is a feature, not a bug.

    Note that the Java JDK 1.0.2 will *not* render images on black and white displays (e.g. a SPARCstation ELC) correctly, but displays the images in white on white ;-) Again, complain to Sun Microsystems.


5. Object editing

The following screenshot image shows one selected (left) and one normal (right) object each:


Reading and writing files


last modified: 27.03.98 Norman Hendrich