Event Markers: General and Visual Settings

• Overview
• Grouping Mode
• Stacking Settings
• Specifying Marker Character
• For a Specific Event Marker
• For a Group of Markers
• Visual Settings
• Marker Shape and Size
• Customizing Fill, Border and Font for Various States
• Customizing Connector
• Mouse Cursor
• Enabling event marker selection
• Positioning Markers
• Positioning a Specific Marker
• Positioning a Group of Markers
• Marker placement adjustment

Overview

This article covers all visual and functional settings of event markers. Before getting started with this article, it is highly recommended to have first studied the structure of the <event_markers> node in XML Reference.

Grouping Mode

By default, if two or more event markers have the same date or fall onto the same point after grouping a series from a greater time span, they pile up one above the other.

This mechanism is good if the number of hashes isn't too great. But in a situation when tens of markers fall onto one timestamp, they simply don't fit its height physically, and some of them could get cut, leading to the data loss for end user.

The marker grouping mode is configured globally for all markers presented on the chart. There are two grouping modes are available for displaying markers:

• PutInStack - this mode is used by default. Event markers with identical timestamp or fallen onto the same point after grouping a series from a greater time span appear one above the other. For this mode, the component offers several options, which are covered in Stacking Settings.
• Merge - in this mode, markers with an identical timestamp visually appear as a single marker; that allows using a greater number of markers. For markers grouped this way, the component has a special set of event handlers that allow obtaining the list of markers fallen into the group, along with complete information on them.

Grouping mode is defined with the grouping_mode attribute in the <event_markers> node, which can accept the PutInStack and Merge values, described above. Here is a sample XML syntax for setting a grouping mode:

Now let's look at these modes by the live examples:

1. PutInStack: For demonstrating this example, we are going to use one group of markers with different characters on each of them:

2. Merge: For demonstrating this mode, we are going to use two groups of markers labeled with the "A" and "B" characters. All the event markers in the "A" group have the timestamp "2008-10-12", and in the "B" group - three markers have the "2008-10-12", and the other three - "2008-12-06".

When merging markers with an identical timestamp into a single marker, their original grouping is also taken into account. In other words, for example, a marker from the "A" group cannot merge to a marker from the "B" group, as they might have a completely different logical essence. Thus, merged markers appear one above the other and submit to the stacking settings described in Stacking Settings.

There are no internal mechanisms for displaying merged markers, but there is a way to obtain all the required information on them using the external events and display them using the external means. Examples demonstrating the use of such events are available in a bunch of samples in Online HTML/JavaScript Samples Center: Working with Event Markers section.

Stacking Settings

The event marker stacking settings are global and apply to all markers presented on the chart. They are provided in the <stack_settings> node. Here is a list of attributes available for the node along with their descriptions:

Attribute Name	Description	Type	Possible Values	Default Value
mode	Sets events markers stack behavior on mouse click.	Enum	AlwaysExpanded Interactive	Interactive
spacing_in_collapsed_state	Sets the spacing between items when event markers are stacked.	Number	N/A	3
collapse_after	Sets the lower limit of event markers in stack when it is forced to collapse (in Interactive stack mode).	Number	N/A	2

Special coverage is to be given to the use of the mode attribute. By default, it is set to Interactive. In this mode, the markers in the stack collapse into packs of three markers, one behind another, and whenever user clicks on a pack of this kind, it expands, arranging the markers one above the other.

To have all the event markers visible at all times, disable the collapsing by setting the mode attribute to AlwaysExpanded. Here is a live sample that demonstrates the use of such mode:

Specifying Marker Character

Each event marker can have a character or text of any length displayed on its body. The character or text to be displayed on markers can be specified for a specific event marker or for an entire group to avoid the redundancy in the configuration file.

For a Specific Event Marker

To specify a character for a specific event marker, use the format attribute in the event node. The attribute can accept the character that you want to bind to the event. Below is the sample XML syntax for specifying characters for different markers within one group:

Here is a live sample demonstrating specifying characters for several markers:

For a Group of Markers

To specify the same character for an entire group, also use the format attribute, but now in the group node. Here is a sample syntax for specifying a character for two different groups:

The live sample below demonstrates the use of such settings:

Visual Settings

The following elements of the event markers' settings can be customized:

• Shape and size of the background drawn behind marker character or text
• Background fill and border for various states
• Text font for various states
• Connector line, connecting the background of the marker with the point it is drawn against

All these elements are covered in detail in this section.

Shape and Size

Marker shape and size, like many other settings, can be defined for all markers, for a group or for a specific marker. Marker shape and size is configured in the <shape> node. Below is the sample syntax for making such customization for all markers:

Marker shape and size are controlled by the following attributes, which can be used in the <shape> node:

Attribute	Possible Values	Description
type	Flag Circle Rect Pin	Sets event marker shape.
size	Any number (e.g. 10)	Sets background width and height. The value is set in pixels.
width	Any number (e.g. 10)	Sets background width. The value is set in pixels.
height	Any number (e.g. 10)	Sets background height. The value is set in pixels.
auto_size	true false	If this attribute is set to true, the background width and height will be calculated automatically to fit the text. By default, this attribute is set to false.

Here is a table with the graphic representation of the shapes supported by event markers:

Sample	Shape Type
	Flag
	Circle
	Rect
	Pin

Here is a live sample demonstrating the use of markers of different shapes on the same chart:

Customizing Fill, Border and Font for Various States

Event Marker has four visual states, and each one of them is used for plotting a marker in one or the other situation. Here is a list of the attributes available for the node along with their descriptions:

• Normal - used if the marker is not selected, and the mouse pointer is not within its area.
• Hover - used if the marker is not selected, and the mouse pointer is within its area.
• Selected Normal - used if the marker is selected, and the mouse pointer is not within its area.
• Selected Hover - used if the marker is selected, and the mouse pointer is within its area.

Please note that the Selected Normal and Selected Hover states are applicable when user is allowed to select markers. This option is further described in Enabling Event Marker Selection.

For each of the state, you can configure an individual fill, background borders, corners - for rectangular markers, and font to be used for displaying the character or text on the marker.

Below is a sample syntax for configuring these settings for all four states, by the example of a group of markers:

The live sample below demonstrates the use of such settings:

The AnyChart Stock component gallery has a special section demonstrating capabilities of event markers. It contains several examples for various visualization configurations.

To learn more about them, please refer to:

• Gallery: Event Markers
• Online HTML/JavaScript Samples Center: Working with Event Markers.

Customizing Connector

The line connecting the point with the actual marker has two settings: length and visual properties.

Connector is configured in the connector node, which can be used on any level. Connector length is customized with the length attribute, which specifies the height in pixels. Below is the sample syntax for customizing the connector height and visualization for a group markers:

Here is a live sample demonstrating customization of connector settings for a group of markers:

For the comprehensive coverage on all available connector settings, please refer to XML Reference.

Mouse Cursor

By default when you hover event markers the arrow cursor is used, if you want to use hand cursor you need to set use_hand_cursor for a group or a selected event marker:

Here is a sample of a chart with two groups of event markers, the A groups uses hand cursor for all markers and the B group uses it for the last one:

Enabling Event Marker Selection

By default, user cannot select event markers. When event marker selection is disabled, the visual states Selected Normal and Selected Hover do not trigger.

To enable the option, use the following syntax:

Once the allow_select attribute is set to true, user can select specific events with the selected attribute, as shown on the listing above.

Here is a live sample with an enabled event marker selection option; click on an event marker to make sure they have become selectable.

Please note that only one event marker at a time can be selected on a chart.

Besides the end-user's actions, marker can be selected with the external method selectEventMarker, and drop the selection with resetEventMarkerSelection.

Positioning Markers

Event markers can be plotted in two positions: on a point in the series the group of markers is bound to or within the X-axis area. The position can be set for each specific marker or for an entire group of markers.

Positioning a Specific Marker

A specific event marker's position is configured with the position and direction attributes in the <event> node.

position attribute accept the following values:

• Series - marker is positioned on the value point of the series the group of markers containing this marker is bound to.
• SeriesPositive - marker is positioned on the value point of the series the group of markers containing this marker is bound to, but if series value is negative - marker is placed on zero.
• SeriesNegative - marker is positioned on the value point of the series the group of markers containing this marker is bound to, but if series value is positive - marker is placed on zero.
• Axis - marker is positioned at the bottom of the chart over the X-axis area; it does not change its vertical position depending on the value in the point of the series.

direction attribute accepts the following values:

• Up - marker is displayed above the value it is bound to.
• Down - marker is displayed below the value it is bound to.

Note: direction works only with Series, SeriesPositive and SeriesNegative.

Below is a sample syntax for positioning markers within one group:

Here is a live sample demonstrating event markers within the same group that hold different positions:

Positioning a Group of Markers

To define a position for an entire group of event markers, you can use the same position and/or direction attribute, now in the <group> node. The position attribute can as well accept the Axis, Series, SeriesPositive or SeriesNegative values, and direction can be Up or Down .

Below is a sample syntax for positioning a group of markers on the X-axis:

The live sample below uses three groups of markers, where two are positioned on the series, but with different direction, and one sits on the axis.

Marker placement adjustment

Be default all event markers are bound to "close" value (i.e. they are drawn near this value). It works fine, when you show group of markers on Lines, Splines, Areas, etc, but when you use Candlesticks, OHLC or range-based series, you may want to bind them to another value. To change the filed, to which markers are bound you should alter field_type attribute:

In this attribute you can use standard field names ("Open", "Low", etc.) or set it to "Custom" and specify custom name in field_custom_type_name attribute, as it is shown below:

Illustration below shows event marker positioning adjustment with Candlestick series:

And here is a live sample with Candlestick series and two groups of event markers: bound to "High" field and "Low" field, note how direction attribute can make them look even better.