Understanding the box.set_text_wrap() Function in Pine Script

The box.set_text_wrap() function is a vital tool for customizing the appearance of text within box drawings. This function enables developers to control how text content is displayed, particularly useful in enhancing the readability and presentation of annotations on charts. Let’s delve into the specifics of this function, its syntax, and its application.

Syntax

The box.set_text_wrap() function is used to set the text wrapping mode within a box object. Its syntax is as follows:

box.set_text_wrap(id, wrapMode) → void

Arguments

• id (series box): This is the identifier of the box object whose text wrapping mode you want to adjust. The box must have been previously created using box.new() or similar box creation functions.
• wrapMode (series string): Specifies how the text should be wrapped within the box. There are two possible values:
• text.wrap_auto: This mode automatically wraps text to fit the width of the box, ensuring that the text does not overflow horizontally.
• text.wrap_none: This mode disables text wrapping, causing all text to be displayed on a single line, regardless of the box’s width.

Example: Applying Text Wrapping in a Box

Let’s explore how to use the box.set_text_wrap() function with a practical example. In this scenario, we’ll create a box and demonstrate both wrapping modes.

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

// Creating a box
var box myBox = na
if bar_index >= 10
    myBox := box.new(left=bar_index-10, top=close, right=bar_index, bottom=close + 10, bgcolor=color.new(color.red, 90), border_color=color.red)

// Setting the text with auto wrap
if not na(myBox)
    box.set_text_wrap(myBox, text.wrap_auto)
    box.set_text(myBox, "This is a long piece of text that demonstrates how text wrapping works with `text.wrap_auto`. The text should automatically wrap to fit within the box.")
    box.set_text_color(myBox,color.white)
box.delete(myBox[1])

Walkthrough

1. Indicator Declaration: The script begins with the declaration of a version 5 indicator using //@version=5. The indicator function names the script “Box Text Wrapping Example” and sets it to overlay on the main chart (overlay=true).
2. Box Object Initialization:
   • A variable myBox of type box is declared and initialized with na (not applicable), indicating that it initially doesn’t reference any box object.
   • The script uses a conditional statement if bar_index >= 10 to ensure the box is created only after at least 10 bars have been plotted on the chart. This condition helps in positioning the box relative to the existing bars.
3. Box Creation:
   • Within the conditional block, myBox is assigned a new box object created by box.new(). This box spans from bar_index-10 to bar_index, covering 10 bars horizontally. Vertically, it extends from the current close price to close + 10. The box’s background and border colors are set to a semi-transparent red.
4. Text Wrapping and Display:
   • Another conditional statement if not na(myBox) checks if myBox has been successfully created or not. This is to avoid attempting to modify a non-existent box.
   • box.set_text_wrap(myBox, text.wrap_auto) sets the box’s text wrapping mode to automatic, ensuring long text is wrapped within the box boundaries.
   • box.set_text(myBox, "...") sets the box’s text content to a lengthy message, demonstrating the automatic text wrapping feature.
   • box.set_text_color(myBox, color.white) changes the text color to white for better visibility against the box’s red background.
5. Box Deletion:
   • box.delete(myBox[1]) deletes the previous instance of the box object created in the last bar. This is because myBox[1] refers to the myBox object from the previous bar ([1] is a historical reference operator in Pine Script). This line ensures that only the box associated with the current bar is displayed, keeping the chart uncluttered.

Key Features and Takeaways

• Function Usability: box.set_text_wrap() is crucial for managing the visual presentation of text within box objects, enhancing readability.
• Syntax and Application: The function is straightforward, requiring the box’s ID and the desired wrapping mode as arguments.
• Flexible Text Display: Offers two modes (text.wrap_auto and text.wrap_none) to accommodate different presentation needs.

By understanding and utilizing the box.set_text_wrap() function in Pine Script, developers can significantly improve the visual quality of their chart annotations, making them more readable and engaging for viewers.