Below is the list of methods that the widget supports. You can call them using the widget object that is returned to you by the widget's constructor.

Remark: Please note that it's safe to call any method only after onChartReady callback function is called.

Example:

widget.onChartReady(function() {
    // It's now safe to call any other methods of the widget
});

Methods

Subscribing To Chart Events
Chart Actions
Saving/Loading Charts
Custom UI Controls
- onContextMenu(callback)
- createButton(options)
Dialogs
Getters
Customization
💹 Trading Terminal only
- watchList()
💹 Multiple Charts Layout

Subscribing To Chart Events

onChartReady(callback)

callback: function()

The Charting Library will call the callback function 1 time when chart is initialized. You can safely call all other methods starting from this moment.

headerReady()

Returns a Promise object that should be used to handle an event when the Charting Library header widget API is ready (e.g. createButton). The Promise object became available in 2015 which is why some older browsers, such as Internet Explorer do not support it. The Charting Library contains polyfills inside the iFrame only. Therefore, if you want to use this method in IE11, you should be adding the Promise polyfill.

onGrayedObjectClicked(callback)

callback: function(subject)
1. subject: object {type, name}
  - type: drawing | study
  - name: string, name of a clicked subject

The Library will call the callback function every time a user clicks on a grayed out object.

Example:

new TradingView.widget({
    drawings_access: {
        type: "black",
        tools: [
            { name: "Trend Line" },
            { name: "Trend Angle", grayed: true },
        ]
    },
    studies_access: {
        type: "black",
        tools: [
            { name: "Aroon" },
            { name: "Balance of Power", grayed: true },
        ]
    },
    <...> // other widget settings
});

widget.onChartReady(function() {
    widget.onGrayedObjectClicked(function(data) {
        // this function will be called when a user tries to
        // create the Balance Of Power study or the Trend Angle shape

        alert(data.name + " is grayed out!");
    })
});

onShortcut(shortcut, callback)

shortcut
callback: function(data)

The Library will call the callback function every time the shortcut key is pressed.

Example:

widget.onShortcut("alt+s", function() {
  widget.chart().executeActionById("symbolSearch");
});

subscribe(event, callback)

event: can be

Event name	Library Version	Description
`toggle_sidebar`		Drawing toolbar is shown/hidden
`indicators_dialog`		Indicators dialog is shown
`toggle_header`		Chart header is shown/hidden
`edit_object_dialog`		Chart/Study Properties dialog is shown
`chart_load_requested`		New chart is about to be loaded
`chart_loaded`
`mouse_down`
`mouse_up`
`drawing`	1.7	A drawing is added to a chart. The arguments contain an object with the `value` field that corresponds with the name of the drawing.
`study`	1.7	An indicator is added to a chart. The arguments contain an object with the `value` field that corresponds with the name of the indicator.
`undo`	1.7
`redo`	1.7
`undo_redo_state_changed`	1.14	The Undo/Redo state has been changed. The arguments contain an object with the state of the Undo/Redo stack. This object has the same structure as the result of UndoRedoState method
`reset_scales`	1.7	Reset scales button is clicked
`compare_add`	1.7	A compare dialog is shown
`add_compare`	1.7	A compare instrument is added
`load_study` template	1.7	A study template is loaded
`onTick`		Last bar is updated
`onAutoSaveNeeded`		User changed the chart. `Chart change` means any user action that can be undone. The callback function will not be called more than once every 5 seconds. See also auto_save_delay
`onScreenshotReady`		A screenshot URL is returned by the server
`onMarkClick`		User clicked a mark on a bar. Mark ID will be passed as an argument
`onTimescaleMarkClick`		User clicked a timescale mark. Mark ID will be passed as an argument
`onSelectedLineToolChanged`		Selected line tool is changed
`study_event`	1.15	An event related to the study. The callback function receives two arguments: a study ID and an event type (currently possible values for this argument are `remove` and at version 1.16 - `price_scale_changed`)
`series_event`	1.16	An event related to the series. The callback function receives an argument - an event type (currently the only possible value for this argument is `price_scale_changed`)
`drawing_event`	1.15	Drawing was hidden, shown, moved, removed, or clicked. The callback function will receive two arguments: a drawing ID and an event type. Possible values of the event type argument are `hide`, `show`, `move`, `remove`, `click`
`study_properties_changed`	1.14	Study properties are changed. Entity ID will be passed as an argument
`series_properties_changed`	1.15	Main series properties are changed.
`panes_height_changed`	1.15	Panes' size is changed.
`panes_order_changed`	1.15	Panes' order is changed.
💹 `layout_about_to_be_changed`		Amount or placement of the charts is about to be changed
💹 `layout_changed`		Amount or placement of the charts is changed
💹 `activeChartChanged`		Active chart is changed

callback: function(arguments)

The library will call the callback function when a GUI event has happened. Every event can have a different set of arguments.

unsubscribe(event, callback)

Unsubscribes a previously subscribed callback function from a given event (that is one of the events in the table above).

Chart Actions

chart()

Returns a chart object that you can use to call Chart-Methods

setLanguage(locale)

locale: language code

Sets the language of the widget. For now, this call reloads the chart. Please avoid using it.

setSymbol(symbol, interval, callback)

symbol: string
interval: string
callback: function()

Changes the symbol and resolution of the chart. The callback function is called only when new symbol's data has been received.

remove()

Removes the chart widget from the web page.

closePopupsAndDialogs()

Calling this method closes all context menus, pop-ups or dialogs.

selectLineTool(drawingId)

drawingId: may be one of the identifiers or
1. cursor
2. dot
3. arrow_cursor
4. eraser
5. measure
6. zoom
7. brush

Selects a drawing or a cursor. It's the same as a single click on a drawing button.

selectedLineTool()

Returns an identifier of the selected drawing or cursor (see above).

takeScreenshot()

This method creates a snapshot of the chart and uploads it to the server. When it is done the onScreenshotReady callback function is called. The URL of the snapshot will be passed as an argument to the callback function.

lockAllDrawingTools()

This method returns a WatchedValue object that can be used to read/set/watch the state of Lock All Drawing Tools button.

hideAllDrawingTools()

This method returns a WatchedValue object that can be used to read/set/watch the state of Hide All Drawing Tools button.

magnetEnabled()

This method returns a WatchedValue object that can be used to read/set/watch the state of the Magnet (enabled - true or disabled - false).

magnetMode()

This method returns a WatchedValue object that can be used to read/set/watch the mode of the Magnet.

Available modes:

0 - weak magnet mode
1 - strong magnet mode

Saving/Loading Charts

save(callback)

callback: function(object)

Saves the chart state to JS object. Charting Library will call your callback function and pass the state object as an argument.

This call is part of the low-level save/load API.

load(state)

state: object

Loads the chart from the state object. This call is part of the low-level save/load API.

getSavedCharts(callback)

callback: function(objects)

objects is an array of:

id
name
image_url
modified_iso
short_symbol
interval

Returns a list of chart descriptions saved to the server for the current user.

loadChartFromServer(chartRecord)

chartRecord is an object that you get using getSavedCharts(callback)

Loads and displays a chart from the server.

saveChartToServer(onCompleteCallback, onFailCallback, options)

onCompleteCallback: function()
onFailCallback: function()
options: object { chartName }
- chartName: name of a chart. Should be specified for new charts and when renaming the chart.
- defaultChartName: default name of a chart. It will be used if the current chart has no name.

Saves the current chart to the server.

removeChartFromServer(chartId, onCompleteCallback)

chartId: the id should be received from the object that is returned by the getSavedCharts(callback)
onCompleteCallback: function()

Removes the chart from the server.

Custom UI Controls

onContextMenu(callback)

callback: function(unixtime, price). This callback function is expected to return a value (see below).

The Charting Library will call the callback function every time user opens a context menu on the chart. The arguments that are passed to the callback function contain unix time and price of the clicked point on the chart.

You have to return an array of objects that have the following format to add or remove items from the context menu.

{
    position: 'top' | 'bottom',
    text: 'Menu item text',
    click: <onItemClicked callback>
}

position: position of the item in the context menu
text: menu item text
click: a callback function that will be called when a user selects your menu item

Use the minus sign to add a separator. Example: { text: "-", position: "top" }.

Use the minus sign in front of the item text to remove an existing item from the menu.

Example:

widget.onChartReady(function() {
    widget.onContextMenu(function(unixtime, price) {
        return [{
            position: "top",
            text: "First top menu item, time: " + unixtime + ", price: " + price,
            click: function() { alert("First clicked."); }
        },
        { text: "-", position: "top" },
        { text: "-Objects Tree..." },
        {
            position: "top",
            text: "Second top menu item 2",
            click: function() { alert("Second clicked."); }
        }, {
            position: "bottom",
            text: "Bottom menu item",
            click: function() { alert("Third clicked."); }
        }];
    });

createButton(options)

options: object { align: "left" }
- align: right | left. default: left

Creates a new DOM element in the top toolbar of the chart and returns HTMLElement for this button. You can use it to add custom controls right on the chart.

NOTE: This method MUST be called after headerReady promise is resolved.

Example:

widget.headerReady().then(function() {
    var button = widget.createButton();
    button.setAttribute('title', 'My custom button tooltip');
    button.addEventListener('click', function() { alert("My custom button pressed!"); });
    button.textContent = 'My custom button caption';
});

Dialogs

Starting from version 1.6.

showNoticeDialog(params)

params: object:
- title: text to be shown in the title
- body: text to be shown in the body
- callback: function to be called when ok button is pressed

This method shows a dialog with custom title and text along with the "OK" button.

showConfirmDialog(params)

params: object:
- title: text to be shown in the title
- body: text to be shown in the body
- callback(result): function to be called when ok button is pressed. result is true if OK is pressed, otherwise it is false.

This method shows a dialog with the custom title and text along with the "OK" and "CANCEL" buttons.

showLoadChartDialog()

Displays the "Load chart layout" dialog.

showSaveAsChartDialog()

Displays the "Copy chart layout" dialog.

Getters

symbolInterval()

Charting Library returns an object that contains the symbol and interval of the chart.

mainSeriesPriceFormatter()

Returns an object with the format method that you can use to format the prices. This was introduced in version 1.5.

getIntervals()

Returns an array of supported resolutions. This was introduced in version 1.7.

getStudiesList()

Returns an array of IDs of all studies. They can be used to create a study.

undoRedoState()

Returns an object with the state of the Undo/Redo stack. The object has the following keys:

enableUndo: boolean flag that shows the undo action availability
undoText: name of the next undo operation. If the undo stack is empty then it is undefined.
enableRedo: boolean flag that shows the redo action availability
redoText: name of the next redo operation. If the redo stack is empty then it is undefined.

getTheme()

Starting from version 1.16.

This method returns the chart theme name.

console.log(widget.getTheme());

Customization

changeTheme(themeName, options)

Starting from version 1.13.

themeName should be "Light" | "Dark"
options is an optional object added in version 1.17 with one field:
- disableUndo - boolean flag that shows the undo action availability.

This method changes the chart theme without reloading the chart.

You can also use the theme in the Widget Constructor to create the chart with a custom theme.

addCustomCSSFile(url)

url should be an absolute or relative path to the static folder

This method was introduced in version 1.3.

Starting from version 1.4 use custom_css_url instead.

applyOverrides(overrides)

Starting from version 1.5.

overrides is an object. It is the same as overrides in the Widget Constructor.

This method applies "overrides" to the properties without reloading the chart.

applyStudiesOverrides(overrides)

Starting from version 1.9.

overrides is an object. It is the same as studies_overrides in the Widget Constructor.

This method applies "overrides" to the styles or inputs of the indicators without reloading the chart.

💹 Trading Terminal only

The following methods are available in Trading Terminal only.

💹 watchList()

Starting from version 1.9.

Returns an object to manage the watchlist. The object has the following methods:

defaultList() - allows you to get a default list of symbols.
getList(id?: string) - allows you to get a list of symbols. If the id parameter is not provided then the current list will be returned. If there is no WatchList then null will be returned.
getActiveListId() - allows you to get the ID of the current list. If there is no WatchList then null will be returned.
getAllLists() - allows you to get all lists. If there is no WatchList then null will be returned.
setList(symbols: string[]) - allows you to set a list of symbols into the watchlist. It will replace the entire list. Obsolete. Will be removed in version 1.13. Use updateList instead.
updateList(listId: string, symbols: string[]) - allows you to edit the list of symbols.
renameList(listId: string, newName: string) - allows you to rename the list to newName.
createList(listName?: string, symbols?: string[]) - allows you to create a list of symbols with listName name. If the listName parameter is not provided or there is no WatchList then null will be returned;
saveList(list: SymbolList) - allows you to save a list of symbols where list is an object with the following keys:
```
id: string;
title: string;
symbols: string[];
```
If there is no WatchList or an equivalent list already exists then false will be returned, otherwise true will returned.
deleteList(listId: string) - allows you to delete a list of symbols.
onListChanged() - you can use this method to be notified when the symbols of the active watchlist are changed. You can subscribe and unsubscribe using the [[Subscription]] object returned by this function.
onActiveListChanged() - you can use this method to be notified when a different list of the watchlist is selected. You can subscribe and unsubscribe using the [[Subscription]] object returned by this function.
onListAdded() - - you can use this method to be notified when the new list is added to the watchlist. You can subscribe and unsubscribe using the [[Subscription]] object returned by this function.
onListRemoved() - you can use this method to be notified when the list is removed from the watchlist. You can subscribe and unsubscribe using the [[Subscription]] object returned by this function.
onListRenamed() - - you can use this method to be notified when the list is renamed in the watchlist. You can subscribe and unsubscribe using the [[Subscription]] object returned by this function.

💹 Multiple Charts Layout

💹 chart(index)

index: index of a chart starting from 0. index is 0 by default.

Returns a chart object that you can use to call Chart-Methods

💹 activeChart()

Returns a chart object of the active chart that you can use to call Chart-Methods

💹 chartsCount()

Returns the amount of charts in the current layout.

💹 layout()

Returns the current layout mode. Possible values are: 4, 6, 8, s, 2h, 2-1, 2v, 3h, 3v, 3s, 1-2, 3r, 4h, 4v, 4s, 1-3, 2-2, 1-4, 5s, 6c, 8c.

💹 setLayout(layout)

layout: Possible values are: 4, 6, 8, s, 2h, 2-1, 2v, 3h, 3v, 3s, 1-2, 3r, 4h, 4v, 4s, 1-3, 2-2, 1-4, 5s, 6c, 8c.

Changes the current chart layout.

💹 layoutName()

Returns the current layout name. If the current layout has not yet been saved then it returns undefined.

💹 symbolSync()

Returns a WatchedValue object that can be used to read/set/watch the state of symbol sync between charts.

if (widget.symbolSync().value()) {
    // Do something
}

💹 intervalSync()

Returns a WatchedValue object that can be used to read/set/watch the state of interval sync between charts.

widget.intervalSync().setValue(true);

💹 crosshairSync()

Returns a WatchedValue object that can be used to read/set/watch the state of crosshair sync between charts.

widget.crosshairSync().setValue(true);

💹 timeSync()

Returns a WatchedValue object that can be used to read/set/watch the state of time sync between charts.

widget.timeSync().setValue(true);

Files

Widget-Methods.md

Latest commit

History

Widget-Methods.md

File metadata and controls

Methods

Subscribing To Chart Events

onChartReady(callback)

headerReady()

onGrayedObjectClicked(callback)

onShortcut(shortcut, callback)

subscribe(event, callback)

unsubscribe(event, callback)

Chart Actions

chart()

setLanguage(locale)

setSymbol(symbol, interval, callback)

remove()

closePopupsAndDialogs()

selectLineTool(drawingId)

selectedLineTool()

takeScreenshot()

lockAllDrawingTools()

hideAllDrawingTools()

magnetEnabled()

magnetMode()

Saving/Loading Charts

save(callback)

load(state)

getSavedCharts(callback)

loadChartFromServer(chartRecord)

saveChartToServer(onCompleteCallback, onFailCallback, options)

removeChartFromServer(chartId, onCompleteCallback)

Custom UI Controls

onContextMenu(callback)

createButton(options)

Dialogs

showNoticeDialog(params)

showConfirmDialog(params)

showLoadChartDialog()

showSaveAsChartDialog()

Getters

symbolInterval()

mainSeriesPriceFormatter()

getIntervals()

getStudiesList()

undoRedoState()

getTheme()

Customization

changeTheme(themeName, options)

addCustomCSSFile(url)

applyOverrides(overrides)

applyStudiesOverrides(overrides)

💹 Trading Terminal only

💹 watchList()

💹 Multiple Charts Layout

💹 chart(index)

💹 activeChart()

💹 chartsCount()

💹 layout()

💹 setLayout(layout)

💹 layoutName()

💹 symbolSync()

💹 intervalSync()

💹 crosshairSync()

💹 timeSync()

See Also