LabelManagement

7 hari lalu

Label management with fluent configuration, change tracking, and named registry

LabelManagement is a Pine Script library for creating and managing dynamic chart labels. Built with a fluent-style API, it simplifies label creation, styling, positioning, and content updates through method chaining and centralized control.

Manage 'sticky' labels easily across bars with expressive, readable code that reduces clutter and improves code clarity.

Example usage:

// Close label – to the right of the last bar
labels.get("close")
  .style(label.style_label_left)
  .bgColor(color.gray)
  .xy(bar_index, close)
  .textValue("C: " + str.tostring(close, "#.##"))
  .textColor(color.white)
  .tooltip("This is the close price")
  .apply()

Key features:

• Fluent API – Build and update labels using a chainable configuration flow
  
• Named label registry – Access and manage labels by name, e.g., "entry", "stop", "target"
  
• Change tracking – Update only when necessary to reduce redraws
  
• Deferred application – Apply all changes in one efficient operation
  
• Centralized control – Works well in modular or multi-label environments
  

This library is designed for Pine developers who want more control and less boilerplate when managing visual elements on the chart.



method clone(this)
  Creates a new LabelConfig by copying all properties from this instance
  Namespace types: LabelConfig
  Parameters:
    this (LabelConfig): (LabelConfig) The LabelConfig instance
  Returns: (LabelConfig) New LabelConfig instance with identical properties

method applyTo(this, target)
  Applies configuration to specified label (required parameter)
  Namespace types: LabelConfig
  Parameters:
    this (LabelConfig): (LabelConfig) The LabelConfig instance
    target (label): (label) Label to apply config to
  Returns: (LabelConfig) Self-reference for method chaining

method update(this, updates)
  Creates a new LabelUpdater with change tracking for this label
  Namespace types: series label
  Parameters:
    this (label): (label) The label instance
    updates (LabelConfig): (LabelConfig) Optional existing config to apply and reuse (if provided, applies to label first)
  Returns: (LabelUpdater) New LabelUpdater with blank configs for change tracking

method x(this, value)
  Sets the X coordinate with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (int): (int) New X coordinate
  Returns: (LabelUpdater) Self-reference for method chaining

method y(this, value)
  Sets the Y coordinate with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (float): (float) New Y coordinate
  Returns: (LabelUpdater) Self-reference for method chaining

method xy(this, x, y)
  Sets both X and Y coordinates with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    x (int): (int) New X coordinate
    y (float): (float) New Y coordinate
  Returns: (LabelUpdater) Self-reference for method chaining

method textValue(this, value)
  Sets the text content with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New text content
  Returns: (LabelUpdater) Self-reference for method chaining

method textColor(this, value)
  Sets the text color with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (color): (color) New text color
  Returns: (LabelUpdater) Self-reference for method chaining

method textSize(this, value)
  Sets the text size with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New text size
  Returns: (LabelUpdater) Self-reference for method chaining

method bgColor(this, value)
  Sets the background color with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (color): (color) New background color
  Returns: (LabelUpdater) Self-reference for method chaining

method style(this, value)
  Sets the label style with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New style
  Returns: (LabelUpdater) Self-reference for method chaining

method yloc(this, value)
  Sets the Y location mode with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New yloc
  Returns: (LabelUpdater) Self-reference for method chaining

method xloc(this, value)
  Sets the X location mode with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New xloc
  Returns: (LabelUpdater) Self-reference for method chaining

method tooltip(this, value)
  Sets the tooltip content with change tracking (fluent interface)
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New tooltip content
  Returns: (LabelUpdater) Self-reference for method chaining

method size(this, value)
  Sets the text size with change tracking (fluent interface) - alias for textSize
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
    value (string): (string) New text size
  Returns: (LabelUpdater) Self-reference for method chaining

method size(this)
  Gets the count of registered labels
  Namespace types: LabelManager
  Parameters:
    this (LabelManager): (LabelManager) The LabelManager instance
  Returns: (int) Number of labels in the registry

method apply(this)
  Applies pending changes to linked label and updates tracking
  Namespace types: LabelUpdater
  Parameters:
    this (LabelUpdater): (LabelUpdater) The LabelUpdater instance
  Returns: (LabelUpdater) Self-reference for method chaining

method get(this, name)
  Gets or creates a LabelUpdater for the specified name
  Namespace types: LabelManager
  Parameters:
    this (LabelManager): (LabelManager) The LabelManager instance
    name (string): (string) Unique identifier for the label
  Returns: (LabelUpdater) Existing or newly created LabelUpdater for the name

method has(this, name)
  Checks if a label with the specified name exists
  Namespace types: LabelManager
  Parameters:
    this (LabelManager): (LabelManager) The LabelManager instance
    name (string): (string) Name to check for existence
  Returns: (bool) True if label exists, false otherwise

method remove(this, name)
  Removes a label from the registry and deletes the underlying Pine Script label
  Namespace types: LabelManager
  Parameters:
    this (LabelManager): (LabelManager) The LabelManager instance
    name (string): (string) Name of the label to remove
  Returns: (LabelManager) Self-reference for method chaining

method clear(this)
  Removes all labels from registry and deletes all underlying Pine Script labels
  Namespace types: LabelManager
  Parameters:
    this (LabelManager): (LabelManager) The LabelManager instance
  Returns: (LabelManager) Self-reference for method chaining

newManager()
  Creates a new LabelManager with empty registry
  Returns: (LabelManager) New LabelManager instance ready for use

LabelConfig
  LabelConfig Configuration object for label appearance and positioning
  Fields:
    x (series int): (series int) X-coordinate (na = unchanged)
    y (series float): (series float) Y-coordinate (na = unchanged)
    style (series string): (series string) Label style (na = unchanged)
    yloc (series string): (series string) Y-location type (na = unchanged)
    xloc (series string): (series string) X-location type (na = unchanged)
    bgColor (series color): (series color) Background color (na = unchanged)
    textValue (series string): (series string) Label text content (na = unchanged)
    textSize (series string): (series string) Text size (na = unchanged)
    textColor (series color): (series color) Text color (na = unchanged)
    tooltip (series string): (series string) Tooltip text (na = unchanged)

LabelUpdater
  LabelUpdater Smart label updater with change tracking and minimal updates
  Fields:
    label (series label): (label) Reference to the label being updated
    latest (LabelConfig): (LabelConfig) Current known state of the label
    updates (LabelConfig): (LabelConfig) Pending changes to apply

LabelManager
  LabelManager Central registry for managing named labels with automatic creation
  Fields:
    registry (map<string, LabelUpdater>): (map<string, LabelUpdater>) Internal storage mapping names to LabelUpdater instances

19 jam lalu

Nota Keluaran

v2 Exposes a newLabel function for getting a new LabelUpdater without a manager/registry.

Added:
newLabel()
  Creates a new label and LabelUpdater
  Returns: (LabelUpdater) Newly created LabelUpdater containing the label

19 jam lalu

Nota Keluaran

v3 More appropriate API: was "textSize", now "size" as the size value does not just affect text.

Updated:
LabelConfig
  LabelConfig Configuration object for label appearance and positioning
  Fields:
    x (series int): (series int) X-coordinate (na = unchanged)
    y (series float): (series float) Y-coordinate (na = unchanged)
    xloc (series string): (series string) X-location type (na = unchanged)
    yloc (series string): (series string) Y-location type (na = unchanged)
    size (series string): (series string) Text size (na = unchanged)
    style (series string): (series string) Label style (na = unchanged)
    bgColor (series color): (series color) Background color (na = unchanged)
    textColor (series color): (series color) Text color (na = unchanged)
    textValue (series string): (series string) Label text content (na = unchanged)
    tooltip (series string): (series string) Tooltip text (na = unchanged)

Removed:
method textSize(this, value)
  Sets the text size with change tracking (fluent interface)