Understanding box.set_border_width() Function in Pine Script

In this article, we will discuss and explore the box.set_border_width() function in Pine Script. This function plays a crucial role in customizing the visual aspects of box drawings in trading scripts, allowing users to adjust the border width according to their analytical needs.

Introduction to the box.set_border_width() Function

The box.set_border_width() function is a Pine Script utility that enables script developers to modify the border width of a box drawing. This modification is essential for enhancing the visual representation of analytical markers on price charts. The function’s syntax is straightforward:

box.set_border_width(identifier, newWidth)

• identifier is the unique ID of the box whose border width you want to adjust. This ID is typically obtained from the box.new() function, which is used to create the box.
• newWidth represents the new border width in pixels. The default and minimum possible width is 1 pixel. Setting this parameter to zero (0) effectively removes the box’s border, making it invisible.

Practical Example: Highlighting Moving Average Crossovers

To illustrate the use of the box.set_border_width() function, let’s examine a modified version of the provided code example. This script identifies crossovers between two Exponential Moving Averages (EMAs) and highlights these events with box drawings on a price chart.

//@version=5
indicator(title="Highlight EMA Crossover", overlay=true)

// Calculation of two Exponential Moving Averages
quickEMA = ta.ema(close, 20)
gradualEMA = ta.ema(close, 80)

// Plotting the EMAs
plot(series=quickEMA, color=color.red, title="Quick EMA")
plot(series=gradualEMA, color=color.green, title="Gradual EMA")

// Box drawing variable initialization
var box highlightBox = na

The Logic for Box Creation and Border Width Adjustment

// Detecting EMA crossovers and adjusting box drawings
if ta.cross(quickEMA, gradualEMA)
    highlightBox := box.new(left=bar_index, top=high * 1.15,
         right=bar_index + 20, bottom=low * 0.85,
         bgcolor=color.new(color.green, 90), border_width=2,
         border_color=color.blue)

    // Updating the border of the previous box to make it invisible
    box.set_border_width(id=highlightBox[1], width=0)

Detailed Explanation

• Indicator Configuration: The script begins by defining its properties, such as the title, and ensuring it overlays on the price chart.
• EMA Calculations: Two EMAs are calculated using the ta.ema() function, with periods of 20 and 80 bars, respectively. These are stored in quickEMA and gradualEMA.
• EMA Plots: Both EMAs are plotted on the chart, with distinct colors for easy differentiation.
• Box Variable: The highlightBox variable is declared to store the current box drawing. It’s initialized with na and declared with var to retain its value across bars.
• Crossover Detection and Box Drawing: Within a if statement, the script checks for crossovers between the two EMAs using ta.cross(). Upon detection, a new box is drawn using box.new(), specified dimensions and aesthetics. The border width is initially set to 2 pixels.
• Border Width Adjustment: Finally, the script uses box.set_border_width() to remove the border of the previously drawn box by setting its width to 0. This ensures only the most recent box has a visible border.

Key Features and Takeaways

• The box.set_border_width() function is essential for dynamically adjusting the visual presentation of box drawings in Pine Script.
• It accepts two parameters: the box identifier and the new border width.
• The script demonstrates how to visually highlight EMA crossovers with boxes, enhancing chart analysis.
• By adjusting the border width of boxes, developers can create clear, visually distinct markers for various trading conditions on price charts.

This tutorial not only guides you through the box.set_border_width() function’s usage but also emphasizes the importance of visual aids in trading analysis. By customizing box drawings, Pine Script developers can enhance the interpretability and effectiveness of their trading indicators.