API Reference
Namespaces
Classes
Events
Global
Externals

Class: Marker

CIQ. Marker


new Marker(params)

A marker is a DOM object that is managed by the chart.

Makers are placed in containers which are div elements whose placement and size correspond with a panel on the chart. A container exists for each panel.

A marker's primary purpose is to provide additional information for a data point on the chart. As such, markers can be placed by date, tick, or bar to control their position on the x-axis, and by value (price) to control their position on the y-axis. Additional default positioning is also available, including the ability to create custom positioning logic. Once the positioning logic is established for markers, they are repositioned as needed when the user scrolls or zooms the chart.

Alternatively, a marker can also be placed at an absolute position using CSS positioning, in which case the chart does not control the marker's positioning.

The default placement function for any markers is CIQ.ChartEngine#defaultMarkerPlacement.

See the Markers tutorial for additional implementation details and information about managing performance on deployments requiring a large number of markers.

Parameters:
Name Type Description
params Object

Parameters that describe the marker.

Properties
Name Type Argument Default Description
stx CIQ.ChartEngine

The chart to which the marker is attached.

x *

A valid date, tick, or bar (depending on the selected xPositioner) used to select a candle to which the marker is associated.

y Number <optional>

A valid value for positioning the marker on the y-axis (depending on selected yPositioner). If this value is not provided, the marker is set "above_candle" as long as a valid candle is selected by params.x.

node HTMLElement | CIQ.Marker.Simple | CIQ.Marker.Performance <optional>

The HTML element that contains the marker. This element should be detached from the DOM. If an element is not provided, an empty div is created. You can create your own or use the provided CIQ.Marker.Simple and CIQ.Marker.Performance node creators.

panelName string <optional>
"chart"

The name of the panel to which the node is attached. Defaults to the main chart panel.

xPositioner string <optional>
"date"

Determines the x-axis position of the marker. Values include:

  • "date" — params.x must be set to a JavaScript date object. This will be converted to the closest masterData position if the provided date does not exactly match any existing points. Be sure the same timezone as masterData is used.
  • "master" — params.x must be set to a masterData position.
  • "tick" — params.x must be set to a dataSet position.
  • "bar" — params.x must be set to a dataSegment position.
  • "none" — Use CSS positioning; params.x is not used.
candleOffset Number <optional>

Number of candlewidths to offset the marker left or right from its horizontal position.

yPositioner string <optional>
"value"

Determines the y-axis position of the marker. Values include:

  • "value" — params.y must be set to an exact y-axis value. If params.y is omitted, the y-axis position defaults to "above_candle".
  • "above_candle" — Positions the marker right above the candle or line. If more than one marker is at the same position, the markers are aligned upwards from the first. The params.y value is not used.
  • "below_candle" — Positions the marker right below the candle or line. If more than one marker is at the same position, the markers are aligned downwards from the first. The params.y value is not used.
  • "on_candle" — Position the marker in the center of the candle or line, covering it. If more than one marker is at the same position, the markers are aligned downwards from the first. The params.y value is not used.
  • "top" — Position the marker at the top of the chart, right below the margin. If more than one marker is at the same position, the markers are aligned downwards from the first. The params.y value is not used.
  • "top_lane" — Same as "top", but each marker type (defined by label) gets its own row, or lane.
  • "bottom" — Position the marker at the bottom of the chart, right above the margin. If more than one marker is at the same position, the markers are aligned upwards from the first. The params.y value is not used.
  • "bottom_lane" — Same as "bottom", but each marker type (defined by label) gets its own row, or lane.
  • "none" — Use CSS positioning; params.y is not used.
field string <optional>

When yPositioner is set to position relative to a candle, this parameter determined which field in the dataSet to use for the candle. Attach a marker to a non-primary series (e.g. a comparison or study) by setting "field" equal that comparison's or study's symbol. When not specified, uses available HLC data.

permanent boolean <optional>
false

The marker stays on the chart even when the chart is re-initialized by a symbol change, call to loadChart() or initializeChart(), and so forth.

label string <optional>
"generic"

A label for the marker. Multiple markers can be assigned the same label, which allows them to be deleted simultaneously.

includeAxis boolean <optional>
false

If "true", then the marker can display on the x- or y-axis. Otherwise, it is cropped. at the axis edge.

chartContainer Boolean <optional>

If true, then the marker is placed directly in the chart container as opposed to in a container or holder node. When placing the marker directly in the chart container, the z-index setting for the marker should be set in relation to the z-index of other holders in order to place the marker above or below markers inside the holders.

groupable Boolean <optional>
true

When multiple groupable markers are placed at the same position, they will consolidate into a single group marker. Default setting is true. Set to false to stack markers vertically.

Since:
  • 15-07-01
  • 05-2016-10 Added the following params.yPositioner values: "value", "above_candle", "below_candle", "on_candle", "top", and "bottom".
  • 8.6.0 Added params.xPositioner options "tick", params.yPositioner options "top_lane", and "bottom_lane".
  • 9.1.0 Added params.candleOffset. Updated params.field to accept the symbol of a non-primary series.
  • 9.2.0 Added params.groupable
Example
new CIQ.Marker({
    stx: stxx,
	   xPositioner: "date",
    yPositioner: "value",
	   x: someDate,
	   y: somePrice,
	   field: "someSymbol", // Include if you wish to place the marker on a non-primary series.
	   label: "events",
	   node: newNode
});

Classes

Group
GroupNode
HeadsUp
NodeCreator
Performance
PinnedTooltip
Simple
TimeSpanEvent

Methods


click(params)

Called when a marker node is clicked. Checks to see whether the node has its own click function and, if it does, calls that function, passing all arguments to it.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Description
cx number

The clientX coordinate of the click event.

cy number

The clientY coordinate of the click event.

panel CIQ.ChartEngine.Panel

Panel where the click took place.

Since:
  • 7.2.0
  • 8.0.0 Signature changed to accept the params object.

createSliderMarker()

Creates a small marker on the range selector.

Requires "js/extras/pinnedMarkers.js"

Version:
  • ChartIQ Extras Package
Since:
  • 9.1.0


<abstract> doubleClick(params)

Called when a marker node is double-clicked.

Override this function with your own implementation. Return a truthy value to prevent CIQ.ChartEngine#doubleClick from dispatching the "doubleClick" event and invoking the doubleClickEventListener.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Description
cx number

The clientX coordinate of the double-click event.

cy number

The clientY coordinate of the double-click event.

panel CIQ.ChartEngine.Panel

Panel where the double-click took place.

Since:
  • 8.0.0

Returns:

true to indicate the double-click event has been handled; otherwise, false.

Type
boolean

getMarkerGroup()

Returns the CIQ.GroupMarker object representing the marker if it is placed in a group.

Since:
  • 9.2.0

Returns:

Marker representing the group

Type
CIQ.Marker.Group

makeDraggable( [dropzone])

Enables or disables a marker's ability to be dragged to within a specified dropzone. If the marker is expandable, the draggable portion is limited to that expandable portion.

This uses the HTML5 Drag and Drop API, which is not well supported on touch devices. As a result, the markers may not be able to be dragged using touch gestures.

Parameters:
Name Type Argument Default Description
dropzone HTMLElement | boolean <optional>
true

The container which will receive the dragged marker when it is dropped. Defaults to true, which will use the marker's panel for the dropzone. Setting this parameter to false will disable dragging.

Since:
  • 9.1.0


makePinnable( [isTooltip])

Makes an event marker pinnable. See CIQ.PinnedMarker for details. If you would like the marker subsystem to manage pinnable markers for you, you can set the pinnable flag to true for simple and performance markers: CIQ.Marker.Simple.prototype.pinnable = true; CIQ.Marker.Performance.prototype.pinnable = true; The pinnable flag is read when a marker is created. If you change these flags to true, all new markers of the relevant type pinnable. However, if you then change that flag to false, existing markers will remain pinnable, as the flag is not reread. To turn off the pinnable feature for an existing pinned marker, you must either destroy and recreate this marker or change the pinnable flag at the instance level. as well as all markers created while the flag continues to be true.

Requires "js/extras/pinnedMarkers.js"

Parameters:
Name Type Argument Description
isTooltip boolean <optional>

If true this is a pinned tooltip, otherwise a pinned marker.

Version:
  • ChartIQ Extras Package
Since:
  • 9.1.0


remove()

Removes the marker from the chart object

Since:
  • 15-07-01


render()

Normally the chart will take care of positioning the marker automatically but you can force a marker to render itself by calling this method. This will cause the marker to call its placement function. You might want to do this for instance if your marker morphs or changes position outside of the animation loop.


initializeScrollBehavior(node)

Initializes the scroll behavior of marker expands.

For proper styling, the perfect scrollbar requires elements to have been mounted on the DOM prior to initialization. As a result, this function should only be called on mounted nodes.

Parameters:
Name Type Description
node HTMLElement

The marker that contains the expand for which scroll behavior is initialized.

Since:
  • 8.2.0


positionContentVerticalAndHorizontal(node [, evenIfNotVisible])

Content positioner for any markers using the 'stx-marker-expand' class. It takes into consideration the marker's node location within its container and determines where to place the content so it is all showing regardless if it is to the left, right, top, or bottom of the marker node.

Parameters:
Name Type Argument Description
node HTMLElement

The HTML element representing the marker which has content.

evenIfNotVisible boolean <optional>

True to position the marker even if not visible. This makes any transition of the marker appear to be in the correct place. Note that positioning invisible markers will negatively affect performance.

Since:
  • 5.1.2
  • 8.6.0 Added evenIfNotVisible parameter.
  • 9.2.0 Modified to handle positioning of CIQ.Marker.Group markers

removeByLabel(stx, label)

Removes all markers with the specified label from the chart object

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

label string

The label

Since:
  • 15-07-01