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

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
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
-------------
I am not liable for any damage caused by the use of this program.



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.)
The most recent version of Java can be obtained from http://java.sun.com/j2se/
Compiling JGraph requires Ant, which may be obtained from http://ant.apache.org/

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 CVS distribution compiles
with both versions of Java, whereas the binary and source distribution are
only compatible with certain versions of Java. In all cases, the sequence 
of commands is the same, and independent of the Java version.
All distributions require Ant for compilation. Ant requires ant.jar, 
xercesImpl.jar, xml-apis.jar and tools.jar from Java. (Note: Do not type
the newline inside the classpath declarations below!)

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 CLASSPATH=$JAVA_HOME/lib/tools.jar:$ANT_HOME/lib/ant.jar:
                      $ANT_HOME/lib/xercesImpl.jar:$ANT_HOME/lib/xml-apis.jar
     $JAVA_HOME/bin/java org.apache.tools.ant.Main

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 CLASSPATH=%JAVA_HOME%\lib\tools.jar;%ANT_HOME%\lib\ant.jar;
                   %ANT_HOME%\lib\xercesImpl.jar;%ANT_HOME%\lib\xml-apis.jar
     %JAVA_HOME%\bin\java org.apache.tools.ant.Main

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 CVS- and Java 1.3-distribution of JGraph.)
This means that you cannot use the CVS-distribution in an IDE that runs on
Java 1.3. You must use the Java 1.3-distribution in this case.

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:

o On Unix:
     $JAVA_HOME/bin/java org.apache.tools.ant.Main example

o On Windows:
     %JAVA_HOME%\bin\java org.apache.tools.ant.Main example



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 License: BSD-style license
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://jgraph.sourceforge.net/faq.html

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/doc/paper/t1.html, a 
tutorial is available at http://www.jgraph.com/doc/tutorial/t1.html.

5.2 Support
-----------
Support is provided via the Home Page at http://www.jgraph.com/
and Sourceforge project page at http://sourceforge.net/projects/jgraph/
Please review the FAQ and forums before submitting a request.
No support is provided via Email.



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 and JGraphpad are placed under a BSD-style license 
and are available via anonymous CVS or as zip files at 
http://sourceforge.net/projects/jgraph/
JGraph's SourceForge.net CVS repository can be checked out through anonymous 
(pserver) CVS with the following instruction:
cvs -d:pserver:anonymous@cvs.jgraph.sourceforge.net:/cvsroot/jgraph co jgraph
Updates from within the module's directory do not need the -d parameter.



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.



8. License
----------
For legal and licensing issues, please read the LICENSE file.



9. Contact Email
----------------
Gaudenz Alder  (developer)     alder at jgraph.org

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


