## GanttChart: Minimum Specification

The minimum specification for a GanttChart requires a valid data model that assigns the Task, EarlyStart, and EarlyFinish variable roles to appropriate Variables in the data. If any one of these roles is not assigned, the GanttChart does not display a graph.

Example
Basic Requirements for Creating a GanttChart

## GanttChart: Functional Overview

The TaskVariable role in a Gantt chart is used to determine the number and placement of Gantt bars in the chart. Each unique value of the Task variable is displayed as a separate bar. If the data model contains multiple rows for a Task value, only the first row is displayed in the chart; the other rows are ignored.

At a minimum, the schedule data must contain EarlyStart and EarlyFinish dates for each task. In that case, the length of each bar spans between the specified start and finish dates for the corresponding task. If a schedule also tracks late start and finish dates for each task, the late dates are displayed on the same bar as the early date, but in a different color. The span from the early start to early finish dates determines the duration of a normal task, and the span from the early finish to late finish dates identifies the slack time allowed for each task.

The following project characteristics are automatically displayed when both early and late project dates are tracked:

Project Interval | Represented as ...
--- | ---
Duration of a Normal job | The span from the EarlyStart to the EarlyFinish dates
Slack Time for a Normal job | The span from the EarlyFinish to the LateFinish dates
Critical Job | The task with the latest finish date

In addition to plotting the predicted early and late dates, you can visually monitor a project in progress with the actual schedule and compare the actual schedule against a target baseline schedule. You can also graphically view the effects of scheduling a project subject to resource limitations.

By default, the Gantt Chart displays early, late, and actual schedules in a single bar to produce a more meaningful schedule for tracking a task in progress. It displays basline and resource-constrained dates in a separate bar to allow for better comparison. You can modify the default display for actual dates by displaying them beside the predicted dates rather than overlaying the predicted dates.

A Gantt chart can display weekends, reference lines, and depict milestones on the chart. Zero duration activities are milestones and denoted with a milestone symbol. The default milestone symbol is a filled diamond.

The Gantt chart's horizontal axis is displayed at the top and represents time. The chart's vertical axis is displayed on the left and represents the sequence of tasks. By default, the task axis does not display values. You can specify a table of variables for the axis display, where each variable is represented by a column in the table, and variable values form the table rows.

When task-axis values are displayed, the chart is divided into two frames. The left frame displays the task-axis values, and the right frame displays the Gantt chart. You can drag the border between the frames to adjust their width, and you can scroll the contents of each frame to adjust its display. If you click on a point in either frame, the data elements and axis values that are represented at that point are selected in both frames.

If you drag the mouse pointer over the bars in a Gantt chart, data tips are displayed to show the values that are represented by the bar under the current pointer position. By default, values are shown for all variables that are represented in the graph. You can add values to the data tips for variables that are not represented in the graph.

Finally, the GanttChart component can capture click events when the user clicks on a bar in the chart. This enables you to capture the data associated with the bar and pass that information to your application.

## GanttChart: Data Access

A Gantt chart's data properties are defined in a data model that descends from GanttChartDataModel, an abstract class whose subclasses provide a handle to the data and determine the number and arrangement of data elements (horizontal Gantt bars). GanttChartDataModel has the following subclasses:

- GanttChartTableDataModel models relational data from a Swing TableModel and maps the data columns to the Gantt bars.
- GanttChartAnnotationTableDataModel models relational data from a Swing TableModel and maps the data columns to chart annotations, such as labels and milestone markers.

Schedule data for the chart are always stored in a GanttChartTableDataModel.

Annotation data for the chart can be stored with the schedule data in the GanttChartTableDataModel, or separately in a GanttChartAnnotationTableDataModel. A a GanttChartAnnotationTableDataModel's primary advantage is that it makes it easy to display multiple annotations for a single task. A secondary advantage is that it separates the annotation information from the schedule information. When the annotation data are stored in a GanttChartAnnotationTableDataModel, you associate the annotation data with the schedule data by calling `GanttChartTableDataModel.setAnnotationTableDataModel()`.

For more details about data access, see the documentation for each of the data models.

## GanttChart: Display Properties

A GanttChart's individual display properties can be set by calling the GanttChart's getGraphModel() method, which returns a GanttChartModel that can be used to set the desired properties. The GanttChartModel class contains

- GanttChart-specific properties
- Common graph properties
- A collection of models that control the appearance of the graph's peripheral elements, such as its axes and legend.

Although modifying the GanttChartModel provides considerable control, it can be tedious to modify properties individually. For example, the following code fragment changes a chart's milestone marker style and other properties:

    GanttChart ganttChart = new GanttChart();
    GanttChartModel ganttChartModel = ganttChart.getGraphModel();

    // Set the milestone marker to filled circle
    ganttChartModel.getDataElementStyles()
      .setMilestoneMarkerStyle(new MarkerStyle(MarkerStyle.CIRCLE_FILLED));

    // Set the critical job fill style color to blue
    ganttChartModel.setCriticalJobFillStyle(new FillStyle(Color.blue));

    // Set the date-axis value text color to red
    ganttChartModel.getDateAxisModel().getValueTextStyle().setColor(Color.red);

An easier way to set a GanttChart's display properties is to apply a pre-defined GraphStyle to the chart. A graph style sets many of the graph's visual characteristics, such as its use of colors, fonts, background, transparency, drop shadows, and more. A graph style can be used as is or modified through the GraphStyle class.

A graph style can be specified as an argument on a GanttChart's constructor. Or, it can be applied to an existing chart by calling the GanttChart's applyGraphStyle() method as follows:

    GanttChart ganttChart = new GanttChart();
    ganttChart.applyGraphStyle(new GraphStyle(GraphStyle.STYLE_SCIENCE);

Applying a GraphStyle to a graph propagates the GraphStyle's properties onto all applicable graph properties, including those in the graph model.

Rather than use the style as is, you can modify it before applying it. Modifying the style definition is typically easier and more convenient than modifying the graph's individual display properties. For example, the GraphStyle class contains only a single set of value text properties. After applying the modified style, you can still adjust individual properties through the graph model.

The following code fragment modifies a graph style before applying it to a graph, and then uses the graph model to adjust an individual property.

    // Create and modify a graph style
    GraphStyle graphStyle = new GraphStyle(GraphStyle.STYLE_SCIENCE);
       graphStyle.getValueTextStyle().setColor(Color.darkGray);
       graphStyle.getValueTextStyle().setFont(new java.awt.Font("Arial",Font.BOLD,14));

    // Apply the modified graph style to a chart
    GanttChart ganttChart = new GanttChart();
       ganttChart.applyGraphStyle(graphStyle);

Whether you set a graph style or individual display properties, the new display settings override any previous settings that were applied to the graph. For example, if a gray background and red axis lines have been set on a graph, and then a style is applied to that same graph, the style's background and axis line settings replace the previously set gray background and red axis lines.

## GanttChart: Events on the Gantt Bars

The GanttChart component can capture events that occur on the Gantt bars in the chart. The events include a GraphActionEvent (mouse click) and a ProbeEvent (mouse pointer moves over a bar). The capture capability enables you to capture the data associated with the Gantt bars and pass that information to your application.

To ensure that the chart is notified when a Gantt bar is clicked, add a GraphActionListener to the chart by calling `GanttChart.addActionListener(GraphActionListener)` to register a GraphActionListener with the chart. To ensure that the chart is notified when the mouse pointer moves over a Gantt bar, add a ProbeListener to the chart by calling `GanttChart.addProbeListener(ProbeListener)` to register a ProbeListener with the chart.

The listeners that are passed as the arguments on `addActionListener()` and `addProbeListener()` must be implemented in your code. The implementations must

- create a PickInfo object that gets the data associated with the affected Gantt bar
- contain or call the code that uses the captured data.

To implement the GraphActionListener interface, use the `GraphActionListener.actionPerformed(GraphActionEvent)` method to define the required functionality. To implement the ProbeListener interface, use the `ProbeListener.probeUpdate(ProbeEvent)` method to define the required functionality. The `GraphActionEvent` and `ProbeEvent` objects that are passed as arguments on these methods are automatically created by the event, so you can use them to create a PickInfo object to hold the data. You can then get the data from the PickInfo object. For example, you could call `PickInfo.getLabelValueCollection()` to get all of the variable labels and values from the schedule data and store them as label/value pairs in a Vector collection.

The following code fragment defines a class implentation of the GraphActionListener interface.

    // Create a GraphActionListener to capture click events on the Gantt bars
       class MyGraphActionListener implements GraphActionListener
       {
         public void actionPerformed(GraphActionEvent e)
         {
         // Create a PickInfo object to get data associated with the Gantt bars
            PickInfo pickInfo=(PickInfo)e.getPickInfo();

         // Get all variable labels and values from the PickInfo
            Vector[] labelValueCollection=pickInfo.getLabelValueCollection();

         // Loop through the data collection to get each label/value pair
            for(int i=0; i>labelValueCollection.length; i++) {
              Vector labelValues = labelValueCollection[i];
              // Do something with the data ....
            }
         }
       }

The PickInfo object holds all of the variable information that is associated with the affected bar, regardless of whether the variables are represented in the chart or displayed in the data tips. For example, if the data model contains several auxiliary variables that are not dispalyed in the chart and not displayed in the data tips, the data associated with those auxiliary variables are nevertheless held in the PickInfo object and can be passed to your application.

To register the GraphActionListener defined above with a Gantt chart, call `GanttChart.addActionListener()`:

    // Register MyGraphActionListener on a Gantt chart
       MyGraphActionListener graphListener=new MyGraphActionListener();

    // Listen for mouse clicks and return data associated with the clicked bar
       ganttChart.addActionListener(graphListener);

Example
Capture Click Events

## GanttChart: Titles and Footnotes

The GanttChart component supports four titles and two footnotes, each with its own display attributes. To display multiple lines of text with the same attributes, use the line-end character (\n) in the specified text string.

To assign a title or footnote,

- Create a NoteModel to encapsulate a text value with associated display attributes
- Assign the model to the chart by calling one of the GanttChart's setTitle() or setFootnote() methods.

The easiest way to set the text for a title or footnote is to get the chart's title or footnote property and set its text as follows:

    ganttChart.getTitle1().setText("Line One\nLine Two");

To change the text attributes for a title or footnote, set the attributes on a NoteModel and assign the NoteModel to the appropriate title or footnote. The following example sets the title "Preliminary Schedule" and displays it in blue, using a 24-point TimesRoman font with a drop shadow.

    NoteModel myTitle = new NoteModel( "Preliminary Schedule" );
    myTitle.getTextStyle().setColor(Color.blue);
    myTitle.getTextStyle().setFont(new java.awt.Font("TimesRoman",Font.PLAIN,24));
    myTitle.getTextStyle().getShadowStyle().setVisible(true);

    // Create the graph and assign the title
    GanttChart ganttChart = new GanttChart();
    ganttChart.setTitle1( myTitle );

## GanttChart: Behavior

The GanttChart asynchronously updates when a PropertyChangeEvent is received from any of its models (DataModel, GraphModel or NoteModels).