The timeline control is a container for the Dateline and the Eventline. It is displayed above the Graphics control and provides several methods for scrolling and zooming, both of which can be done with or without animation. The timeline also keeps track of the current time (see TimeTracker).
Navigation
The timeline is used to navigate through time. It provides methods to jump to the current time or a given time. It can be requested to show a specific time unit ("show days"), or a time range.
| Method | Description |
|---|---|
showNow() showNow(boolean center) |
Changes the start time of the timeline model in such a way that the current time (as already stored in the TimelineModel) will be displayed either on the left edge of the dateline or right in the middle. |
showTime(Instant time) showTime(Instant time, boolean center) |
Changes the start time of the timeline model in such a way that the given time will be displayed either on the left edge of the dateline or right in the middle. |
showRange(Instant start, Instant end) showRange(Instant start, Duration duration) showRange(TimeInterval range) |
Changes the start time and the "millis per pixel" value of the timeline model in such a way that the given time range will become fully visible in the dateline. |
showTemporalUnit(TemporalUnit unit, double width) |
Changes the start time and the "millis per pixel" value of the timeline model in such a way that the given time unit will be used in the dateline. Each cell in the dateline will be as wide as the given width. |
It should be noted that the timeline in cooperation with the dateline can only make a best-effort attempt at fulfillng these requests as they depend on the availability of dateline resolutions in the dateline model.
The methods above can be executed with or without animation. This animation can be controlled via the help of two properties: moveAnimated and moveDuration. The appropriate getter and setter methods for these properties are available on Timeline.
Zooming
The timeline is responsible for managing anything related to zooming. The user can press the + / - keys to increase the zoom level by a specific zoom factor or he can select a time interval via a "lasso" by dragging the mouse and holding down the SHIFT key. The result will be a selected time interval which is stored in the read-only property selectedTimeInterval. The timeline listens for changes to this property and will automatically try to display the selected time interval across the entire available width, ultimately causing a zoom in operation.
| Method | Description |
|---|---|
zoomIn() zoomOut() |
Makes the timeline modify the timeline model in such a way that the resulting visible time range will be the current time range multiplied by / divided by the current zoom factor. |
zoom(double factor, boolean zoomIn, Instant frozenTime) |
Performs a zoom operation with the given zoom factor (either zoom in or out). The timeline will try to keep the given "frozen" time at its current location. This kind of behaviour is very useful for a pinch-based zoom, where the UI zooms "into" a specific time. |
setZoomLassoEnabled(boolean); boolean isZoomLassoEnabled(); |
Controls the availability of the zoom lasso. |
Just like the moving operations the zoom operations can also be executed in an animated or non-animated way. To control this the two properties zoomAnimated and zoomDuration are available.
Another property is used to fine-tune the zooming behaviour as some applications prefer to either keep the start time, the end time, or the center time while zooming. For this the application can set the zoomMode property. Possible values of this enum are KEEP_START_TIME, KEEP_END_TIME, or CENTER.
Scrolling
The timeline supports scrolling to the left and right in two different speeds.
| Method | Description |
|---|---|
scrollLeft() scrollLeftFast() |
Changes the start time property of the timeline model in such a way that the dateline will end up starting with an earlier time. |
scrollRight() scrollRightFast() |
Changes the start time property of the timeline model in such a way that the dateline will end up starting with a later time. |
These methods can be invoked by the user via the + and - keys. Scrolling will be fast if the user presses SHIFT at the same time.
TimeTracker
The timeline control is responsible for tracking time. This means that it updates the property now of the underlying timeline model. The timeline implements methods for starting and stopping time tracking, however the actual update of now will be delegated to a time tracker class.
| Method | Description |
|---|---|
startTimeTracking() stopTimeTracking() |
Starts and stops time tracking. These methods invoke the equivalent methods on the TimeTracker class. |
timeTrackerProperty() setTimeTracker(TimeTracker tracker) TimeTracker getTimeTracker() |
The time tracker property and its getter and setter methods. The default time tracker (uses the system time) can be replaced with a custom one. |
Visible Time Interval
Two read-only properties are keeping track of the earliest and latest times shown by the timeline . They are called visibleStartTime and visibleEndTime and the methods getVisibleStartTime(), getVisibleEndTime(), and getVisibleDuration() can be used to work with them.
