JGraph - The JFC/Swing Graph Component (c)2001-2005

A component to display and edit graphs (networks) with Java

by Gaudenz Alder


TABLE OF CONTENTS
*****************

1. Disclaimer
2. Installation
   2.1 Requirements
   2.2 Compiling
   2.3 Obtaining a Java 1.3 Release
3. What is it?
   3.1 Purpose
   3.2 Features
   3.3 History
4. Overview
   4.1 Implementation
   4.2 Architecture
5. Getting Help
   5.1 Documentation
   5.2 Support
6. Obtaining JGraph
   6.1 Binaries
   6.2 Source Code
7. Misc
   7.1 Tips and tricks
   7.2 Showcase
8. License
9. Contact Email



1. Disclaimer
-------------
Please read the license under which your version of JGraph is licensed for any
warranty limitation.



2. Installation
---------------

2.1 Requirements
----------------
o  JGraph for Java 1.3 requires a Java 1.3 or later compatible virtual 
   machine for your operating system. (Java 1.4.1 is recommended.)
o  JGraph for Java 1.4 requires a Java 1.4 or later compatible virtual 
   machine for your operating system. (Java 1.4.1 is recommended.)
   Java 1.5.x is known to work correctly.
o  Apache Ant.   
   
The most recent version of Java can be obtained from http://java.sun.com/j2se/
Compiling JGraph requires Ant. To obtain Ant go to http://ant.apache.org/
and select Binary Distributions of the left hand side navigation. Select the 
nearest mirror then download the compressed file appropriate for your platform
(.zip for Windows and .tar.gz for UNIX). Then decompress the file into your
selected directory path for the Ant binaries.

2.2 Compiling
-------------
The project has the following directory structure:

src/      Source root
examples/ Examples root
build/    Build environment
dist-*/   Distributables

The compilation of JGraph requires Ant and the build.xml file. The same build
file is used for all distributions. However, the binary and source distribution
are only compatible with certain versions of Java.

o On Unix, type the following depending on the location of Java and Ant:
     export JAVA_HOME=/usr/java/j2sdk1.4.1_02
     export ANT_HOME=/usr/ant/ant-1.5.4
     export PATH=$PATH:$JAVA_HOME/bin:$ANT_HOME/bin/

o On Windows, type the following depending on the location of Java and Ant:
     set JAVA_HOME=c:\jdk1.3.1_06
     set ANT_HOME=c:\ant-1.5.4
     set PATH=%PATH%;%JAVA_HOME%\bin;%ANT_HOME%\bin

The build.xml file will automatically insert the TransferHandler.java file into 
the source tree and modify a series of source files when used with Java 1.3.
(The TransferHandler ships with the Java 1.3-distribution of JGraph.)
You must use the Java 1.3-distribution in an IDE that runs on Java 1.3.

The build.xml file offers the following targets:

- all (*)      --> Clean up and produce all distributions
- apidoc       --> Generate the API specification (javadoc)
- build        --> Run all tasks to completely populate the build directory
- clean        --> Delete all generated files and directories
- compile      --> Prepare (migrate) and compile the source tree
  - migrate    --> Migrate source code to Java 1.3
  - prepare    --> Copy source code to build directory
- dist         --> Produce fresh distributions
- distclean    --> Clean up the distribution files only
- doc          --> Generate all documentation
- init         --> Initialize the build; create directories, call tstamp
- jar          --> Build all Java archives (JARs)
- make-example --> Compile the example tree
- example      --> Run the main example UI

(*) all is the default target.

Target names may be appended to the above Java commands. For example,
to compile and run the example UI type the following:

ant example

2.3 Obtaining a Java 1.3 Release
--------------------------------
You must download a source distribution to create a Java 1.3 source tree.
The Java 1.3-compatible source code may be created using the build target
in a Java 1.3 environment. Make sure to use the source code from the build
directory in your development environment. The source code in the build
directory is a modified version of the original source tree. The original
source tree does not work with Java 1.3.



3. What is it?
--------------
The intention of this project is to provide a freely
available and fully Swing compliant implementation of a
graph component.

3.1 Purpose
-----------
With the JGraph zoomable component, you can display objects
and relations (networks) in any Swing UI. JGraph can also be
used on the server-side, for example to read a GXL graph,
apply a custom layout algorithm, and return the result as an
SVG image.

3.2 Features
------------
o Edge Editing: Add/Remove/Edit Points; Connect, Disconnect; Labels
o Moving/Sizing: Transaction-Based, with Live-Preview
o Selection: Single-Cell and Marquee Selection.
o Zoom: Arbitrary  Zoom; Uses JavaTM 2D
o Layering: View-Dependent Inter- and Intracell Layering
o Grouping: Children Selectable; Uses Tree-Interface
o Grid:Customizable Size, Color, Appearance
o In-Place Editing: Direct Text Editing for all Cells
o View Attributes: Cells have Separate Attributes for each attached View
o Ports: Multiple Connection Points for each Cell
o Handles: Flexible Interface for Cell-Modifications
o Drag and Drop: Between JGraphs, JVMs and other applications/OS
o Clipboard: Supports Multiple Transfer Formats
o Command History: Multi-View; for all available Operations
o Look-and-Feel: All Swing Pluggable Look-and-Feels
o Routing: Customizable Routing with default algorithms
o Visibility: Hide edges, vertices and groups
o Attribute-Split: Per attribute control of view-only attributes
o Clustering: Folding/Unfolding of groups into vertices
o Ant-based: Ant-based build environment
o Precision: Double precision coordinates
o Labels: Draws labels along edges



4. Overview
-----------

4.1 Implementation
------------------
The following design principles guided the implementation
of JGraph:
  
o Full Swing Compatibility
o Clear & Efficient Design
o Short Download Time
o 100 % Pure JavaTM

4.2 Architecture
----------------
No need to learn another complex product! JGraph integrates
nicely into the Swing component class hierarchy, because it
is based on the Swing MVC pattern. The API and implementation
complies with the JavaTM Code Conventions. All classes in
JGraph have their equivalents in Swing, and all features are
fully Swing compatible.



5. Getting Help
---------------
The FAQ is at http://www.jgraph.com/faq/

5.1 Documentation
-----------------
The API specification is included in this distribution and also available at 
http://api.jgraph.com/. For additional information, updates, binaries and 
source code see the Home Page of JGraph at http://www.jgraph.com/
A paper is available at http://www.jgraph.com/paper.html, and a
tutorial is available at http://www.jgraph.com/tutorial.html.

5.2 Support
-----------
Community support is available through the Community section of the JGraph
web site at http://www.jgraph.com/community.html. On this page the process
of finding help is explained. Please note that no free support is provided
via email.

Commercial support is available for pre-paid support time blocks, 3, 6 or 12
months maintainance, general consultancy or JGraph application development.
Contact sales (at) jgraph (dot) com for more details.

Customers purchasing JGraph are given priority for answers of the forum. This
is not assurance of getting your question answered, but when the development
team have free time, they will answer yours first. You, obviously, need to
indicate you have purchased JGraph, providing the shareit purchase number.

The purchased version of JGraph also contains a number of examples as well
as a version updating guide and the JGraph Adapter example.



6. Obtaining JGraph
-------------------
The Home Page of JGraph can be found at http://www.jgraph.com/

6.1 Binaries
------------
The Binaries of JGraph are distributed on
http://sourceforge.net/projects/jgraph/

6.2 Source code
---------------
The sources of JGraph are placed under the LGPL and a commercially oriented
license, and the LGPL version is available via anonymous CVS or as zip files 
via the download link at http://www.jgraph.com/download.html.


7. Misc
-------

7.1 Tips and Tricks
-------------------
To create multiline labels you can use HTML. Here is an example:
<html>first line<br>second line</html>
The following key bindings are supported by default: 
o Alt-Drag: Force marquee selection
o Shift-Select: Extend selection
o Control-Select: Toggle selection
o Control-Drag: Clones selection
o Shift-Drag: Constrained drag
To add and remove bends (edge points) you can press the right mouse button 
while holding down the Shift key. To use the quadratic and bezier line style 
the edge must have 1 and 2 intermediate points respectively.

7.2 Showcase
------------
Please send screenshots to showcase@jgraph.com.

7.3 Other JGraph packages
-------------------------
Also available are JGraph Layout Pro, JGraph Addons and JGraphpad.

JGraph Layout Pro is a package of commercial-grade layout routines supporting
the full range of JGraph features. The layouts are speed optimised and come
with an application note explaining how they are used. Layout Pro comes with
an example application that demonstrating features such as auto-layout,
collapsing/expanding of grouped cells, graph morphing and selective layouting
of sub-graphs.

JGraph Addons is a community driven package providing graph layouts, algebra,
example cell view and various i/o format support. Addons is licensed under
the BSD license.

JGraphpad is an example application built on JGraph and JGraph Addons. It
serves as a technology demonstration showcasing all of the features available
in JGraph and Addons. JGraphpad is licensed under the GPL and a commercially
oriented license.


8. License
----------
For legal and licensing issues, please read the LICENSE file.
All source and binaries in this package remain copyrighted to Gaudenz Alder.



9. Contact Email
----------------
Sales                          sales (at) jgraph (dot) com
Commercial Support             support (at) jgraph (dot) com

For more information please visit
http://www.jgraph.com/
