Options
All
  • Public
  • Public/Protected
  • All
Menu

Class PieChart

Abstract base class for Pie Charts. Visualizes proportions and percentages between categories, by dividing a circle into proportional segments.

Set data using PieChart.addSlice( name: string, value: number )

There are multiple implementations of PieChart, each with their own visual design and API for customizing it. List of selectable options can be found in: PieChartTypes

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

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.

addSlice

  • addSlice(name: string, value: number): PieSlice
  • Add new Slice to the Pie Chart. The Slice will be automatically assigned an unique style (using SliceFillStylePalette), that will not be affected by sorting of Slices.

    Currently there is no way to override the individual style of a Slice - style modifications must be done using the API of Pie Chart.

    Parameters

    • name: string

      Initial name for Slice as string.

    • value: number

      Initial value for Slice as number.

    Returns PieSlice

    New Slice object.

addSlices

  • addSlices(multiSlice: object[]): Array<PieSlice>
  • This method is used for the adding multiple slices in the funnel chart.

    Parameters

    • multiSlice: object[]

      Array of slices

    Returns Array<PieSlice>

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

disableAnimations

  • disableAnimations(): this
  • Disable all animations for the chart.

    All animations have to be re-enabled individually if you wish to re-enable animations.

    deprecated

    Deprecated in v3.1.0. Will be removed in v4.0.0. Use setAnimationsEnabled instead.

    Returns this

    Chart itself for fluent interface.

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

getAnimationsEnabled

  • getAnimationsEnabled(): boolean
  • Gets if animations are enabled or not.

    Returns boolean

    Boolean state for animations enabled

getBackgroundFillStyle

  • Get fillstyle of chart background.

    Returns FillStyle

    FillStyle

getBackgroundStrokeStyle

  • Get stroke style of chart background.

    Returns LineStyle

    LineStyle

getInnerRadius

  • getInnerRadius(): number
  • Get inner radius of Pie Chart.. This property can be used to style the Pie Chart as a "Donut Chart", with the center being hollow.

    Returns number

    Inner radius as a percentage of outer radius [0, 100]

getLabelFillStyle

  • Get fill style of Pie Slice Labels.

    Returns FillStyle

    FillStyle object

getLabelFont

  • Get font of Slice Labels.

    Returns FontSettings

    FontSettings

getLabelFormatter

  • Get formatter of Slice Labels.

    Returns SliceLabelFormatter<PieSlice>

    SliceLabelFormatter - function which generates text of Labels per Slice.

getMultipleSliceExplosion

  • getMultipleSliceExplosion(): boolean
  • Get a boolean flag which implies whether it is allowed for multiple Slices to be 'exploded' at the same time or not. When a Slice is exploded, it is drawn differently from non-exploded state

    • usually slightly "pushed away" from the center of Pie Chart.

    Returns boolean

    Is behavior allowed as boolean flag

getPadding

  • Get padding around Chart in pixels.

    Returns Margin

    Padding datastructure

getSliceExplosionOffset

  • getSliceExplosionOffset(): pixel
  • Get offset of exploded Slices in pixels.

    Returns pixel

    Offset of exploded Slices in pixels

getSliceFillStyle

  • Get style of Pie Slices fill. This style is managed as a continuous Palette of FillStyle objects. Each Slice of Pie will be assigned an incremental index, which will be used to pick its fill style from this Palette.

    So, for example... We have a Pie Chart with 5 Slices, and we give it a Palette with only 3 possible values (0 = red, 1 = green, 2 = blue). The resulting Slice fill styles will be: red, green, blue, red, green. Note that this means, that the supplied Palette will have to work in a continuous manner!

    Returns Palette<FillStyle>

    Palette

getSliceSorter

  • Get sorter of Pies' Slices as a comparator-function.

    Returns SliceSorter<PieSlice>

    PieSliceSorter - function which sorts Slices of Pie with JavaScript API: Array.sort.

getSliceStrokeStyle

  • Get stroke style of Pie Slices border.

    Returns LineStyle

    LineStyle object

getSlices

  • Get all Slices of Pie Chart. NOTE: Manual modifications to returned Array can have unforeseen side-effects. Removing or adding Slices is intended to be done using other APIs (PieChart.addSlice, Slice.dispose, ...)

    Returns PieSlice[]

    Array of Slices

getTheme

  • Returns the Theme currently being used.

    Returns Theme

    An object containing the Theme.

getTitle

  • getTitle(): string
  • Get text of Chart title.

    Returns string

    Chart title as a string.

getTitleFillStyle

  • Get fill style of Chart Title.

    Returns FillStyle

    FillStyle object

getTitleFont

  • Get font of Chart title.

    Returns FontSettings

    FontSettings object

getTitleMarginBottom

  • getTitleMarginBottom(): number
  • Returns number

    Padding after Chart title

getTitleMarginTop

  • getTitleMarginTop(): number
  • Returns number

    Padding before Chart title

getTitleRotation

  • getTitleRotation(): number
  • Get rotation of Chart title.

    Returns number

    Rotation in degrees

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

setAnimationsEnabled

  • setAnimationsEnabled(animationsEnabled: boolean): this
  • Sets if animations are enabled or not.

    Parameters

    • animationsEnabled: boolean

      Boolean state for animations enabled

    Returns this

    Pie Chart itself

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

  • 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

    Returns this

    Object itself

setInnerRadius

  • setInnerRadius(innerRadius: number): this
  • Set inner radius of Pie Chart. This method can be used to style the Pie Chart as a "Donut Chart", with the center being hollow.

    Parameters

    • innerRadius: number

      Inner radius as a percentage of outer radius [0, 100]

    Returns this

    Pie Chart itself

setLUT

  • setLUT(lut?: LUT): this
  • Attach lookup table (LUT) to fill the slices with Colors based on value.

    The color for the slice would be selected from a specified LUT, which contains the information about gradient steps. After setting LUT to undefined all the slices stay colorized, but no further lookup.

    LUT class stores information about values and its associated colors,

    • which provides efficient lookup of the color based on provided value
    • as well as linear and step interpolation between colors.
    const pie = lightningChart()
     .Pie( { type: PieChartTypes.LabelsOnSides } )
     .setLUT( new LUT (steps: [
             { value: 10, color: ColorRGBA( 0, 0, 0 ) },
             { value: 20, color: ColorRGBA( 30, 255, 0 ) },
             { value: 30, color: ColorRGBA( 60, 204, 0 ) },
             { value: 40, color: ColorRGBA( 90, 128, 0 ) },
             { value: 50, color: ColorRGBA( 255, 0, 0 ) } ) ],
         interpolate: true } )
    

    Parameters

    • lut: LUT

      Lookup table

    Returns this

    Pie itself for fluent interface

setLabelFillStyle

  • Set fill style of Pie Slices Labels.

    Parameters

    Returns this

    Pie Chart itself

setLabelFont

setLabelFormatter

  • Set formatter of Slice Labels.

    See SliceLabelFormatters for a collection of default options.

    Parameters

    Returns this

    Pie Chart itself

setMultipleSliceExplosion

  • setMultipleSliceExplosion(multipleSliceExplosionAllowed: boolean): this
  • Set if it is allowed for multiple Slices to be 'exploded' at the same time or not. When a Slice is exploded, it is drawn differently from non-exploded state

    • usually slightly "pushed away" from the center of Pie Chart.

    Does not affect state of already exploded Slices!

    Parameters

    • multipleSliceExplosionAllowed: boolean

      Is behavior allowed as boolean flag

    Returns this

    Pie Chart itself

setPadding

  • setPadding(padding: Partial<Margin> | number): this
  • Set padding around Chart in pixels.

     // Example 1, specify complete padding (four sides).
     ChartXY.setPadding({ left: 16, right: 16, top: 32, bottom: 8 })
    
     // Example 2, specify only single padding.
     ChartXY.setPadding({ right: 64 })
    

    Parameters

    • padding: Partial<Margin> | number

      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 this

    Object itself

setSliceExplosionOffset

  • setSliceExplosionOffset(sliceExplosionOffset: pixel): this
  • Set offset of exploded Slices in pixels.

    Parameters

    • sliceExplosionOffset: pixel

      Offset of exploded Slices in pixels

    Returns this

    Pie Chart itself

setSliceFillStyle

  • Set style of Pie Slices fill. This style is managed as a continuous Palette of FillStyle objects. Each Slice of Pie will be assigned an incremental index, which will be used to pick its fill style from this Palette.

    So, for example... We have a Pie Chart with 5 Slices, and we give it a Palette with only 3 possible values (0 = red, 1 = green, 2 = blue). The resulting Slice fill styles will be: red, green, blue, red, green. Note that this means, that the supplied Palette will have to work in a continuous manner!

    Parameters

    Returns this

    Pie Chart itself

setSliceHighlightOnHover

  • setSliceHighlightOnHover(state: boolean): this
  • Set if slices should be highlighted on mouse hover / touch. Applies to all Slices.

    Parameters

    • state: boolean

      True if Slices should be highlighted on hover, false if not. This applies to all existing Slices and new Slices added.

    Returns this

setSliceSorter

  • Set sorter of Pies' Slices as a comparator-function.

    For some commonly needed default implementations, can refer to PieSliceSorters-collection.

    Parameters

    • sliceSorter: SliceSorter<PieSlice>

      PieSliceSorter - function which sorts Slices of Pie with JavaScript API: Array.sort.

    Returns this

    Pie Chart itself

setSliceStrokeStyle

  • Set stroke style of Pie Slices border.

    Parameters

    Returns this

    Pie Chart itself

setTitle

  • setTitle(title: string): this
  • Set text of Chart title.

    Parameters

    • title: string

      Chart title as a string.

    Returns this

    Object itself for fluent interface.

setTitleFillStyle

  • Set fill style of Chart Title.

    Example usage:

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

    Parameters

    Returns this

    Chart itself

setTitleFont

  • Set font of Chart Title.

    Example usage:

    // Create a new FontSettings
    Chart.setTitleFont(new FontSettings({ size: 24, style: 'italic' }))
    // Change existing settings
    Chart.setTitleFont((fontSettings) => fontSettings.setWeight('bold'))
    

    Parameters

    Returns this

    Chart itself

setTitleMarginBottom

  • setTitleMarginBottom(marginPixels: pixel): this
  • Specifies padding after chart title.

    This does not have an effect if title is hidden (empty FillStyle).

     // Example usage,
     // Add empty space between title and series.
     ChartXY.setTitleMarginBottom(32)
    

    Parameters

    • marginPixels: pixel

      Gap after the chart title in pixels.

    Returns this

    Chart itself for fluent interface

setTitleMarginTop

  • setTitleMarginTop(marginPixels: pixel): this
  • Specifies padding before chart title.

    This does not have an effect if title is hidden (empty FillStyle).

     // Example usage,
     // Add empty space at top of chart, before title.
     ChartXY.setTitleMarginTop(32)
    

    Parameters

    • marginPixels: pixel

      Gap between the top of chart and its title in pixels.

    Returns this

    Chart itself for fluent interface

setTitleRotation

  • setTitleRotation(value: number): this
  • Set rotation of Chart title.

    Parameters

    • value: number

      Rotation in degrees

    Returns this

    Object itself