API Docs

Class: Legend

PD.SVG. Legend

Generates a simple horizontal legend as an SVG element.

     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |       |       |       |       |
     |0.0   0.25    0.5    0.75   1.0|

new Legend(config)

Creates a new horizontal legend instance.

Parameters:
Name Type Description
config object

A configuration object.
Properties of config:
Name Type Argument Description
svgId SVGElement | string

The SVG element to use, or the DOM ID of an SVG element.
trackLegend PD.Legend <optional>

An optional legend to track.
Author:
  • drajmarsh
Throws:

Throws an error if provided with an invalid svgId element or id.

Type
Error

Extends

Members

:number

_colorType

The type of color gradient to use, defaults to 0 (rainbow).

Type
  • number
Inherited From:
Overrides:
:string

className <readonly>

The name of the subclass for this object instance.

This name must match the name of this class within the PD.Registry. Thus, the base implementation simply references this.constructor.getClassName() to ensure that this is always the case even for subclasses. As a result, there is rarely any need to override this method.

This property is used when copying, storing and exporting data for subclass instances to ensure that they are recreated as instances of the right class.

Type
  • string
Inherited From:
Overrides:
:number

colorType

The type of color gradient to use, default to 0 (rainbow).

Type
  • number
Inherited From:
Overrides:
:number

decimals

The number of decimal places for values.

Type
  • number
:number

displacement

A maximum displacement to offset cells from their grid plane by their values in mm, defaults to 0.

Type
  • number
Inherited From:
Overrides:
:string

displayName <readonly>

The name to display for this class within the user interface.

Type
  • string
Inherited From:
Overrides:
:PD.FORMAT

format

The format for displaying value range text.

Type
:boolean

hasChanged

Whether or not the scale range has changed.

Type
  • boolean
Inherited From:
Overrides:
:string

iconName <readonly>

The name of the SVG icon to associate with this object instance.

This name should match the name of the icon associated with this class within the PD.Registry. Thus, the default implementation simply references this.constructor.getClassName() to ensure that this is always the case, even for subclasses. However, you can override this property if you want a different icon dependant on other properties of the class instance, as shown in the example below.

Type
  • string
Inherited From:
Overrides:
Example
// Overriding the icon name.

MyElements.Table = class extends PD.Base {
    /// ...
    get iconName() {
        if (this.hasRoundTop) return 'MyElements.Table.Round';
        return this.constructor.getClassName();
    };
    /// ...
 };
:number

id

A unique identifier for this legend.

Type
  • number
:boolean

isLegend <readonly>

A flag identifying this object as a grid legend.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isSet <readonly>

A flag indicating if the scale range has been specifically set yet.

Type
  • boolean
Inherited From:
Overrides:
:number

max

The absolute value representing the top of the scale, defaults to 1.

Type
  • number
Inherited From:
Overrides:
:number

min

The absolute value representing the bottom of the scale, defaults to 0.

Type
  • number
Inherited From:
Overrides:
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:boolean

showContourBands

Whether to show contours in block colors at the current step values.

Type
  • boolean
Inherited From:
Overrides:
:boolean

showContourLines

Whether to show contour lines at the current step values.

Type
  • boolean
Inherited From:
Overrides:
:boolean

showGridLines

Whether to show grid lines or triangulation edges.

Type
  • boolean
Inherited From:
Overrides:
:boolean

showSmooth

Whether to show data as a continuous smooth surface rather than as block values, defaults to true.

Type
  • boolean
Inherited From:
Overrides:
:number

steps

The number of steps in the color chart (1 to 128), defaults to 20.

Type
  • number
Inherited From:
Overrides:
:SVGElement

svgElem

The SVG element to render the diagram to.

Type
  • SVGElement
:PD.Legend

trackLegend

The grid legend being represented in range and colors.

Type
:string

units

The units of the metric the legend is displaying, defaults to percentage (%).

Type
  • string
Inherited From:
Overrides:
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:

Methods

clone()

Creates a copy of this instance with different name and uuid.

Inherited From:
Overrides:
Returns:

Returns a new instance with copied values.

Type
PD.Base | null

computeColour(value [, result])

Calculates the legend colour from the absolute value.

Parameters:
Name Type Argument Description
value number

The value to calculate the colour for.
result THREE.Color <optional>

An optional colour value, defaults to internal shared color.
Inherited From:
Overrides:
Returns:

Returns a shared color value.

Type
THREE.Color

computeDisplacement(value)

Calculates the displacement of a cell value in model units.

Parameters:
Name Type Description
value number

The value to calculate the displacement for.
Inherited From:
Overrides:
Returns:

Returns the displacement distance.

Type
number

computeFraction(value)

Calculates the normalised scale fraction from the given absolute value.

Parameters:
Name Type Description
value number

The value to calculate the fraction for.
Inherited From:
Overrides:
Returns:

Returns the normalised scale fraction.

Type
number

copyToPolyMesh(mesh, width, height)

Add geometry representing the legend to the given WebGL mesh.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to add the legend to.
width number

The horizontal width of the legend in virtual pixels.
height number

The vertical height of the legend in virtual pixels.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

fromJSON(data)

Safely copy properties from a source object.

See the PD.Base#fromJSON method for more details.

Parameters:
Name Type Description
data object

The source object containing data to copy.
Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.Legend

getContourIncrement()

Computes the value range divided by steps.

Inherited From:
Overrides:
Returns:

Returns the computed contour increment.

Type
number

getValueRange()

Retrieves the range of values, effectively max minus min.

Inherited From:
Overrides:

includeInRange(value)

Expands the value range to accommodate the given value.

Parameters:
Name Type Description
value number

The value to accommodate in range.
Inherited From:
Overrides:
Returns:

Returns true if the range changed.

Type
boolean

reset()

Resets the value range to begin accommodating new values.

This method initialises the scale range that you can call the includeInRange() method to set the range based on multiple values. After you have finished setting the range, call the update() method.

Inherited From:
Overrides:
Returns:

Returns this legend instance to support method chaining.

Type
PD.Legend

set(config)

Sets the legend data use.

Parameters:
Name Type Description
config number

A configuration object.
Properties of config:
Name Type Argument Description
trackLegend PD.Legend <optional>

An optional legend to track the state of.
Returns:

Returns true if anything changed, otherwise false.

Type
boolean

setRange(min, max)

Sets the new value range.

Parameters:
Name Type Description
min number

The new minimum value.
max number

The new minimum value.
Inherited From:
Overrides:
Returns:

Returns true if the range changed.

Type
boolean

toJSON( [data])

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

See the PD.Base#toJSON method for more details.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Inherited From:
Overrides:
Returns:

Returns a JSON object.

Type
object

update( [forceUpdate])

Performs a complete update of the legend.

See the PD.Legend#update method for more details.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

Whether or not to update even if legend has not changed, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this legend instance to support method chaining.

Type
PD.SVG.Legend

validRange()

Determines if the legend has a valid and useable scale.

A usable scale is when the maximum value is greater the minimum, which is basically what this method checks for.

Inherited From:
Overrides:
Returns:

Returns true if the maximum value is greater the minimum.

Type
boolean