Options
All
  • Public
  • Public/Protected
  • All
Menu

Class UILegendBoxPanel

Component that can be added to a Dashboard, with method Dashboard.createLegendBoxPanel.

It is a convenience component for placing legend box items from multiple different charts into a single row layout.

Example usage:

 // Add a UILegendBoxPanel to a Dashboard.
 const legendBoxPanel = dashboard.createLegendBoxPanel({
     columnIndex: 0,
     rowIndex: 0,
     columnSpan: 1,
     rowSpan: 1,
 })

 // Add charts to shared Legend.
 legendBoxPanel
     .add(myChart1)
     .add(myChart2)

 // Internally created LegendBoxes can be modified via callback.
 legendBoxPanel.setLegendBoxes((legendBox, chart) => {
     // Check reference to only apply style to LegendBox matching a specific chart.
     if (chart !== myChart1) return
     // Now, only the LegendBox matching 'myChart1' will be affected.
     legendBox
         .setTitle('Custom legend title')
         .setTitleFont((font) => font.setWeight('bold'))
 })

Frequently used methods:

Related APIs:

For more application specific LegendBox requirements, it is recommended to:

  • Use UIPanel and manage UI layouts and checkboxes on user application side.
  • Craft the user interface outside LCJS, with HTML for example.

Index

Properties

Methods

Properties

Readonly engine

engine : PublicEngine

Public, safe interface for Panels rendering engine.

pixelScale

pixelScale : LinearScaleXY

Scale for panel area in pixels.

uiScale

uiScale : LinearScaleXY

Scale for panel area in percentages (0-100).

Methods

add

  • Attach a Chart or collection of Charts to the legend box panel.

    This appends a new legend box to the panel, which will contain entries for all the attachable components in the supplied chart.

    The supplied argument can be either a single chart, or a dashboard, in which case all currently existing charts inside the dashboard will be attached.

    The created legend boxes can be styled afterwards using UILegendBoxPanel.setLegendBoxes.

    Example usage:

    // Add charts to LegendBoxPanel.
legendBoxPanel
    .add(myChart1)
    .add(myChart2)

// ... or add all charts inside a Dashboard with a single call.
legendBoxPanel.add(dashboard)

    Parameters

    Returns this

    Object itself.

addLegendBox

  • Add a legendbox.

    Legendbox is a type of UI element, that floats inside the chart/component it is created inside. It can be freely moved around with user interactions, as well as positioned in application code.

    The purpose of legendbox is to describe the series and other visual components of the chart, by displaying their names and colors. Hovering over a series' legendbox entry will highlight that series, and clicking on the entry will toggle that series' visibility.

    Legendbox alignment:

    Alignment of legendbox can be selected by supplying one of the available LegendBoxBuilders to addLegendBox:

     // Default (vertical) LegendBox.
 const legendBox = ChartXY.addLegendBox()

 // Horizontal LegendBox.
 const horizontalLegendBox = ChartXY.addLegendBox(LegendBoxBuilders.HorizontalLegendBox)

    Custom Legendbox positioning:

    By default LegendBoxes are placed on the right side, or bottom of the chart (depending on alignment).

    A custom location can be configured with UIElement API:

    Position coordinate system is specified when creating legendbox.

    1. LegendBox with default positioning coordinate system.
     addLegendBox( LegendBoxBuilders.VerticalLegendBox )
     // Position = [0, 100] as percentages.
     .setPosition({ x: 50, y: 50 })
    1. Position in pixel coordinate system.
     addLegendBox( LegendBoxBuilders.VerticalLegendBox, chart.pixelScale )
     // Position = pixels.
     .setPosition({ x: 300, y: 100 })
    1. Position on Axes.
     addLegendBox( LegendBoxBuilders.VerticalLegendBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
     // Position = Axis values.
     .setPosition({ x: 5, y: 5 })

    Parameters

    • builder: UILegendBoxBuilder

      LegendBoxBuilder. If omitted, VerticalLegendBox will be selected. Use LegendBoxBuilders for selection.

    • scale: UserScaleDefinition

      Optional parameter for altering the coordinate system used for positioning the LegendBox. Defaults to whole Chart in percentages [0, 100].

    Returns LegendBox & UIElement

    Object with two interfaces: LegendBox and UIElement.

addUIElement

  • Add a stand-alone UIElement using a builder.

    Example usage:

    1. TextBox with default positioning coordinate system.
     addUIElement( UIElementBuilders.TextBox )
     // Position = [0, 100] as percentages.
     .setPosition({ x: 50, y: 50 })
    1. Position in pixel coordinate system.
     addUIElement( UIElementBuilders.TextBox, chart.pixelScale )
     // Position = pixels.
     .setPosition({ x: 300, y: 100 })
    1. Position on Axes.
     addUIElement( UIElementBuilders.TextBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
     // Position = Axis values.
     .setPosition({ x: 5, y: 5 })

    Type parameters

    • UIElementType: UIPart = UITextBox

      Type of UIElement that is specified by 'builder'-parameter.

    Parameters

    • builder: UIElementBuilder<UIElementType>

      UIElementBuilder. If omitted, TextBoxBuilder will be selected. Use UIElementBuilders for selection.

    • scale: UserScaleDefinition

      Optional parameter for altering the coordinate system used for positioning the UIElement. Defaults to whole Chart in percentages [0, 100].

    Returns UIElementType & UIElement

    Object that fulfills interfaces: UIElementType (typeparam) and UIElement

dispose

  • dispose(): this

  • Permanently dispose 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 this

    Object itself for fluent interface

getBackgroundFillStyle

  • Get fillstyle of chart background.

    Returns FillStyle

    FillStyle

getBackgroundStrokeStyle

  • getBackgroundStrokeStyle(): LineStyle

  • Get stroke style of chart background.

    Returns LineStyle

    LineStyle

getMinimumSize

  • getMinimumSize(): Point | undefined

  • Get minimum size of UIPanel in pixels as set by user.

    Returns Point | undefined

    Point minimum size in pixels or undefined

offBackgroundMouseClick

  • offBackgroundMouseClick(token: Token): boolean

  • Remove subscription from mouse-click event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseDoubleClick

  • offBackgroundMouseDoubleClick(token: Token): boolean

  • Remove subscription from mouse-doubleClick event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseDown

  • offBackgroundMouseDown(token: Token): boolean

  • Remove subscription from mouse-down event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseDrag

  • offBackgroundMouseDrag(token: Token): boolean

  • Remove subscription from mouse-drag event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseDragStart

  • offBackgroundMouseDragStart(token: Token): boolean

  • Remove subscription from mouse-dragStart event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseDragStop

  • offBackgroundMouseDragStop(token: Token): boolean

  • Remove subscription from mouse-dragStop event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseEnter

  • offBackgroundMouseEnter(token: Token): boolean

  • Remove subscription from mouse-enter event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseLeave

  • offBackgroundMouseLeave(token: Token): boolean

  • Remove subscription from mouse-leave event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseMove

  • offBackgroundMouseMove(token: Token): boolean

  • Remove subscription from mouse-move event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseTouchStart

  • offBackgroundMouseTouchStart(token: Token): boolean

  • Remove subscription from touch-start event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseUp

  • offBackgroundMouseUp(token: Token): boolean

  • Remove subscription from mouse-up event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundMouseWheel

  • offBackgroundMouseWheel(token: Token): boolean

  • Remove subscription from mouse-wheel event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundTouchEnd

  • offBackgroundTouchEnd(token: Token): boolean

  • Remove subscription from touch-end event on Panel background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offBackgroundTouchMove

  • offBackgroundTouchMove(token: Token): boolean

  • Remove subscription from touch-move event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

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

offResize

  • offResize(token: Token): boolean

  • Remove event listener from resize event.

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

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

onBackgroundMouseClick

  • Subscribe to mouse-click event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDoubleClick

  • Subscribe to mouse-doubleClick event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDown

  • Subscribe to mouse-down event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDrag

  • Subscribe to mouse-drag event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDragStart

onBackgroundMouseDragStop

onBackgroundMouseEnter

  • Subscribe to mouse-enter event on Chart background

    Parameters

    Returns Token

onBackgroundMouseLeave

  • Subscribe to mouse-leave event on Chart background

    Parameters

    Returns Token

onBackgroundMouseMove

  • Subscribe to mouse-move event on Chart background

    Parameters

    Returns Token

onBackgroundMouseUp

  • Subscribe to mouse-up event on Chart background

    Parameters

    Returns Token

onBackgroundMouseWheel

  • Subscribe to mouse-wheel event on Chart background

    Parameters

    Returns Token

onBackgroundTouchEnd

  • Subscribe to touch-end event on Chart background

    Parameters

    Returns Token

onBackgroundTouchMove

  • Subscribe to touch-move event on Chart background

    Parameters

    Returns Token

onBackgroundTouchStart

  • Subscribe to touch-start event on Chart background

    Parameters

    Returns Token

onResize

  • onResize(handler: function): Token

  • Subscribe to resize event. This event is triggered whenever the area of chart changes (due to document or dashboard resizing).

     // Example usage,
 ChartXY.onResize((chart, width, height, engineWidth, engineHeight) => {
     console.log('Chart resized', 'width', width, 'height', height, 'engineWidth', engineWidth, 'engineHeight', engineHeight)
 })

    Parameters

    • handler: function

      Handler function for event

        • Parameters

          • obj: this
          • width: pixel
          • height: pixel
          • engineWidth: pixel
          • engineHeight: pixel

          Returns void

    Returns Token

    Token of subscription

saveToFile

  • saveToFile(fileName: string, type?: undefined | string, encoderOptions?: undefined | number): this

  • Capture rendered state in an image file. Prompts the browser to download the created file.

    NOTE: The download might be blocked by browser/plugins as harmful. To prevent this, only call the method in events tied to user-interactions. From mouse-event handlers, for example.

    Has two optional parameters which directly reference JavaScript API HTMLCanvasElement.toDataURL. For supported image formats, compression quality, Etc. refer to:

    https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

    Example usage:

    // Download 'screenshot.png'
Panel.saveToFile('screenshot')
// Attempt download 'maybeNotSupported.bmp'
Panel.saveToFile('maybeNotSupported', 'image/bmp')
// Attempt download jpeg.file with specified compression quality
Panel.saveToFile('fileName', 'image/jpeg', 0.50)
    sideeffect

    If 'type' is not supported by browser, an Error will be thrown.

    Parameters

    • fileName: string

      Name of prompted download file as string. File extension shouldn't be included as it is automatically detected from 'type'-argument.

    • type: undefined | string

      A DOMString indicating the image format. The default format type is image/png.

    • encoderOptions: undefined | number

      A Number between 0 and 1 indicating the image quality to use for image formats that use lossy compression such as image/jpeg and image/webp. If this argument is anything else, the default value for image quality is used. The default value is 0.92.

    Returns this

setBackgroundFillStyle

  • Set FillStyle of chart background.

     // Example usage,
 ChartXY.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA( 80, 0, 0 ) }))

    Related API:

    • Use SolidFill to describe a solid fill color.
    • Use ColorRGBA to create a color from Red, Green, Blue (and optionally) Alpha values in range [0, 255].

    Parameters

    Returns this

    Object itself

setBackgroundStrokeStyle

  • setBackgroundStrokeStyle(value: LineStyle | ImmutableMutator<LineStyle>): this

  • Set [[LineStyle]] of chart background border stroke.

     // Example usage,
 ChartXY.setBackgroundStrokeStyle(new SolidLine({
     thickness: 2,
     fillStyle: new SolidFill({ color: ColorRGBA( 0, 255, 0 ) })
 }))

    Related API:

    • Use SolidLine to describe a solid line style.
    • Use SolidFill to describe a solid fill color.
    • Use ColorRGBA to create a color from Red, Green, Blue (and optionally) Alpha values in range [0, 255].

    Parameters

    • value: LineStyle | ImmutableMutator<LineStyle>

      LineStyle or function which mutates the active LineStyle.

    Returns this

    Object itself

setLegendBoxes

  • setLegendBoxes(clbk: function): this

  • Trigger a callback for each legend box inside the panel. Each legend box is paired with a single chart that the user has attached to the legend box panel, which can be used for applying modifications to any particular legend boxes only.

    Example usage:

     // Style internally created LegendBoxes. NOTE: Must be called after the LegendBoxes are created, using LegendBoxPanel.add()
 LegendBoxPanel.setLegendBoxes((legendBox, chart) => {
     legendBox
         // Style LegendBox title.
         .setTitleFont((font) => font.setWeight('bold'))
         // Style LegendBox entries.
         .setEntries((entry) => entry
             .setTextFont((font) => font.setSize(12))
         )
 })

 // Style can be applied to selected LegendBoxes only by checking reference to supplied chart.
 LegendBoxPanel.setLegendBoxes((legendBox, chart) => {
     // Only apply style to LegendBox matching one single chart.
     if (chart !== myChart1) return

     // Style legendBox ...
 })

    Parameters

    • clbk: function

      Function that is called for each existing legend box, and attached chart.

        • Parameters

          Returns void

    Returns this

    Object itself for fluent interface.

setMinimumSize

  • setMinimumSize(minimumSize: Point): this

  • Set minimum size of UIPanel in pixels. This will affect its resizability by dragging dashboard splitters.

    Parameters

    • minimumSize: Point

      Minimum size as Point pixels

    Returns this