Skip to main content

Interface: IChartWidgetApi

Charting Library.IChartWidgetApi

The main chart API.

This interface can be retrieved by using the following widget (IChartingLibraryWidget) methods:

Methods

applyStudyTemplate

applyStudyTemplate(template): void

Apply a study template to the chart.

Example

widget.activeChart().applyStudyTemplate(template);

Parameters

NameTypeDescription
templateobjectA study template object.

Returns

void


availableZOrderOperations

availableZOrderOperations(sources): AvailableZOrderOperations

Get an object with operations available for the specified set of entities.

Example

widget.activeChart().availableZOrderOperations([id]);

Parameters

NameTypeDescription
sourcesreadonly EntityId[]An array of entity IDs.

Returns

AvailableZOrderOperations


barTimeToEndOfPeriod

barTimeToEndOfPeriod(unixTime): number

Get the bar time to the end of the period

Parameters

NameTypeDescription
unixTimenumberdate timestamp

Returns

number


bringForward

bringForward(sources): void

Move the sources one level up in the Z-order.

Example

widget.activeChart().bringForward([id]);

Parameters

NameTypeDescription
sourcesreadonly EntityId[]An array of source IDs.

Returns

void


bringToFront

bringToFront(sources): void

Move the sources to the top of the Z-order.

Example

widget.activeChart().bringToFront([id]);

Parameters

NameTypeDescription
sourcesreadonly EntityId[]An array of source IDs.

Returns

void


canZoomOut

canZoomOut(): boolean

Check if the chart can be zoomed out using the zoomOut method.

Example

if(widget.activeChart().canZoomOut()) {
widget.activeChart().zoomOut();
};

Returns

boolean

true if the chart can be zoomed out.


cancelSelectBar

cancelSelectBar(): void

Cancel any active bar selection requests.

Example

widget.activeChart().cancelSelectBar();

Returns

void


chartType

chartType(): SeriesType

Returns the main series style type.

console.log(widget.activeChart().chartType());

Returns

SeriesType


clearMarks

clearMarks(marksToClear?): void

Remove marks from the chart.

Example

widget.activeChart().clearMarks();

Parameters

NameTypeDescription
marksToClear?ClearMarksModetype of marks to clear. If nothing is specified both bar & timescale marks will be removed.

Returns

void


createAnchoredShape

createAnchoredShape<TOverrides>(position, options): EntityId

Create a new anchored drawing. Anchored drawings maintain their position when the chart's visible range changes.

Example

widget.createAnchoredShape({ x: 0.1, y: 0.9 }, { shape: 'anchored_text', text: 'Hello, charts!', overrides: { color: 'green' }});

Type parameters

NameType
TOverridesextends object

Parameters

NameTypeDescription
positionPositionPercentsPercent-based x and y position of the new drawing, relative to the top left of the chart.
optionsCreateAnchoredShapeOptions<TOverrides>An options object for the new drawing.

Returns

EntityId


createExecutionShape

createExecutionShape(options?): IExecutionLineAdapter

Creates a new trade execution on the chart.

Example

widget.activeChart().createExecutionShape()
.setText("@1,320.75 Limit Buy 1")
.setTooltip("@1,320.75 Limit Buy 1")
.setTextColor("rgba(0,255,0,0.5)")
.setArrowColor("#0F0")
.setDirection("buy")
.setTime(widget.activeChart().getVisibleRange().from)
.setPrice(160);

Parameters

NameTypeDescription
options?UndoOptionsOptional undo options.

Returns

IExecutionLineAdapter

An API object for interacting with the execution.


createMultipointShape

createMultipointShape<TOverrides>(points, options): EntityId

Create a new multi point drawing.

Example

const from = Date.now() / 1000 - 500 * 24 * 3600; // 500 days ago
const to = Date.now() / 1000;
widget.activeChart().createMultipointShape(
[{ time: from, price: 150 }, { time: to, price: 150 }],
{
shape: "trend_line",
lock: true,
disableSelection: true,
disableSave: true,
disableUndo: true,
text: "text",
}
);

Type parameters

NameType
TOverridesextends object

Parameters

NameTypeDescription
pointsShapePoint[]An array of points that define the drawing.
optionsCreateMultipointShapeOptions<TOverrides>An options object for the new drawing.

Returns

EntityId

The ID of the new drawing if it was created successfully, or null otherwise.


createOrderLine

createOrderLine(options?): IOrderLineAdapter

Create a new trading order on the chart.

Example

widget.activeChart().createOrderLine()
.setTooltip("Additional order information")
.setModifyTooltip("Modify order")
.setCancelTooltip("Cancel order")
.onMove(function() {
this.setText("onMove called");
})
.onModify("onModify called", function(text) {
this.setText(text);
})
.onCancel("onCancel called", function(text) {
this.setText(text);
})
.setText("STOP: 73.5 (5,64%)")
.setQuantity("2");

Parameters

NameTypeDescription
options?UndoOptionsOptional undo options.

Returns

IOrderLineAdapter

An API object for interacting with the order.


createPositionLine

createPositionLine(options?): IPositionLineAdapter

Creates a new trading position on the chart.

Example

widget.chart().createPositionLine()
.onModify(function() {
this.setText("onModify called");
})
.onReverse("onReverse called", function(text) {
this.setText(text);
})
.onClose("onClose called", function(text) {
this.setText(text);
})
.setText("PROFIT: 71.1 (3.31%)")
.setTooltip("Additional position information")
.setProtectTooltip("Protect position")
.setCloseTooltip("Close position")
.setReverseTooltip("Reverse position")
.setQuantity("8.235")
.setPrice(160)
.setExtendLeft(false)
.setLineStyle(0)
.setLineLength(25);

Parameters

NameTypeDescription
options?UndoOptionsOptional undo options.

Returns

IPositionLineAdapter

An API object for interacting with the position.


createShape

createShape<TOverrides>(point, options): EntityId

Create a new single point drawing.

Example

widget.activeChart().createShape({ time: 1514764800 }, { shape: 'vertical_line' });

Type parameters

NameType
TOverridesextends object

Parameters

NameTypeDescription
pointShapePointA point. The location of the new drawing.
optionsCreateShapeOptions<TOverrides>An options object for the new drawing.

Returns

EntityId

The ID of the new drawing if it was created successfully, or null otherwise.


createStudy

createStudy<TOverrides>(name, forceOverlay?, lock?, inputs?, overrides?, options?): Promise<EntityId>

Adds an indicator or a symbol for comparison to the chart. For more information, refer to the Indicators article.

Type parameters

NameType
TOverridesextends StudyOverrides

Parameters

NameTypeDescription
namestringname of an indicator as shown in the Indicators widget
forceOverlay?booleanforces the Charting Library to place the created indicator on the main pane
lock?booleanwhether a user will be able to remove/change/hide the indicator or not
inputs?Record<string, StudyInputValue>From version v22, it's an object containing named properties from the indicator properties dialog.
overrides?TOverridesAn object that contains overrides for a new indicator. Note that you should not specify the indicator name. Overrides for built-in indicators are listed in SingleIndicatorOverrides.
options?CreateStudyOptionsstudy creation options

Returns

Promise<EntityId>

ID of the created study


createStudyTemplate

createStudyTemplate(options): object

Save the current study template to a object.

Example

const options = { saveSymbol: true, saveInterval: true };
const template = widget.activeChart().createStudyTemplate(options);

Parameters

NameTypeDescription
optionsCreateStudyTemplateOptionsAn object of study template options.

Returns

object

A study template object.


crossHairMoved

crossHairMoved(): ISubscription<(params: CrossHairMovedEventParams) => void>

Get a subscription object for the crosshair moving over the chart.

Example

widget.activeChart().crossHairMoved().subscribe(
null,
({ time, price }) => console.log(time, price)
);

Returns

ISubscription<(params: CrossHairMovedEventParams) => void>

A subscription object for the crosshair moving over the chart.


dataReady

dataReady(callback): boolean

Provide a callback function that will be called when chart data is loaded. If chart data is already loaded when this method is called, the callback is called immediately.

Example

widget.activeChart().dataReady(() => {
// ...
}

Parameters

NameTypeDescription
callback() => voidA callback function called when chart data is loaded.

Returns

boolean


endOfPeriodToBarTime

endOfPeriodToBarTime(unixTime): number

Get the end of period to bar time

Parameters

NameTypeDescription
unixTimenumberdate timestamp

Returns

number


executeActionById

executeActionById(actionId): void

Execute an action.

Example

// ...
widget.activeChart().executeActionById("undo");
// ...
widget.activeChart().executeActionById("drawingToolbarAction"); // Hides or shows the drawing toolbar
// ...

Parameters

NameTypeDescription
actionIdChartActionIdAn action ID.

Returns

void


exportData

exportData(options?): Promise<ExportedData>

Export the current data from the chart.

Example

// Exports series' data only
widget.activeChart().exportData({ includeTime: false, includedStudies: [] });
// Exports series' data with times
widget.activeChart().exportData({ includedStudies: [] });
// Exports series' data with with user time
widget.activeChart().exportData({ includeTime: false, includeUserTime: true, includedStudies: [] });
// Exports data for the indicator which ID is STUDY_ID
widget.activeChart().exportData({ includeTime: false, includeSeries: false, includedStudies: ['STUDY_ID'] });
// Exports all available data from the chart
widget.activeChart().exportData({ includeUserTime: true });
// Exports series' data before 2018-01-01
widget.activeChart().exportData({ includeTime: false, to: Date.UTC(2018, 0, 1) / 1000 });
// Exports series' data after 2018-01-01
widget.activeChart().exportData({ includeTime: false, from: Date.UTC(2018, 0, 1) / 1000 });
// Exports series' data in the range between 2018-01-01 and 2018-02-01
widget.activeChart().exportData({ includeTime: false, from: Date.UTC(2018, 0, 1) / 1000, to: Date.UTC(2018, 1, 1) / 1000 });
// Exports all displayed data on the chart
widget.activeChart().exportData({ includeDisplayedValues: true });

Parameters

NameTypeDescription
options?Partial<ExportDataOptions>Optional object of options to control the exported data.

Returns

Promise<ExportedData>

A promise that resolves with the exported data.


getAllPanesHeight

getAllPanesHeight(): number[]

Get an array of the heigh of all panes.

Example

console.log(widget.activeChart().getAllPanesHeight());

Returns

number[]

An array of heights.


getAllShapes

getAllShapes(): EntityInfo[]

Get an array of IDs and name for all drawings on the chart.

Example

widget.activeChart().getAllShapes().forEach(({ name }) => console.log(name));

Returns

EntityInfo[]

An array of drawing information.


getAllStudies

getAllStudies(): EntityInfo[]

Get an array of IDs and names for all studies on the chart.

Example

widget.activeChart().getAllStudies().forEach(({ name }) => console.log(name));

Returns

EntityInfo[]

An array of study information.


getCheckableActionState

getCheckableActionState(actionId): boolean

Get the state of a checkable action.

Example

if (widget.activeChart().getCheckableActionState("drawingToolbarAction")) {
// ...
};

Parameters

NameTypeDescription
actionIdChartActionIdAn action ID.

Returns

boolean

true if the action is checked, false otherwise.


getPanes

getPanes(): IPaneApi[]

Get an array of API objects for interacting with the chart panes.

Example

widget.activeChart().getPanes()[1].moveTo(0);

Returns

IPaneApi[]


getPriceToBarRatio

getPriceToBarRatio(): number

Get the chart's price to bar ratio.

Example

console.log(widget.activeChart().getPriceToBarRatio());

Returns

number

The ratio or null if no ratio is defined.


getSeries

getSeries(): ISeriesApi

Get the main series.

Example

widget.activeChart().getSeries().setVisible(false);

Returns

ISeriesApi

An API object for interacting with the main series.


getShapeById

getShapeById(entityId): ILineDataSourceApi

Get a drawing by ID.

Example

widget.activeChart().getShapeById(id).bringToFront();

Parameters

NameTypeDescription
entityIdEntityIdA drawing ID.

Returns

ILineDataSourceApi

An API object for interacting with the drawing.


getStudyById

getStudyById(entityId): IStudyApi

Get a study by ID.

Example

widget.activeChart().getStudyById(id).setVisible(false);

Parameters

NameTypeDescription
entityIdEntityIdThe study ID.

Returns

IStudyApi

An API object for interacting with the study.


getTimeScale

getTimeScale(): ITimeScaleApi

Get an API object for interacting with the timescale.

Example

var time = widget.activeChart().getTimeScale().coordinateToTime(100);

Returns

ITimeScaleApi


getTimezoneApi

getTimezoneApi(): ITimezoneApi

Get an API object for interacting with the chart timezone.

Returns

ITimezoneApi


getVisibleRange

getVisibleRange(): VisibleTimeRange

Get the current visible time range.

Example

console.log(widget.activeChart().getVisibleRange());

Returns

VisibleTimeRange


isMaximized

isMaximized(): boolean

Check if the chart is maximized or not.

Returns

boolean

true if maximized, false otherwise.


isPriceToBarRatioLocked

isPriceToBarRatioLocked(): boolean

Get the locked/unlocked state of the chart's price to bar ratio.

Example

console.log(widget.activeChart().isPriceToBarRatioLocked());

Returns

boolean


isSelectBarRequested

isSelectBarRequested(): boolean

Check if bar selection mode is active or not.

Example

var isRequested = widget.activeChart().isSelectBarRequested();

Returns

boolean

true if active, false otherwise.


loadChartTemplate

loadChartTemplate(templateName): Promise<void>

Load and apply a chart template.

Parameters

NameTypeDescription
templateNamestringThe name of the template to load.

Returns

Promise<void>


marketStatus

marketStatus(): IWatchedValueReadonly<MarketStatus>

Get a readonly watched value that can be used to read/subscribe to the state of the chart's market status.

Returns

IWatchedValueReadonly<MarketStatus>


maximizeChart

maximizeChart(): void

Maximize to its full size currently selected chart.

Example

widget.activeChart().maximizeChart();

Returns

void


onChartTypeChanged

onChartTypeChanged(): ISubscription<(chartType: SeriesType) => void>

Get a subscription object for the chart type changing.

Example

widget.activeChart().onChartTypeChanged().subscribe(
null,
(chartType) => console.log('The type of chart is changed')
);

Returns

ISubscription<(chartType: SeriesType) => void>

A subscription object for the chart type changing.


onDataLoaded

onDataLoaded(): ISubscription<() => void>

Get a subscription object for new data being loaded for the chart.

Example

widget.activeChart().onDataLoaded().subscribe(
null,
() => console.log('New history bars are loaded'),
true
);

Returns

ISubscription<() => void>

A subscription object for new data loaded for the chart.


onHoveredSourceChanged

onHoveredSourceChanged(): ISubscription<(sourceId: EntityId) => void>

Get a subscription object for the ID of the study or series hovered by the crosshair.

Returns

ISubscription<(sourceId: EntityId) => void>

A subscription object for the ID of the study or series hovered by the crosshair. Subscribers will be called with null if there is no study or series hovered.


onIntervalChanged

onIntervalChanged(): ISubscription<(interval: ResolutionString, timeFrameParameters: { timeframe?: TimeFrameValue }) => void>

Get a subscription object for the chart resolution (interval) changing. This method also allows you to track whether the chart's date range is changed. The timeframe argument represents if a user clicks on the time frame toolbar or changes the date range manually. If timeframe is undefined, you can change a date range before data loading starts. To do this, you can specify a time frame value or a certain date range.

Examples

The following code sample specifies a time frame value:

widget.activeChart().onIntervalChanged().subscribe(null, (interval, timeframeObj) =>
timeframeObj.timeframe = {
value: "12M",
type: "period-back"
});

The following code sample specifies a certain date range:

widget.activeChart().onIntervalChanged().subscribe(null, (interval, timeframeObj) =>
timeframeObj.timeframe = {
from: new Date('2015-01-01').getTime() / 1000,
to: new Date('2017-01-01').getTime() / 1000,
type: "time-range"
});

Returns

ISubscription<(interval: ResolutionString, timeFrameParameters: { timeframe?: TimeFrameValue }) => void>

A subscription object for the chart interval (resolution) changing.


onSymbolChanged

onSymbolChanged(): ISubscription<() => void>

Get a subscription object for the chart symbol changing.

Example

widget.activeChart().onSymbolChanged().subscribe(null, () => console.log('The symbol is changed'));

Returns

ISubscription<() => void>

A subscription object for when a symbol is resolved (ie changing resolution, timeframe, currency, etc.)


onVisibleRangeChanged

onVisibleRangeChanged(): ISubscription<(range: VisibleTimeRange) => void>

Get a subscription object for the chart's visible range changing.

Example

widget.activeChart().onVisibleRangeChanged().subscribe(
null,
({ from, to }) => console.log(from, to)
);

Returns

ISubscription<(range: VisibleTimeRange) => void>

A subscription object for the chart's visible range changing.


priceFormatter

priceFormatter(): INumberFormatter

Returns the object with 'format' function that you can use to format the prices.

widget.activeChart().priceFormatter().format(123);

Returns

INumberFormatter


refreshMarks

refreshMarks(): void

Force the chart to re-request all bar marks and timescale marks.

Example

widget.activeChart().refreshMarks();

Returns

void


removeAllShapes

removeAllShapes(): void

Remove all drawings from the chart.

Example

widget.activeChart().removeAllShapes();

Returns

void


removeAllStudies

removeAllStudies(): void

Remove all studies from the chart.

Example

widget.activeChart().removeAllStudies();

Returns

void


removeEntity

removeEntity(entityId, options?): void

Remove an entity (e.g. drawing or study) from the chart.

Example

widget.activeChart().removeEntity(id);

Parameters

NameTypeDescription
entityIdEntityIdThe ID of the entity.
options?UndoOptionsOptional undo options.

Returns

void


requestSelectBar

requestSelectBar(): Promise<number>

Switch the chart to bar selection mode.

Example

widget.activeChart().requestSelectBar()
.then(function(time) {
console.log('user selects bar with time', time);
})
.catch(function() {
console.log('bar selection was rejected');
});

Returns

Promise<number>

A promise that resolves to the timestamp of a bar selected by the user. Rejects if the bar selection was already requested or is cancelled.


resetData

resetData(): void

Force the chart to re-request data. Before calling this function the onResetCacheNeededCallback callback from IDatafeedChartApi.subscribeBars should be called.

Example

widget.activeChart().resetData();

Returns

void


resolution

resolution(): ResolutionString

Get the current resolution (interval).

Example

console.log(widget.activeChart().resolution());

Returns

ResolutionString


restoreChart

restoreChart(): void

Restore to its initial size currently selected chart.

Example

widget.activeChart().restoreChart();

Returns

void


selection

selection(): ISelectionApi

Get an API object for interacting with the selection.

Example

widget.activeChart().selection().clear();

Returns

ISelectionApi


sendBackward

sendBackward(sources): void

Move the sources one level down in the Z-order.

Example

widget.activeChart().sendBackward([id]);

Parameters

NameTypeDescription
sourcesreadonly EntityId[]An array of source IDs.

Returns

void


sendToBack

sendToBack(entities): void

Move the group to the bottom of the Z-order.

Example

widget.activeChart().sendToBack([id]);

Parameters

NameType
entitiesreadonly EntityId[]

Returns

void


setAllPanesHeight

setAllPanesHeight(heights): void

Set the height for each pane in the order provided.

Example

console.log(widget.activeChart().setAllPanesHeight([250, 400, 200]));

Parameters

NameTypeDescription
heightsreadonly number[]An array of heights.

Returns

void


setChartType

setChartType(type, callback?): void

Change the chart's type.

Example

widget.activeChart().setChartType(12); // Specifies the High-low type

Parameters

NameTypeDescription
typeSeriesTypeA chart type.
callback?() => voidAn optional callback function. Called when the chart type has changed and data has loaded.

Returns

void


setPriceToBarRatio

setPriceToBarRatio(ratio, options?): void

Set the chart's price to bar ratio.

Example

widget.activeChart().setPriceToBarRatio(0.4567, { disableUndo: true });

Parameters

NameTypeDescription
rationumberThe new price to bar ratio.
options?UndoOptionsOptional undo options.

Returns

void


setPriceToBarRatioLocked

setPriceToBarRatioLocked(value, options?): void

Lock or unlock the chart's price to bar ratio.

Example

widget.activeChart().setPriceToBarRatioLocked(true, { disableUndo: false });

Parameters

NameTypeDescription
valuebooleantrue to lock, false to unlock.
options?UndoOptionsOptional undo options.

Returns

void


setResolution

setResolution(resolution, options?): void

Change the chart's interval (resolution).

Example

widget.activeChart().setResolution('2M');

Note: if you are attempting to change multiple charts (multi-chart layouts) at the same time with multiple setResolution calls then you should set doNotActivateChart option to true.

Parameters

NameTypeDescription
resolutionResolutionStringA resolution.
options?SetResolutionOptions | () => voidOptional object of options for the new resolution or optional callback that is called when the data for the new resolution has loaded.

Returns

void


setScrollEnabled

setScrollEnabled(enabled): void

Enable or disable scrolling of the chart.

Example

widget.activeChart().setScrollEnabled(false);

Parameters

NameTypeDescription
enabledbooleantrue to enable scrolling, false to disable.

Returns

void


setSymbol

setSymbol(symbol, options?): void

Change the chart's symbol.

Example

widget.activeChart().setSymbol('IBM');

Note: if you are attempting to change multiple charts (multi-chart layouts) at the same time with multiple setSymbol calls then you should set doNotActivateChart option to true.

Parameters

NameTypeDescription
symbolstringA symbol.
options?SetSymbolOptions | () => voidOptional object of options for the new symbol or optional callback that is called when the data for the new symbol has loaded.

Returns

void


setTimeFrame

setTimeFrame(timeFrame): void

Set the time frame for this chart.

Note: This action will set this chart as active in a multi-chart layout.

Example To apply the '1Y' timeframe:

tvWidget.setTimeFrame({
val: { type: 'period-back', value: '12M' },
res: '1W',
});

Parameters

NameTypeDescription
timeFrameRangeOptionsObject specifying the range and resolution to be applied

Returns

void


setVisibleRange

setVisibleRange(range, options?): Promise<void>

Scroll and/or scale the chart so a time range is visible.

Example

widget.activeChart().setVisibleRange(
{ from: 1420156800, to: 1451433600 },
{ percentRightMargin: 20 }
).then(() => console.log('New visible range is applied'));

Parameters

NameTypeDescription
rangeSetVisibleTimeRangeA range that will be made visible.
options?SetVisibleRangeOptionsOptional object of options for the new visible range.

Returns

Promise<void>

A promise that is resolved when the range has been set.


setZoomEnabled

setZoomEnabled(enabled): void

Enable or disable zooming of the chart.

Example

widget.activeChart().setZoomEnabled(false);

Parameters

NameTypeDescription
enabledbooleantrue to enable zooming, false to disable.

Returns

void


shapesGroupController

shapesGroupController(): IShapesGroupControllerApi

Get an API object for interacting with groups of drawings.

Example

widget.activeChart().shapesGroupController().createGroupFromSelection();

Returns

IShapesGroupControllerApi


showPropertiesDialog

showPropertiesDialog(studyId): void

Show the properties dialog for a study or drawing.

Example

const chart = widget.activeChart();
chart.showPropertiesDialog(chart.getAllShapes()[0].id);`

Parameters

NameTypeDescription
studyIdEntityIdAn ID of the study or drawing.

Returns

void


symbol

symbol(): string

Get the name of the current symbol.

Example

console.log(widget.activeChart().symbol());

Returns

string


symbolExt

symbolExt(): SymbolExt

Get an extended information object for the current symbol.

Example

console.log(widget.activeChart().symbolExt().full_name);

Returns

SymbolExt


zoomOut

zoomOut(): void

Zoom out. The method has the same effect as clicking on the "Zoom out" button.

Returns

void