3.4.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. To access it, you can use the timeline.getModel() method. The timeline model can be typed for different temporal units. ScheduleJS ships with a ChronoUnitTimelineModel that the timeline will refer to.
Time unit
The timeline as most of the time-related elements of ScheduleJS accepts numbers as a measurement of time. By default, this number is expressed in seconds since Unix time (also referred as Epoch). If you are looking for more info on this topic you can visit this page.
Start Time & Millis Per Pixel
The two most important variables of the TimelineModel are the startTime and the millisPerPixel. The start time determines the first visible time in the Gantt chart while the current width of the timeline in combination with the millisPerPixel value determine the last visible time and hence the visible time range. Increasing the millisPerPixel 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 |
|---|---|
model.setStartTime(time: number) | Stores, sets, and retrieves the current start time, the first visible time in the Gantt chart. The default time unit is expressed in seconds since Unix epoch. The earliest start time can be restricted using the model.setHorizonStartTime() method. |
model.setMillisPerPixel(millis: number) | Stores, sets, and retrieves the millis per pixel value. The default value for millis per pixel 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 (TimeUtil.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 methods to set, store and retreive the current time.
| Method | Description |
|---|---|
model.setNow(time: number) | Stores, sets, and retrieves the current time. |
model.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. The now location is always dependent on the value of the current time. The location can only be changed by changing the current time 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 |
|---|---|
model.calculateLocationForTime(time: number) | Returns the x coordinate for the given time. |
model.calculateTimeForLocation(location: number) | 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 with model.setHorizonStartTime() and model.setHorizonEndTime() ensures that the user will not be able to scroll to a time outside the horizon.
Smallest Temporal Unit
Not all applications require all available units of a temporal unit. ChronoUnit for example defines units for nanos until millennia. The model.getSmallestTemporalUnit() model enable the application to verify the smallest unit supported by the gantt, e.g. hours to months.