ZoomCharts Documentation

ZoomCharts.TimeChart

Inheritance hierarchy

This type inherits from BaseApi.

Constructors

.ctor: (settings: TimeChartSettings)
Parameters
Return value
Data type: TimeChart

Methods

addData: (data: TimeChartDataObject, sourceId?: string): void
Inherited from: BaseApi

Adds the given data to whatever data the chart has currently loaded. The chart will automatically be updated to display this new data if it falls within the currently visible bounds.

Parameters
sourceId: string

the ID of the data source that will be updated. The default value is default.

addSubchartContainer: (container: HTMLElement): void
Inherited from: BaseApi
This property is deprected; use settings.parentChart instead.
Parameters
container: string | HTMLElement
back: (): this
Inherited from: BaseApi
Return value
Data type: this
clearHistory: (): this
Inherited from: BaseApi
Return value
Data type: this
customize: (name: string): this
Inherited from: BaseApi

Applies one of the built-in themes to the chart. This is an alternative to calling updateSettings({ theme: ZoomCharts.TimeChart.themes.dark }).

Parameters
name: string

The name of the theme to be applied, must be one of the values defined in the TimeChart.themes static property.

Return value
Data type: this
displayUnit: (unit?: string, animate?: boolean, rescale?: boolean): string
Version 1.14.0: Removed the support for rescale parameter. Added the support for setting the auto display unit.

Gets or sets the current display unit. Note that setting the display unit might also result in changes of the current time range to ensure that the unit follows the min/max widths.

If unit: "auto" is used to select the best-fit display unit, the chart determines the correct display unit based on timeAxis.unitSizePolicy setting.

Note that this method can be used to set a display unit that the chart is not configured to use but in this case a warning will be displayed in the browser console because user interactions will not preserve this setting. To avoid this, specify the needed display units in area.displayUnits.

Parameters
unit: string

If specified, updates the current display unit. Example values: m, s, h, 2 h, 10 m, auto.

animate: boolean

When setting the display unit, specifies if the chart animates the transition.

rescale: boolean

Deprecated as of 1.14.0.

Return value
Data type: string

The current display unit in format {count} {unit} or null if the display unit is not yet set.

export: (type: "png" | "jpg" | "pdf" | "csv" | "xlsx", dimensions?: BaseExportDimensions, transparent?: boolean): void
Inherited from: BaseApi

Launches a file download that contains an image or the data of the current state of the chart.

Note that in some browsers calling this method will send the data to a proxy. When handling sensitive data you should install the proxy on your own server, see advanced.exportProxyURL setting.

Parameters
type: "png" | "jpg" | "pdf" | "csv" | "xlsx"

The format in which the data will be exported.

Specifies the dimensions for the image formats.

transparent: boolean
Version 1.12.0: default changed to false.

Specifies if the resulting image should have transparent background. This setting is only valid for png image format. Default is false.

Note that if area.style.fillColor is set, this will have no effect.

exportAsString: (type: "png" | "jpg" | "pdf" | "csv" | "xlsx", callback: (dataUri: string, mimeType: string, extension: string) => void, dimensions?: BaseExportDimensions, transparent?: boolean): void
Inherited from: BaseApi

Saves the current chart state as a data-URI.

If image type is specified, the URI can be used as the image source in <img src="">.

Note that some output settings might require sending the data to a proxy. When handling sensitive data you should install the proxy on your own server, see advanced.exportProxyURL setting.

Parameters
type: "png" | "jpg" | "pdf" | "csv" | "xlsx"

The format in which the data will be exported.

callback: (dataUri: string, mimeType: string, extension: string) => void

The callback that will be invoked once the result is generated.

Parameters
dataUri: string

The data-uri that contains the generated image or data file.

mimeType: string

The mime type of the generated file.

extension: string

The extension of the generated file.

Specifies the dimensions for the image formats.

transparent: boolean

Specifies if the resulting image should have transparent background. This setting is only valid for png image format. Default is false.

Note that if area.style.fillColor is set, this will have no effect.

exportGetDimensions: (dimensions: BaseExportDimensions): { width: number; height: number; scale: number; chartWidth: number; chartHeight: number; }
Inherited from: BaseApi
This property is deprected; use `exportImageGetDimensions` instead

Returns the dimensions for the image exported with exportImageAsString.

Parameters
Return value
Data type: anonymous type
Properties
width: number
height: number
scale: number
chartWidth: number
chartHeight: number
exportImageAsString: (type: "png" | "jpg" | "pdf" | "csv" | "xlsx", dimensions: BaseExportDimensions, transparent: boolean): string
Inherited from: BaseApi
This property is deprected; use `exportAsString` instead.

Saves the current chart state as an image.

Note that this method does not support custom DPI setting, for that exportAsString method has to be used.

Parameters
type: "png" | "jpg" | "pdf" | "csv" | "xlsx"
transparent: boolean
Return value
Data type: string

A base64 encoded data-URI that contains the image data. This URI can be used as the image source in <img src="">.

exportImageGetDimensions: (dimensions: BaseExportDimensions): { width: number; height: number; scale: number; chartWidth: number; chartHeight: number; }
Inherited from: BaseApi

Returns the dimensions for the image exported with exportImageAsString.

Parameters
Return value
Data type: anonymous type
Properties
width: number
height: number
scale: number
chartWidth: number
chartHeight: number
exportVisibleData: (): Array<Array<string | number>>
Return value
Data type: Array<Array<string | number>>
fullscreen: (isFullscreen?: boolean): boolean
Inherited from: BaseApi

Gets or sets the fullscreen state of the chart.

Parameters
isFullscreen: boolean

specify true or false to set the state, omit the value to get the current state.

Return value
Data type: boolean
getEnabledSeries: (): Array<TimeChartSettingsSeries>
Introduced in version 1.14.0.

Gets the currently enabled series

Return value
Introduced in version 1.18.2.

Gets all series even those that are not enabled

Return value
home: (): boolean
Inherited from: BaseApi
Return value
Data type: boolean
off: (name: string, listener: (event: BaseMouseEvent, args: BaseChartEventArguments) => void): boolean
Inherited from: BaseApi

Removes an event listener that was added by a call to on or by specifying it in settings. Note that the listener must be the exact same reference, which means that anonymous functions should not be used in call to on.

Parameters
name: string

the type of the event. Please see the documentation for on about valid values.

listener: (event: BaseMouseEvent, args: BaseChartEventArguments) => void
Parameters
Return value
Data type: boolean

true if the listener was removed, false if the listener was not previously registered.

on: (name: string, listener: (event: BaseMouseEvent, args: BaseChartEventArguments) => void): void
Inherited from: BaseApi

Adds event listener.

Parameters
name: string

The type of the event for which the listener will be added. See method overloads for valid values.

listener: (event: BaseMouseEvent, args: BaseChartEventArguments) => void

The callback function. It receives two arguments - the mouse event data and a separate object containing chart specific information.

Parameters
Overloads
on: (name: "animationDone", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void

Adds an event listener for when the scroll animation completes.

Parameters
name: "animationDone"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "chartUpdate", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "chartUpdate"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "click", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "click"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "doubleClick", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "doubleClick"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "error", listener: (event: BaseMouseEvent, args: BaseChartErrorEventArguments) => void): void
Parameters
name: "error"
listener: (event: BaseMouseEvent, args: BaseChartErrorEventArguments) => void
Parameters

An empty mouse event.

on: (name: "hoverChange", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "hoverChange"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "positionChange", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "positionChange"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "rightClick", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "rightClick"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "selectionChange", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "selectionChange"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
on: (name: "settingsChange", listener: (event: BaseMouseEvent, args: BaseChartSettingsChangeEventArguments) => void): void
Parameters
name: "settingsChange"
on: (name: "tripleClick", listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void): void
Parameters
name: "tripleClick"
listener: (event: BaseMouseEvent, args: TimeChartChartEventArguments) => void
paintNow: (force?: boolean): this
Inherited from: BaseApi

Does immediate repaint. Use to sync updates between multiple charts.

Parameters
force: boolean
Return value
Data type: this
profiler: (): BaseProfiler
Inherited from: BaseApi
Return value
Data type: BaseProfiler
reloadData: (sourceId?: string): void
Inherited from: BaseApi

Clears data cache and loads new data. The current view is preserved.

Parameters
sourceId: string
remove: (): void
Inherited from: BaseApi

Removes chart from DOM. This method is automatically called when you create a new chart within the same container element.

This method should always be called when the chart HTML element is removed as otherwise there might be additional resources such as event handlers remaining that will prevent the browser from properly releasing memory.

replaceData: (data: TimeChartDataObject, sourceId?: string): void
Inherited from: BaseApi

Replaces the data already in the data cache with the given values.

Parameters
sourceId: string

the ID of the data source that will be updated. The default value is default.

replaceSeries: (series: Array<LinearChartSettingsSeries>): this
Use `replaceSettings({series: seriesData})` instead.

Replaces the existing series configuration with new one instead of merging it like updateSettings.

Parameters
Return value
Data type: this
replaceSettings: (changes: TimeChartSettings): this
Inherited from: BaseApi
Introduced in version 1.10.0.

Updates the chart settings but instead of merging some settings that are arrays or dictionaries (such as data) these collections are replaced completely. For example, this allows removal of series or value axis within TimeChart.

Parameters
Return value
Data type: this
restoreState: (state: string, animate?: boolean): void
Inherited from: BaseApi
Parameters
state: string
animate: boolean
resumePaint: (): void
Inherited from: BaseApi
Experimental property - the API might not be stable and is subject to change.

Decrements the suspend counter that was set using suspendPaint() method.

This method also automatically schedules an async repaint.

saveAsImage: (type: "png" | "jpg" | "pdf" | "csv" | "xlsx", dimensions: BaseExportDimensions, transparent: boolean): string
Inherited from: BaseApi
This property is deprected; use `exportAsString` instead

Saves the current chart state as an image.

Parameters
type: "png" | "jpg" | "pdf" | "csv" | "xlsx"
transparent: boolean
Return value
Data type: string

A base64 encoded data-URI that contains the image data. This URI can be used as the image source in <img src="">.

saveState: (): string
Inherited from: BaseApi
Return value
Data type: string
scroll: (amount: string, animate?: boolean, snap?: boolean): void

Scrolls the visible chart area left or right.

Parameters
amount: string

how much to scroll

animate: boolean

scroll with animation or without

snap: boolean

adjust the scroll to snap according to the current displayUnit

The amount property format: < amount unit or > amount unit.

  • < scrolls to the left, > scrolls to the right
  • amount: integer amount of units to scroll
  • unit: one of the following: page, bar, y, M, d, w, h, m, s, ms.

Examples:

  • scroll("< 1 s") - scrolls left 1 second, no animation
  • scroll("> 10 y", true) - scrolls right, 10 years with animation
selection: (from?: number | Date | moment.Moment, to?: number | Date | moment.Moment): [number, number]
Version 1.12.0: parameters now take an UTC timestamp and not the chart internal timestamp.
Version 1.15.0: parameters that are Date or moment instances are now accepted.

Gets or sets the selection in javascript timestamp (milliseconds). All timestamps are in UTC.

Use from: null, to: null to remove selection. If the chart does not have a selection, the method returns [null, null].

Note that this method will return [null, null] if moment-timezone library is still being downloaded.

Parameters
Return value
Data type: [number, number]
setDisplayPeriod: (period: string, anchor: number | "newestData" | "now" | "oldestData", animate?: boolean): void
Version 1.12.0: period parameter now takes UTC timestamps and not the chart internal timestamps.

Set displayed time range using period and anchor.

See initialDisplayAnchor and initialDisplayPeriod documentation for possible period / anchor values.

Parameters
period: string
anchor: number | "newestData" | "now" | "oldestData"
animate: boolean
showInfoPopup: (from: number | Date | moment.Moment, to?: number | Date | moment.Moment, contents?: string): void
Introduced in version 1.12.2.
Version 1.15.0: parameters can now be passed as Date or moment instances.

Displays the info popup for a specified time interval. The interval must be visible on screen.

Note that if info.enabled is set to false this method still works. In this case the info popup shown by this method will not be hidden as the user hovers the mouse over the chart.

Parameters

UTC timestamp of the start of the interval (inclusive). The value will be automatically rounded down based on the current display unit. Passing null will hide the info popup.

UTC timestamp of the end of the interval (non-inclusive). The value will be automatically rounded up based on the current display unit. If not specified, selects a single unit starting with the from timestamp.

contents: string

Optional HTML code that will be used as the contents of the info popup. If this is not specified, the default contents will be generated.

suspendPaint: (): void
Inherited from: BaseApi
Experimental property - the API might not be stable and is subject to change.

Suspends the animation of the chart until resumePaint() is called.

This should be used when the chart element is hidden from the user to conserve browser resources.

Note that if suspendPaint() is called multiple time then resumePaint() has to be called the same number of times.

targetDisplayUnit: (): string
Introduced in version 1.15.0.

When the chart is animating, gets the target display unit (otherwise returns the current display unit).

See also
Return value
Data type: string
targetTime: (): [number, number]
Introduced in version 1.14.0.

When the chart is animating, gets the target time range (otherwise returns the current time range).

This method is useful when there are related data objects (such as data tables or other charts) that have to be filtered based on the visible time range in the chart. By using onChartUpdate event and this method it is possible to start updating the page as soon as the animation change but do it for the values the chart is animating towards.

If the data has not yet been loaded, this method returns [null, null].

See also
Return value
Data type: [number, number]

Array with two members - the first is the UTC timestamp of the start, the second the UTC timestamp of the end of the time range.

time: (from?: number | Date | moment.Moment, to?: number | Date | moment.Moment, animate?: boolean): [number, number]
Version 1.12.0: parameters now take UTC timestamps and not the chart internal timestamp.
Version 1.13.2: the new time range will be modified accoring to the limits in chart configuration and display unit might be changed based on the range.
Version 1.15.0: parameters can now be passed as Date or moment instances.

Gets or sets the displayed time range in JavaScript timestamp (milliseconds). Note that both from and to must be specified for the time range to be updated.

All timestamps are specified in UTC.

Note that this method will return [null, null] if moment-timezone library is still being downloaded.

Parameters
Return value
Data type: [number, number]
updateFilters: (): void
Inherited from: BaseApi

Re-evaluate data filters on next paint.

updateSettings: (changes: TimeChartSettings): this
Inherited from: BaseApi

Updates the chart settings. Only the settings that have to be changed should be passed. Note that some arrays and dictionaries (such as data) are merged by the ID values - if instead they should be replaced, use replaceSettings() method.

Parameters
Return value
Data type: this
updateSize: (): this
Inherited from: BaseApi

Call when the container size has been changed to update the chart.

Return value
Data type: this
updateStyle: (): void
Inherited from: BaseApi

Re-evaluate style for all objects on next paint.

zoomIn: (unit?: string, center?: number | Date | moment.Moment, animate?: boolean): void
Version 1.12.0: center parameter now takes an UTC timestamp and not the chart internal timestamp.
Version 1.15.0: center parameter can now be passed as Date or moment instance.

Decreases the visible time range on the chart.

Has no effect if the chart data has not been yet loaded.

Parameters
unit: string

the target unit in form 1 d; if not specified, the unit is determined automatically.

the UTC timestamp that should be the new center of the visible area.

animate: boolean

determines if the zoom animation is executed.

zoomOut: (unit?: string, animate?: boolean): void

Increases the visible time range on the chart.

Has no effect if the chart data has not been yet loaded.

Parameters
unit: string

the target unit in form 1 d; if not specified, the unit is determined automatically.

animate: boolean

determines if the zoom animation is executed.

Static properties

Lists the predefined themes for the chart. These can be used within the settings objects or via the customize() method:

var chart = new ZoomCharts.TimeChart({ theme: ZoomCharts.TimeChart.themes.dark });
chart.updateSettings({ theme: ZoomChart.TimeChart.themes.dark });
chart.customize("dark");
Properties
Introduced in version 1.8.0.
Version 1.15.0: improved to also disable toolbar buttons and clicking on the chart.

Disables all user interactions so that the initial view is always persisted.

Properties

typeName: string
Inherited from: BaseApi

Gets the name of the chart the JavaScript object references. For example 'PieChart' or 'TimeChart'. This field is read-only.

X