API Docs for: 3.8.0
Show:

Axis Class

Defined in: charts/js/Axis.js:1
Module: charts-base
Parent Module: charts

The Axis class. Generates axes for a chart.

Methods

_clearLabelCache

() private

Removes axis labels from the dom and clears the label cache.

_createLabelCache

() private

Creates a cache of labels that can be re-used when the axis redraws.

_dataChangeHandler

(
  • e
)
private

Handles change to the dataProvider

Parameters:

_drawAxis

() private

Draws an axis.

_getDefaultStyles

() protected

Gets the default value for the styles attribute. Overrides base implementation.

Returns:

Object

_getLabelBounds

(
  • Value
)
private

Returns the coordinates (top, right, bottom, left) for the bounding box of a label.

Parameters:

Returns:

Object

_getTextRotationProps

(
  • styles
)
private

Generates the properties necessary for rotating and positioning a text field.

Parameters:

  • styles Object

    properties for the text field

Returns:

Object

_handleSizeChange

(
  • e
)
private

Updates the axis when the size changes.

Parameters:

_positionChangeHandler

(
  • e
)
private

Handles change to the position attribute

Parameters:

_removeChildren

() private

Removes all DOM elements from an HTML element. Used to clear out labels during detruction phase.

_rotate

(
  • label
  • props
)
private

Rotates and positions a text field.

Parameters:

  • label HTMLElement

    text field to rotate and position

  • props Object

    properties to be applied to the text field.

_setCanvas

() private

Creates a graphic instance to be used for the axis line and ticks.

_setText

(
  • label
  • val
)
private

Updates the content of text field. This method writes a value into a text field using appendChild. If the value is a String, it is converted to a TextNode first.

Parameters:

  • label HTMLElement

    label to be updated

  • val String

    value with which to update the label

_setTotalTitleSize

(
  • styles
)
private

Calculates and sets the total size of a title.

Parameters:

  • styles Object

    Properties for the title field.

_simulateTransformOrigin

(
  • matrix
  • rot
  • transformOrigin
  • w
  • h
)
private

Simulates a rotation with a specified transformOrigin.

Parameters:

  • matrix Matrix

    Reference to a Matrix instance.

  • rot Number

    The rotation (in degrees) that will be performed on a matrix.

  • transformOrigin Array

    An array represeniting the origin in which to perform the transform. The first index represents the x origin and the second index represents the y origin.

  • w Number

    The width of the object that will be transformed.

  • h Number

    The height of the object that will be transformed.

_updateGraphic

(
  • position
)
private

Updates the the Graphic instance

Parameters:

  • position String

    Position of axis

_updateHandler

(
  • e
)
private

Handles changes to axis.

Parameters:

_updatePathElement

() private

Updates path.

_updateTitle

() private

Updates the content and style properties for a title field.

destructor

() protected

Destructor implementation Axis class. Removes all labels and the Graphic instance from the widget.

drawLine

(
  • startPoint
  • endPoint
  • line
)
private

Draws a line segment between 2 points

Parameters:

  • startPoint Object

    x and y coordinates for the start point of the line segment

  • endPoint Object

    x and y coordinates for the for the end point of the line segment

  • line Object

    styles (weight, color and alpha to be applied to the line segment)

getFirstPoint

(
  • pt
)
private

Gets the position of the first point on an axis.

Parameters:

  • pt Object

    Object containing x and y coordinates.

Returns:

Object

getLabel

(
  • pt
  • styles
)
private

Creates or updates an axis label.

Parameters:

  • pt Object

    x and y coordinates for the label

  • styles Object

    styles applied to label

Returns:

HTMLElement

getLastPoint

() private

Calculates the placement of last tick on an axis.

Returns:

Object

getLength

() private

Calcuates the width or height of an axis depending on its direction.

Returns:

Number

getLineEnd

() private

Gets the end point of an axis.

Returns:

Object

getMaxLabelBounds

()

Returns the coordinates (top, right, bottom, left) for the bounding box of the last label.

Returns:

Object

getMinLabelBounds

()

Returns the coordinates (top, right, bottom, left) for the bounding box of the first label.

Returns:

Object

getNextPoint

(
  • point
  • majorUnitDistance
)
private

Gets the position of the next point on an axis.

Parameters:

  • point Object

    Object containing x and y coordinates.

  • majorUnitDistance Number

    Distance in pixels between ticks.

Returns:

Object

getPosition

(
  • point
)
private

Calculates position on the axis.

Parameters:

  • point Object

    contains x and y values

renderUI

() private

syncUI

() private

Properties

_calculatedHeight

Number private

Storage for calculatedHeight value.

_calculatedWidth

Number private

Storage for calculatedWidth value.

_layoutClasses

Object private

Maps key values to classes containing layout algorithms

maxLabelSize

Number protected

Length in pixels of largest text bounding box. Used to calculate the height of the axis.

Attributes

appendLabelFunction

Function

Function used to append an axis value to an axis label. This function has the following signature:

textField
The axis label to be appended. (HTMLElement)
val
The value to attach to the text field. This method will accept an HTMLELement or a String. This method does not use (HTMLElement | String)
The default method appends a value to the HTMLElement using the appendChild method. If the given value is a String, the method will convert the the value to a textNode before appending to the HTMLElement. This method will not convert an HTMLString to an HTMLElement.

Fires event appendLabelFunctionChange

Fires when the value for the configuration attribute appendLabelFunction is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

appendTitleFunction

Function

Function used to append a title value to the title object. This function has the following signature:

textField
The title text field to be appended. (HTMLElement)
val
The value to attach to the text field. This method will accept an HTMLELement or a String. This method does not use (HTMLElement | String)
The default method appends a value to the HTMLElement using the appendChild method. If the given value is a String, the method will convert the the value to a textNode before appending to the HTMLElement element. This method will not convert an HTMLString to an HTMLElement.

Fires event appendTitleFunctionChange

Fires when the value for the configuration attribute appendTitleFunction is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

bottomTickOffset

Number

Distance determined by the tick styles used to calculate the distance between the axis line in relation to the bottom of the axis.

Fires event bottomTickOffsetChange

Fires when the value for the configuration attribute bottomTickOffset is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

calculatedHeight

Number private

Calculated value of an axis' height. By default, the value is used internally for horizontal axes. If the height attribute is explicitly set, this value will be ignored.

Fires event calculatedHeightChange

Fires when the value for the configuration attribute calculatedHeight is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

calculatedWidth

Number private

Calculated value of an axis' width. By default, the value is used internally for vertical axes. If the width attribute is explicitly set, this value will be ignored.

Fires event calculatedWidthChange

Fires when the value for the configuration attribute calculatedWidth is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

edgeOffset

Number protected

Difference betweend the first/last tick and edge of axis.

Fires event edgeOffsetChange

Fires when the value for the configuration attribute edgeOffset is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

graphic

Graphic

The graphic in which the axis line and ticks will be rendered.

Fires event graphicChange

Fires when the value for the configuration attribute graphic is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

height

Number

When set, defines the height of a horizontal axis instance. By default, horizontal axes automatically size based on their contents. When the height attribute is set, the axis will not calculate its height. When the height attribute is explicitly set, axis labels will postion themselves off of the the inner edge of the axis and the title, if present, will position itself off of the outer edge. If a specified height is less than the sum of the axis' contents, excess content will overflow.

Fires event heightChange

Fires when the value for the configuration attribute height is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

labelFunction

Function

Method used for formatting a label. This attribute allows for the default label formatting method to overridden. The method use would need to implement the arguments below and return a String or HTMLElement.

val
Label to be formatted. (String)
format
Template for formatting label. (optional)

Fires event labelFunctionChange

Fires when the value for the configuration attribute labelFunction is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

labelFunctionScope

Object

Object which should have by the labelFunction

Fires event labelFunctionScopeChange

Fires when the value for the configuration attribute labelFunctionScope is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

labels

Array

Collection of labels used to render the axis.

Fires event labelsChange

Fires when the value for the configuration attribute labels is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

leftTickOffset

Number

Distance determined by the tick styles used to calculate the distance between the axis line in relation to the left of the axis.

Fires event leftTickOffsetChange

Fires when the value for the configuration attribute leftTickOffset is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

maxLabelSize

Number protected

Length in pixels of largest text bounding box. Used to calculate the height of the axis.

Fires event maxLabelSizeChange

Fires when the value for the configuration attribute maxLabelSize is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

node

HTMLElement

Contains the contents of the axis.

Fires event nodeChange

Fires when the value for the configuration attribute node is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

overlapGraph

Boolean

Indicates whether the axis overlaps the graph. If an axis is the inner most axis on a given position and the tick position is inside or cross, the axis will need to overlap the graph.

Fires event overlapGraphChange

Fires when the value for the configuration attribute overlapGraph is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

path

Shape private readonly

Fires event pathChange

Fires when the value for the configuration attribute path is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

position

String

Direction of the axis.

Fires event positionChange

Fires when the value for the configuration attribute position is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

rightTickOffset

Number

Distance determined by the tick styles used to calculate the distance between the axis line in relation to the right side of the axis.

Fires event rightTickOffsetChange

Fires when the value for the configuration attribute rightTickOffset is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

styles

Object

Style properties used for drawing an axis. This attribute is inherited from Renderer. Below are the default values:

majorTicks
Properties used for drawing ticks.
display
Position of the tick. Possible values are inside, outside, cross and none. The default value is inside.
length
The length (in pixels) of the tick. The default value is 4.
color
The color of the tick. The default value is #dad8c9
weight
Number indicating the width of the tick. The default value is 1.
alpha
Number from 0 to 1 indicating the opacity of the tick. The default value is 1.
line
Properties used for drawing the axis line.
weight
Number indicating the width of the axis line. The default value is 1.
color
The color of the axis line. The default value is #dad8c9.
alpha
Number from 0 to 1 indicating the opacity of the tick. The default value is 1.
majorUnit
Properties used to calculate the majorUnit for the axis.
determinant
The algorithm used for calculating distance between ticks. The possible options are count and distance. If the determinant is count, the axis ticks will spaced so that a specified number of ticks appear on the axis. If the determinant is distance, the axis ticks will spaced out according to the specified distance. The default value is count.
count
Number of ticks to appear on the axis when the determinant is count. The default value is 11.
distance
The distance (in pixels) between ticks when the determinant is distance. The default value is 75.
label
Properties and styles applied to the axis labels.
color
The color of the labels. The default value is #808080.
alpha
Number between 0 and 1 indicating the opacity of the labels. The default value is 1.
fontSize
The font-size of the labels. The default value is 85%
rotation
The rotation, in degrees (between -90 and 90) of the labels. The default value is 0.
margin
The distance between the label and the axis/tick. Depending on the position of the Axis, only one of the properties used.
top
Pixel value used for an axis with a position of bottom. The default value is 4.
right
Pixel value used for an axis with a position of left. The default value is 4.
bottom
Pixel value used for an axis with a position of top. The default value is 4.
left
Pixel value used for an axis with a position of right. The default value is 4.

Fires event stylesChange

Fires when the value for the configuration attribute styles is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

tickPath

Shape private readonly

Fires event tickPathChange

Fires when the value for the configuration attribute tickPath is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

tickPoints

Array

Collection of points used for placement of labels and ticks along the axis.

Fires event tickPointsChange

Fires when the value for the configuration attribute tickPoints is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

title

String

Title for the axis. When specified, the title will display. The position of the title is determined by the axis position.

top
Appears above the axis and it labels. The default rotation is 0.
right
Appears to the right of the axis and its labels. The default rotation is 90.
bottom
Appears below the axis and its labels. The default rotation is 0.
left
Appears to the left of the axis and its labels. The default rotation is -90.

Fires event titleChange

Fires when the value for the configuration attribute title is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

topTickOffset

Number

Distance determined by the tick styles used to calculate the distance between the axis line in relation to the top of the axis.

Fires event topTickOffsetChange

Fires when the value for the configuration attribute topTickOffset is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

width

Number

When set, defines the width of a vertical axis instance. By default, vertical axes automatically size based on their contents. When the width attribute is set, the axis will not calculate its width. When the width attribute is explicitly set, axis labels will postion themselves off of the the inner edge of the axis and the title, if present, will position itself off of the outer edge. If a specified width is less than the sum of the axis' contents, excess content will overflow.

Fires event widthChange

Fires when the value for the configuration attribute width is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.