JGantt Manual

Content

• 1 Introduction
• 1.1 JGantt features
• 1.2 Quick start
• 2 Installation
• 2.1 Packages
• 2.2 License installation
• 3 Model for JGantt
• 3.1 TimelineObject
• 3.2 Dependency
• 3.3 GanttModel
• 4 Gantt Tree Table
• 4.1 JTreeTable description
• 4.2 GanttNode
• 4.3 Gantt Column and data binding
• 4.4 Localization
• 5 Gantt chart
• 5.1 Chart header
• 5.2 Chart component
• 5.3 Layer
• 5.4 List of implemented layers
• 6 Gantt actions
• 6.1 AbstractGanttAction
• 6.2 Localization
• 6.3 Undo / Redo
• 6.4 List of the implemented actions
• 7 JGantt component
• 7.1 Getting standard sub-components
• 7.2 Building a treetable
• 7.3 Building a chart
• 7.4 Mouse support
• 7.5 Localization
• 7.6 License
• 8 Shipping to customer

1 Introduction

JGantt is the Swing component for the gantt chart painting and editing.

1.1 JGantt features

This chapter contains descriptions of JGantt's most essential features:

Standard view - Standard chart appearance and behavior customizable settings. There are a treetable and a chart component side by side. The treetable on the left hand side, and the chart component on the right. Exactly as you know it from other gantt components. But you can modify their appearance as you need.

Advanced treetable - The treetable has a few very interesting features: It is derived from eu.beesoft.gaia.swing.JTreeTable, so it has the features of JTable and JTree - it is easy to use it, if you are familiar with Swing programming. JTreeTable can paint "zebra" background and also show / hide columns on user selection (right click on treetable header displays popup menu with column names to hide / show). There is also built-in support for the context popup menu and double click processing.

Data binding - Model for JGantt is oriented on the easy programming and usage. One of its features is automated data binding. You can set a name of the property of your domain object you want to display in some column and JGantt displays it without any more programming. And the same it does with setting user-changed visual data to domain object.

Lazy loading - If your application works with a large dataset, it is suitable to load to the memory just the visible part of the data. JGantt treetable listens to treeexpand event and if node is expanded for the first time, it invokes method explore() on GanttModel. This is the place you can load data for node's user object and build subnodes. Do you know any more simple solution?

Layers - Gantt chart is painted in some layers. You can choose which layers you want install into gantt chart, and also you can hide / show layers at runtime. Each layer has specific purpose and paints only the gadgets it is programmed for. You can develop new layers or customize the existing. This is the way you can customize the whole chart, change the shape of timeline objects or dependency lines or add an absolutelly new functionality. In each layer you can solve also a mouse service, there is a built-in support.

Relationships - Timeline objects (tasks) can have relationship with each other. You can define constraints on such relationship (for example: this task can start after that task is finished). In the JGantt you need implement one interface on the domain objects level. And you can subclass layer for dependencies painting to get your own visualization of dependencies, if the delivered is nor suitable for you.

Actions - JGantt comes with predefined set of actions. There are actions for zoom-in and zoom-out, creating, deleting and moving nodes (and their user-objects) in the tree hierarchy, and also actions for undo and redo operations. And also abstract superclasses for the smart building another actions.

Localization - JGantt uses data from resource bundle for treetable column names and action properties. There is a built-in mechanism to do it without any programming. If your application contains more resource bundles for more languages, you can build a multi-lingual gantt chart in a very simple way. JGantt listens to the language changes at runtime and repaints itself if gets event.

1.2 Quick start

Here is the picture of our demo application distributed with JGantt:

Every object you want to display in JGantt treetable must implement eu.beesoft.gantt.TimelineObject interface. There are methods in this interface to get / set a start and end date of object, etc. In our example we create class Task for our domain objects. Our Task is the bean with some additional logic to handle start and end date changes:

public class Task extends AbstractBean implements TimelineObject {

	private String taskId;
	private String name;
	private String description;
	private Date startDate;
	private Date endDate;
	private long effort;
	private boolean milestone;
	private Task supertask;
	private List<Task> subtask;
	private List<Dependency> dependencies;
	private Resource assignee;


	

	public Task () {
		// empty
	}



	public String getName () {
		return name;
	}



	public void setName (String name) {
		String old = this.name;
		this.name = name;
		firePropertyChange ("name", old, name);
	}


        .....


	public Date getStartDate () {
		if ((startDate == null) && isSummary ()) {
			updateStart ();
		}
		return startDate;
	}



	public void setStartDate (Date start) {
		if (Objects.equals (this.startDate, start)) {
			return;
		}
		Date old = this.startDate;
		this.startDate = start;
		if (supertask != null) {
			supertask.updateStart ();
		}
		firePropertyChange ("startDate", old, start);
	}



	private void updateStart () {
		if (isSummary ()) {
			Date thisStart = null;
			List<Task> tasks = getSubtask ();
			for (Task task : tasks) {
				Date taskStart = task.getStartDate ();
				if (taskStart != null) {
					if ((thisStart == null) || thisStart.after (taskStart)) {
						thisStart = taskStart;
					}
				}
			}
			if (thisStart != null) {
				setStartDate (thisStart);
			}
		}
	}


        .....
}

Next, we create our model. We implement these methods:

• getColumnClass() - in our treetable are dates in columns 2 and 3 (counted from 0), so we want to say to the treetable about it
• isCellEditable() - column 1 contains non-editable task ID, other columns are editable
• explore() - method is invoked when treenode is the first time expanded and has no children yet. In our example we build new nodes for task children.
• moveObject(), deleteObject() and createObject() - these methods are required to implement by parent class (they are abstract). They are invoked when user executes corresponding action. JGantt makes its work on treetable nodes level, but a programmer has to serve the domain objects level. So in these methods we handle the Task objects hierarchy. Note the undo / redo support you should use in these methods.
• getLabel() - we use the LabelLayer layer later in our example and it requires to implement this method - here it returns a name of a task assignee

Here is the source:

public class Model extends GanttModel {

	public Model () {
		super ();
	}



	@Override
	public Class getColumnClass (int column) {
		switch (column) {
			case 2:
			case 3:
				return Date.class;
			default:
				return super.getColumnClass (column);
		}
	}



	@Override
	public boolean isCellEditable (TreeTableNode node, int column) {
		if (column == 0) {
			return true;
		}
		return (column >= 2);
	}



	@Override
	public void explore (GanttNode node) {
		Task task = (Task) node.getUserObject ();
		for (Task t : task.getSubtask ()) {
			GanttNode child = new GanttNode (this, t);
			if (t.getSubtask ().isEmpty ()) {
				child.setExplorable (false);
			}
			node.add (child);
		}
	}



	@Override
	public boolean moveObject (TimelineObject object,
	        TimelineObject newContainer, int newIndex, UndoStep undo) {
		Task task = (Task) object;
		Task supertask = (Task) newContainer;
		undo.registerObject (task);
		undo.registerObject (supertask);
		Task oldSupertask = task.getSupertask ();
		if (supertask != oldSupertask) {
			if (oldSupertask != null) {
				undo.registerObject (oldSupertask);
				oldSupertask.removeSubtask (task);
			}
			supertask.addSubtask (task);
		}
		supertask.shiftSubtask (task, newIndex);
		return true;
	}



	@Override
	public boolean deleteObject (TimelineObject what, UndoStep undo) {
		Task task = (Task) what;
		Task parent = task.getSupertask ();
		undo.registerObject (parent);
		undo.registerObject (task);
		parent.removeSubtask (task);
		return true;
	}



	@Override
	public TimelineObject createObject (TimelineObject parent, int index,
	        UndoStep undo) {
		undo.registerObject (parent);
		Task parentTask = (Task) parent;
		Task task = new Task ();
		String id = Gantt.getNextTaskId ();
		task.setTaskId (id);
		task.setName ("Task " + id);
		parentTask.addSubtask (task);
		parentTask.shiftSubtask (task, index);
		return task;
	}



	@Override
	public String getLabel (TimelineObject object) {
		if (object instanceof Task) {
			Resource assignee = ((Task) object).getAssignee ();
			if (assignee != null) {
				return assignee.getName ();
			}
		}
		return null;
	}
}

Now we can create our DemoGantt class that subclasses JGantt. It is very simple class, it has only two methods to support mouse actions:

• getPopupActions() - returns the list of actions to show in popup menu
• doubleClicked() - invokes dialog to edit task properties when user double-clicked on task node

public class DemoGantt extends JGantt {

	private static Action createNodeAction;
	private static Action editNodeAction;
	private static Action deleteNodeAction;
	private static Action indentNodeAction;
	private static Action unindentNodeAction;
	private static Action moveNodeUpAction;
	private static Action moveNodeDownAction;
	private static Action expandAllNodesAction;
	private static Action collapseAllNodesAction;
	private static Action zoomInAction;
	private static Action zoomOutAction;
	private static Action todayAction;
	private static Action undoAction;
	private static Action redoAction;
	private List popupActions;



	public DemoGantt (GanttModel model) {
		super (model);
	}



	@Override
	protected List<Action> getPopupActions (List<GanttNode> selectedNodes) {
		if (popupActions == null) {
			popupActions = new ArrayList<Action> ();
			popupActions.add (createNodeAction);
			popupActions.add (editNodeAction);
			popupActions.add (deleteNodeAction);
			popupActions.add (null);
			popupActions.add (indentNodeAction);
			popupActions.add (unindentNodeAction);
			popupActions.add (moveNodeUpAction);
			popupActions.add (moveNodeDownAction);
		}
		return popupActions;
	}



	@Override
	public void doubleClicked (GanttNode node) {
		Task task = (Task) node.getUserObject ();
		TaskPropertiesAction.showTaskProperties (task, this);
	}
}

To keep the example here as simple as possible we ignore another auxiliary classes (as actions, form to edit task properties or date cell renderer). All of them you can find in our DEMO directory.

So what we need is put it all together. It is done in DemoGantt.main() method:

		// create model
		// it extends GanttModel
		GanttModel model = new Model ();

		// create domain objects
		// they should come from database or server in real application
		Resource worker_1 = new Resource ();
		worker_1.setName ("Smith John");

		.....

		Task task_1_1 = createTask ("Task 1.1", -20, +1, 92);
		task_1_1.setAssignee (worker_1);

		.....

		Task task_1 = createTask ("Task 1", 0, 0, 0);
		task_1.addSubtask (task_1_1);

		.....

		Project project = new Project ();
		project.setName ("Project");
		project.addResource (worker_1);
		project.addSubtask (task_1);

		.....

		// set created project as gantt model root object
		model.setRootObject (project);


		.....

		// create gantt component with "zebra" background
		// and vertical column-line-separators
		JGantt gantt = new DemoGantt (model);
		JTreeTable treeTable = gantt.getTreeTable ();
		treeTable.setAlternateBackground (treeTable
		        .getDefaultAlternateBackground ());
		treeTable.setShowVerticalLines (true);

		// create columns in gantt tree-table
		// this is the first column with task tree
		GanttColumn column = new GanttColumn ();
		column.setHeaderValue ("Task name");
		column.setBinding ("name");
		gantt.addColumn (column);

		column = new GanttColumn ();
		column.setHeaderValue ("Task ID");
		column.setBinding ("taskId");
		gantt.addColumn (column);

		.....

		// resize columns to appropriate width
		gantt.getTreeTable ().pack ();

		// create layers for gantt chart
		// order of layers is important for painting
		gantt.addLayer (new BackgroundLayer ());
		gantt.addLayer (new CalendarLayer ());
		gantt.addLayer (new GridLayer ());
		gantt.addLayer (new TodayLayer ());
		gantt.addLayer (new GanttNodeLayer ());
		gantt.addLayer (new LabelLayer ());
		gantt.addLayer (new DependencyLayer ());

		// create gantt actions
		createNodeAction = new CreateNodeAction (gantt);
		editNodeAction = new TaskPropertiesAction (gantt);

		.....
		
		build menu and toolbar, create a swing frame and show it

Note in this example:

• you don't need to act with treenodes - we build our task hierarchy and then we set the top object (project) as the root object to model
• note setBinding() method usage when we construct treetable columns - by this method you can tell to the treetable which property of your domain object you want to display in the column - there is no manual programming of data get / set access
• note also layers setting - you can see that the look of the chart component is conditional - it depends on the layers you use to paint it. You can write your own layers to give your application a specific look.

2 Installation

Simply unzip downloaded file to appropriate directory (you must create such directory). You will get this structure:

    JGANTT                      - this is the root directory
        license.txt             - license agreement
        DEMO                    - Java demo example for JGantt usage, contains sources and JAR file with instructions
        DOC                     - documentation directory
             manual.html        - JGantt manual, this is what you are reading
             IMAGES             - directory with images for manual
             API                - Javadoc directory 
        LIB                     - jars directory
             jgantt_2010_2.jar  - component library
             gaia_2010_2.jar    - BeeSoft general library
             abeona_2010_3.jar  - license protector

You can copy JAR files to any appropriate place for your development. It is not necessary to keep them in the installation directory.

2.1 Packages

JGantt consists of these packages:

JGantt strongly uses classes from our Gaia library. This is our company general library and is available for free. Current version of this library is included in your distribution, but you can upgrade at any time. These packages from Gaia are used by JGantt:

2.2 License installation

JGantt is component protected by Abeona protection system. You can freely download this component and use it, but there is one feature built-in: if JGantt is not licensed, it stops to work 10 minutes after it was constructed. You must restart your application which uses this component.

When you purchase a license for JGantt, you will get a license file to your email. Copy this file where you want to your classpath and then complete your application with a similar code:

       JGantt gantt = new JGantt ();

       ... init gantt component

       InputStream is = SomeMyClass.class.getInputStream ("path-to-license-file");
       License license = gantt.setLicense (is);
       if (license == null) {
            throw new RuntimeException ("Ooops, something goes wrong here...");
       }

3 Model for JGantt

The model for JGantt consists of:

• the TimelineObject interface
• the Dependency interface
• the GanttModel class

That's all. Your domain objects must implement the given interfaces. And your model must subclass the GanttModel class to serve some methods.

3.1 TimelineObject

TimelineObject is an interface that prescribes some methods for your domain objects. Each of these methods concerns on getting / setting data for the gantt chart:

A typical application's domain object that has to implement this interface is a task.

3.2 Dependency

Dependency is an interface that describes dependency between TimelineObjects. Here is the list of methods you need to implement:

There are some constants defined in the Dependency interface. They define the type of dependency:

3.3 GanttModel

GanttModel extends JTreeTable model from Gaia library. You have to implement these methods:

The methods above are designed to manipulate with objects on the domain objects level. You don't need to work with treetable nodes.

If you want to paint in the chart component on the time lines some texts (if you use LabelLayer or TooltipLayer), you need override these methods:

GanttModel supports lazy loading for treetable data. The possibilities of ExplorableTreeNode, which is an ancestor of GanttNode, is emplyed here. When node is expanded and was not explored still, method explore(GanttNode) is invoked.

• get a user object from given node
• load children of user object and build hierarchy
• for each loaded child create instance of GanttNode and set child as its user object
• add each created instance of GanttNode as a child to the given node

4 Gantt Tree Table

GanttTreeTable is the tree table for gantt chart. It is the left-located component of the JGantt.

GanttTreeTable is the descendant of the eu.beesoft.gaia.swing.JTreeTable (you can read about it in the next chapter, and the next informations are accessible in API documentation).

4.1 JTreeTable description

The eu.beesoft.gaia.swing.JTreeTable class is a combination of a JTree and a JTable - a component capable of both expanding and contracting rows, as well as showing multiple columns of data.

This component always displays a tree in the first column and the additional data in the next columns. You can see its usage in a very simple example of the directory tree.

This component has the next features:

• it inherits from its parent class ability to hide / show columns
• right click on the table header shows popup menu with list of all columns - this is the user way to show / hide columns
• also inherits possible "zebra" look (even rows can have an alternate background color)
• the tree is always painted in the first column of the treetable
• as its model you must use eu.beesoft.gaia.swing.TreeTableModel or subclasse it (that's what GanttModel does)
• descendants of the eu.beesoft.gaia.swing.TreeTableNode are only nodes acceptable in the JTreeTable (and GanttNode is the descendant of TreeTableNode)

4.2 GanttNode

GanttNode is the only javax.swing.tree.TreeNode acceptable by a gantt tree data structure. It is a final class, so there is no way to customize it.

Here are the key features of the GanttNode:

• a TimelineObject is used as an user object in tree node. Each user object must implement this interface.
• it inherits ability of the data lazy-loading
• although GanttNode is a part of the treetable, it holds some informations for chart component (the bounds of timeline, for example)

4.3 Gantt column and data binding

GanttColumn represents a column in the GanttTreeTable. It is a descendant of javax.swing.table.TableColumn . It supports:

• resource bundle usage for column label
• data binding for getting / setting values from GanttNode's user object

Data binding is implemented by eu.beesoft.gaia.util.Miner class. It gets values from any object and sets them in. In the first step via property accessors (getter / setter) and if appropriate accessor is not found, on the field access level. More informations about Miner class you can find in API documentation.

GanttModel has implemented these methods related to data binding:

These methods support data binding in GanttColumn:

4.4 Localization

A GanttColumn has built-in support for resource bundle usage. These methods are implemented:

First two methods operates with resource bundle key. It is a key under which is stored localized text in resource bundle. The third method is a listener method and is invoked, when you change language settings in application. It is invoked from eu.beesoft.gaia.util.Language.

What resource bundle is used? The way the resource bundle is found, is described here.

5 Gantt Chart

Gantt chart is located on the right side of the JGantt component. It consists of:

• chart header
• chart component

All classes of the gantt chart are in the package eu.beesoft.gantt.chart.

There are two important classes for whole package:

• TimeUnit
• TimeSpan

TimeUnit is an enumeration for time unit granularity. It contains constants from seconds to year and some useful methods.

TimeSpan envelopes date range (start time - end time). Instances of TimeSpan are created by ChartComponent in its updateChart() method. They contains information about:

• start date of time span
• end date of time span
• whether it is a holiday or weekend
• x-position of this time span in chart component coordinates
• width of this time span in pixels

All of these informations are used by chart component to prepare painting.

The painting in gantt chart is implemented through the layers. A Layer is an abstract class that provides functionality to paint chart and interact with a user.

When you construct a gantt, you set to the ChartComponent several layers. Chart component, when painting, iterates through them and invokes the paint(Graphics) method on each of them. The order you add layers to ChartComponent is important.

5.1 Chart header

ChartHeader paints headers above the ChartComponent instance. This component contains two headers - major and minor - and their models.

HeaderModel is used to paint major or minor header for ChartComponent. It contains data for header columns.

HeaderColumn is a subclass of javax.swing.table.TableColumn to hold list of TimeSpan instances. These instances are used to calculate sizes of the column.

There is very low probability you need to customize these classes. They are created by JGantt in initialization phase. All you need to do is to use them.

5.2 Chart component

A ChartComponent is one of the most meaningful sub-components of JGantt. It is painted on the right side of JGantt (there is an instance of JTreeTable on the left).

It co-ordinates painting with registered instances of the Layer class and dispatches events to them.

The ChartComponent is created by JGantt in initialization phase and there is no way to customize it.

5.3 Layer

A layer is an object having a graphical representation that can be displayed in the gantt chart and that can interact with the user.

The Layer class is the abstract superclass of the each gantt chart layer.

The gantt ChartComponent holds a stack of user-defined layers. When the method paint(Graphics) on ChartComponent is invoked, it walks through this stack (in order the layers were added) and if the layer is visible (method isVisible() returns true) calls method paint(Graphics) on it.

Here are the methods that eu.beesoft.gantt.chart.Layer class provides:

There is a set of implemented layers you can use. Of course, you can write your own - subclass eu.beesoft.gantt.chart.Layer and implement method paint(Graphics).

You can also modify an existing layer - subclass it and override method you need.

5.4 List of the implemented layers

Here is the list of the implemented layers you can use:

6 Gantt actions

As a standard Swing component, JGantt is controlled by actions.

6.1 AbstractGanttAction

AbstractGanttAction is a base class for gantt component actions. It is not necessary to subclass this class, you can use any action. But AbstractGanttAction offers these features:

• ability to return JGantt instance
• built-in resource bundle and language support
• undo / redo support

AbstractGanttAction processes actionPerformed (ActionEvent) method to offer undo / redo support. It invokes executeAction (ActionEvent, UndoStep) method, which is an abstract method, and if it returns true, registers all changes from UndoStep in UndoManager.

6.2 Localization

AbstractGanttAction gets its properties from resource bundle. All action properties (currently: text, icon and tooltip) must be described in resource bundle. This process is automated, so you must observed some rules:

• each property name must be prefixed by fully qualified or simple action class name
• property name for action text (label) is text
• property name for action icon is icon - it is path to icon image on classpath
• property name for action tooltip text is tooltip

For example, if your action class is mydomain.mypackage.MyAction, then in the resource bundle should be:

mydomain.mypackage.MyAction.text=Text for action
mydomain.mypackage.MyAction.icon=mydomain/mypackage/MyIcon.gif
mydomain.mypackage.MyAction.tooltip=This is a tooltip for my action

MyAction.text=Text for action
MyAction.icon=mydomain/mypackage/MyIcon.gif
MyAction.tooltip=This is a tooltip for my action

The way the resource bundle is found, is described here.

6.3 Undo / Redo

JGantt uses Swing undo package functionality to provide support for undo/redo operations.

There are two classes in eu.beesoft.gantt.undo package for that purpose:

• UndoStep
• StateEditableObject

StateEditableObject implements javax.swing.undo.StateEditable interface. Its constructor takes one object, and StateEditableObject can this object introspect and to remember changed properties.

UndoStep is the descendant of javax.swing.undo.CompoundEdit class. It serves as a container of all operations for one undo / redo step. It offers two methods:

If you want to process undo / redo, you have to:

1. create an instance UndoStep
2. call registerObject(Object) for each object that can be changed in executed action before any change occurs
3. call end() after action finished
4. obtain from JGantt instance an UndoManager
5. on UndoManager instance invoke addEdit (UndoStep) method

AbstractGanttAction supports all of these steps except step 2. So what you have to do, if your action is deriver from AbstractGanttAction, is to call registerObject(Object) for each object that can be changed in method executeAction (ActionEvent, UndoStep) only.

6.4 List of the implemented actions

Here is the list of the implemented actions you can use:

7 JGantt component

JGantt covers all above components:

• GanttTreeTable
• ChartComponent
• ChartHeader

These components are constructed in the initialization phase and developer has no impact to it. You can change their properties only.

7.1 Getting standard sub-components

The standard JGantt subcomponents are accessible by these methods:

7.2 Building a treetable

Here are JGantt methods you can use to build a chart:

The methods working with columns are implemented in GanttTreeTable and methods in JGantt simply redirect to them.

7.3 Building a chart

Here are JGantt methods you can use to build a chart:

All of these methods are implemented in ChartComponent and methods in JGantt simply redirect to them.

7.4 Mouse support

JGantt has built-in mouse support, so you don't need to work with mouse listeners. Use these methods instead:

Method doubleClicked() is invoked from treetable and also from gantt chart component. The getPopupActions() is treetable method only. If you return a non-null list, the popup menu is displayed.

7.5 Localization

The JGantt components (treetable columns and actions) intense use resource bundle technique. These methods of JGantt are about resource bundles:

The main class for these purposes is eu.beesoft.gaia.util.Language. In the Swing environment is a singleton (but it has a public constructor, so you can create as many instances as you need in server environment). The singleton is accessible via method

      Language.getInstance ();

which returns last created instance of Language. Using Language has big advantage when you change application's Locale. Setting this into Language provides for all LanguageListeners notification to easy reloading texts from resource bundles.

When you take a look at Language API documentation, you can see method getText() with first argument either a resource bundle name or some object. These methods are used from JGantt and its subcomponents.

1. if resource bundle name is set (by method JGantt.setResourceBundleName()), this resource bundle is constructed and used. Note, that resource bundle name must have a form of class name.
2. if no resource bundle name is set, then the name of current JGantt class (its subclass) is taken and used to find resource. If resource is not found, or key with given name is not found, Language class takes a superclass name and repeats searching.

7.6 License

JGantt is protected by the Abeona protection system.

It works without any license, but 10 minutes after JGantt was created it displays a warning message and stops to paint itself.

So if you want to develop an application, which will work more than 10 minutes, you need purchase the license from BeeSoft. License is plain properties file protected by digital signature and here are methods to tell JGantt about license:

The first method has an input stream from license file as argument, and returns newly created License instance. You don't need to work with this object, just check for non-null return value. If it is null, you have some problem with that file.

8 Shipping to customer

When you will deploy your application based on the JGantt at your customer (or you will ship it), your product must contain libraries from our JGantt lib directory these JAR files:

• JGantt
• Gaia
• Abeona

and also license file you obtain when you purchase JGantt.

No other files are required.