Time Bar

Removes all data from the time bar.

Destroys the current instance of the time bar, freeing any allocated resources.

Note: This action cannot be undone. Create a new time bar instance with KeyLines.create() to access the timebar namespace.

timebar.destroy();

Returns an array of the ids that have datetimes in the specified range. A datetime dt is in the specified range if it satisfies dt1 <= dt < dt2.

Determines whether the item has a datetime either within the time bar's time range, or which overlaps any part of a time period in the range. Note that the item must have been loaded into the time bar.

If the item does not have a datetime, or the item does not exist or overlap a time period in the time bar's loaded data, then inRange() will return false.

Replaces the time bar data with the new data specified.

The data argument is a JavaScript Object, not a JSON string. It should have the properties specified by the Time Bar Item Properties.

If the loaded data changes the current time range, the timebar.change() event is not fired. If you don't want the range to change, first set the maxRange time bar option to take account of the data you're about to load.

To fit the time bar to the data once it has been loaded, use returned promise:

timebar.load(data).then(() => {
  return timebar.zoom('fit', { animate: false });
});

Sets or gets a list of dates or time periods (with both start time and end time specified) which should be marked in a different colour in the histogram.

This example shows how to mark one time as well as a range of times:

const marks = [
  // mark 1 - single date
  new Date('26 Jul 2010 08:00:00'),
  // mark 2 - time period - both start and end time must be set
  {
    dt1: new Date('18 Jul 2010 14:00:00'),
    dt2: new Date('21 Jul 2010 14:00:00')
  }
];
timebar.mark(marks);

To clear all the marks pass an empty array as an argument.

Inserts new data into the time bar, merging it with any existing time bar data.

Incoming items that exactly match existing items in the time bar are merged with them on a one-to-one basis.

Note that the items argument is a JavaScript object or array, not a JSON string. It should have the properties specified in the Time Bar Object Properties.

Detaches an event handler function for one or more events attached to the time bar using the on() function.

timebar.off('change', changeEventHandler);

If no handler is supplied, all handlers for the specified event are detached. If no event name is supplied, all event handlers for all events are detached.

Attaches an event handler function for one or more Time Bar Events to the time bar.

function changeEventHandler() {
  // respond to change event
}
timebar.on('change', changeEventHandler);

To detach event handlers, use off().

See Events Basics for more details.

Sets or gets options for the time bar.

Note that using this promisified function as a getter still returns an object in a synchronous way. See Special Cases: getters and setters for more detail.

Pans the time bar in the direction specified.

Stops the continuous animation of the time bar range started by play().

Starts a continuous animation of the time bar range. The speed of the animation can be set via the options function's playSpeed property.

Sets or gets the time range of the time bar. If called without parameters, it returns the time range of the time bar without updating it.

Setting the time range causes different visual effects according to whether the sliders are fixed, free, or not present.

• If the sliders are fixed then setting the time range moves and zooms the scale underneath the sliders.
• If the sliders are free then the sliders themselves move to the time range specified and scale does not change.
• If there are no sliders (sliders:'none') then the time range is displayed in the full width of the time bar.

Things to note:

• There are minimum and maximum limits on the time range size, and the time range must either overlap or be adjacent to the time range of loaded data. The requested range may be adjusted to meet these constraints.
• The range function returns a JavaScript Date object. For more details see Time Zones.
• Using this promisified function as a getter still returns an object in a synchronous way. See Special Cases: getters and setters for more detail.

Removes item or items with the id(s) specified. Pass a single id to remove a single item, or an array of id strings to remove many items at once. Note that there is no event to detect items being removed from the time bar.

Sets or gets the time bar selection lines.

This example shows how to create multiple selection lines by passing an array:

const lines = [
  // selection 1 - blue colour
  { id: ['id1', 'id2'], index: 0, c: 'blue' },
  // selection 2 - default colour
  { id: ['id3', 'id4'], index: 1 }
];
timebar.selection(lines);

To clear all the selections pass an empty array as argument. To clear a specific selection pass a selection object with an empty array as the id and its index.

Things to note:

• The maximum number of selection lines available is 3: any selection with an index greater than 2 will be ignored. The default colours for the selection lines are: 0: green; 1: orange; 2: dark red.
• The selection lines use a different scale to the histogram bars. Selection lines are scaled depending on the values within the selection range.
• Passing a smaller array in subsequent selection() calls will not clear all selection lines. To clear existing selection lines, pad the array with empty objects.

Sets the location of the time bar in the DOM. Pass null as the argument to hide it completely.

Things to note:

• You must specify the container parameter in KeyLines.create() to use setContainer.
• While the container is set to null all drawing and animations are paused.

timebar.setContainer('timebarContainer');

Zooms the time bar in the manner specified.