Understanding the box.set_text() Function in Pine Script

This tutorial will delve into the box.set_text() function, providing a comprehensive guide on its syntax, usage, and practical applications.

Syntax

The box.set_text() function is straightforward, with its primary purpose being to set or update the text displayed inside a box object on the chart. Its syntax is:

box.set_text(id, content) → void

Arguments:

• id (series box): This is the identifier for the box object whose text you wish to set or update. It’s important that this box has been previously created and assigned to a variable.
• content (series string): The text you want to display inside the box. This can be a static string or a dynamic one, generated based on calculations or conditions in your script.

Example

Let’s consider a practical example where we create a box and then use box.set_text() to display dynamic content within it.

//@version=5
indicator("My Box Text Example", overlay=true)

// Create a box
myBox = box.new(bar_index - 10, low, bar_index, high, border_color=color.blue, bgcolor=color.new(color.blue, 90))

// Set text for the box
boxContent = "Low: " + str.tostring(low) + "\nHigh: " + str.tostring(high)
box.set_text(myBox, boxContent)
box.delete(myBox[1])

Detailed Walkthrough

• Indicator Declaration:
  • //@version=5: Specifies the version of Pine Script being used, which is version 5, the latest at the time of writing.
  • indicator("My Box Text Example", overlay=true): Declares a new indicator with the name “My Box Text Example”. The overlay=true parameter indicates that this indicator will be drawn over the main price chart.
• Box Creation:
  • myBox = box.new(bar_index - 10, low, bar_index, high, border_color=color.blue, bgcolor=color.new(color.blue, 90)): Creates a new box object and assigns it to the variable myBox. The box is drawn from 10 bars ago (bar_index - 10) to the current bar (bar_index), covering the vertical range from the lowest price (low) to the highest price (high) in that range. The box has a blue border and a semi-transparent blue background (90% transparency).
• Setting Text for the Box:
  • boxContent = "Low: " + str.tostring(low) + "\nHigh: " + str.tostring(high): Defines a string variable boxContent that concatenates the words “Low: ” with the current low price and “High: ” with the current high price, separating them with a newline (\n) for better readability. The str.tostring() function is used to convert the numeric values of low and high into strings.
  • box.set_text(myBox, boxContent): Sets the text inside myBox to be the value of boxContent. This makes the current low and high prices appear inside the box.
• Deleting the Previous Box:
  • box.delete(myBox[1]): Deletes the box that was created in the previous bar.

Key Features and Takeaways

• Function Usability: The box.set_text() function is essential for adding dynamic textual information to boxes, enhancing the information conveyed through chart visuals.
• Syntax: It requires an existing box object and a string of text, allowing for both static and dynamic content.
• Application: Ideal for highlighting specific information directly on the chart, such as price ranges, indicators’ values, or custom messages based on trading conditions.

By incorporating box.set_text() into your Pine Script tools, you enhance not only the interactivity of your charts but also the depth of information readily available at a glance.