FlexGanttFX Developer Manual : 3.5.1 Timeline Model

Introduction

The timeline uses a model of type TimelineModel. This model provides the most important parameters for the timeline and the dateline in order for them to work properly. The timeline model can by typed for different temporal units. FlexGanttFX ships with a ChronoUnitTimelineModel and a SimpleUnitTimelineModel.

Start Time & Millis Per Pixel

The two most important properties of the TimelineModel are the startTime and the millisPerPixel (MPP) properties. The start time determines the first visible time in the Gantt chart while the current width of the timeline in combination with the MPP value determine the last visible time and hence the visible time range. Increasing the MPP value will cause the timeline to show a larger time range while reducing this value will result in a shorter time range. The methods found in the Timeline class for showing a time, scrolling to a time, zooming into a range are all playing with these two variables to achieve their purpose. The following table lists the methods related to these properties:

Method Description
ObjectProperty<Instant> startTimeProperty();
setStartTime(Instant time);
Instant getStartTime();

Stores, sets, and retrieves the current start time, the first visible time in the Gantt chart.

The earliest possible start time can be restricted via the horizonStartTime property.

DoubleProperty millisPerPixel();
setMillisPerPixel(double mpp);
double getMillisPerPixel();

Stores, sets, and retrieves the millis per pixel value (mpp).

The default value of mpp is 24 * 60 * 60 * 1000 / 30. This results in days having the width of 30 pixels.

Now Time / Now Location

Gantt charts often have a requirement to mark the "current" time. This time can either be the system time (java.time.Instant.now()) or an arbitrary value controlled by the application. The latter is often the case in software that runs some kind of simulation and the Gantt chart is used to track the simulation time. To support these use cases the timeline model defines a property called now.

The value of now is usually updated by a time tracker that can be controlled via the timeline.

Method DescriptionDesDesdf
ObjectProperty<Instant> nowProperty();
void setNow(Instant now);
Instant getNow();now
Stores, sets, and retrieves the current time.
ReadOnlyDoubleProperty nowLocation();
double getNowLocation();

Stores and retrieves the location of the current time. The now location is calculated by the model based on the start time, and the millis per pixel value.

This property is a read-only property as the now location is always dependent on the value of the now time. The location can only changed by changing now itself.

Time & Coordinate Calculations

The primary purpose of the timeline model is to convert time into a location and vice versa. For this the model provides several methods:

Method DescriptionD
double calculateLocationForTime(Instant);
Returns the x coordinate for the given time.
Instant calculateTimeForLocation(double);
Returns the time for the given x coordinate.

The Horizon

Scheduling applications often work with a horizon, defined by an earliest and latest time. These times might be based on the loaded dataset (min / max calculation of the start and end times of the activities) or the planning horizon (Q1, Q2, Q3, Q4). Setting the values of horizonStartTime and horizonEndTime ensures that the user will not be able to scroll to a time outside the horizon.

Highest & Lowest Temporal Unit

Not all applications require all available units of a temporal unit. java.time.temporal.ChronoUnit for example defines units for nanos until millennia. The highestTemporalUnit and the lowestTemporalUnit property enable the application to restrict the unit range to something more sensible, e.g. hours to months.