API Reference
Namespaces
Classes
Events
Global
Externals

Class: TimeSpanEvent

CIQ.Marker. TimeSpanEvent

new TimeSpanEvent(params)

Creates a time span event marker.

Note: Time span events are also known as life cycle events.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Argument Default Description
stx CIQ.ChartEngine

The chart engine.
alwaysZoom boolean <optional>

When true, the marker can trigger event zoom (see toggleEventZoom) regardless of whether it has sub-children. Overrides the property of the same name in CIQ.TimeSpanEventPanel.
label string

Indicates the category of the event represented by the marker; for example, "News" or "Filing". Also provides the text displayed on the y-axis to identify the swim lane that contains the marker.
spanType string

Categorizes the time span events contained in the swim lane. Must be one of the following: "spanEvent", "durationEvent", or "singleEvent".
xPositioner string <optional>
 "date"

Determines the x-axis position of the marker. Please refer to CIQ.Marker for other values.
yPositioner string <optional>
 "value"

Determines the y-axis position of the marker. Please refer to CIQ.Marker for other values.
infoPanel string <optional>

Specifies the panel where pop-up displays appear when a marker is selected. Must be "panel" or "main" for the pop-up displays to appear in the time span events panel or main chart area, respectively. To prevent pop-up displays from appearing, set the value to null or a string that is not "panel" or "main". Note: This parameter overrides the respective value in the infoPanel parameter of CIQ.TimeSpanEventPanel.
panelName string

The name of the time span event panel.
datum object

Configuration parameters that encapsulate all the marker properties.

Properties
Name Type Argument Description
startDate Date

The date on which the time span event begins.
endDate Date

The date on which the time span event ends.
spanLabel string

Text displayed on the time span event marker to identify the event. Also appears as the heading in the event marker pop-up display if the headline parameter is not provided.
spacing number

The number of pixels to place between rows of time span event markers.
spacingModifier number

The number of pixels to offset the time span event marker from the top of the Time Span Event panel's y-axis.
bgColor string <optional>

The background color of the marker.
textColor string <optional>

The color of the spanLabel text when the span label appears on the marker (as opposed to in the marker pop-up display).
subChildren Array.<object> <optional>

An array of objects that define sub-events within the time span event represented by this marker.
headline string <optional>

The heading that appears in a pop-up display when the marker is selected.
story string <optional>

The body text that appears in a pop-up display when the marker is selected.
img string <optional>

The file name and path of a png, jpeg, or other image file. The file name and path are set as the value of the src property of an image object which provides the visual depiction of the event. Note: The file path must start from within the chartiq library folder; for example plugins/timespanevent/images/alert.png.
isActive boolean <optional>

Indicates whether the event is ongoing; that is, has not yet finished. Typically, only one event in a swim lane is active.
showPriceLines boolean <optional>

Specifies whether to draw price lines on the main chart from the first and last sub-child of the event represented by this marker to the y-axis, pointing out the values related to those sub-events.
eventZoomPeriodicity CIQ.ChartEngine~PeriodicityParameters <optional>

The periodicity of the event zoom date range. See toggleEventZoom.
Since:
  • 7.2.0
  • 7.3.0 Added the img, isActive, and showPriceLines parameters.
  • 8.0.0 Added the alwaysZoom and eventZoomPeriodicity parameters.

Classes

Group
GroupNode

Methods

click(params)

Called when a time span event marker is selected.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Description
cx number

The x-axis coordinate of the selection event.
cy number

The y-axis coordinate of the selection event.
panel object

The panel where the marker was selected.
Since:
  • 7.2.0
  • 8.0.0 Signature changed to accept the params object.

doubleClick(params)

Toggles the event zoom of a time span event marker.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Description
x number

The clientX value of the doubleClick event.
y number

The clientY value of the doubleClick event.
panel CIQ.ChartEngine.Panel

The panel in which the doubleClick event occurred.
Since:

  • 8.0.0

drawOnChart(params)

Draws the shaded area and x-axis labels when a time span event marker is activated.

Parameters:
Name Type Description
params object

Necessary information to draw.

Properties
Name Type Description
pixelLeft number

X-coordinate of the start date.
pixelRight number

X-coordinate of the end date.
startDate Date

Start date of the time span event, used for the x-axis label.
endDate Date

End date of the time span event, used for the x-axis label.
color string

Color value to fill/stroke the time span event shape.
firstPrice number

The first price in the event data. Setting this value causes a price line to be drawn if showPriceLines is set to true.
lastPrice number

The last price in the event data. Setting this value causes a price line to be drawn if showPriceLines is set to true.
showPriceLines string

A boolean that determines whether to draw price lines on the main chart.
Since:
  • 7.2.0
  • 7.3.0 Added firstPrice, lastPrice, and showPriceLines parameters.

drawSelected(params)

Draws the highlights when hovering or activating a time span event.

Parameters:
Name Type Description
params object

Necessary information to draw.

Properties
Name Type Description
pixelLeft number

X-coordinate of the start date.
pixelRight number

X-coordinate of the end date.
yPixel number

Y-coordinate at which the time span event is located.
color string

Color value to fill/stroke the time span event shape.
Since:

  • 7.2.0

drawSingleOrDurationEvent(spanEvent)

Draws a single or duration event in the time span events panel. Duration events have sub-event data.

Parameters:
Name Type Description
spanEvent object

The object that represents the time span event.
Since:

  • 7.2.0

drawSpanEvent(spanEvent)

Draws a span event in the time span events panel.

Parameters:
Name Type Description
spanEvent object

The object that represents the time span event.
Since:

  • 7.2.0

placeLabelOnYAxis(spanEvent)

Places a time span event label on the time span events panel y-axis.

Parameters:
Name Type Description
spanEvent object

The object that represents the time span event.
Since:

  • 7.2.0

positionTooltip(parameter)

Positions the marker's tooltip node in panel.

Parameters:
Name Type Description
parameter object

Contains the function parameters.

Properties
Name Type Description
chartLeftPX number

The leftmost pixel of the chart.
panel CIQ.ChartEngine.Panel

Panel in which the tooltip is located.
yPixel number

The y-axis coordinate of the tooltip.
Since:

  • 8.0.0

toggleEventZoom(active [, periodicity])

Zooms and un-zooms the display of the time span event marker's date range.

The date range is based on the sub-children of the time span event. The first and last sub-children become the dtLeft and dtRight values, respectively, in a call to CIQ.ChartEngine#setRange, which sets the date range of the chart.

The periodicity of the zoomed date range is set by one of the following (in order of precedence):

  1. Periodicity supplied by the event marker's eventZoomPeriodicity property (see CIQ.Marker.TimeSpanEvent)
  2. The periodicity argument of this function
  3. The default periodicity calculations of CIQ.ChartEngine#setRange
Parameters:
Name Type Argument Description
active boolean

Toggles the event zoom on or off.
periodicity CIQ.ChartEngine~PeriodicityParameters <optional>

Sets the periodicity of the zoomed date range if the marker does not provide a value in its eventZoomPeriodicity property.
Since:

  • 8.0.0

<static> createSpanDateObject(dataSegment, startDate, endDate)

Helper function to ensure the data is only drawn on the visible chart and whether an indicator is needed to show the event continues.

Parameters:
Name Type Description
dataSegment object

The stx.chart.dataSegment.
startDate Date

When the span event actually begins.
endDate Date

When the span event actually ends.
Since:

  • 7.2.0

Returns:

An object that contains the start and end dates to draw and a boolean to determine whether an indicator needs to be drawn on the span event.

Type
object

<static> placementFunction(params)

Determines the placement of time span events.

Parameters:
Name Type Description
params object

Parameters passed from the Marker render function.

Properties
Name Type Description
stx CIQ.ChartEngine

A reference to the chart engine.
panel object

The panel where the marker is being placed.
Since:

  • 7.2.0

<static> truncateString(ctx, string, maxWidth)

Helper function to take a string that is too long and add an ellipsis on the end of the string.

Parameters:
Name Type Description
ctx external:CanvasRenderingContext2D

The canvas context.
string string

The string that needs to be truncated.
maxWidth number

The width that the string needs to fit into.
Since:

  • 7.2.0

Returns:

The truncated string.

Type
string