Skip to main content
Version: 4.2

Interface: ITimeScaleApi<HorzScaleItem>

Interface to chart time scale

Type parameters

Name
HorzScaleItem

Methods

scrollPosition

scrollPosition(): number

Return the distance from the right edge of the time scale to the lastest bar of the series measured in bars.

Returns

number


scrollToPosition

scrollToPosition(position, animated): void

Scrolls the chart to the specified position.

Parameters

NameTypeDescription
positionnumberTarget data position
animatedbooleanSetting this to true makes the chart scrolling smooth and adds animation

Returns

void


scrollToRealTime

scrollToRealTime(): void

Restores default scroll position of the chart. This process is always animated.

Returns

void


getVisibleRange

getVisibleRange(): Range<HorzScaleItem>

Returns current visible time range of the chart.

Note that this method cannot extrapolate time and will use the only currently existent data. To get complete information about current visible range, please use getVisibleLogicalRange and barsInLogicalRange.

Returns

Range<HorzScaleItem>

Visible range or null if the chart has no data at all.


setVisibleRange

setVisibleRange(range): void

Sets visible range of data.

Note that this method cannot extrapolate time and will use the only currently existent data. Thus, for example, if currently a chart doesn't have data prior 2018-01-01 date and you set visible range with from date 2016-01-01, it will be automatically adjusted to 2018-01-01 (and the same for to date).

But if you can approximate indexes on your own - you could use setVisibleLogicalRange instead.

Example

chart.timeScale().setVisibleRange({
from: (new Date(Date.UTC(2018, 0, 1, 0, 0, 0, 0))).getTime() / 1000,
to: (new Date(Date.UTC(2018, 1, 1, 0, 0, 0, 0))).getTime() / 1000,
});

Parameters

NameTypeDescription
rangeRange<HorzScaleItem>Target visible range of data.

Returns

void


getVisibleLogicalRange

getVisibleLogicalRange(): LogicalRange

Returns the current visible logical range of the chart as an object with the first and last time points of the logical range, or returns null if the chart has no data.

Returns

LogicalRange

Visible range or null if the chart has no data at all.


setVisibleLogicalRange

setVisibleLogicalRange(range): void

Sets visible logical range of data.

Example

chart.timeScale().setVisibleLogicalRange({ from: 0, to: Date.now() / 1000 });

Parameters

NameTypeDescription
rangeRange<number>Target visible logical range of data.

Returns

void


resetTimeScale

resetTimeScale(): void

Restores default zoom level and scroll position of the time scale.

Returns

void


fitContent

fitContent(): void

Automatically calculates the visible range to fit all data from all series.

Returns

void


logicalToCoordinate

logicalToCoordinate(logical): Coordinate

Converts a logical index to local x coordinate.

Parameters

NameTypeDescription
logicalLogicalLogical index needs to be converted

Returns

Coordinate

x coordinate of that time or null if the chart doesn't have data


coordinateToLogical

coordinateToLogical(x): Logical

Converts a coordinate to logical index.

Parameters

NameTypeDescription
xnumberCoordinate needs to be converted

Returns

Logical

Logical index that is located on that coordinate or null if the chart doesn't have data


timeToCoordinate

timeToCoordinate(time): Coordinate

Converts a time to local x coordinate.

Parameters

NameTypeDescription
timeHorzScaleItemTime needs to be converted

Returns

Coordinate

X coordinate of that time or null if no time found on time scale


coordinateToTime

coordinateToTime(x): HorzScaleItem

Converts a coordinate to time.

Parameters

NameTypeDescription
xnumberCoordinate needs to be converted.

Returns

HorzScaleItem

Time of a bar that is located on that coordinate or null if there are no bars found on that coordinate.


width

width(): number

Returns a width of the time scale.

Returns

number


height

height(): number

Returns a height of the time scale.

Returns

number


subscribeVisibleTimeRangeChange

subscribeVisibleTimeRangeChange(handler): void

Subscribe to the visible time range change events.

The argument passed to the handler function is an object with from and to properties of type Time, or null if there is no visible data.

Example

function myVisibleTimeRangeChangeHandler(newVisibleTimeRange) {
if (newVisibleTimeRange === null) {
// handle null
}

// handle new logical range
}

chart.timeScale().subscribeVisibleTimeRangeChange(myVisibleTimeRangeChangeHandler);

Parameters

NameTypeDescription
handlerTimeRangeChangeEventHandler<HorzScaleItem>Handler (function) to be called when the visible indexes change.

Returns

void


unsubscribeVisibleTimeRangeChange

unsubscribeVisibleTimeRangeChange(handler): void

Unsubscribe a handler that was previously subscribed using subscribeVisibleTimeRangeChange.

Example

chart.timeScale().unsubscribeVisibleTimeRangeChange(myVisibleTimeRangeChangeHandler);

Parameters

NameTypeDescription
handlerTimeRangeChangeEventHandler<HorzScaleItem>Previously subscribed handler

Returns

void


subscribeVisibleLogicalRangeChange

subscribeVisibleLogicalRangeChange(handler): void

Subscribe to the visible logical range change events.

The argument passed to the handler function is an object with from and to properties of type number, or null if there is no visible data.

Example

function myVisibleLogicalRangeChangeHandler(newVisibleLogicalRange) {
if (newVisibleLogicalRange === null) {
// handle null
}

// handle new logical range
}

chart.timeScale().subscribeVisibleLogicalRangeChange(myVisibleLogicalRangeChangeHandler);

Parameters

NameTypeDescription
handlerLogicalRangeChangeEventHandlerHandler (function) to be called when the visible indexes change.

Returns

void


unsubscribeVisibleLogicalRangeChange

unsubscribeVisibleLogicalRangeChange(handler): void

Unsubscribe a handler that was previously subscribed using subscribeVisibleLogicalRangeChange.

Example

chart.timeScale().unsubscribeVisibleLogicalRangeChange(myVisibleLogicalRangeChangeHandler);

Parameters

NameTypeDescription
handlerLogicalRangeChangeEventHandlerPreviously subscribed handler

Returns

void


subscribeSizeChange

subscribeSizeChange(handler): void

Adds a subscription to time scale size changes

Parameters

NameTypeDescription
handlerSizeChangeEventHandlerHandler (function) to be called when the time scale size changes

Returns

void


unsubscribeSizeChange

unsubscribeSizeChange(handler): void

Removes a subscription to time scale size changes

Parameters

NameTypeDescription
handlerSizeChangeEventHandlerPreviously subscribed handler

Returns

void


applyOptions

applyOptions(options): void

Applies new options to the time scale.

Parameters

NameTypeDescription
optionsDeepPartial<HorzScaleOptions>Any subset of options.

Returns

void


options

options(): Readonly<HorzScaleOptions>

Returns current options

Returns

Readonly<HorzScaleOptions>

Currently applied options