API Reference
Namespaces
Classes
Events
Global
Externals

Class: TimeSpanEventPanel

CIQ. TimeSpanEventPanel

new TimeSpanEventPanel(params)

The time span events panel that contains and displays all the time span events created by the user.

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

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Argument Description
stx CIQ.ChartEngine

The chart object.
height number

The static height of the time span events panel in pixels. If this parameter is set, the panel remains at the specified height regardless of the number of event swim lanes in the panel. If this parameter is not set, the height of the panel is calculated based on the number of swim lanes and the swim lane spacing specified in params.customConstants and the plugins/timespanevent/constants.js file.
context CIQ.UI.Context <optional>

The chart user interface context. Note: Required when CIQ.UI is non-null.
menuItemSelector string <optional>

The CSS selector used to identify menu items for selecting time span events.
loadSample boolean <optional>

If true, load the built-in time span events sample.
infoPanel object <optional>

Specifies the panel where pop-up displays appear when a marker is selected. Can also specify that a pop-up display should not appear. Pop-up displays contain information about time span events or sub-events. The value of the object properties — spanEvent, durationEvent, and singleEvent (see below) — must be "panel" or "main" for the displays to appear in the time span events panel or main chart area, respectively. To prevent pop-up displays from appearing, omit the spanEvent, durationEvent, or singleEvent property or set the property value to null or a string other than "panel" or "main". Note: The properties of this object are overridden by the infoPanel property of swim lane data objects passed to the CIQ.TimeSpanEventPanel#showTimeSpanEvent function.

Properties
Name Type Argument Description
spanEvent string <optional>

Location for span event pop-up displays.
durationEvent string <optional>

Location for duration event pop-up displays.
singleEvent string <optional>

Location for single event pop-up displays.
showTooltip boolean <optional>

If true, shows a tooltip on hover over a span event or single event marker.
customConstants object <optional>

Modifies the values of the constants in plugins/timespanevent/constants.js or establishes new time span event constants. The object properties can be the names of constants in constants.js or new constant names. If the name of a property in this object matches the name of a constant in constant.js, the value of the constant is overwritten by the property value. If a property name in this object does not match the name of a constant in constant.js, a new time span event constant is created. The new constant is assigned the property value. See example below.
cb function <optional>

Callback function to execute upon completion of this constructor.
alwaysZoom boolean <optional>

Sets the alwaysZoom property.
Since:
  • 7.2.0
  • 8.0.0 Added params.customConstants, params.cb, params.infoPanel, params.showTooltip, and params.alwaysZoom. Added the alwaysZoom property.
Example

Declare a time span event panel and enable/disable using commands to be triggered from a menu.

var stxx = new CIQ.ChartEngine({ container: document.querySelector(".chartContainer") });

// Instantiate the time span event panel.
new CIQ.TimeSpanEventPanel({
	stx: stxx,
	infoPanel: {
		durationEvent: "main",
		spanEvent: "panel",
		singleEvent: null,
	},
	customConstants: {
		SPACING: 35,
		RECT_HEIGHT: 25,
		RADIUS_DEFAULT: 13,
		RADIUS_HIGHLIGHT: 16,
		MY_NEW_CONSTANT: 99,
	},
});

// To display the panel from a menu, use:
stxx.layout.timeSpanEventPanel = true; // Show the panel.
stxx.changeOccurred("layout"); // Signal the change to force a redraw.

// To hide the panel from a menu, use:
stxx.layout.timeSpanEventPanel = false; // Hide the panel.
stxx.changeOccurred("layout"); // Signal the change to force a redraw.

Members

alwaysZoom

Enables event zoom on any time span event regardless of whether the event has sub-children.

Note: Individual event markers can set their own alwaysZoom property for more granular control (see CIQ.Marker.TimeSpanEvent). If a marker sets its alwaysZoom property to false, the marker's property takes precedence, and the marker zooms only if it has sub-children.

Since:

  • 8.0.0

Default Value:
  • true

Methods

calculatePanelHeight(lanes)

Helper function used to dynamically calculate the height of the time span events panel based on the number of swim lanes.

Parameters:
Name Type Description
lanes number

The number of swim lanes to be rendered in the panel.
Since:

  • 8.0.0

Returns:

The panel height in pixels.

Type
number

calculateSpacingModifier(index)

Helper function used to calculate the spacingModifier for a swim lane (see the spanEvent parameters of renderTimeSpanEvent).

Parameters:
Name Type Description
index number

The index of the swim lane for which the spacing modifier is calculated. Swim lanes are indexed from top to bottom in the time span events panel, starting with index zero.
Since:

  • 8.0.0

Returns:

The number of pixels of the spacing modifier.

Type
number

checkSetPanelHeight()

Helper function used to check and set the required height of the time span events panel.

Typically called when the chart is resized, the layout changes, or a swim lane is added or removed from the time span events panel.

Does nothing if the params.height parameter is provided to the CIQ.TimeSpanEventPanel constructor function.

Since:

  • 8.0.0

createEventDetailPanel()

Creates the information pop-up display that appears when a time span event marker is selected.

Parameters:
Name Type Description
params.stx CIQ.ChartEngine

The chart object to which the pop-up display is added.
Since:

  • 8.0.0

display(on)

Creates and displays the panel or destroys the panel depending on the state.

Parameters:
Name Type Description
on Boolean

State Boolean that determines whether to show or destroy the panel; true = display, false = destroy.
Since:

  • 7.2.0

removeChartArtifacts(type)

Helper function to remove all the injection and markers from the main chart.

Parameters:
Name Type Description
type string

The type of marker that needs its injections and markers removed.
Since:

  • 7.2.0

removeTimeSpanEvent(type)

Removes time span events from the panel.

Parameters:
Name Type Description
type string

The type of time span events to remove from the panel; for example, "News" or "CEO". See the spanEvent.type property in showTimeSpanEvent.
Since:

  • 7.2.0

renderTimeSpanEvent(spanEvents)

Creates time span event markers.

Parameters:
Name Type Description
spanEvents object

Defines a swim lane (horizontal row) of time span events.

Properties
Name Type Argument Description
type string

Identifies the swim lane and the type of events contained in the swim lane; for example, "News" or "CEO". Values are implementation specific.
events Array.<object>

An array of objects that define the individual time span events that appear in the swim lane.
spanType string

Categorizes the time span events contained in the swim lane. Must be one of the following: "spanEvent", "durationEvent", or "singleEvent".
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.
spacingModifier number

Specifies the amount of space between time span event swim lanes.
Since:
  • 7.2.0
  • 8.0.0 Added the infoPanel parameter.

showEventDetail(marker, panel, cx)

Sets the position and shows or hides the information pop-up display for a time span event marker.

Parameters:
Name Type Description
marker object

The selected time span event marker for which the pop-up display is shown or hidden.
panel object

The panel containing the selected marker.
cx number

The x-axis coordinate used to calculate the position of the left edge of the pop-up display for a spanEvent type marker.
Since:

  • 8.0.0

Returns:

true, if the function has processed and responded to selection of a singleEvent type marker.

Type
boolean

showTimeSpanEvent(spanEvent [, preLoad])

Displays time span events in the panel.

Parameters:
Name Type Argument Description
spanEvent object

Defines a swim lane (horizontal row) of time span events.

Properties
Name Type Argument Description
type string

Identifies the swim lane and the type of events contained in the swim lane; for example, "Reports", "Weather", "Filings". Values are implementation specific.
events Array.<object>

An array of objects that define the individual time span events that appear in the swim lane.
spanType string

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

Specifies the panel where information 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 other than "panel" or "main". Note: This parameter overrides the respective value in the infoPanel parameter of CIQ.TimeSpanEventPanel.
preLoad boolean <optional>

If true, the event data already exists, which is the case when time span event data is loaded before the panel is active.
Since:
  • 7.2.0
  • 8.0.0 Added the infoPanel parameter.