Interface LegendBox<BackgroundType>

Legend box is a component that describes collections of chart components, like series, highlighters, etc.

It contains a title, and buttons for each attached chart component that display the component name and can be clicked to toggle visibility of that particular component. These buttons are known as legend box entries. Additionally, attaching a series with an associated color look-up table (LUT) will result in the LegendBox automatically visualizing the color look up range.

A Legend box can be created with the addLegendBox method, which is supported by all chart types. For example: addLegendBox.

Adding items to LegendBox:

Use add to add a series into the LegendBox (if chart, or dashboard is supplied, then all contained series will be attached).

 // Example, attach a series to LegendBox.
const mySeries = ChartXY.addLineSeries()
LegendBox.add(mySeries)

Configuring LegendBox title:

LegendBox has a built-in title component, which can be configured with setTitle:

 // Example 1, specify LegendBox title.
LegendBox.setTitle('Groups Legend')
 // Example 2, hide LegendBox title.
LegendBox.setTitle('')

Configuring LegendBox entries

When a series is attached to LegendBox, it creates a LegendBoxEntry associated with that series. This entry shows as a button + label inside the LegendBox. All entries that currently exist inside a LegendBox can be styled with the setEntries method:

 // Example, style LegendBoxEntries.
// First attach series to create entries.
LegendBox.add(mySeries)
// Then style each entry using a callback function.
LegendBox.setEntries((entry, component) => entry
.setTextFont((font) => font
.setStyle('italic')
)
)

See LegendBoxEntry for available configuration API for each entry.

Styling an automatically created UILUTCheckBox requires a type cast (TypeScript users):

 // Example, styling a UILUTCheckBox that is automatically created when a series with associated LUT is attached.
LegendBox.add(myHeatmapSeries)
// Heatmap series is styled with `PalettedFill` -> style the created UILUTCheckBox using a reference check + type cast.
LegendBox.setEntries((entry, component) => {
if (component === myHeatmapSeries) {
const lutCheckBox = entry as UILUTCheckBox
lutCheckBox
.setLUTLength(200)
.setLUTThickness(30)
.setLUTTextFont((font) => font
.setSize(10)
)
}
})

Type Parameters

Hierarchy

Properties

origin: Point = ...
position: Point = ...

Pixel location of UiElements origin. To get position use getPosition(relativePosition).

Coordinate system = position scale (UIElement.scale)

renderingScale: LinearScaleXY
scale: ScaleXY<ViewportScale1D>
size: Point = ...

Methods

  • Permanently destroy the component.

    To fully allow Garbage-Collection to free the resources used by the component, make sure to remove any references to the component and its children in application code.

    let chart = ...ChartXY()
    let axisX = chart.getDefaultAxisX()
    // Dispose Chart, and remove all references so that they can be garbage-collected.
    chart.dispose()
    chart = undefined
    axisX = undefined

    Returns

    Object itself for fluent interface

    Returns LegendBox<BackgroundType>

  • Get theme effect enabled on component or disabled.

    A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components. Whether this effect is drawn above a particular component can be configured using the setEffect method.

     // Example, disable theme effect from a particular component.
    Component.setEffect(false)

    For the most part, theme effects are enabled by default on most components.

    Theme effect is configured with effect property.

    Returns

    Boolean that describes whether drawing the theme effect is enabled around the component or not.

    Returns boolean

  • Get boolean flag for whether object is currently under mouse or not

    Returns

    Boolean for is object under mouse currently

    Returns boolean

  • Get the position origin of this UiElement. Affects how the "position" of UIElement is interpreted.

    Returns

    Vec2 with each plane in range [-1, 1], where 0 is middle

    Returns Point

  • Returns the position of this UiElement at given location relative to elements size.

    Returns

    Object itself for fluent itself

    Parameters

    • relativePosition: Point = ...

      Relative position vector (-1 to 1 which specifies position of origin, 0 is center of the object)

    • spaceOfInterest: UISpace = UISpace.Everything

      Parameter to disregard parts of object when calculating the asked position.

    Returns Point

  • Returns the size of the UiElements in pixels including any Margins or Paddings

    Returns

    Object size in pixels

    Parameters

    • spaceOfInterest: UISpace = UISpace.Everything

      Parameter to disregard parts of object when calculating the position. Defaults to Margin, which includes everything. Should only ever be necessary for sub-classes

    Returns Point

  • Get text of LegendBox title.

    Returns

    LegendBox title as a string.

    Returns string

  • Get fill style of LegendBox Title.

    Returns

    FillStyle object

    Returns FillStyle

  • Get rotation of LegendBox title.

    Returns

    Rotation in degrees

    Returns number

  • Get element visibility.

    Returns

    true when element is set to be visible and false otherwise.

    Returns boolean

  • Remove event listener from dispose event.

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Unsubscribe from Highlight object event. This is called whenever an object is highlighted

    Returns

    True if the unsubscription was successful.

    Parameters

    • token: Token

      Token that was received when subscribing to the event.

    Returns boolean

  • Remove event listener from Mouse Click Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Double Click Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Down Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Drag Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Drag Start Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Drag Stop Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Enter Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Leave Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Move Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Up Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Mouse Wheel Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Touch End Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Touch Move Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Remove event listener from Touch Start Event

    Returns

    True if the listener is successfully removed and false if it is not found

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

  • Subscribe onDispose event. This event is triggered whenever the ChartComponent is disposed.

     // Example usage

    figure.onDispose(() => {
    console.log('figure was disposed')
    })

    figure.dispose()

    Returns

    Token of subscription

    Parameters

    • listener: ((object: LegendBox<BackgroundType>) => unknown)

      Event handler function

        • (object: LegendBox<BackgroundType>): unknown
        • Parameters

          Returns unknown

    Returns Token

  • Subscribe to highlight object event. This is called whenever an object is highlighted.

    Returns

    Token that can be used to unsubscribe from the event.

    Parameters

    • handler: ((isHighlighted: number | boolean) => void)

      Function that is called when event is triggered.

        • (isHighlighted: number | boolean): void
        • Parameters

          • isHighlighted: number | boolean

          Returns void

    Returns Token

  • Register new event listener to visibleStateChanged event.

    Parameters

    • listener: VisibleStateChangedHandler<LegendBox<BackgroundType>>

      Event listener for visibleStateChanged

    Returns Token

  • Set auto dispose behavior for this UI element.

    Can be used to set a condition, where the UI element is automatically disposed, removing it from view.

     // Example, remove UI element when it is larger than 20% of viewport.
    UIElement.setAutoDispose({
    type: 'max-width',
    maxWidth: 0.20,
    })

    Returns

    Object itself for fluent interface.

    Parameters

    Returns LegendBox<BackgroundType>

  • Member function that updates the size of the UI elements contents. UiElements should apply this inside 'update'

    Parameters

    • sizeInPixels: Point

      Size of element in pixels

    Returns void

  • Set theme effect enabled on component or disabled.

    A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components. Whether this effect is drawn above a particular component can be configured using the setEffect method.

     // Example, disable theme effect from a particular component.
    Component.setEffect(false)

    For the most part, theme effects are enabled by default on most components.

    Theme effect is configured with effect property.

    Returns

    Object itself.

    Parameters

    • enabled: boolean

      Theme effect enabled

    Returns LegendBox<BackgroundType>

  • Set style of LegendBoxEntries with a callback function.

    To set style of Entry matching a specific component, use the component parameter with a custom check.

    Example usage:

    • Style specific series entry only
     setEntries((entry, component) =>
    // Only apply for single series.
    component === mySeries &&
    entry.setTextFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    )
    • Style UILUTCheckBox
     setEntries((entry, component) =>
    // Must check for series with attached LUT
    component === myHeatmapSeries &&
    // Cast type to UILUTCheckBox
    (entry as UILUTCheckBox)
    .setLookUpUnit('mm/h')
    .setLUTThickness(50)
    )

    Returns

    Object itself.

    Parameters

    Returns LegendBox<BackgroundType>

  • Set highlighted state of the Object. Implementations should also remember to highlight themselves here.

    Returns

    Object itself for fluent interface

    Parameters

    • highlight: number | boolean

      Highlight state of the object

    Returns LegendBox<BackgroundType>

  • Set margin around object in pixels.

    Returns

    Object itself

    Parameters

    • margin: number | Partial<MMargin>

      Number with pixel margins for all sides or datastructure with individual pixel margins for each side. Any side can be omitted, only passed values will be overridden.

    Returns LegendBox<BackgroundType>

  • Set mouse interactions enabled or disabled

    Returns

    Object itself for fluent interface

    Parameters

    • state: boolean

      Specifies state of mouse interactions

    Returns LegendBox<BackgroundType>

  • Sets the position origin of this UiElement. Affects how the "position" of UIElement is interpreted.

    See UIOrigins for a collection of common arguments in an easy-to-read format.

    Returns

    Object itself

    Parameters

    Returns LegendBox<BackgroundType>

  • Set padding around object in pixels. Padding is empty space between the UiElements content and Background

    Returns

    Object itself

    Parameters

    • padding: number | Partial<Margin>

      Number with pixel margins for all sides or datastructure with individual pixel paddings for each side. Any side can be omitted, only passed values will be overridden.

    Returns LegendBox<BackgroundType>

  • Sets the position of this UiElement relative to its origin.

    NOTE: UIElements scale can't be changed apart from when it is created.

    Returns

    Object itself

    Parameters

    • position: Point

      Location on the UIElements scale, where its origin should be positioned

    Returns LegendBox<BackgroundType>

  • Set text of LegendBox title.

    Returns

    Object itself for fluent interface.

    Parameters

    • title: string

      LegendBox title as a string.

    Returns LegendBox<BackgroundType>

  • Set fill style of LegendBox Title.

    Example usage:

    // Create a new style
    setTitleFillStyle(new SolidFill({ color: ColorHEX('#F00') }))
    // Change transparency
    setTitleFillStyle((solidFill) => solidFill.setA(80))
    // Set hidden
    setTitleFillStyle(emptyFill)

    Returns

    LegendBox itself

    Parameters

    Returns LegendBox<BackgroundType>

  • Set rotation of LegendBox title.

    Returns

    Object itself

    Parameters

    • value: number

      Rotation in degrees

    Returns LegendBox<BackgroundType>

  • Set element visibility.

    Returns

    Object itself.

    Parameters

    • state: boolean

      true when element should be visible and false when element should be hidden.

    Returns LegendBox<BackgroundType>