lightweight-charts-python/docs/source/callbacks.md

Events

Events allow asynchronous and synchronous callbacks to be passed back into python.

---

chart.events

events.search -> chart | string: Fires upon searching. Searchbox will be automatically created.

events.new_bar -> chart: Fires when a new candlestick is added to the chart.

events.range_change -> chart | bars_before | bars_after: Fires when the range (visibleLogicalRange) changes.

Chart events can be subscribed to using: chart.events.<name> += <callable>

---

How to use Events

Take a look at this minimal example:

from lightweight_charts import Chart


def on_search(chart, string):
    print(f'Search Text: "{string}" | Chart/SubChart ID: "{chart.id}"')
    
    
if __name__ == '__main__':
    chart = Chart()
    chart.events.search += on_search
    chart.show(block=True)

Upon searching in a pane, the expected output would be akin to:

Search Text: "AAPL" | Chart/SubChart ID: "window.blyjagcr"

The ID shown above will change depending upon which pane was used to search, allowing for access to the object in question.

* When using `show` rather than `show_async`, block should be set to `True` (`chart.show(block=True)`).
* Event callables can be either coroutines, methods, or functions.

---

TopBar

The TopBar class represents the top bar shown on the chart:

This object is accessed from the topbar attribute of the chart object (chart.topbar.<method>).

Switchers, text boxes and buttons can be added to the top bar, and their instances can be accessed through the topbar dictionary. For example:

chart.topbar.textbox('symbol', 'AAPL') # Declares a textbox displaying 'AAPL'.
print(chart.topbar['symbol'].value) # Prints the value within ('AAPL')

chart.topbar['symbol'].set('MSFT') # Sets the 'symbol' textbox to 'MSFT'
print(chart.topbar['symbol'].value) # Prints the value again ('MSFT')

Events can also be emitted from the topbar. For example:

from lightweight_charts import Chart

def on_button_press(chart):
    new_button_value = 'On' if chart.topbar['my_button'].value == 'Off' else 'Off'
    chart.topbar['my_button'].set(new_button_value)
    print(f'Turned something {new_button_value.lower()}.')
    
    
if __name__ == '__main__':
    chart = Chart()
    chart.topbar.button('my_button', 'Off', func=on_button_press)
    chart.show(block=True)

---

switcher

name: str | options: tuple | default: str | func: callable

• name: the name of the switcher which can be used to access it from the topbar dictionary.
• options: The options for each switcher item.
• default: The initial switcher option set.

---

textbox

name: str | initial_text: str

• name: the name of the text box which can be used to access it from the topbar dictionary.
• initial_text: The text to show within the text box.

---

button

name: str | button_text: str | separator: bool | func: callable

• name: the name of the text box to access it from the topbar dictionary.
• button_text: Text to show within the button.
• separator: places a separator line to the right of the button.
• func: The event handler which will be executed upon a button click.

---

Callbacks Example:

import pandas as pd
from lightweight_charts import Chart


def get_bar_data(symbol, timeframe):
    if symbol not in ('AAPL', 'GOOGL', 'TSLA'):
        print(f'No data for "{symbol}"')
        return pd.DataFrame()
    return pd.read_csv(f'../examples/6_callbacks/bar_data/{symbol}_{timeframe}.csv')


def on_search(chart, searched_string):
    new_data = get_bar_data(searched_string, chart.topbar['timeframe'].value)
    if new_data.empty:
        return
    chart.topbar['symbol'].set(searched_string)
    chart.set(new_data)

    
def on_timeframe_selection(chart):
    new_data = get_bar_data(chart.topbar['symbol'].value, chart.topbar['timeframe'].value)
    if new_data.empty:
        return
    chart.set(new_data, True)

    
def on_horizontal_line_move(chart, line):
    print(f'Horizontal line moved to: {line.price}')


if __name__ == '__main__':
    chart = Chart(toolbox=True)
    chart.legend(True)

    chart.topbar.textbox('symbol', 'TSLA')
    chart.topbar.switcher('timeframe', ('1min', '5min', '30min'), default='5min',
                          func=on_timeframe_selection)

    df = get_bar_data('TSLA', '5min')
    chart.set(df)

    chart.horizontal_line(200, func=on_horizontal_line_move)

    chart.show(block=True)