Widget-Methods

Here is a list of supported widget's methods. You can call them using widget object returned to you by widget's constructor.

Remark: Please note that it's safe to call any method only after onChartReady callback is fired. So the common practice is to do smth like

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

Methods

Before 1.5 [[Chart Methods]] belonged to the Widget. Please see the full list of actions [[here|Chart-Methods]]

Subscribing To Chart Events
- [[onChartReady(callback)|Widget-Methods#onchartreadycallback]]
- [[onGrayedObjectClicked(callback)|Widget-Methods#ongrayedobjectclickedcallback]]
- [[onShortcut(shortcut, callback)|Widget-Methods#onshortcutshortcut-callback]]
- [[subscribe(event, callback)|Widget-Methods#subscribeevent-callback]]
- [[unsubscribe(event, callback)|Widget-Methods#unsubscribeevent-callback]]
Chart Actions
- [[chart()|Widget-Methods#chart]]
- [[setLanguage(locale)|Widget-Methods#setlanguagelocale]]
- [[setSymbol(symbol, interval, callback)|Widget-Methods#setsymbolsymbol-interval-callback]]
- [[remove()|Widget-Methods#remove]]
- [[closePopupsAndDialogs()|Widget-Methods#closepopupsanddialogs]]
- [[selectLineTool(drawingId)|Widget-Methods#selectlinetooldrawingid]]
- [[selectedLineTool()|Widget-Methods#selectedlinetool]]
Saving/Loading Charts
- [[save(callback)|Widget-Methods#savecallback]]
- [[load(state)|Widget-Methods#loadstate]]
- [[getSavedCharts(callback)|Widget-Methods#getsavedchartscallback]]
- [[loadChartFromServer(chartRecord)|Widget-Methods#loadchartfromserverchartrecord]]
- [[saveChartToServer(onCompleteCallback, onFailCallback, saveAsSnapshot, options)|Widget-Methods#savecharttoserveroncompletecallback-onfailcallback-saveassnapshot-options]]
- [[removeChartFromServer(chartId, onCompleteCallback)|Widget-Methods#removechartfromserverchartid-oncompletecallback]]
Custom UI Controls
- [[onContextMenu(callback)|Widget-Methods#oncontextmenucallback]]
- [[createButton(options)|Widget-Methods#createbuttonoptions]]
Dialogs
- [[showNoticeDialog(params)|Widget-Methods#shownoticedialogparams]]
- [[showConfirmDialog(params)|Widget-Methods#showconfirmdialogparams]]
- [[showLoadChartDialog()|Widget-Methods#showloadchartdialog]]
- [[showSaveAsChartDialog()|Widget-Methods#showsaveaschartdialog]]
Getters
- [[symbolInterval(callback)|Widget-Methods#symbolintervalcallback]]
- [[mainSeriesPriceFormatter()|Widget-Methods#mainseriespriceformatter]]
- [[getIntervals()|Widget-Methods#getintervals]]
- [[getStudiesList()|Widget-Methods#getstudieslist]]
Customization
- [[addCustomCSSFile(url)|Widget-Methods#addcustomcssfileurl]]
- [[applyOverrides(overrides)|Widget-Methods#applyoverridesoverrides]]
- [[applyStudiesOverrides(overrides)|Widget-Methods#applystudiesoverridesoverrides]]
:chart: [[Trading Terminal]] specific
- [[showSampleOrderDialog(order)|Widget-Methods#chart-showsampleorderdialogorder]]
- [[watchList()|Widget-Methods#chart-watchlist]]
:chart: Multiple Charts Layout
- [[chart(index)|Widget-Methods#chart-chartindex]]
- [[activeChart()|Widget-Methods#chart-activechart]]
- [[chartsCount()|Widget-Methods#chart-chartscount]]
- [[layout()|Widget-Methods#chart-layout]]
- [[setLayout(layout)|Widget-Methods#chart-setlayoutlayout]]

Subscribing To Chart Events

onChartReady(callback)

callback: function()

The Charting Library will call the callback provided once when chart is initialized and ready. You can safely call all other methods from this moment.

onGrayedObjectClicked(callback)

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

The Library will call the callback provided every time when user clicks on grayed out object. Example:

new TradingView.widget({
    drawings_access: {
        type: "black",
        tools: [
            { name: "Regression Trend" },
            { 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 one tries to
        // create Balance Of Power study or Trend Angle shape

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

onShortcut(shortcut, callback)

shortcut
callback: function(data)

The Library will call the callback provided every time when shortcut is pressed.

Example:

widget.onShortcut("alt+s", function() {
  widget.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 heder is shown/hidden
edit_object_dialog		Chart/Study Properties dialog is shown
chart_load_requested		new chart about to be loaded
chart_loaded
mouse_down
mouse_up
drawing	1.7	a drawing is added to a chart. Arguments contains an object with `value` field that is the name of the drawing.
study	1.7	an indicator is added to a chart. Arguments contains an object with `value` field that is the name of the indicator.
undo	1.7
redo	1.7
reset_scales	1.7	reset scales button is clicked
compare_add	1.7	Compare dialog is shown
add_compare	1.7	Compare instrument is added
load_study template	1.7	A study template is loaded
onTick		callback will be called every time when recent bar updates
onAutoSaveNeeded		callback will be called every time when user changes the chart. `Chart change` means any user action that can be undone. The callback will not be called more than once in five seconds. See also auto_save_delay
onScreenshotReady		callback will be called every time when user creates a screenshot and server returns the created image name
onMarkClick		callback will be called every time when user clicks a [[mark on bar	Marks-On-Bars]]. Mark ID will be passed as an argument
onTimescaleMarkClick		callback will be called every time when user clicks a timescale mark. Mark ID will be passed as an argument
onSelectedLineToolChanged		callback will be called every time when selected line tool changes
:chart: layout_about_to_be_changed		amount or placement of charts about to be changed
:chart: layout_changed		amount or placement of charts is changed
:chart: activeChartChanged		active chart is changed

callback: function(arguments)

The library will call callback when GUI event is happened. Every event can have different set of arguments.

unsubscribe(event, callback)

Unsubscribe a previously subscribed callback listener from a given event (which 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|Localization]]

Sets the Widget's language. For now, this call reloads the chart. Please avoid using it.

setSymbol(symbol, interval, callback)

symbol: string
interval: string
callback: function()

Makes the chart to change its symbol and resolution. Callback is called after new symbol's data arrived.

remove()

Removes chart widget from your page.

closePopupsAndDialogs()

Calling this method closes a context menu or a dialog if it is shown.

selectLineTool(drawingId)

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

Selection of a drawing or cursor which is identical to a single click on a drawing button.

selectedLineTool()

Returns an [[identifier|Shapes and Overrides]] of the selected drawing or cursor (see above).

Saving/Loading Charts

save(callback)

callback: function(object)

Saves the chart state to JS object. Charting Library will call your callback and pass the state object as argument. This call is a part of low-level [[save/load API|Saving-and-Loading-Charts]].

load(state)

state: object

Loads the chart from state object. This call is a part of low-level [[save/load API|Saving-and-Loading-Charts]].

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 on a server for current user.

loadChartFromServer(chartRecord)

chartRecord is an object that you get using [[getSavedCharts(callback)|Widget-Methods#getsavedchartscallback]]

Loads and displays a chart from a server.

saveChartToServer(onCompleteCallback, onFailCallback, saveAsSnapshot, options)

onCompleteCallback: function()
onFailCallback: function()
saveAsSnapshot: should be always false
options: object { chartName }
1. chartName: name of a chart. Should be specified for new charts and renaming.
2. defaultChartName: default name of a chart. It will be used if current chart has no name.

Saves current chart to the server.

removeChartFromServer(chartId, onCompleteCallback)

chartId: id should be got from a record received using [[getSavedCharts(callback)|Widget-Methods#getsavedchartscallback]]
onCompleteCallback: function()

Removes chart from the server.

Custom UI Controls

onContextMenu(callback)

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

The Library will call the callback provided every time when user opens context menu on the chart. Unix time and price of context menu point will be provided as arguments. To customize context menu items you have to return array of items descriptors. Item descriptor has following structure:

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

position: position of item in context menu
text: text of menu item
click: callback which will be called when user select your menu item

To add a separator use minus sign. Example: { text: "-", position: "top" }.

To remove an existing item from a menu use minus sign in front of the item text.
Example: { text: "-Objects Tree..." }

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" }
1. align: "right" | "left". default: "left"

Creates a new DOM element in chart top toolbar and returns jQuery object for this button. You can use it to append custom controls right on the chart. Example:

widget.onChartReady(function() {
    widget.createButton()
        .attr('title', "My custom button tooltip")
        .on('click', function (e) { alert("My custom button pressed!"); })
        .append($('<span>My custom button caption</span>'));
});

Dialogs

Since 1.6 version

showNoticeDialog(params)

params: object:
1. title: text to be shown in the title
2. body: text to be shown in the body
3. callback: function to be called when ok button is pressed

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

showConfirmDialog(params)

params: object:
1. title: text to be shown in the title
2. body: text to be shown in the body
3. 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 custom title and text and "OK", "CANCEL" buttons.

showLoadChartDialog()

Displays Load chart dialog.

showSaveAsChartDialog()

Displays Save As... chart dialog.

Getters

symbolInterval(callback)

callback: function(result)
1. result: object {symbol, interval}

Since 1.4 the function returns the result immediately. Callback is kept for compatability.

Charting Library will call your callback with an object containing chart's symbol and interval.

mainSeriesPriceFormatter()

Returns object with method format that you can use to format prices. Introduced in 1.5.

getIntervals()

Returns an array of supported resolutions. Introduced in 1.7.

getStudiesList()

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

Customization

addCustomCSSFile(url)

url should be absolute or relative path to 'static` folder

This method was introduced in version 1.3. Starting from 1.4 use custom_css_url instead.

applyOverrides(overrides)

Introduced in Charting Library 1.5

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

This method applies overrides to properties without reloading the chart.

applyStudiesOverrides(overrides)

Introduced in Charting Library 1.9

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

This method applies studies overrides to indicators' style or inputs without reloading the chart.

:chart: Trading Terminal

The following methods are available in [[Trading Terminal]] only.

:chart: showSampleOrderDialog(order)

order: object

Displays a sample order dialog. This dialog looks like Trading View Paper Trading one. Usually you don't need to use the sample dialog. This method is used in the trading sample.

:chart: watchList()