Syntax

Built-in Functions

Structures

Built-in Variables

KLineChart

This function is used to perform custom drawing while a strategy is running, using a drawing approach similar to the Pine language.


    
    
    
KLineChart(options)

Examples

If you need to draw on the strategy's custom chart area, you must first create a chart control object, which can be created using the KLineChart() function. The argument of the KLineChart() function is a chart configuration structure. The chart configuration structure used in the reference code is very simple: {overlay: true}.

This chart configuration structure only sets the drawing content to be output on the main chart. If overlay is set to a falsy value (for example false), then all the chart content will be output on the sub-chart; if you need to specify that a certain drawing function draws on the main chart, you can also specify the argument overlay as a truthy value (for example true) in the specific function call.


    javascript
    
    
function main() {
    // Call the KLineChart function to create the chart control object c
    let c = KLineChart({
        overlay: true
    })

    // Test with a spot exchange object to obtain K-line data. If testing with a futures exchange object, you need to set the contract first
    let bars = exchange.GetRecords()
    if (!bars) {
        return
    }

    // Iterate over the K-line data to perform drawing operations. Each drawing operation must start with a ```c.begin(bar)``` function call and end with a ```c.close(bar)``` function call.
    bars.forEach(function(bar, index) {
        c.begin(bar)
        c.barcolor(bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(0, 0, 0, 0.2)')
        if (bar.Close > bar.Open) {
            c.bgcolor('rgba(0, 255, 0, 0.5)')
        }
        let h = c.plot(bar.High, 'high')
        let l = c.plot(bar.Low, 'low')

        c.fill(h, l, {
            color: bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(255, 0, 0, 0.2)'
        })
        c.hline(bar.High)
        c.plotarrow(bar.Close - bar.Open)
        c.plotshape(bar.Low, {
            style: 'diamond'
        })
        c.plotchar(bar.Close, {
            char: 'X'
        })
        c.plotcandle(bar.Open*0.9, bar.High*0.9, bar.Low*0.9, bar.Close*0.9)
        if (bar.Close > bar.Open) {
            // long/short/closelong/closeshort
            c.signal("long", bar.High, 1.5)
        } else if (bar.Close < bar.Open) {
            c.signal("closelong", bar.Low, 1.5)
        }
        c.close(bar)
    })
}


    python
    
    
def main():
    # Call the KLineChart function to create the chart control object c
    c = KLineChart({
        "overlay": True
    })

    # Test with a spot exchange object to obtain K-line data. If testing with a futures exchange object, you need to set the contract first
    bars = exchange.GetRecords()
    if not bars:
        return

    for bar in bars:
        c.begin(bar)
        c.barcolor('rgba(255, 0, 0, 0.2)' if bar.Close > bar.Open else 'rgba(0, 0, 0, 0.2)')
        if bar.Close > bar.Open:
            c.bgcolor('rgba(0, 255, 0, 0.5)')

        h = c.plot(bar.High, 'high')
        l = c.plot(bar.Low, 'low')

        c.fill(h, l, 'rgba(255, 0, 0, 0.2)' if bar.Close > bar.Open else 'rgba(255, 0, 0, 0.2)')
        c.hline(bar.High)
        c.plotarrow(bar.Close - bar.Open)
        c.plotshape(bar.Low, style = 'diamond')
        c.plotchar(bar.Close, char = 'X')
        c.plotcandle(bar.Open*0.9, bar.High*0.9, bar.Low*0.9, bar.Close*0.9)
        if bar.Close > bar.Open:
            # long/short/closelong/closeshort
            c.signal("long", bar.High, 1.5)
        elif bar.Close < bar.Open:
            c.signal("closelong", bar.Low, 1.5)

        c.close(bar)


    rust
    
    
fn main() {
    // Call KLineChart::new to create the chart control object c
    let mut c = KLineChart::new(r#"{"overlay": true}"#);

    // Test with a spot exchange object to obtain K-line data. If testing with a futures exchange object, you need to set the contract first
    let bars = exchange.GetRecords(None, None, None).unwrap();

    // Iterate over the K-line data to perform drawing operations. Each drawing operation must start with a c.begin(bar) function call and end with a c.close() function call.
    for bar in &bars {
        c.begin(bar);
        c.barcolor(if bar.Close > bar.Open { "rgba(255, 0, 0, 0.2)" } else { "rgba(0, 0, 0, 0.2)" }, "{}");
        if bar.Close > bar.Open {
            c.bgcolor("rgba(0, 255, 0, 0.5)", "{}");
        }
        let h = c.plot(bar.High, r#"{"title": "high"}"#);
        let l = c.plot(bar.Low, r#"{"title": "low"}"#);

        c.fill(h, l, if bar.Close > bar.Open { r#"{"color": "rgba(255, 0, 0, 0.2)"}"# } else { r#"{"color": "rgba(255, 0, 0, 0.2)"}"# });
        c.hline(bar.High, "{}");
        c.plotarrow(bar.Close - bar.Open, "{}");
        c.plotshape(bar.Low > 0.0, r#"{"style": "diamond"}"#);
        c.plotchar(bar.Close > 0.0, r#"{"char": "X"}"#);
        c.plotcandle(bar.Open * 0.9, bar.High * 0.9, bar.Low * 0.9, bar.Close * 0.9, "{}");
        if bar.Close > bar.Open {
            // long/short/closelong/closeshort
            c.signal("long", bar.High, 1.5, "long");
        } else if bar.Close < bar.Open {
            c.signal("closelong", bar.Low, 1.5, "closelong");
        }
        c.close();
    }
}


    c++
    
    
// Not supported yet

Use the pricePrecision and volumePrecision parameters to control the display precision of the chart data. You can set the display precision for price and volume according to your actual needs. For example, for instruments with large price fluctuations, you can set the precision to 0 to display integers; for instruments with finer price granularity, you can set it to 2 or a higher precision.


    javascript
    
    
function main() {
    // Create the chart control object, setting both price precision and volume precision to 0 (i.e., display integers)
    let c = KLineChart({
        overlay: true,
        pricePrecision: 0,   // Price data precision; set to 2 to keep 2 decimal places
        volumePrecision: 0   // Volume data precision
    })

    // Select the appropriate trading pair based on the exchange type
    let symbol = exchange.GetName().includes("Futures_") ? "ETH_USDT.swap" : "ETH_USDT"
    Log("Test symbol:", symbol)

    // Get K-line data
    let bars = exchange.GetRecords(symbol)
    if (!bars) {
        return
    }

    // Iterate over the K-line data and draw the chart
    bars.forEach(function(bar, index) {
        c.begin(bar)
        c.barcolor(bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(0, 0, 0, 0.2)')
        c.plot(bar.High, 'high')
        c.plot(bar.Low, 'low')
        c.close(bar)
    })
}


    python
    
    
def main():
    # Create the chart control object, setting both price precision and volume precision to 0 (i.e., display integers)
    c = KLineChart({
        "overlay": True,
        "pricePrecision": 0,   # Price data precision; set to 2 to keep 2 decimal places
        "volumePrecision": 0   # Volume data precision
    })

    # Select the appropriate trading pair based on the exchange type
    exName = exchange.GetName()
    symbol = "ETH_USDT.swap" if "Futures_" in exName else "ETH_USDT"
    Log("Test symbol:", symbol)

    # Get K-line data
    bars = exchange.GetRecords(symbol)
    if not bars:
        return

    # Iterate over the K-line data and draw the chart
    for bar in bars:
        c.begin(bar)
        c.barcolor('rgba(255, 0, 0, 0.2)' if bar.Close > bar.Open else 'rgba(0, 0, 0, 0.2)')
        c.plot(bar.High, 'high')
        c.plot(bar.Low, 'low')
        c.close(bar)


    rust
    
    
fn main() {
    // Create the chart control object, setting both price precision and volume precision to 0 (i.e., display integers)
    // pricePrecision is the price data precision; set to 2 to keep 2 decimal places; volumePrecision is the volume data precision
    let mut c = KLineChart::new(r#"{"overlay": true, "pricePrecision": 0, "volumePrecision": 0}"#);

    // Select the appropriate trading pair based on the exchange type
    let symbol = if exchange.GetName().contains("Futures_") { "ETH_USDT.swap" } else { "ETH_USDT" };
    Log!("Test symbol:", symbol);

    // Get K-line data
    let bars = exchange.GetRecords(symbol, None, None).unwrap();

    // Iterate over the K-line data and draw the chart
    for bar in &bars {
        c.begin(bar);
        c.barcolor(if bar.Close > bar.Open { "rgba(255, 0, 0, 0.2)" } else { "rgba(0, 0, 0, 0.2)" }, "{}");
        c.plot(bar.High, r#"{"title": "high"}"#);
        c.plot(bar.Low, r#"{"title": "low"}"#);
        c.close();
    }
}


    c++
    
    
// Not supported yet

The Pine language drawing interface functions supported in drawing operations are as follows:

barcolor: Sets the color of the candlesticks.

barcolor(color, offset, editable, show_last, title, display)

The available values for the display parameter are: "none", "all"


    javascript
    
    
c.barcolor(bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(0, 0, 0, 0.2)')   // The usage is the same as the reference code in the example above, so it will not be repeated here


    python
    
    
c.barcolor('rgba(255, 0, 0, 0.2)' if bar.Close > bar.Open else 'rgba(0, 0, 0, 0.2)')


    rust
    
    
c.barcolor(if bar.Close > bar.Open { "rgba(255, 0, 0, 0.2)" } else { "rgba(0, 0, 0, 0.2)" }, "{}");   // The usage is the same as the reference code in the example above, so it will not be repeated here


    c++
    
    
//  Not supported yet

bgcolor: Fills the candlestick background with the specified color.

bgcolor(color, offset, editable, show_last, title, display, overlay)

The available values for the display parameter are: "none", "all"


    javascript
    
    
c.bgcolor('rgba(0, 255, 0, 0.5)')


    python
    
    
c.bgcolor('rgba(0, 255, 0, 0.5)')


    rust
    
    
c.bgcolor("rgba(0, 255, 0, 0.5)", "{}");


    c++
    
    
// Not supported yet

plot: Plots a series of data on the chart.

plot(series, title, color, linewidth, style, trackprice, histbase, offset, join, editable, show_last, display)

The available values for the style parameter are: "stepline_diamond", "stepline", "cross", "areabr", "area", "circles", "columns", "histogram", "linebr", "line"

The available values for the display parameter are: "none", "all"


    javascript
    
    
c.plot(bar.High, 'high')


c.plot(bar.Open < bar.Close ? NaN : bar.Close, "Close", {style: "linebr"})  // Supports plotting discontinuous data lines


    python
    
    
h = c.plot(bar.High, 'high')


h = c.plot(None if bar.Open < bar.Close else bar.Close, "Close", style = "linebr")  # Supports plotting discontinuous data lines


    rust
    
    
let h = c.plot(bar.High, r#"{"title": "high"}"#);


c.plot(if bar.Open < bar.Close { f64::NAN } else { bar.Close }, r#"{"title": "Close", "style": "linebr"}"#);  // Supports plotting discontinuous data lines


    c++
    
    
// Not supported yet

fill, fills the background area between two plots or hlines with a specified color. > fill(hline1, hline2, color, title, editable, fillgaps, display) > display parameter options: "none", "all"

Since the JavaScript language cannot pass arguments by parameter name, to solve this problem you can use the {key: value} structure to pass arguments to specified parameter names. For example, the reference code uses {color: bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(255, 0, 0, 0.2)'} to assign a value to the color parameter of the fill function.

To pass arguments to multiple parameter names consecutively, you can use {key1: value1, key2: value2, key3: value3}.

For example, this sample additionally specifies a title parameter: {color: bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(255, 0, 0, 0.2)', title: 'fill'}.

Color values can be set either using the 'rgba(255, 0, 0, 0.2)' format or the '#FF0000' format.
```
    javascript
    
    
let h = c.plot(bar.High, 'high')
let l = c.plot(bar.Low, 'low')
c.fill(h, l, {color: bar.Close > bar.Open ? 'rgba(255, 0, 0, 0.2)' : 'rgba(255, 0, 0, 0.2)'})
```
```
    python
    
    
h = c.plot(bar.High, 'high')
l = c.plot(bar.Low, 'low')
c.fill(h, l, color = 'rgba(255, 0, 0, 0.2)' if bar.Close > bar.Open else 'rgba(255, 0, 0, 0.2)')
```
```
    rust
    
    
let h = c.plot(bar.High, r#"{"title": "high"}"#);
let l = c.plot(bar.Low, r#"{"title": "low"}"#);
c.fill(h, l, if bar.Close > bar.Open { r#"{"color": "rgba(255, 0, 0, 0.2)"}"# } else { r#"{"color": "rgba(255, 0, 0, 0.2)"}"# });
```
```
    c++
    
    
// Not supported yet
```
hline, draws a horizontal line at a given fixed price level.

hline(price, title, color, linestyle, linewidth, editable, display)

linestyle parameter options: "dashed", "dotted", "solid"

display parameter options: "none", "all"
```
    javascript
    
    
c.hline(bar.High)
```
```
    python
    
    
c.hline(bar.High)
```
```
    rust
    
    
c.hline(bar.High, "{}");
```
```
    c++
    
    
// Not supported yet
```

plotarrow, draws up and down arrows on the chart.

plotarrow(series, title, colorup, colordown, offset, minheight, maxheight, editable, show_last, display)

display parameter options: "none", "all"


    javascript
    
    
c.plotarrow(bar.Close - bar.Open)


    python
    
    
c.plotarrow(bar.Close - bar.Open)


    rust
    
    
c.plotarrow(bar.Close - bar.Open, "{}");


    c++
    
    
// Not supported yet

plotshape, draws visual shapes on the chart.

plotshape(series, title, style, location, color, offset, text, textcolor, editable, size, show_last, display)

The style parameter can be: "diamond", "square", "label_down", "label_up", "arrow_down", "arrow_up", "circle", "flag", "triangle_down", "triangle_up", "cross", "xcross"

The location parameter can be: "abovebar", "belowbar", "top", "bottom", "absolute"

The size parameter can be: "10px", "14px", "20px", "40px", "80px", corresponding respectively to size.tiny, size.small, size.normal, size.large, and size.huge in the Pine language.

size.auto is equivalent to size.small.

The display parameter can be: "none", "all"
```
    javascript
    
    
c.plotshape(bar.Low, {style: 'diamond'})
```
```
    python
    
    
c.plotshape(bar.Low, style = 'diamond')
```
```
    rust
    
    
c.plotshape(bar.Low > 0.0, r#"{"style": "diamond"}"#);
```
```
    c++
    
    
// Not supported yet
```
plotchar, draws visual shapes on the chart using any given Unicode character.

plotchar(series, title, char, location, color, offset, text, textcolor, editable, size, show_last, display)

The location parameter can be: "abovebar", "belowbar", "top", "bottom", "absolute"

The size parameter can be: "10px", "14px", "20px", "40px", "80px", corresponding respectively to size.tiny, size.small, size.normal, size.large, and size.huge in the Pine language.

size.auto is equivalent to size.small.

The display parameter can be: "none", "all"
```
    javascript
    
    
c.plotchar(bar.Close, {char: 'X'})
```
```
    python
    
    
c.plotchar(bar.Close, char = 'X')
```
```
    rust
    
    
c.plotchar(bar.Close > 0.0, r#"{"char": "X"}"#);
```
```
    c++
    
    
// Not supported yet
```

plotcandle, draws a candlestick chart on the chart.

plotcandle(open, high, low, close, title, color, wickcolor, editable, show_last, bordercolor, display)

The display parameter can be: "none", "all"


    javascript
    
    
c.plotcandle(bar.Open*0.9, bar.High*0.9, bar.Low*0.9, bar.Close*0.9)


    python
    
    
c.plotcandle(bar.Open*0.9, bar.High*0.9, bar.Low*0.9, bar.Close*0.9)


    rust
    
    
c.plotcandle(bar.Open * 0.9, bar.High * 0.9, bar.Low * 0.9, bar.Close * 0.9, "{}");


    c++
    
    
// Not supported yet

signal, this is a function that does not exist in the Pine language; here it is used to draw buy/sell signals.

signal(direction, price, qty, id)

The parameter "long" indicates the trade direction, which can be "long", "closelong", "short", or "closeshort". The parameter bar.High indicates the position of the signal marker on the Y-axis.

The parameter 1.5 indicates the trade quantity of the signal. A fourth parameter can be passed to replace the default text drawn; the default text of the signal marker is the trade direction, for example: "closelong".
```
    javascript
    
    
c.signal("long", bar.High, 1.5)
```
```
    python
    
    
c.signal("long", bar.High, 1.5)
```
```
    rust
    
    
c.signal("long", bar.High, 1.5, "long");
```
```
    c++
    
    
// Not supported yet
```
reset, this is a function that does not exist in the Pine language; it is used to clear chart data.

reset(remain)

The reset() method accepts a parameter remain, used to specify the number of data entries to retain. If the remain parameter is not passed, it means all data will be cleared.
```
    javascript
    
    
c.reset()
```
```
    python
    
    
c.reset()
```
```
    rust
    
    
c.reset(0);
```
```
    c++
    
    
// Not supported yet
```

Returns

Type Description

object

Chart object.

The chart object returned by the KLineChart() function contains multiple methods, among which begin(bar) and close(bar) deserve special attention. When iterating over K-line data to perform drawing operations, each drawing operation must start with a call to the begin(bar) function and end with a call to the close(bar) function.

Arguments

Name Type Required Description

options

object / object array

Yes

The options parameter is a chart configuration object that supports the following properties:

overlay: Boolean value, used to set whether the drawing content is overlaid onto the main chart. When set to true, it is displayed on the main chart; when set to false, it is displayed on the sub-chart.
pricePrecision: Number, price data precision, used to control the number of decimal places for price data in the chart. For example, setting it to 2 keeps 2 decimal places, and setting it to 0 keeps no decimal places (rounded to an integer).
volumePrecision: Number, volume data precision, used to control the number of decimal places for volume data in the chart. For example, setting it to 2 keeps 2 decimal places, and setting it to 0 keeps no decimal places (rounded to an integer).