FlexGanttFX Developer Manual : 3.7 Dateline

Introduction

Scale Resolutions

The dateline can display one to five rows. Each row is called a "dateline scale" and each one of these scales displays a "resolution". A resolution is comprised of a temporal unit (e.g. day, week, month), a pattern for formatting, and a quantity. The quantity is needed to specify resolutions like "5 minutes", "15 minutes", and so on. The entire list of resolutions that are currently shown by the dateline can be retrieved by calling getScaleResolutions(). 

One example for a use of this method is given by the system layer GridLinesLayer. It calls this method in order to use the resolutions to calculate the locations of the vertical grid lines. For this the Resolution class offers the methods truncate() to go to the beginning of a unit (e.g. the beginning of a day) and increment() to go to the next unit (e.g. the next day). For more information on Resolution please go to the dateline model documentation.

Primary Temporal Unit

A dateline with three scales could for example display the resolutions "month", "week", and "day". The smallest resolution "day" gets displayed at the bottom of the dateline. The temporal unit ChronoUnit.DAYS that is used by this resolution is also called "primary temporal unit". The current value of this unit is stored in the read-only property primaryTemporalUnit. The value of this property is used when querying activities from activity repositories. This way the repository can decide how fine-grained the result of its invocation will be or if certain activities will not be shown at all.

One example for a good use of the primary temporal unit is the WeekendCalendar class. It implements Calendar, which is an extension of ActivityRepository. The purpose of the WeekendCalendar is to return the weekend days (Saturday, Sunday) for a given time interval. When it gets invoked it will not return anything if the primary temporal unit is too large or too small. It makes no sense to return weekend information if the user is currently looking at minutes or decades.

Timezone

The dateline needs to know for which timezone it is displaying the dates (e.g. EST or GMT). Hence it features the property zoneIdProperty(). It is writable and can be set via setZoneId(). The value of this property can be made visible in the control by calling setZoneId(true). 

Selection Model

The dateline control allows the user to perform single or multiple selections of time intervals by clicking the primary mouse button while pressing the shortcut modifier key (CTRL on Windows / Linux, Option on Mac). Whether single or multiple selection is supported depends on the value of selectionModeProperty().

Only those intervals can be selected that are currently visible in any one of the rows / scales. So if the dateline is currently showing weeks and days then the user can only select an entire weeks or entire days. This list of selected intervals can be retrieved by calling getSelectedTimeIntervals(). 

Hover Time Interval

When the mouse cursor hovers over the dateline it also implies that it is hovering over a time interval. Depending on the resolution shown in the dateline row / scale at the given mouse location the interval might be an entire week or a single day. Whatever it is, the interval will be stored in the read-only property hoverTimeIntervalProperty().

Events

Applications can listen to scrolling events fired by the dateline when they need to react to any changes in the currently visible time range.This is done by passing an event listener to the setOnVisibleRangeChanged() method or by calling addEventListener(DatelineScrollingEvent.ANY, myListener).

Cell Factory

setCellFactory(SimpleUnit.class, 
	unit -> new SimpleUnitDatelineCell());
setCellFactory(ChronoUnit.class, 
	unit -> new ChronoUnitDatelineCell());