Understanding box.all Function in Pine Script

In this article  we’ll delve into the box.all function, a powerful tool for managing box objects in your scripts.

What is box.all?

The box.all function is a Pine Script feature that retrieves an array containing all the current box objects drawn by a script on the chart. Each box object represents a rectangular graphical element that can highlight areas on the chart for various analytical purposes.

Type

array<box>

Example

Consider an example where we need to delete all boxes drawn by a script at the beginning of its execution:

//@version=5
indicator("My Box Manipulator", overlay=true)
// Drawing a box
box.new(time, open, time + 60 * 60 * 24, close, xloc=xloc.bar_time, border_style=line.style_dashed)
myBoxes = box.all
if array.size(myBoxes) > 0
    for i = 0 to array.size(myBoxes) - 1
        box.delete(array.get(myBoxes, i))

In this example, a box is initially drawn using box.new(), spanning from the current bar’s opening time to the same time the next day, from the opening to the closing price. The box.all function is then used to retrieve an array (myBoxes) of all box objects created by the script. If the array contains any boxes, a for loop iterates through the array, and each box is deleted using box.delete().

Remarks

• Read-Only Array: The array returned by box.all is read-only. You can’t modify the boxes directly via this array, but you can use functions like box.delete() to manipulate them.
• Array Indexing: The first element (index zero) in the array is the ID of the oldest box object drawn on the chart by the script.

Key Features and Takeaways

• Functionality: box.all allows scripts to interact with all box objects they have drawn, enabling complex graphical manipulations and analysis.
• Use Cases: This feature is particularly useful for scripts that need to adjust their graphical output based on certain conditions, such as deleting all boxes before drawing new ones for a fresh analysis.
• Syntax and Application: The function is straightforward to use, requiring no parameters. It’s essential for managing boxes in dynamic trading strategies or indicators.
• Limitations: Since the array is read-only, direct modifications to the boxes through it are not possible. Instead, use other box functions for manipulation.

Understanding and utilizing the box.all function can significantly enhance the dynamic graphical capabilities of your Pine Script indicators and strategies, making them more interactive and user-friendly.