picasso.js

v1.4.2

A charting library streamlined for building visualizations for the Qlik Sense Analytics platform.

picassojs(cfg)

function

picasso.js entry point

Parameters

cfg

No description

Returns

No description

Properties

version
string

picasso.js version

import picasso from 'picasso.js';

const configuredPicasso = picasso({ renderer: { prio: ['canvas'] } }) // All components will render using the canvas renderer

picassojschart(definition)

function

Parameters

definition

No description

Returns

Chart instance

picasso.chart({
    element: document.querySelector('#container'), // This is the element to render the chart in
    data: [
      {
        type: 'matrix',
        data: [
          ['Month', 'Sales', 'Margin'],
          ['Jan', 1106, 7],
          ['Feb', 5444, 53],
          ['Mar', 147, 64],
          ['Apr', 7499, 47],
          ['May', 430, 62],
          ['June', 9735, 13],
          ['July', 5832, 13],
          ['Aug', 7435, 15],
          ['Sep', 3467, 35],
          ['Oct', 3554, 78],
          ['Nov', 5633, 23],
          ['Dec', 6354, 63],
        ],
      },
    ],
    settings: {
      scales: {
        x: { data: { field: 'Margin' } },
        y: { data: { field: 'Sales' } },
      },
      components: [
        {
          // specify how to render the chart
          type: 'axis',
          scale: 'y',
          layout: {
            dock: 'left',
          },
        },
        {
          type: 'axis',
          scale: 'x',
          layout: {
            dock: 'bottom',
          },
        },
        {
          type: 'point',
          data: {
            extract: {
              field: 'Month',
              props: {
                x: { field: 'Margin' },
                y: { field: 'Sales' },
              },
            },
          },
          settings: {
            x: { scale: 'x' },
            y: { scale: 'y' },
            size: function () {
              return Math.random();
            },
          },
        },
      ],
    },
  });

picassojscomponent(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

picassojsdata(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

picassojsformatter(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

picassojsinteraction(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

picassojsrenderer(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

const svgFactory = picassojs.renderer('svg');
const svgRenderer = svgFactory();

picassojsscale(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

picassojsuse(plugin, options?)

function

Plugin registry

Parameters

plugin

Callback function to register a plugin

options
optional
object

No description

Brush()

interface

A brush context

Brushend()

event

Triggered when this brush is deactivated

Brushstart()

event

Triggered when this brush is activated

Brushupdate(added, removed)

event

Triggered when this brush is updated

Parameters

added
Array<object>

The added items

removed
Array<object>

The removed items

BrushaddAndRemoveValues(addItems, removeItems)

function

Add and remove values in a single operation almost the same as calling addValues and removeValues but only triggers one 'update' event

If the state of the brush changes, an 'update' event is emitted.

Parameters

addItems
Array<object>

Items to add

removeItems
Array<object>

Items to remove

BrushaddKeyAlias(key, alias)

function

Adds an alias to the given key

Parameters

key
string

Value to be replaced

alias
string

Value to replace key with

brush.addKeyAlias('BadFieldName', 'Region');
brush.addValue('BadFieldName', 'Sweden'); // 'BadFieldName' will be stored as 'Region'
brush.containsValue('Region', 'Sweden'); // true
brush.containsValue('BadFieldName', 'Sweden'); // true

BrushaddRange(key, range)

function

Adds a numeric range to this brush context

Parameters

key
string

An identifier that represents the data source of the range

range

The range to add to this brush

brush.addRange('Sales', { min: 20, max: 50 });

BrushaddRanges(items)

function

Parameters

items

Items containing the ranges to remove

BrushaddValue(key, value)

function

Adds a primitive value to this brush context

If this brush context is not started, a 'start' event is emitted. If the state of the brush changes, ie. if the added value does not already exist, an 'update' event is emitted.

Parameters

key
string

An identifier that represents the data source of the value

value
string | number

The value to add

brush.addValue('countries', 'Sweden');
brush.addValue('/qHyperCube/qDimensionInfo/0', 3);

BrushaddValues(items)

function

Parameters

items
Array<object>

Items to add

Brushbrushes()

function

Returns all brushes within this context

Returns

object

No description

Brushclear()

function

Clears this brush context

Brushconfigure(config)

function

Configure the brush instance.

Parameters

config

No description

brushInstance.configure({
  ranges: [
    { key: 'some key', includeMax: false },
    { includeMax: true, includeMin: true },
  ]
})

BrushcontainsRange(key, range)

function

Checks if a range segment is contained within this brush context

Returns true if the range segment exists for the provided key, returns false otherwise.

Parameters

key
string

An identifier that represents the data source of the value

range

The range to check for

Returns

boolean

No description

brush.addRange('Sales', { min: 10, max: 50 });
brush.containsRange('Sales', { min: 15, max: 20 }); // true - the range segment is fully contained within [10, 50]
brush.containsRange('Sales', { min: 5, max: 20 }); // false - part of the range segment is outside [10, 50]
brush.containsRange('Sales', { min: 30, max: 80 }); // false - part of the range segment is outside [10, 50]

BrushcontainsRangeValue(key, value)

function

Checks if a value is contained within a range in this brush context

Returns true if the values exists for the provided key, returns false otherwise.

Parameters

key
string

An identifier that represents the data source of the value

value
number

The value to check for

Returns

boolean

No description

brush.addRange('Sales', { min: 10, max: 50 });
brush.containsRangeValue('Sales', 30); // true
brush.containsRangeValue('Sales', 5); // false

BrushcontainsValue(key, value)

function

Checks if a certain value exists in this brush context

Returns true if the values exists for the provided key, returns false otherwise.

Parameters

key
string

An identifier that represents the data source of the value

value
string | number

The value to check for

Returns

boolean

No description

brush.addValue('countries', 'Sweden');
brush.containsValue('countries', 'Sweden'); // true
brush.toggleValue('countries', 'Sweden'); // remove 'Sweden'
brush.containsValue('countries', 'Sweden'); // false

Brushend(args)

function
emitsend

Ends this brush context

Ends this brush context and emits an 'end' event if it is not already ended.

Parameters

args
any

arguments to be passed to 'end' listeners

Brushintercept(name, ic)

function

Adds an event interceptor

Parameters

name
string

Name of the event to intercept

ic
function

Handler to call before event is triggered

brush.intercept('add-values', items => {
 console.log('about to add the following items', items);
 return items;
});

BrushisActive()

function

Checks if this brush is activated

Returns true if started, false otherwise

Returns

boolean

No description

BrushremoveAllInterceptors(name?)

function

Removes all interceptors

Parameters

name
optional
string

Name of the event to remove interceptors for. If not provided, removes all interceptors.

BrushremoveInterceptor(name, ic)

function

Removes an interceptor

Parameters

name
string

Name of the event to intercept

ic
function

Handler to remove

BrushremoveKeyAlias(key)

function

Removes an alias

This will only remove the key to alias mapping for new manipulations of the brush, no changes will be made to the current state of this brush.

Parameters

key
string

Value to remove as alias

brush.removeKeyAlias('BadFieldName');

BrushremoveRange(key, range)

function

Removes a numeric range from this brush context

Parameters

key
string

An identifier that represents the data source of the range

range

The range to remove from this brush

BrushremoveRanges(items)

function

Parameters

items
Array<object>

Items containing the ranges to remove

BrushremoveValue(key, value)

function

Removes a primitive values from this brush context

If the state of the brush changes, ie. if the removed value does exist, an 'update' event is emitted.

Parameters

key
string

An identifier that represents the data source of the value

value
string | number

The value to remove

brush.removeValue('countries', 'Sweden');

BrushremoveValues(items)

function

Parameters

items
Array<object>

Items to remove

BrushsetRange(key, range)

function

Sets a numeric range to this brush context

Overwrites any active ranges identified by key

Parameters

key
string

An identifier that represents the data source of the range

range

The range to set on this brush

BrushsetRanges(items)

function

Parameters

items
Array<object>

Items containing the ranges to set

BrushsetValues(items)

function

Parameters

items
Array<object>

Items to set

Brushstart(args)

function
emitsstart

Starts this brush context

Starts this brush context and emits a 'start' event if it is not already started.

Parameters

args
any

arguments to be passed to 'start' listeners

BrushtoggleRange(key, range)

function

Toggles a numeric range in this brush context

Removes the range if it's already contained within the given identifier, otherwise the given range is added to the brush.

Parameters

key
string

An identifier that represents the data source of the range

range

The range to toggle in this brush

BrushtoggleRanges(items)

function

Parameters

items
Array<object>

Items containing the ranges to toggle

BrushtoggleValue(key, value)

function

Toggles a primitive value in this brush context

If the given value exists in this brush context, it will be removed. If it does not exist it will be added.

Parameters

key
string

An identifier that represents the data source of the value

value
string | number

The value to toggle

brush.toggleValue('countries', 'Sweden');

BrushtoggleValues(items)

function

Parameters

items
Array<object>

Items to toggle

BrushConfig

object

Properties

ranges
optional

Range configurations

BrushConfigRanges

object

Properties

includeMax
optional, default=true
boolean

Whether or not the maximum value of a range should be included when determining if a value is brushed.

includeMin
optional, default=true
boolean

Whether or not the minimum value of a range should be included when determining if a value is brushed.

key
optional
string

An identifier that represents the data source of the value

BrushConsumeSettings

object

Properties

context
optional
string

Name of the brush context to observe

data
optional
Array<string>

The mapped data properties to observe

mode
optional
string

Data properties operator: and, or, xor.

style
optional

The style to apply to the shapes of the component

{
   context: 'selection',
   data: ['x'],
   filter: (shape) => shape.type === 'circle',
   style: {
     active: {
       fill: 'red',
       stroke: '#333',
       strokeWidth: (shape) => shape.strokeWidth * 2,
     },
     inactive: {},
   },
}

BrushConsumeSettingsfilter

function

Filtering function

BrushTargetConfig

object

Properties

key
string

Component key

contexts
optional
Array<string>

Name of the brushing contexts to affect

data
optional
Array<string>

The mapped data properties to add to the brush

action
optional, default='set'
string

Type of action to respond with

BrushTriggerSettings

object

Properties

on
optional
string

Type of interaction to trigger brush on

action
optional
string

Type of interaction to respond with

contexts
optional
Array<string>

Name of the brushing contexts to affect

data
optional
Array<string>

The mapped data properties to add to the brush

propagation
optional
string

Control the event propagation when multiple shapes are tapped. Disabled by default

globalPropagation
optional
string

Control the event propagation between components. Disabled by default

touchRadius
optional
number

Extend contact area for touch events. Disabled by default

mouseRadius
optional
number

Extend contact area for regular mouse events. Disabled by default

{
   on: 'tap',
   action: 'toggle',
   contexts: ['selection', 'tooltip'],
   data: ['x'],
   propagation: 'stop', // 'stop' => prevent trigger from propagating further than the first shape
   globalPropagation: 'stop', // 'stop' => prevent trigger of same type to be triggered on other components
   touchRadius: 24,
   mouseRadius: 10
 }

canvasRendererFactory(sceneFn?)

function

Create a new canvas renderer

Parameters

sceneFn
optional
function

Scene factory

Returns

A canvas renderer instance

Chart()

interface

Chart instance

Properties

interactions

Get all interaction instances

Chartbrush(name)

function

Get or create brush context for this chart

Parameters

name
string

Name of the brush context. If no match is found, a new brush context is created and returned.

Returns

A brush context

ChartbrushFromShapes(shapes, config)

function

Brush data by providing a collection of data bound shapes.

Parameters

shapes

An array of data bound shapes.

config

Options

const shapes = chartInstance.shapesAt(...);
const config = {
 components:[
   {
     key: 'key1',
     contexts: ['myContext'],
     data: [''],
     action: 'add'
   }
 ]
};
chartInstance.brushFromShapes(shapes, config);

Chartcomponent(key)

function

Get a component context

Parameters

key
string

Component key

Returns

Component instance

ChartcomponentsFromPoint(p)

function

Get components overlapping a point.

Parameters

p

Point with x- and y-coordinate. The coordinate is relative to the browser viewport.

Returns

Array of component contexts

Chartdataset(key)

function

Get

Parameters

key
string

Get the dataset identified by key

Returns

No description

Chartdestroy()

function

Destroy the chart instance.

ChartfindShapes(selector)

function

Get all nodes matching the provided selector

Parameters

selector
string

CSS selector [type, attribute, universal, class]

Returns

Array of objects containing matching nodes

chart.findShapes('Circle') // [<CircleNode>, <CircleNode>]
chart.findShapes('Circle[fill="red"][stroke!="black"]') // [CircleNode, CircleNode]
chart.findShapes('Container Rect') // [Rect, Rect]

Chartformatter(v)

function

Get or create a formatter for this chart

Parameters

v
string | object

Formatter reference or formatter options

Returns

No description

instance.formatter('nameOfMyFormatter'); // Fetch an existing formatter by name
instance.formatter({ formatter: 'nameOfMyFormatter' }); // Fetch an existing formatter by name
instance.formatter({ type: 'q' }); // Fetch an existing formatter by type
instance.formatter({
 formatter: 'd3',
 type: 'number',
 format: '1.0.%'
}); // Create a new formatter

Chartformatters()

function

Get all registered formatters

Returns

No description

ChartgetAffectedShapes(context, mode, props, key)

function

Get all shapes associated with the provided context

Parameters

context
string

The brush context

mode
string

Property comparison mode.

props
Array<string>

Which specific data properties to compare

key
string

Which component to get shapes from. Default gives shapes from all components.

Returns

Array<object>

Array of objects containing shape and parent element

ChartlayoutComponents(def?)

function
experimental

Layout the chart with new settings and / or data

Parameters

def
optional

New chart definition

Chartscale(v)

function

Get or create a scale for this chart

Parameters

v
string | object

Scale reference or scale options

Returns

Scale instance

instance.scale('nameOfMyScale'); // Fetch an existing scale by name
instance.scale({ scale: 'nameOfMyScale' }); // Fetch an existing scale by name
instance.scale({ source: '0/1', type: 'linear' }); // Create a new scale

Chartscales()

function

Get all registered scales

Returns

No description

ChartshapesAt(shape, opts)

function

Get all nodes colliding with a geometrical shape (circle, line, rectangle, point, polygon, geopolygon).

The input shape is identified based on the geometrical attributes in the following order: circle => line => rectangle => point => polygon => geopolygon. Note that not all nodes on a scene have collision detection enabled.

Parameters

shape

A geometrical shape. Coordinates are relative to the top-left corner of the chart instance container.

opts

Options

Returns

Array of objects containing colliding nodes

chart.shapesAt(
 {
   x: 0,
   y: 0,
   width: 100,
   height: 100
 },
 {
   components: [
     { key: 'key1', propagation: 'stop' },
     { key: 'key2' }
   ],
   propagation: 'stop'
 }
);

CharttoggleBrushing(val?)

function

Parameters

val
optional
boolean

Toggle brushing on or off. If value is omitted, a toggle action is applied to the current state.

Chartupdate(def?)

function

Update the chart with new settings and / or data

Parameters

def
optional

New chart definition

ChartDefinition

object

Properties

data

Chart data

element
HTMLElement

Element to attach chart to

settings

Chart settings

ChartDefinitionbeforeDestroy()

function

Called before the chart has been destroyed

ChartDefinitionbeforeMount()

function

Called before the chart has been mounted

ChartDefinitionbeforeRender()

function

Called before the chart has been rendered

ChartDefinitionbeforeUpdate()

function

Called before the chart has been updated

ChartDefinitioncreated()

function

Called when the chart has been created

ChartDefinitiondestroyed()

function

Called after the chart has been destroyed

ChartDefinitionmounted(element)

function

Called after the chart has been mounted

Parameters

element
HTMLElement

The element the chart been mounted to

ChartDefinitionupdated()

function

Called after the chart has been updated

ChartSettings

object

Properties

components
optional

Components

scales
optional

Dictionary with scale definitions

formatters
optional

Dictionary with formatter definitions

strategy

Dock layout settings

interactions
optional

Interaction handlers

collections
optional

Collections

Circle

object

Properties

cx
number

Center x-coordinate

cy
number

Center y-coordinate

r
number

Circle radius

CollectionSettings

interface

Properties

key
string

Unique key for the collection

data

Used to extract data from a DataSource

{
    key: 'my-collection',
    data: {
      extract: [{
        source: 'Products',
        field: 'Product',
        value: d => d.name,
        label: d => `<${d.name}>`
        props: {
          year: { field: 'Year' }
          num: { field: 'Sales' }
        }
      }],
      filter: d => d.label !== 'Sneakers', // extract everything except Sneakers
      sort: (a, b) => a.label > b.label ? -1 : 1, // sort descending
    }
}

Component

object

Component instance

Properties

type
string

Type of component

key
string

Key of the component

ComponentAxis

object

Properties

scale
string

reference to band or linear scale

settings

discrete or continuous axis settings

{
 type: 'axis',
 scale: '<name-of-scale>'
}

ComponentAxisContinuousSettings

object

Continuous axis settings

Properties

align
optional, default='auto'
string

Set the anchoring point of the axis. Available options are auto/left/right/bottom/top. In auto the axis determines the best option. The options are restricted based on the axis orientation, a vertical axis may only anchor on left or right

labels

No description

line

No description

minorTicks

No description

paddingEnd
optional, default=10
number

Padding in direction perpendicular to the axis

paddingStart
optional
number

Padding in direction perpendicular to the axis

ticks

No description

{
 type: 'axis',
 scale: '<name-of-linear-scale>',
 settings: {
   minorTicks: {
     show: false,
   },
 },
}

ComponentAxisDiscreteSettings

object

Discrete axis settings

Properties

align
optional, default='auto'
string

Set the anchoring point of the axis. Available options are auto/left/right/bottom/top. In auto the axis determines the best option. The options are restricted based on the axis orientation, a vertical axis may only anchor on left or right

labels

No description

line

No description

paddingEnd
optional, default=10
number

Padding in direction perpendicular to the axis

paddingStart
optional
number

Padding in direction perpendicular to the axis

ticks

No description

{
 type: 'axis',
 scale: '<name-of-band-scale>',
 settings: {
   labels: {
     mode: 'tilted',
     tiltAngle: 40,
   },
 },
}

ComponentBox

object

Properties

data

No description

settings

No description

{
  type: "box",
  data: {
   mapTo: {
     min: { source: "/qHyperCube/qMeasureInfo/0" },
     start: { source: "/qHyperCube/qMeasureInfo/1" },
     med: { source: "/qHyperCube/qMeasureInfo/2" },
     end: { source: "/qHyperCube/qMeasureInfo/3" },
     max: { source: "/qHyperCube/qMeasureInfo/4" },
   },
   groupBy: {
     source: "/qHyperCube/qDimensionInfo/0"
   }
 },
 settings: {
   major: {
     scale: { source: "/qHyperCube/qDimensionInfo/0" }
   },
   minor: {
     scale: { source: ["/qHyperCube/qMeasureInfo/0",
              "/qHyperCube/qMeasureInfo/1",
              "/qHyperCube/qMeasureInfo/2",
              "/qHyperCube/qMeasureInfo/3",
              "/qHyperCube/qMeasureInfo/4"] }
   }
 }
}

ComponentBoxMajorReference

object

Properties

start
string

Reference to the data property of the start value along the major axis

end
string

Reference to the data property of the end value along the major axis

ComponentBrushArea

object

A component that can brush a rectangular area

Properties

settings

No description

{
 type: 'brush-area',
 brush: {
   components: [{ key: '<target-component>', contexts: ['highlight'] }]
 }
}

ComponentBrushAreaDir

object

Properties

settings

No description

ComponentBrushLasso

object

Properties

settings

Component settings

{
 type: 'brush-lasso',
 settings: {
   brush: {
     components: [{ key: '<target-component>', contexts: ['<brush-context>'] }]
   }
 },
}

ComponentBrushRange

object

Properties

settings

No description

ComponentContainer

object
experimental

Properties

type
experimental
optional, default='container'
string

No description

{
 type: 'container',
 preferredSize: ({ inner, outer, dock, children }) => {
   const sizes = children.map(c => c.preferredSize({ inner, outer }));
   return Math.max(...sizes);
 },
 strategy: (rect, components) => {
   const height = rect.height / components.length;
   components.forEach((c, i) => {
     c.resize({ ...rect, height, y: rect.y + i * height })
   });
   return { visible: components, hidden: [], order: components };
 },
 components: [
    ...
 ],
}

ComponentGridLine

object

Properties

settings

Component settings

{
 type: 'grid-line',
 settings: {
   x: {
     scale: '<name-of-scale>',
   },
   y: {
     scale: '<name-of-scale>',
   },
 },
}

ComponentLabels

object

Properties

settings

Component settings

{
  type: 'labels',
  settings: {
    sources: [
      {
        component: 'bars',
        selector: 'rect', // select all 'rect' shapes from the 'bars' component
        strategy: {
          type: 'bar', // the strategy type
          settings: {
            labels: [
              {
                label({ data }) {
                  return data ? data.end.label : '';
                },
                placements: [
                  // label placements in prio order. Label will be placed in the first place it fits into
                  { position: 'inside', fill: '#fff' },
                  { position: 'outside', fill: '#666' },
                ],
              },
            ],
          },
        },
      },
    ],
  },
}

ComponentLabelsBarsLabelStrategy

object

Properties

type
default='bar'
string

Name of strategy

settings

Bars strategy settings

ComponentLabelsRowsLabelStrategy

object

Properties

type
default='rows'
string

Name of strategy

settings

Rows strategy settings

ComponentLabelsSlicesLabelStrategy

object

Properties

type
default='slice'
string

Name of strategy

settings

Slices strategy settings

ComponentLabelsSource

object

Properties

component
string

Key of target component

selector
string

Shape selector

strategy

Strategy settings

ComponentLegendCat

object

Properties

scale
string

Reference to categorical color scale

settings

Component settings

{
  type: 'legend-cat',
  scale: '<categorical-color-scale>',
}

ComponentLegendSeq

object

Properties

settings

Component settings

{
  type: 'legend-seq',
  settings: {
    fill: '<sequential-color-scale>',
    major: '<linear-scale>',
  }
}

ComponentLine

object

Properties

settings

Component settings

{
  type: "line",
  data: {
    extract: {
      field: "Year",
      props: {
        sales: { field: "Sales" },
      },
    },
  },
  settings: {
    coordinates: {
      major: { scale: "t" },
      minor: { scale: "y", ref: "sales" },
    },
  },
}

ComponentLineLayerSort(a, b)

function

Callback function for layer sort

Parameters

a

No description

b

No description

ComponentPie

object

Properties

settings

Component settings

{
  type: 'pie',
  data: {
    extract: {
      field: 'Region',
      props: {
        num: { field: 'Population' }
      }
    }
  },
  settings: {
    startAngle: Math.PI / 2,
    endAngle: -Math.PI / 2,
    slice: {
      arc: { ref: 'num' },
      fill: 'green',
      stroke: 'red',
      strokeWidth: 2,
      strokeLinejoin: 'round',
      innerRadius: 0.6,
      outerRadius 0.8,
      opacity: 0.8,
      offset: 0.2
    }
  }
}

ComponentPoint

object

Properties

settings

Component settings

{
  type: 'point',
  data: {
    extract: {
      field: 'Month',
      props: {
        x: { field: 'Margin' },
        y: { field: 'Year' }
      }
    }
  },
  settings: {
    x: { scale: 'm' },
    y: { scale: 'y' },
  }
}

ComponentRefLine

object

Properties

settings

Component settings

{
 type: 'ref-line',
 lines: {
   y: [{
     scale: 'y',
     value: 5000,
     label: {
       text: 'value label'
     }
   }]
 }
}

ComponentRefLineGenericObject

object

Properties

fill
optional, default='#fff'
string

Fill color

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

opacity
optional, default=1
number

Opacity

ComponentRefLineGenericText

object

Properties

text
optional, default=''
string

Text (if applicable)

fontSize
optional, default='12px'
string

Font size (if applicable)

fontFamily
optional, default='Arial'
string

Font family

fill
optional, default='#fff'
string

Fill color

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

strokeDasharray
optional
string

Stroke dash array

opacity
optional, default=1
number

Opacity

ComponentRefLineLine

object

Properties

value
number | function

The value of the reference line. If a scale is specified, it is applied.

scale
optional
string

Scale to use (if undefined will use normalized value 0-1)

line
optional, default=ComponentRefLine~GenericObject

The style of the line

label
optional, default=ComponentRefLine~LineLabel

The label style of the line

ComponentRefLineLineLabel

object

Properties

padding
default=5
number

Padding inside the label

text
optional, default=''
string

Text

fontSize
optional, default='12px'
string

Font size

fontFamily
optional, default='Arial'
string

Font family

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

opacity
optional, default=1
number

Opacity

align
optional
number | string

Alignment property left to right (0 = left, 1 = right). Also supports string ('left', 'center', 'middle', 'right')

vAlign
optional
number | string

Alignment property top to bottom (0 = top, 1 = bottom). Also supports string ('top', 'center', 'middle', 'bottom')

maxWidth
optional, default=1
number

The maximum relative width to the width of the rendering area (see maxWidthPx as well)

maxWidthPx
optional, default=9999
number

The maximum width in pixels. Labels will be rendered with the maximum size of the smallest value of maxWidth and maxWidthPx size, so you may specify maxWidth 0.8 but maxWidthPx 100 and will never be over 100px and never over 80% of the renderable area

background
optional, default=ComponentRefLine~LineLabelBackground

The background style (rect behind text)

showValue
optional, default=true
boolean

Show value label

ComponentRefLineLineLabelBackground

object

Properties

fill
optional, default='#fff'
string

Fill color

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

opacity
optional, default=0.5
number

Opacity

ComponentSettings

interface

Generic settings available to all components

Properties

type
string

Component type (ex: axis, point, ...)

brush
optional

Brush settings

layout
optional

Layout settings

show
optional, default=true
boolean

If the component should be rendered

scale
optional
string

Named scale. Will be provided to the component if it asks for it.

formatter
optional
string

Named formatter. Fallback to create formatter from scale. Will be provided to the component if it asks for it.

components
experimental
optional

Optional list of child components

strategy

Layout strategy used for child components.

data

Extracted data that should be available to the component

rendererSettings
experimental
optional

Settings for the renderer used to render the component

ComponentSettingspreferredSize

function

Function returning the preferred size

ComponentSettingscreated

function

Called when the component has been created

ComponentSettingsbeforeMount

function

Called before the component has been mounted

ComponentSettingsmounted

function

Called after the component has been mounted

ComponentSettingsbeforeUpdate

function

Called before the component has been updated

ComponentSettingsupdated

function

Called after the component has been updated

ComponentSettingsbeforeRender

function

Called before the component has been rendered

ComponentSettingsbeforeDestroy

function

Called before the component has been destroyed

ComponentSettingsdestroyed

function

Called after the component has been destroyed

ComponentText

object

Properties

text
string | function

Text to display

settings

No description

{
 type: 'text',
 text: 'my title',
 dock: 'left',
 settings: {
   anchor: 'left',
 }
}

ComponentTooltip

object

Properties

settings

No description

type
default='tooltip'
string

No description

picasso.chart({
  settings: {
    interactions: [{
      type: 'native',
      events: {
        mousemove(e) {
          const tooltip = this.chart.component('<tooltip-key>');
          tooltip.emit('show', e);
        },
        mouseleave(e) {
          const tooltip = this.chart.component('<tooltip-key>');
          tooltip.emit('hide');
        }
      }
    }],
    components: [
      {
        key: '<tooltip-key>',
        type: 'tooltip'
      }
    ]
  },
  ...
});

customLayoutFunction(rect, components)

function

Parameters

rect

No description

components

No description

DataExtraction

object

Used to extract data from a DataSource

Properties

extract

Data extraction definition. Define how and what kind of data should be extracted from a DataSource.

stack
optional

If provided, defines how the data should be stacked

{
  extract: [{
    source: 'Products',
    field: 'Product',
    value: d => d.name,
    label: d => `<${d.name}>`
    props: {
      year: { field: 'Year' }
      num: { field: 'Sales' }
    }
  }],
  filter: d => d.label !== 'Sneakers', // extract everything except Sneakers
  sort: (a, b) => a.label > b.label ? -1 : 1, // sort descending
}

DataExtractionfilter(datum)

FilterCallback

Callback function to filter the extracted data items

Parameters

datum

The extracted datum

Returns

boolean

Return true if the datum should be included in the final data set

DataExtractionsort(a, b)

SortCallback

Callback function to sort the extracted data items

Parameters

a

The extracted datum

b

The extracted datum

Returns

number

If less than 0, sort a before b. If greater than 0, sort b before a

DataExtractionExtract

object

Data extraction definition. Define how and what kind of data should be extracted from a DataSource.

Properties

source
string

Which data source to extract from

field
string

The field to extract data from

value
optional
ValueFn | string | number | boolean

The field value accessor

label
optional
LabelFn | string | number | boolean

The field label accessor

reduce
optional
ReduceFn | string

Reducer function

reduceLabel
optional
ReduceLabelFn | string

Label reducer function

props
optional

Additional properties to add to the extracted item

{
    source: 'Products',
    field: 'Product',
    value: (val) => val,
    label: (val) => `<${val}>`
    props: {
      year: { field: 'Year' }
      num: { field: 'Sales' }
    }
  }

ExtracttrackBy(cell)

TrackByFn

TrackBy callback function

Parameters

cell
any

The field cell

Returns

any

No description

Extractfilter(cell)

FilterFn

Filter callback function

Parameters

cell
any

The field cell

Returns

boolean

No description

ExtractFilterFn(cell)

function

Filter callback function

Parameters

cell
any

The field cell

Returns

boolean

No description

ExtractLabelFn(cell)

function

Label callback function

Parameters

cell
any

The field cell

Returns

string

No description

ExtractProps

object

Properties

field
string

The field to extract data from

value
optional
ValueFn | string | number | boolean

The field value accessor

label
optional
LabelFn | string | number | boolean

The field label accessor

{
 field: 'Sales',
 value: (val) => Math.round(val),
 label: (val) => `<${val}>`
}

ExtractReduceFn(values)

function

Reduce callback function

Parameters

values
Array<any>

The collected values to reduce

Returns

any

No description

ExtractReduceLabelFn(labels, value)

function

ReduceLabel callback function

Parameters

labels
Array<any>

The collected labels to reduce

value
any

Reduced value

Returns

string

No description

ExtractTrackByFn(cell)

function

TrackBy callback function

Parameters

cell
any

The field cell

Returns

any

No description

ExtractValueFn(cell)

function

Value callback function

Parameters

cell
any

The field cell

Returns

any

No description

DataExtractionFilterCallback(datum)

function

Callback function to filter the extracted data items

Parameters

datum

The extracted datum

Returns

boolean

Return true if the datum should be included in the final data set

DataExtractionSortCallback(a, b)

function

Callback function to sort the extracted data items

Parameters

a

The extracted datum

b

The extracted datum

Returns

number

If less than 0, sort a before b. If greater than 0, sort b before a

DataExtractionStackKeyCallback(datum)

function

Callback function. Should return the key to stack by

Parameters

datum

The extracted datum

Returns

any

The data value to stack by

DataExtractionStackValueCallback(datum)

function

Callback function. Should return the data value to stack with

Parameters

datum

The extracted datum

Returns

any

The data value to stack with

DataFieldExtraction

object

Properties

source
string

Which data source to extract from

field
string

The field to extract data from

value
optional
ValueFn | string | number | boolean

The field value accessor

label
optional
LabelFn | string | number | boolean

The field label accessor

{
 source: 'Products',
 field: 'Sales',
 value: (val) => Math.round(val),
 label: (val) => `<${val}>`
}

Dataset()

interface

Datasetextract(config)

function

Extract data items from this dataset

Parameters

config

No description

Returns

No description

Datasetfield(query)

function

Find a field within this dataset

Parameters

query
string

The field to find

Returns

No description

Datasetfields()

function

Get all fields within this dataset

Returns

No description

Datasethierarchy()

function

Returns

null

No description

Datasetkey()

function

Get the key identifying this dataset

Returns

string

No description

Datasetraw()

function

Get the raw data

Returns

any

No description

DataSource

object

Properties

key
string

Unique identifier for this data source

type
string

The dataset type

data
any

Data

datumAccessor(d)

function

Callback function

Parameters

d

datum

(d) => Math.min(0, d.value);

DatumBoolean

Custom type that is either a boolean, DatumConfig or a datumAccessor

DatumConfig

object

Properties

scale
optional
string

Name of a scale

ref
optional
string

A reference to a DatumExtract property

// Implicitly resolve the datum by passing a referenced data through the scale
{
 scale: '<name-of-scale>',
 ref: '<data-property>'
}

// or explicitly resolve the datum using callback function
{
 fn: (d) => Math.min(0, d.datum.x.value);
}

DatumConfigfn(d)

datumAccessor

Callback function

Parameters

d

datum

(d) => Math.min(0, d.value);

DatumExtract

object

Properties

value
any

The extracted value

label
string

The extracted value as a string

source

The data source of the extracted data

DatumNumber

Custom type that is either a number, DatumConfig or a datumAccessor

DatumString

Custom type that is either a string, DatumConfig or a datumAccessor

DockLayoutSettings

object

Dock layout settings

Properties

logicalSize
optional

Logical size

center
optional

Define how much space the center dock area requires

layoutModes
optional

Dictionary with named sizes

size
optional

Size is equal to that of the container (element) of the chart by default. It's possible to overwrite it by explicitly setting width or height

DockLayoutSettingsLayoutMode

object

Properties

width
number

No description

height
number

No description

Field

object

Fieldformatter()

function

Returns a formatter adapted to the content of this field.

Fieldid()

function

Returns this field's id

Returns

string

No description

Fielditems()

function

Returns the values of this field.

Returns

No description

Fieldkey()

function

Returns this field's key

Returns

string

No description

Fieldmax()

function

Returns the max value of this field.

Returns

number

No description

Fieldmin()

function

Returns the min value of this field.

Returns

number

No description

Fieldraw()

function

Returns the input data

Returns

any

No description

Fieldtags()

function

Returns the tags.

Returns

Array<string>

No description

Fieldtitle()

function

Returns this field's title.

Returns

string

No description

Fieldtype()

function

Returns this field's type: 'dimension' or 'measure'.

Returns

string

No description

formatter()

function

Returns

any

Returns a formatted value

FormatterDefinition

object

Properties

formatter
optional
string

Name of the formatter

type
optional
string

Type of formatter

format
optional
string

Format string

data

The data to create formatter from

Geopolygon

object

Properties

polygons

Array of polygons

Interaction

object

Interaction instance

Properties

key
string

Interaction identifier

Interactionon

function

Enable interaction

Interactionoff

function

Disable interaction

Interactiondestroy

function

Destroy interaction

InteractionSettings

interface

Properties

type
string

Type of interaction handler

key
optional
string

Unique key identifying the handler

enable
function | boolean

Enable or disable the interaction handler. If a callback function is provided, it must return either true or false

{
 type: 'native',
 key: 'nativeHandler',
 enable: () => true,
 events: { // "events" is a property specific to the native handler
   mousemove: (e) => console.log('mousemove', e),
 }
}

Line

object

Properties

x1
number

Start x-coordinate

y1
number

Start y-coordinate

x2
number

End x-coordinate

y2
number

End y-coordinate

Path

object

Properties

d
string

Path definition

plugin(registries, options)

function

Callback function to register a plugin

Parameters

registries

No description

options
object

No description

Point

object

Properties

x
number

X-coordinate

y
number

Y-coordinate

Polygon

object

Properties

points

Array of connected points

Polyline

object

Properties

points

Array of connected points

Rect

object

Properties

x
number

X-coordinate

y
number

Y-coordinate

width
number

Width

height
number

Height

Registries

object

Registriescomponent(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

Registriesdata(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

Registriesformatter(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

Registriesinteraction(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

Registriesrenderer(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

Registriesscale(key, value?)

registry

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

registry(key, value?)

function

Register a value with the given key. If value is omitted, returns the value of key.

Parameters

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returns

any

Registered value

Renderer()

interface

RendererappendTo(element)

function

Parameters

element
HTMLElement

Element to attach renderer to

Returns

HTMLElement

Root element of the renderer

Rendererclear()

function

Clear all child elements from the renderer root element

Returns

The renderer instance

Rendererdestory()

function

Remove the renderer root element from its parent element

Rendererelement()

function

Get the element this renderer is attached to

Returns

HTMLElement

No description

RendererfindShapes(selector)

function

Get all nodes matching the provided selector

Parameters

selector
string

CSS selector [type, attribute, universal, class]

Returns

Array of objects containing matching nodes

RendereritemsAt(geometry)

function

Get nodes renderer at area

Parameters

geometry

Get nodes that intersects with geometry

Returns

No description

RenderermeasureText(opts)

function

Parameters

opts

No description

Returns

object

Width and height of text

measureText({
 text: 'my text',
 fontSize: '12px',
 fontFamily: 'Arial'
}); // returns { width: 20, height: 12 }

Rendererrender(nodes)

function

Parameters

nodes
Array<object>

Nodes to render

Returns

boolean

True if the nodes were rendered, otherwise false

Rendererroot()

function

Get the root element of the renderer

Returns

HTMLElement

No description

Renderersettings(settings?)

function

Set or Get renderer settings

Parameters

settings
optional
object

Settings for the renderer

Renderersize(opts?)

function

Set or Get the size definition of the renderer container.

Parameters

opts

Size definition

Returns

The current size definition

RendererSizeDefinition

object

Properties

x
optional
number

x-coordinate

y
optional
number

y-coordinate

width
optional
number

Width

height
optional
number

Height

scaleRatio
optional

No description

margin
optional

No description

RendererSettings

object
experimental

Properties

canvasBufferSize
experimental
optional
function | object

An object containing width and height of the canvas buffer or a function returning an object on that format. Gets a rect object as input parameter.

RendererSettingstransform()

TransformFunction
experimental

Should return a transform object if transformation should be applied, otherwise undefined or a falsy value. Transforms can be applied with the canvas, svg and dom renderer. Transform is applied when running chart.update, see example. !Important: When a transform is applied to a component, the underlaying node representations are not updated with the new positions/sizes, which can cause problems for operations that relies on the positioning of the shapes/nodes (such as tooltips, selections etc). An extra chart update without a transform is therefore needed to make sure the node position information is in sync with the visual representation again.

Returns

A format to represent a transformation.

const pointComponentDef = {
  type: 'point',
  rendererSettings: {
    tranform() {
      if(shouldApplyTransform) {
        return {
          horizontalScaling: 1,
          horizontalSkewing: 0,
          verticalSkewing: 0,
          verticalScaling: 1,
          horizontalMoving: x,
          verticalMoving: y
        };
      }
    }
  }
  data: {
// ............

chart.update({ partialData: true });

RendererSettingsCanvasBufferSize

experimental

An object containing width and height of the canvas buffer or a function returning an object on that format. Gets a rect object as input parameter.

RendererSettingsTransformFunction()

function
experimental

Should return a transform object if transformation should be applied, otherwise undefined or a falsy value. Transforms can be applied with the canvas, svg and dom renderer. Transform is applied when running chart.update, see example. !Important: When a transform is applied to a component, the underlaying node representations are not updated with the new positions/sizes, which can cause problems for operations that relies on the positioning of the shapes/nodes (such as tooltips, selections etc). An extra chart update without a transform is therefore needed to make sure the node position information is in sync with the visual representation again.

Returns

A format to represent a transformation.

const pointComponentDef = {
  type: 'point',
  rendererSettings: {
    tranform() {
      if(shouldApplyTransform) {
        return {
          horizontalScaling: 1,
          horizontalSkewing: 0,
          verticalSkewing: 0,
          verticalScaling: 1,
          horizontalMoving: x,
          verticalMoving: y
        };
      }
    }
  }
  data: {
// ............

chart.update({ partialData: true });

Scale

interface

Scale instance

Properties

type
string

Type of scale

ScaleBand

object

Properties

type
optional, default='band'
string

No description

padding
optional
number

Sets both inner and outer padding to the same value

paddingInner
optional
number

Inner padding

paddingOuter
optional
number

Outer padding

align
optional, default=0.5
number

Control how the outer padding should be distributed, where 0.5 would distribute the padding equally on both sides

invert
optional
boolean

Invert the output range

maxPxStep
optional
number

Explicitly limit the bandwidth to a pixel value

range
optional, default=[0, 1]
array | function

Set range explicitly (ignored when maxPxStep takes effect)

ScaleBandlabel

function

Callback label function, applied on each datum

ScaleBandvalue

function

Callback value function, applied on each datum

ScaleCategoricalColor

object

Properties

type
optional, default='categorical-color'
string

No description

range
optional
Array<string>

CSS color values of the output range

unknown
optional
string

Value to return when input value is unknown

explicit
optional

Explicitly bind values to an output

ScaleDefinition

object

Definition for creating a scale. Additional properties, specific for a type of scale, can be added as key/value pairs

Properties

type
optional
string

Type of scale

data

Data configuration

ScaleLinear

object

Properties

type
optional, default='linear'
string

No description

expand
optional
number

Expand the output range

invert
optional
boolean

Invert the output range

include
optional
Array<number>

Include specified numbers in the output range

ticks
optional

No description

minorTicks
optional

No description

min
optional
number

Set an explicit minimum value

max
optional
number

Set an explicit maximum value

ScaleSequentialColor

object

Properties

type
optional, default='sequential-color'
string

No description

range
optional
Array<string>

CSS color values of the output range

invert
optional
boolean

Invert range

min
optional
number

Set an explicit minimum value

max
optional
number

Set an explicit maximum value

ScaleThresholdColor

object

Properties

type
optional, default='threshold-color'
string

No description

domain
optional
Array<number>

Values defining the thresholds

range
optional
Array<string>

CSS color values of the output range

invert
optional
boolean

Invert range

min
optional
number

Set an explicit minimum value

max
optional
number

Set an explicit maximum value

nice
optional
boolean

If set to true, will generate 'nice' domain values. Ignored if domain is set.

new SceneNode()

class

Read-only object representing a node on the scene.

Properties

attrs
object

Node attributes

bounds

Bounding rectangle of the node. After any transform has been applied, if any, but excluding scaling transform related to devicePixelRatio. Origin is in the top-left corner of the scene element.

children
Array<SceneNode>

Get child nodes

collider

Collider of the node. Transform on the node has been applied to the collider shape, if any, but excluding scaling transform related to devicePixelRatio. Origin is in the top-left corner of the scene element.

If node has no collider, null is returned.

data
any

Get the associated data

desc
object

Node description

element
HTMLElement

Element the scene is attached to

key
string

Key of the component this shape belongs to

localBounds

Bounding rectangle of the node within its local coordinate system. Origin is in the top-left corner of the scene element.

parent

Get parent node

tag
string

Node tag

type
string

Node type

SceneNodeboundsRelativeTo(target, includeTransform)

function

Bounding rectangle of the node, relative a target.

If target is an HTMLElement, the bounds are relative to the HTMLElement. Any other target type will return the bounds relative to the viewport of the browser.

Parameters

target
HTMLElement | any

No description

includeTransform
default=true
boolean

Whether to include any applied transforms on the node

Returns

No description

node.boundsRelativeTo($('div'));
node.boundsRelativeTo('viewport');

svgRendererFactory(treeFactory?, ns?, sceneFn?)

function

Create a new svg renderer

Parameters

treeFactory
optional
function

Node tree factory

ns
optional
string

Namespace definition

sceneFn
optional
function

Scene factory

Returns

A svg renderer instance

TransformObject

object

A format to represent a transformation.

Properties

horizontalScaling
number

No description

horizontalSkewing
number

No description

verticalSkewing
number

No description

verticalScaling
number

No description

horizontalMoving
number

No description

verticalMoving
number

No description

Was this page helpful?