Using the time scale
Explains how to compose your time scale by specifying its rows.
Explains how to customize time scale rows,
Explains how to control row visibility for an
IlvTimeScale.
Describes the classes and interfaces provided to control row visibility and explains how to customize row visibility.
Explains how to emphasize specific time periods by granting them greater screen width than others.
Describes the precision of date display, and how you can minimize rounding errors by setting a reference time for a custom time converter.
Changing the rows of a time scale
A time scale (class
IlvTimeScale) is composed of rows (class
IlvTimeScaleRow). You can compose your time scale by specifying its rows. The Gantt or Schedule chart has a predefined time scale (class
IlvGanttTimeScale) that has two visible rows and which adjusts the row contents according to the zoom level.
To customize time scale rows, you need to:
1. Create some new time scale rows.
2. Set these rows on the time scale.
The following sections are based on the Relative Time Scale sample found in:
This sample demonstrates the capability of the time scale component, by customizing the time scale rows. The time scale rows are numbered relative to a reference date.
In the sample, two new rows are created, the new week and day rows. They are numbered starting from a reference date, rather than from the absolute date (which is the default numbering).
To create new rows:
1. Use the relative week row implementation is based on the
IlvWeekTimeScaleRow class. It can be found in
2. Use the relative day row implementation is based on the
IlvDayTimeScaleRow class. It are found in:
The code for setting these rows are found in:
To set these rows:
1. Create a time scale and the relative time scale rows:
IlvTimeScale timescale = new IlvTimeScale();
weekRow = new IlvRelativeWeekTimeScaleRow();
dayRow = new IlvRelativeDayTimeScaleRow();
2. Set the relative time scale reference date. In the example, it is set to be the closest hour:
Calendar calendar = Calendar.getInstance();
IlvCalendarUtil.dayFloor(calendar);
referenceDate = calendar.getTime();
weekRow.setReferenceDate(referenceDate);
dayRow.setReferenceDate(referenceDate);
3. Add the rows to the time scale, and set the time scale on the Gantt chart.
timescale.addRow(weekRow);
timescale.addRow(dayRow);
chart.setTimeScale(timescale);
Visibility policy
To control which rows are visible, the concept of visibility policy has been introduced on the Gantt time scale.
The
IlvTimeScaleVisibilityPolicy is an interface which lets you adjust the visible rows for the specified time scale through the
adjustRows method.
When you set a visibility policy on a time scale through the
setVisibilityPolicy method, the time scale will ask the visibility policy to determine which rows are visible when the time scale visible time interval changes.
The visibility policy dictates that:
If the policy is set to null, which is the default value, the visibility of the rows is based on their visible property.
If the policy is not null, the visibility of the rows is adjusted by calling the
adjustRows method.
Controlling row visibility
To enable control of row visibility, the following classes and interfaces are provided:
The class
IlvBasicTimeScaleVisibilityPolicy implements a default visibility policy for
IlvTimeScale. This policy determines which rows are visible when the time scale is resized, based on some visibility predicates applied to the paint context object. This policy keeps track of each visibility predicate, with its set of visible rows, in a specified order. When asked to adjust the rows visibility, the first visibility predicate that evaluates to
true is the one used for adjusting the rows.
The class
IlvTimeWidthVisibilityPredicate provides a way to specify a condition based on the size of a time unit, which can be pixel-based or character-length-based.
The customVisibility code fragment, found in
<installdir>/jviews-gantt/codefragments/timescale/customVisibility shows how to use these classes for controlling visibility. This code fragment can also be run as an application.
To customize row visibility:
1. Create the time scale.
IlvTimeScale timescale = new IlvTimeScale();
2. Create the necessary rows and customize them.
// A customized quarter row
IlvQuarterTimeScaleRow quarterRow = new IlvQuarterTimeScaleRow();
quarterRow.setTextColor(Color.white);
quarterRow.setTextFont(new Font("default", Font.PLAIN, 14));
quarterRow.setTextPosition(IlvBasicTimeScaleRow.CENTER);
...
3. Add the rows to the time scale.
timescale.addRow(quarterRow);
...
4. Create the visibility policy.
IlvBasicTimeScaleVisibilityPolicy visibilityPolicy =
new IlvBasicTimeScaleVisibilityPolicy();
5. Create the list of visibility conditions.
Each visibility condition is characterized by a predicate and the list of visible rows when this predicate is true.
// First visibility condition is to have the 4 rows visible when at
// least 4 characters can be seen for the month.
// Create the predicate
IlvTimeWidthVisibilityPredicate cond1 =
new IlvTimeWidthVisibilityPredicate(
Calendar.DAY_OF_MONTH,
IlvTimeWidthVisibilityPredicate.CHARACTER,
4);
cond1.setFont(new Font("SansSerif", Font.BOLD, 18));
// Create the first visibility condition with the predicate
IlvVisibleTimeScaleRows visCond1 = new IlvVisibleTimeScaleRows(cond1);
// Add the visible rows.
visCond1.addRow(quarterRow);
visCond1.addRow(monthRow);
visCond1.addRow(dayRow);
visCond1.addRow(halfDayRow);
...
6. Add these visibility conditions to the visibility policy.
visibilityPolicy.addVisibleTimeScaleRows(visCond1);
7. Set the visibility on the time scale.
timescale.setVisibilityPolicy(visibilityPolicy);
Nonlinear time scale
In
JViews Gantt, the conversion from time to horizontal screen coordinates is performed by an implementation of the
IlvTimeConverter interface. The default implementation,
IlvLinearTimeConverter, performs a linear conversion. This implies that all time units of equal duration, such as days and hours, will occupy equal width on the screen. However, it is also possible to define a nonlinear time converter that will emphasize specific time periods by granting them greater screen width than others.
NOTE When a nonlinear time converter is set on a Gantt or Schedule chart, scrolling performance is reduced compared to using a linear time converter.
The following table shows the three methods to be implemented in the IlvTimeConverter interface.
Method | Description |
double getUnits(Date time) | Converts time to IlvManager x-axis coordinates |
Date getTime(double units) | Converts IlvManager x-axis coordinates to time |
boolean isLinear() | Indicates whether the time converter is linear |
The getUnits and getTime methods must implement a complementary and reversible conversion. In other words, for any Date t:
t.equals(getTime(getUnits(t)))
and for any manager x-coordinate u:
u == getUnits(getTime(u))
Any nonlinear time converter must implement the isLinear method to return false. Use the source code for the nonlinear WeekTimeConverter class as the starting point for developing your own custom time converter implementation.
An example implementation of a nonlinear time converter is provided in the Nonlinear Time Scale sample. This sample emphasizes days during the work week by giving them greater screen width than days on the weekend.
To view the sample:
1. Open the file:
2. Follow the instructions to run the Nonlinear Time Scale Example.
The source code of this example is found in:
To create a nonlinear time scale:
1. Create a nonlinear time converter instance:
IlvTimeConverter converter = new WeekTimeConverter();
2. Set the nonlinear time converter on the Gantt or Schedule chart:
chart.setTimeConverter(converter);
Controlling rounding errors
The display of activities in
IlvGanttSheet has a precision of seven decimal digits. Therefore, in a Gantt project that contains activities for an interval of one year, the display may have rounding errors of up to 5 seconds, and in a project that lasts one month, rounding errors can affect the accuracy of the display by up to 1 second.
This limitation exists because IlvGanttSheet is based on the JViews Graphic Framework, which uses
float values for the x coordinates. These values have a precision of seven decimal digits. Time points, such as the start and end of an activity, are first converted by
IlvTimeConverter to the
double data type, and then to the
float data type when used as x coordinates.
Time converters use a reference time that they map to 0. Time points near the reference time are mapped with better absolute precision than time points that are far away from the reference time. The reference time is not directly visible in a Gantt sheet. Except for rounding errors, different reference times produce the same display.
The heuristic that IlvGanttSheet uses to determine the reference time of its time converter depends on the data model. It typically uses a time point near the first start time of any activity in the initial contents of the model. If this fails, it uses a time point in the current day as the reference time. To minimize rounding errors, you can override the heuristic, and control the reference time yourself, by creating a time converter and setting it in the chart, using the
setTimeConverter method.
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.
