Welcome to the JGo (tm) Evaluation kit

JGo, JGoLayout, and JGoInstruments for Swing, version 5.40
Northwoods Software Corporation

JGo requires the Java 2 platform (1.2 or later) and depends on Swing and Java2D.

The evaluation kit version of JGo is fully functional, but has some reminders
that it is only an evaluation version.  The source code for the libraries are
not included, but the sources for the examples are in this kit.

You can purchase a license for the full JGo source kit or for the JGoLayout
and JGoInstruments binary libraries at our web site:
  http://www.nwoods.com/go


Platforms

  JGo has been tested with the following environments, all on Windows:
    Sun Java 2 SDK-SE 1.4.2, 1.5.0, 1.6.0
  but should run with older versions (1.2+) and on other platforms (Linux, Mac OS X).
    
  The example applications were compiled with and expect the JRE 1.4+
  functionality.  If you need to use an older version of the JRE, you will
  need to comment out and recompile the code that depends on the mouse wheel
  or on XML libraries.

  If you are using Sun's J2SDK/JRE 1.4.0 on Windows, please upgrade
  to 1.4.1 or later.  If you must use 1.4.0, Sun recommends using
  the -XX:-UseThreadPriorities command-line option to reduce the
  frequency of short freezes during drag-and-drop operations.


Features

Version 5.4

  Version 5.4 adds the ability to easily create thin-client web applications
  using JGo diagrams in Java Server Pages (JSP).

  - Created new JGoWeb.jar containing com.nwoods.jgo.web
  - Added JGoJPEGView to the JGo base library
  - Added JGoImageServlet to the JGoWeb library
  - Added JGoImageEventProcessor to the JGoWeb libary
  - Add 4 new JSP sample applications:
      webminimalreadonly:
        an extremely small sample application demonstrating the creation of
        a read-only JGo diagram on a JSP web page.
      webuserguidesample:
        a sample application described in a new chapter in the JGo User Guide
        illustrating the major features of JGo JSP web applications.
      webdragdropeditor:
        a sample application including a pallet of sample objects that can
        be dragged, dropped, and interconnecting in a work area on a web page.
        Selected object properties are displayed and can be modified via the web page.
      webprimates
        a sample application containing a large diagram that can be browsed via scrolling and zooming.  
        Additional details about diagram nodes are made available as tooltips.  Both scrolling and 
        tooltips are handled locally on the client browser for good performance.

  If you are upgrading from version 5.3 to version 5.4:

  - There are no known incompatibilities between version 5.3 and 5.4.


Contents

  ./  - Release Notes (this README file)
      - JGo.jar, containing the JGo package *.class files
      - JGoSVG.jar, containing support for persistence using SVG
      - JGoLayout.jar, an evaluation version of the layout library
      - JGoInstruments.jar, an evaluation version of the instruments library
      - a BAT file for compiling and running the examples using the JDK on Windows.
      - a shell file for compiling and running the examples using the JDK on Unix.
      - example applications (executable JARs)

  ./docs  - User Guides for JGo, JGoLayout, and JGoInstruments (.pdf)
          - API Reference manual for JGo, JGoLayout, and JGoInstruments (.html)
          - license agreement files

  ./com/nwoods/jgo/svg  - a partial DTD file describing the SVG XML extensions used by JGo;
                          read the comments in this file for more information

  ./com/nwoods/jgo/examples  - some example classes:
        Comment class implements an area displaying text in a JGo3DNoteRect
        GeneralNode classes together implement SimpleNode with varying numbers of ports
        ListArea classes implement an area containing a scrollable list of objects
        MultiPortNode classes together implement a node with an image and a variable number
          of ports at arbitrary positions, and a draggable label
        RecordNode class uses a ListArea and associates ports with each item in the list
        SimpleNode classes together implement a node with an image, a label and two ports
        SVGGoView class renders output-only SVG files for a JGoView
        MinimalApp class implements a minimal applet/application
        BasicApp class implements a simple application using rectangular BasicNodes
        IconicApp class implements a simple application using IconicNodes

  ./com/nwoods/jgo/examples/demo1  - see the basic capabilities of JGo in an application

  ./com/nwoods/jgo/examples/boxapp  - a simple demonstration of using a JGoArea as a container

  ./com/nwoods/jgo/examples/classier  - a simple app that displays the JGo class hierarchy

  ./com/nwoods/jgo/examples/family  - a simple app that displays a family tree

  ./com/nwoods/jgo/examples/flower  - a more complicated app that edits workflow processes

  ./com/nwoods/jgo/examples/instrumentdemo  - an app for displaying several different kinds of instruments

  ./com/nwoods/jgo/examples/jtreeapp  - a simple app demonstrating use of Swing JTrees as nodes within a JGoView
  
  ./com/nwoods/jgo/examples/layoutdemo  - an app for experimenting with the layout package
  ./com/nwoods/jgo/examples/layoutdemo/files  - several data files containing example graphs

  ./com/nwoods/jgo/examples/processor  - another more complicated app for editing graphs of
                                         nodes with varying numbers and positions of ports
                                         connected by orthogonal links that avoid crossing nodes
  ./com/nwoods/jgo/examples/processor/images - images used in the app

  ./com/nwoods/jgo/examples/sampleapp - the sample application built in chapter 9 of the User Guide

  ./com/nwoods/jgo/examples/svg  - the SVGImage class, for displaying SVG as a JGoImage object

  ./com/nwoods/jgo/examples/updatedemo  - a simple demonstration to show how updates happen

  ./com/nwoods/jgo/examples/webwalker  - a simple app that walks web pages and draws a tree

  ./com/nwoods/jgo/examples/webminimalreadonly  - a minimal Java Server Page (JSP) web application

  ./com/nwoods/jgo/examples/webuserguidesample  - a simple JSP web app described in User Guide

  ./com/nwoods/jgo/examples/webdragdropeditor  - a JSP web app desmonstrating a drag-drop editor

  ./com/nwoods/jgo/examples/webprimates  - a JSP web app demonstrating a large diagram with tooltips

Examples

  You can run the sample applications immediately by executing command lines in
  in the top-level JGo directory, in the following manner, using JRE 1.4.1 or later:

    java -jar Demo1.jar

  You can build and modify the example apps yourself.  You can run the command
  file in the root directory to recompile and run all of the examples, after
  you edit it to make sure the paths are correct.

  Note that for the evaluation kit, the sources for the JGo libraries are not
  supplied; but of course they do come with the source kit for JGo.  The sources
  for JGoLayout and JGoInstruments are available separately--please contact
  GoSales@nwoods.com.

  However, you should be able to create new applications using JGo and JGoLayout
  and JGoInstruments or incorporate JGo and JGoLayout and JGoInstruments into
  your existing applications easily enough.

  The examples will compile and run with the basic SDK-SE functionality.
  However, some of the examples have latent functionality that depends on
  optional Java extensions.

  You will need to build the image editor web application in an environment
  that supports J2EE web applications:
  - the examples/imager web application depends on servlets
  Please note that running the evaluation versions of JGo on the server
  will cause JOptionPane message boxes to show up--you will need to click
  on this before the server can respond with the image that JGo renders.
  Please note also that JGoWebApp.war was compiled with JDK 5.0 (1.5);
  if your environment is using an earlier version of the JRE, you will need
  to compile the sample sources yourself.

  You will need to un-comment-out the relevant code and recompile in order
  to use certain extended features:
  - the examples/SVGGoView.java class depends on Apache's Batik's SVG generator


Licensing

  After you have purchased a license to JGo, you may distribute the supplied
  jar files or the files contained in those jar files, without royalties to
  Northwoods Software.  The same applies to JGoLayout and JGoInstruments.

  The software license is fully described in the docs/FullLicense.txt file.
  
  For distribution we recommend including only the files you need from our
  JAR files in your own JAR file, because this simplifies application management
  as well as decreasing disk space or download time.


Known Bugs and Misfeatures

  Problems with bugs in JRE previous to 1.4 have been deleted from this list;
  please refer to older JGo release notes for details.

  Sun's J2SDK/JRE 1.4.0 on Windows exhibits frequent "freezes" of your application
  for a couple of seconds.  The problem is not inherent to JGo.  See Java
  Developer Connection bug 4669873.  Upgrade to 1.4.1 or later.

  With Sun's JRE 1.5.0, updating of text may be off a pixel, causing text to
  appear muddled.  This is particularly true when the view's scale is not 1.0.
  You will need to upgrade to J2SE-RE 5.0 Update 2, 1.5.0_02 or later.


Support

  If you have any questions, send e-mail to:
    jgo@nwoods.com

  It would be helpful if you told us:
    - which version of JGo you are using
    - which JDK/JVM you are using
    - which platform you are running on
    - which development environment
    - how to reproduce the problem (if any) with some concise code
    - what features you would like to see

This Release
============

Detailed list of changes between 5.3 and 5.4:

  - Added JGoJPEGView class to JGo base library.  This is the JGoView base class that should be used
    for all JGoViews used in JSP pages.  This class is able to generate a JPEG image corresponding
    from the diagram shown in the view.  See chapter 8 "JGo Web Applications Using Java Server Pages 
    (JSP)" in the JGo User Guide for more details.

  - Added JGoImageServlet to the JGo base library.  This is the image servlet that should be referenced
    in the <img> element in a JGo JSP page.  See chapter 8 "JGo Web Applications Using Java Server Pages 
    (JSP)" in the JGo User Guide for more details.

  - Added JGoImageEventProcessor to the JGo base library.  The JGoWeb.js javascript functions handle 
    local mouse events resulting from user interaction with the diagram on a web page.  Arguments generated
    from these events are automatically passed back to the server and processed by the JGoImageEventProcessor
    class.  See chapter 8 "JGo Web Applications Using Java Server Pages JSP)" in the JGo User Guide for 
    more details.

  - Add 4 new JSP sample applications:
      webminimalreadonly:
        an extremely small sample application demonstrating the creation of
        a read-only JGo diagram on a JSP web page.
      webuserguidesample:
        a sample application described in a new chapter in the JGo User Guide
        illustrating the major features of JGo JSP web applications.
      webdragdropeditor:
        a sample application including a pallet of sample objects that can
        be dragged, dropped, and interconnecting in a work area on a web page.
        Selected object properties are displayed and can be modified via the web page.
      webprimates
        a sample application containing a large diagram that can be browsed via scrolling and zooming.  
        Additional details about diagram nodes are made available as tooltips.  Both scrolling and 
        tooltips are handled locally on the client browser for good performance.


Previous Releases
=================

Version 5.3
  Version 5.3 has the following significant new features:

  - Added JGoTreeAutoLayout and associated classes for faster and more flexible layouts of primarily tree-structured graphs.

  - Added AnimatedBasicApp sample application demonstrating animated links

  - Added SanKeyNode and SanKeyPort sample classes in Demo1

  - Added Balloon class for creating balloon comments pointing to an associated JGoObject

  If you are upgrading from version 5.2 to version 5.3:

  - There are no known incompatibilities between version 5.2 and 5.3.

Version 5.2

  Version 5.2 has the following significant new features:

  - added JGoCollection, a light weight JGoObjectCollection that you can pass to any method that requires a JGoObjectCollection

  - added JGoDocument.add method
  - added JGoDocument property: LinksLayer, layer to hold links; initially same as JGoDocument.getDefaultLayer()

  - added JGoDocument.addCopy method
  - added JGoObject.copy method
  - added copyComplete and finishDelayedCopies methods to JGoCopyEnvironment and JGoCopyMap

  - refactored JGoSubGraph by splitting into a new base class, JGoSubGraphBase, that can be used to implement your own subgraphs

  - added JGoDocument.sortByZOrder, to sort an array of JGoObjects by their Z-order in the JGoDocument
  - added JGoSelection.toArray, addArray, and addCollection
  - improved JGoView.copySelection, copyToClipboard, and createDragSelection to sort copied objects by their Z-order
  - improved drag-and-drop to transfer a copied JGoDocument instead of the JGoSelection, to avoid serializing the whole document;
  - added JGoView.printShowPageDialog to permit customization of showing of Page dialog

  - added JGoLayeredDigraphAutoLayout property: PackOption, to help control what straightenAndPack does
  - added some methods for manipulating JGoNetworks

  - new UpdateDemo and BoxApp samples

  If you are upgrading from version 5.15 to version 5.2*:
  
  - the Transferable that is used in a drag-and-drop is now a JGoDocument holding a copy of the selected objects,
    rather than the JGoSelection itself, to avoid serializing the whole original document
  - the static methods on JGoSubGraph: findParentSubGraph, reparentToCommonSubGraph, reparentAllLinksToSubGraphs
    have been moved up to the JGoSubGraphBase class and have been generalized to work with JGoSubGraphBase instead of JGoSubGraph

  See the 5.2 release notes for more details.

Version 5.1

  Version 5.1 has the following significant new features:

    - added JGoSubGraph functionality so that the border does not have to be the same as the bounding rectangle
    - added JGoSubGraph property: Port, to represent the subgraph as a whole node
    - added JGoSubGraph property: CollapsedObject, if present is shown instead of the background when collapsed
    - added JGoSubGraph properties: SavedBounds and SavedPaths, hashtables that remember node and link info before collapse
    - added JGoSubGraph property: Opacity, used when BackgroundColor is solid
    - added various JGoSubGraph methods to make it easier to customize
    - added JGoSubGraph ability to be resized, implemented by changing Insets or CollapsedInsets
    - added static methods JGoSubGraph.reparentToCommonSubGraph and reparentAllLinksToSubGraphs

    - DEPRECATED JGoObject.isGrabChildSelection and setGrabChildSelection
    - added JGoArea property PickableBackground
    - CHANGED JGoArea: GrabChildSelection no longer used; assumed to be true regarding selection
    - CHANGED JGoArea: Selectable for areas now really means selectable, as with other JGoObjects
    - CHANGED JGoArea: old use of Selectable for JGoAreas now governed by new PickableBackground property

    - added JGoObject.pick, called by JGoLayer.pickObject and JGoLayer.pickObjects and JGoView.pickObject
    - added JGoLayer.pickObjects, JGoDocument.pickObjects, JGoArea.pickObjects

    - added JGoArea.addCollection and JGoLayer.addCollection, to support reparenting nodes without getting the links disconnected

    - added JGoDocument.isUnoccupied, to tell whether there are any "avoidable" objects in a rectangular region

    - added JGoDocument property: ValidCycle, with associated constants and methods

    - improved support for headless servers

    - improved stroke path for self-loop links to observe Curviness value
    - added JGoLink property: RoundedCorners

    - added JGoText.doEdit and computeEdit, to support validation or canonicalization of in-place text editing

    - added JGoDocumentEvent.{STARTED|FINISHED|ABORTED}_TRANSACTION, {STARTING|FINISHED}_{UNDO|REDO},
        for easier updating of application UI

    - added JGoViewEvent.CLIPBOARD_COPIED, fired by JGoView.copy() and JGoView.cut()
    - added JGoView.canPaste()

    - added JGoView.printPreview

    - added JGoActionObject interface and a new state to JGoView for handling JGoActionObjects, such as buttons or knobs

    - improved routing of Orthogonal links in layered-digraph autolayout
    - added overloads to various JGoNetwork methods to take JGoObject instead of JGoNetworkNode,
        for convenience in customizing the network that will be laid out

    - added JGoInstruments

    - added JGoXMLSaveRestore interface for easier persistence of custom objects
    - added SVGImage example class

    - added TestIconicNode example class
    - added RotText and RotImage example classes to Demo1
    - added JTreeApp example app
    - added JGoWebApp.war file for the imager example web application


  If you are upgrading from version 5.03 to version 5.1*:
    - CHANGED JGoDocument.isAvoidable to be true for nodes, not just any areas

    - CHANGED JGoView.newLink and reLink to call JGoSubgraph.reparentToCommonSubGraph,
        to make sure each new and each reconnected link belongs to a JGoSubGraph that may be
        a common parent of both ports, or else is a top-level object in a layer.
        
    - DEPRECATED JGoObject.isGrabChildSelection and setGrabChildSelection
    - added JGoArea property PickableBackground
    - CHANGED JGoArea: GrabChildSelection no longer used; assumed to be true regarding selection
    - CHANGED JGoArea: Selectable for areas now really means selectable, as with other JGoObjects
    - CHANGED JGoArea: old use of Selectable for JGoAreas now governed by new PickableBackground property

      If you called:
        setSelectable(false);
        setGrabChildSelection(true);
      on a JGoArea, do this instead:
        setSelectable(true);
        setPickableBackground(false);

      If you called:
        setSelectable(false);
        setGrabChildSelection(false);
      on a JGoArea, you can simply do:
        setSelectable(false);

      If you called:
        setSelectable(true);
        setGrabChildSelection( ... either true or false ...);
      on a JGoArea, you can simply do:
        setSelectable(true);
        setPickableBackground(true);
        
  See the 5.1 release notes for more details.


Version 5.0

  Version 5.0 has the following new features:
    - added JGoOverview and JGoPalette
        (previously example classes, but now with additional features)
    - improved bean support
    - added many view events (cases of JGoViewEvent, such as LINK_CREATED and OBJECT_EDITED)
    - improved moving and copying to avoid recalculating link strokes
    - added AdjustingStyle property to JGoLink, to control how the link stroke is replotted
        when a port is moved
    - added Curviness property to JGoLink, so that cubic (Bezier) links are automatically curved
    - added ValidSelfNode and ValidDuplicateLinks properties to JGoPort, heeded by JGoPort.validLink
    - added methods to JGoArea (moveChildren, rescaleChildren, and layoutChildren) called by
        geometryChange and geometryChangeChild
    - added AutoRescale property to JGoObject, heeded by JGoArea.rescaleChildren
    - added generic JGoNode class
    - added JGoBasicNode, JGoIconicNode, JGoTextNode, JGoSubGraph
        (previously example classes, but now with additional features)
    - added PartID property to JGoLink and JGoPort and JGoNode, maintained by JGoDocument when
        JGoDocument.setMaintainsPartIDs(true)
    - added some flexibility to SVG generation
    - improved performance of JGoLayeredDiagraphAutoLayout
    - changed example code:
        = overrides assume super JGoArea.copyChildren copies all child objects and adds them to the area
        = replaced overrides of geometryChange and geometryChangeChild with overrides of layoutChildren
        = changed overrides of JGoPort.validLink to use new ValidSelfNode and ValidDuplicateLinks functionality

  If you are upgrading from version 4.1 to version 5.0:
    - previously deprecated members have been removed from 5.0
    - consider replacing references to JGoGridView with references to JGoView,
        since all grid functionality has been moved into JGoView
    - consider replacing uses of the older example classes with the similar (but not exactly the same)
        supported classes: Overview, Palette, BasicNode, IconicNode, TextNode, SubGraph
        Note that the constructors and initialization of classes derived from the new classes has changed
    - consider updating overrides of JGoArea.copyChildren to assume the super method will
        copy all child objects; for example, replace:
            if (myDrawable != null) {
              newobj.myDrawable = (JGoDrawable)env.copy(myDrawable);
              newobj.addObjectAtHead(newobj.myDrawable);
            }
        with:
            newobj.myDrawable = (JGoDrawable)env.get(myDrawable);
    - consider replacing overrides of JGoObject.geometryChange and geometryChangeChild with
        overrides of layoutChildren, and using AutoRescale property of JGoObject to avoid
        the automatic rescaling of children when an area's size is changed
    - consider replacing overrides of JGoPort.validLink with using the ValidSelfNode and
        ValidDuplicateLinks properties on JGoPort.
    - for custom drawable classes, consider overriding computeBoundingRect and calling
        JGoObject.setBoundingRectInvalid(true) in the appropriate methods
    - consider replacing your overrides of JGoLink.calculateStroke with possibly similar
        functionality provided by the Curviness or AdjustingStyle properties of JGoLink
    - consider your use of JGoPort.getEndSegmentLength now that that property is settable,
        if you had overridden it in order to customize the return value
    - consider using unique PartID property of nodes, ports, and links if you need such
        integers that are unique per document
    - for custom drawable classes, consider overriding JGoObject.getNearestIntersectionPoint

  See the 5.0 release notes for more details.




